PMGuide - Entry-Field Controls

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

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.

Using Entry-Field Controls

This section explains how to perform the following tasks:

• Create an entry field in a dialog or client window
• Change the default size of the entry field

Creating an Entry Field in a Dialog Window

A dialog window usually serves as the parent and owner of an entry field. The dialog window often includes a button that indicates whether the user wants to carry out an operation. When the user selects the button, the application queries the contents of the entry field and proceeds with the operation.

The definition of an entry field in an application's resource-definition file sets the initial text, window identifier, size, position, and style of the entry field. The following example shows how to define an entry field as part of a dialog template:

   DLGTEMPLATE IDD_SAMPLE
   BEGIN
       DIALOG "Sample Dialog", ID_DLG, 7, 7, 253, 145, FS_DLGBORDER,0
       BEGIN
           DEFPUSHBUTTON "~OK", DID_OK, 8, 151, 50, 23, WS_GROUP
           ENTRYFIELD "Here is some text", ID_ENTFLD, 42, 46, 68, 15,
               ES_MARGIN | ES_AUTOSCROLL
       END
   END

Creating an Entry Field in a Client Window

To create an entry field in a non-dialog window, an application calls WinCreateWindow with the window class WC_ENTRYFIELD. The entry field is owned by an application's client window, whose window procedure receives notification messages from the entry field.

The following code fragment shows how to create an entry field in a client window:

   #define ID_ENTRYFIELD 5

   HWND hwnd, hwndEntryField1, hwndClient;
   LONG xPos   =  50, yPos    = 100;
   LONG xWidth = 100, yHeight =  20;

   hwndEntryField1 = WinCreateWindow(
       hwndClient,            /* Parent-window handle */
       WC_ENTRYFIELD,         /* Window class         */
       "initial text",        /* Initial text         */
       WS_VISIBLE    |        /* Visible when created */
       ES_AUTOSCROLL |        /* Scroll text          */
       ES_MARGIN,             /* Create a border      */
       xPos, yPos,            /* x and y position     */
       xWidth, yHeight,       /* Width and height     */
       hwnd,                  /* Owner-window handle  */
       HWND_TOP,              /* Z-order position     */
       ID_ENTRYFIELD,         /* Window identifier    */
       NULL,                  /* No control data      */
       NULL);                 /* No pres. parameters  */

Changing the Default Size of an Entry Field

The default text limit of an entry field is 32 characters. An application can set a non-default size when creating an entry field by setting the cchEditLimit member of an ENTRYFDATA structure and supplying a pointer to the structure as the pCtlData parameter to WinCreateWindow.

The following code fragment creates an entry field with a text limit of 12 characters:

HWND hwndEntryField2;
HWND hwndClient;
ENTRYFDATA efd;
LONG xPos    = 50,
     yPos    = 50;
LONG xWidth  = -1,
     yHeight = -1;     /* Must be -1 for ES_AUTOSIZE */

/* Initialize the ENTRYFDATA structure */
efd.cb = sizeof(ENTRYFDATA);
efd.cchEditLimit = 12;
efd.ichMinSel = 0;
efd.ichMaxSel = 0;

/* Create the entry field */
hwndEntryField2 = WinCreateWindow(
                  hwndClient,            /* Parent-window handle  */
                  WC_ENTRYFIELD,         /* Window class          */
                  "projects.xls",        /* No initial text       */
                  WS_VISIBLE    |        /* Visible when created  */
                  ES_MARGIN     |        /* Create a border       */
                  ES_AUTOSCROLL |        /* Scroll text           */
                  ES_AUTOSIZE,           /* System sets the size  */
                  xPos, yPos,            /* x and y positions     */
                  xWidth, yHeight,       /* Width and height      */
                  hwndClient,            /* Owner-window handle   */
                  HWND_TOP,              /* Z-order position      */
                  0,                     /* Window identifier     */
                  &efd,                  /* Control data          */
                  NULL);                 /* No pres. parameters   */

To expand or reduce the text limit after creating the entry field, an application can send an EM_SETTEXTLIMIT message specifying a new maximum text limit for the entry field. The following code fragment increases to 20 characters the text limit of the entry field created in the previous example:

WinSendMsg(hwndEntryField2, EM_SETTEXTLIMIT, (MPARAM)20, (MPARAM)0);

Retrieving Text From an Entry Field

An application can use the WinQueryWindowTextLength and WinQueryWindowText functions to retrieve the text from an entry field. WinQueryWindowTextLength returns the length of the text; WinQueryWindowText copies the window text to a buffer.

Typically, an application needs to retrieve the text from an entry field only if the user changes the text. An entry field sends an EN_CHANGE notification code in the low word of the first message parameter of the WM_CONTROL message whenever the text changes. The following code fragment sets a flag when it receives the EN_CHANGE code, checks the flag during the WM_COMMAND message and, if it is set, retrieves the text of the entry field:

    HWND hwnd;
    ULONG msg;
    MPARAM mp1;
    CHAR chBuf[64];
    HWND hwndEntryField;
    LONG cbTextLen;
    LONG cbTextRead;
    static BOOL fFieldChanged = FALSE;

    switch (msg) {
        case WM_CONTROL:
            switch (SHORT1FROMMP(mp1)) {
                case IDD_ENTRYFIELD:

                    /* Check if the user changed the entry-field text. */
                    if ((USHORT) SHORT2FROMMP(mp1) == EN_CHANGE)
                        fFieldChanged = TRUE;
                    return 0;
            }

        case WM_COMMAND:
            switch (SHORT1FROMMP(mp1)) {
                case DID_OK:

                    /* If the user changed the entry-field text,       */
                    /* obtain the text and store it in a buffer.       */
                    if (fFieldChanged) {
                        hwndEntryField = WinWindowFromID(hwnd,
                            IDD_ENTRYFIELD);
                        cbTextLen = WinQueryWindowTextLength(hwndEntryField);
                        cbTextRead = WinQueryWindowText(hwndEntryField,
                            sizeof(chBuf), chBuf);
                        .
                        . /* Do something with the text.               */
                        .
                    }
                    WinDismissDlg(hwnd, 1);
                    return 0;
            }
    }