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. │ └────────────────────┴────────────────────────────────────────┘