PMGuide - Entry-Field Controls
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
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. |
Entry-Field Text Editing
The user can insert (type) text or numeric values in an entry field when that entry field has the keyboard focus. An application can insert text by using the WinSetWindowText function. An application can insert numeric values by using the WinSetDlgItemShort function. The text or numeric value is inserted into the entry field at the cursor position.
The entry field's entry mode, either insert or overstrike, determines what happens when the user enters text. The user sets the entry mode by pressing the Insert key; the entry mode toggles each time the Insert key is pressed. The application can set the entry mode by sending the EM_SETINSERTMODE message to the entry field.
The cursor position, identified by a blinking bar, is specified by a character offset relative to the beginning of the text. The user can set the cursor position by using the mouse or the Arrow keys. An application can set the cursor position by using the EM_SETSEL message. This message directs the entry field to move the blinking bar to the given character position.
The EM_SETSEL message also sets the selection. The selection is one or more characters of text on which the entry field carries out an operation, such as deleting or copying to the clipboard. The user selects text by pressing the Shift key while moving the cursor, or by pressing mouse button 1 while moving the mouse. An application selects text by using the EM_SETSEL message to specify the cursor position and the anchor point. The selection includes all text between the cursor position and the anchor point. If the cursor position and anchor point are equal, there is no selection. An application can retrieve the selection (cursor position and anchor point) by using the EM_QUERYSEL message.
The user can delete characters, one at a time, by pressing the Delete key or the Backspace key. The Delete key deletes the character to the right of the cursor; the Backspace key deletes the character to the left of the cursor. The user also can delete a group of characters by selecting them and pressing the Delete key. An application can delete selected text by using the EM_CLEAR message.
An application can use the EM_QUERYCHANGED message to determine whether the contents of an entry field have changed.
An application can prevent the user from editing an entry field by setting the ES_READONLY style in the WinCreateWindow function or in the ENTRYFIELD statement in the resource-definition file. The application also can set and query the read-only state by using the EM_SETREADONLY and ES_QUERYREADONLY messages.
If text extends beyond the left or right edges of an entry field, the user can scroll the text by using the Arrow keys. An application can scroll the text by using the EM_SETFIRSTCHAR message to specify the first character visible at the left edge of the entry field. For scrolling to occur, the entry field must have the ES_AUTOSCROLL style. An application can use the EM_QUERYFIRSTCHAR message to obtain the first character that is currently visible.
Entry-Field Control Copy and Paste Operations
The user can cut, copy, and paste text in an entry field by using the Shift+Delete and Ctrl+Insert key combinations. An application, either by itself or in response to the user, can cut, copy, and paste text by using the EM_CUT, EM_COPY, and EM_PASTE messages. An application can use the ES_CUT and EM_COPY messages to copy the selected text to the clipboard. The EM_CUT message also deletes the text (EM_COPY does not). The EM_PASTE message copies the text on the clipboard to the current position in the entry field, replacing any existing text with the copied text. An application can delete the selected text, without copying it to the clipboard, by using the EM_CLEAR message.
Entry-Field Text Retrieval
An application can retrieve selected text from an entry field by calling WinQueryWindowText and then sending an EM_QUERYSEL message to retrieve the offsets to the first and last characters of the text selection. These offsets are used to retrieve selected text.
An application can retrieve numeric values by calling WinQueryDlgItemShort, passing the entry-field identifier and the handle of the owner window. WinQueryDlgItemShort converts the entry-field text to a signed or unsigned integer and returns the value in a specified variable. The application can use the WinWindowFromID function to retrieve the handle of the control window. The entry-field identifier is specified in the dialog template in the application's resource-definition file.