PMGuide - Entry-Field Controls

An entry field is a control window that enables a user to view and edit a single line of text. This chapter describes how to create and use entry-field controls in your PM applications.

About Entry Fields

An entry field provides the text-editing capabilities of a simple text editor and is useful whenever an application requires a short line of text from the user.

If the application requires more sophisticated text-editing capabilities and multiple lines of text from the user, the application can use a multiple-line entry (MLE) field. See Presentation Manager Programming Guide - Advanced Topics for more information about MLE controls.

Both the user and the application can edit text in an entry field. Applications typically use entry fields in dialog windows, although they can be used in non-dialog windows as well.

An application creates an entry field by specifying either the WC_ENTRYFIELD window class in the WinCreateWindow function or the ENTRYFIELD statement in a resource-definition file.

Entry-Field Styles

An entry field has a style that determines how it appears and behaves. An application specifies the style in either the WinCreateWindow function or the ENTRYFIELD statement in a resource-definition file. An application can specify a combination of the following styles for an entry field.

Style	Description
ES_ANY	Allows the entry-field text to contain a mixture of double-byte and single-byte characters.
ES_AUTOSCROLL	Automatically scrolls text horizontally to show the insertion point.
ES_AUTOSIZE	Automatically sets the size of the entry field, based on the width of the field's text string and the metrics of the current system font. This style can set the width, height, or both-whichever has a value of -1 in the WinCreateWindow function or resource-definition file. This style affects only the initial size of the entry field; it does not adjust the size as the font or text-string width changes.
ES_AUTOTAB	Automatically moves the cursor to the next control window when the user enters the maximum number of characters.
ES_CENTER	Centers text within the entry field.
ES_DBCS	Specifies that the entry-field text consist of double-byte characters only.
ES_LEFT	Left-aligns text within the entry field.
ES_MARGIN	Draws a border around the entry field. The border is 1/2-character wide and 1/4-character high. Without this style, the application draws no border around the entry field. The width of the entry-field rectangle is increased on all sides by the width of this margin. After an entry field with the ES_MARGIN style is created, the WinQueryWindowRect function returns a larger rectangle that includes this margin and whose origin, therefore, is different from the origin specified when the entry field was created. If an application does not adjust for this size difference when moving or sizing an entry field, the entry field becomes larger after each moving and sizing operation.
ES_MIXED	Allows the entry-field text to contain a mixture of single-byte and double-byte characters. Unlike the ES_ANY style, this style lets ASCII DBCS data be converted to EBCDIC DBCS data without causing an overflow condition.
ES_READONLY	Prevents the user from entering or editing text in the entry field.
ES_RIGHT	Right-aligns text within the entry field.
ES_SBCS	Specifies that the entry-field text must consist of single-byte characters only.
ES_UNREADABLE	Displays each character as an asterisk (*). This style is useful when obtaining a password from the user.

Entry-Field Notification Codes

An entry field is always owned by another window. A WM_CONTROL notification message is sent to the owner whenever an event occurs in the entry field. This message contains a notification code that specifies the exact nature of the event. An entry field can send the notification codes described in the following table to its owner.

Notification Code	Description
EN_CHANGE	Indicates that the contents of an entry field have changed.
EN_INSERTMODETOGGLE	Indicates that the insert mode has been toggled.
EN_KILLFOCUS	Indicates that an entry field has lost the keyboard focus.
EN_MEMERROR	Indicates that an entry field cannot allocate enough memory to perform the requested operation, such as extending the text limit.
EN_OVERFLOW	Indicates that either the user or the application attempted to exceed the text limit.
EN_SCROLL	Indicates that the text in an entry field is about to scroll.
EN_SETFOCUS	Indicates that an entry field received the keyboard focus.

An application typically ignores notification messages from an entry field, thereby allowing default text editing to occur. For more specialized uses, an application can use notification messages to filter input. For example, if an entry field is intended for numbers only, an application can use the EN_CHANGE notification code to check the contents of the entry field each time the user enters a non-numeric character.

As an alternative, an application can prevent inappropriate characters from reaching an entry field by using EN_SETFOCUS and EN_KILLFOCUS, in filter code, placed in the main message loop. Whenever the entry field has the keyboard focus, the filter code can intercept and filter WM_CHAR messages before the WinDispatchMsg function passes them to the entry field. An application also can respond to certain keystrokes, such as the Enter key, as long as the entry-field control has the keyboard focus.

Default Entry-Field Behavior

The following table lists and describes all the messages specifically handled by the predefined entry-field control-window class (WC_ENTRYFIELD).

Message	Description
EM_CLEAR	Deletes the current text selection from the control window.
EM_COPY	Copies the current text selection to the system clipboard, in CF_TEXT format.
EM_CUT	Copies the current text selection to the system clipboard, in CF_TEXT format, and deletes the selection from the control window.
EM_PASTE	Copies the current contents of the system clipboard that have CF_TEXT format, replacing the current text selection in the control window.
EM_QUERYCHANGED	Returns TRUE if the text has changed since the last EM_QUERYCHANGED message.
EM_QUERYFIRSTCHAR	Returns the offset to the first character visible at the left edge of the control window.
EM_QUERYREADONLY	Determines whether the entry field is in the read-only state.
EM_QUERYSEL	Returns a long word that contains the offsets for the first and last characters of the current selection in the control window.
EM_SETFIRSTCHAR	Scrolls the text so that the character at the specified offset is the first character visible at the left edge of the control window.
EM_SETINSERTMODE	Toggles the text-entry mode between insert and overstrike.
EM_SETREADONLY	Sets the entry field to the read-only state.
EM_SETSEL	Sets the current selection to the specified character offsets.
EM_SETTEXTLIMIT	Allocates memory from the control heap for the specified maximum number of characters, returning TRUE if it is successful and FALSE if it is not. Failure causes the entry field to send a WM_CONTROL message with the EN_MEMERROR notification code to the owner window.
WM_ADJUSTWINDOWPOS	Changes the size of the control rectangle if the control has the ES_MARGIN style.
WM_BUTTON1DBLCLK	Occurs when the user presses mouse button 1 twice.
WM_BUTTON1DOWN	Sets the mouse capture and keyboard focus to the entry field, and prepares to track the movement of the mouse during WM_MOUSEMOVE messages.
WM_BUTTON1UP	Releases the mouse.
WM_BUTTON2DOWN	Returns TRUE to prevent this message from being processed further.
WM_BUTTON3DOWN	Returns TRUE to prevent this message from being processed further.
WM_CHAR	Handles text entry and other keyboard input events.
WM_CREATE	Validates the requested style and sets the window text.
WM_DESTROY	Frees the memory used for the window text.
WM_ENABLE	Sent when an application changes the enabled state of a window.
WM_MOUSEMOVE	If the mouse button is down, the entry field tracks the text selection. If the mouse button is up, the entry field sets the mouse pointer to the default arrow shape.
WM_PAINT	Draws the entry field and text.
WM_QUERYDLGCODE	Returns the predefined DLGC_ENTRYFIELD constant.
WM_QUERYWINDOWPARAMS	Returns the requested window parameters.
WM_SETFOCUS	If the entry field is gaining the focus, it creates a cursor and sends the owner window a WM_CONTROL message with the EN_SETFOCUS notification code. If the entry field is losing the focus, it destroys the current cursor and sends the owner window a WM_CONTROL message with the EN_KILLFOCUS notification code.
WM_SETSELECTION	Toggles the current selection status.
WM_SETWINDOWPARAMS	Sets the specified window parameters, redraws the entry field, and sends the owner window a WM_CONTROL message with the EN_CHANGE notification code.
WM_TIMER	Blinks the insertion point if the entry field has the focus. The entry field scrolls the text, if necessary, while extending the selection to text that becomes visible in the window.