overview.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
Using Entry-Field Controls (1.2)
About Section  Message Group  Styles            Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
                         Using Entry-Field Controls
 
Entry-field controls can be used in dialog windows and regular client
windows. As part of a dialog window, the entry-field control is defined as
part of the dialog template in the application resource file. In a client
window, the application creates a window with the window class
WC_ENTRYFIELD.
 
Once created, the contents, font, and selection range of the entry-field
control can be changed by sending appropriate messages to the entry-field
control window. Entry-field controls hold up to 32 characters by default,
but applications can expand or reduce this limit, depending on memory
limits, once the control is created. Applications can query the current
contents or the current selection in an entry-field control.
 
Applications can also transfer text and data between the entry-field control
and the system clipboard by using cut, copy, clear, and paste operations.
This facility is useful for moving text from an entry-field control to
another window or process.
 
Entry-Field Controls in a Dialog Window
 
Entry-field controls are typically used in dialog windows. The dialog window
serves as the parent and owner window for the entry-field control. The
application dialog procedure receives notification messages from entry-field
controls. Generally, a dialog window includes a button that signals that the
user wants to carry out an operation. The application ignores most
notification messages from an entry-field control, allowing default text
editing to occur. When the user selects the button that indicates an
operation should begin, the application queries the contents of the
entry-field control and proceeds with the operation.
 
To include an entry-field control in a dialog window, include a definition
for an entry-field control item in the dialog-template definition in the
resource file. The definition sets up the initial text, window ID, size,
position, and style of the entry-field control. The following is a sample
dialog template containing an entry-field control:
 
DLGTEMPLATE IDD_SAMPLE
{
DIALOG "Sample Dialog", 50, 7, 7, 253, 145, FS_DLGBORDER,0
    {
        DEFPUSHBUTTON "~Ok", DID_OK, 8, 151, 50, 23, WS_GROUP
        ENTRYFIELD "Here is some text", ID_ED1, 42, 46, 68, 15,
            ES_MARGIN | ES_AUTOSCROLL
    }
}
 
Once created as part of a dialog window, the entry-field control sends
notification messages to the dialog window. An application handles these
messages in its dialog-window procedure.
 
An application communicates with an entry-field control in a dialog window
by sending messages to the entry-field control window. The handle of the
entry-field control window is obtained by calling the WinWindowFromID
function (using the dialog window as the parent window and the window ID for
the entry-field control as defined in the dialog template).
 
Entry-Field Controls in a Client Window
 
To have an entry-field control in a non-dialog window, an application calls
the WinCreateWindow function with the window class WC_ENTRYFIELD. An
application client window owns the entry-field control. The client-window
procedure receives notification messages from the entry-field control. The
following code fragment shows how to create an entry-field control window in
a client window:
 
hwndEntryField = WinCreateWindow(hwndClient,   /* parent   */
   WC_ENTRYFIELD,                              /* class    */
   "initial text contents",                    /* text     */
   WS_VISIBLE | ES_AUTOSCROLL | ES_MARGIN,     /* style    */
   xPos, yPos,                                 /* x, y     */
   xSize, ySize,                               /* cx, cy   */
   hwndClient,                                 /* owner    */
   HWND_TOP,                                   /* behind   */
   hwndEntryField,                             /* win ID   */
   pCtlData,                                   /* ctl data */
   (PVOID) NULL);                              /* reserved */
 
The entry-field control created in the preceding example has a 32-character
default limit. An application can change this limit by sending an
EM_SETTEXTLIMIT message to the control window. The limit can be set to a
non-default value at creation by supplying a pointer to an ENTRYFDATA
structure as the pCtlData parameter to the WinCreateWindow function.
 
The chPictureMask field in ENTRYFDATA can be used to specify an edit mask
for entered data.  If the ES_PICTUREMASK style is set, then this field will
contain an edit mask consisting of the characters 'L' or space.  An 'L' in a
specific character position in the edit mask means that the corresponding
character position in the entry field is "locked".  Locked characters are
displayed, but may not be changed or deleted. The cursor will skip over any
locked characters. For example:
 
editmask     'L   LL   L    '
initial text '(   )    -    '
user input   '1234567890'
result       '(123) 456-7890'
 
The other fields of the ENTRYFDATA structure can be set to specify the
selection length and the first visible character at the left edge of the
control window. Entry-field control attributes can also be changed by
sending messages to the control after it is created. It is not necessary to
provide this information in the ENTRYFDATA structure for creation to occur.
 
Responding to a Message from an Entry-Field Control
 
An entry-field control communicates with its owner by sending WM_CONTROL
messages. These messages contain notification codes that specify the exact
nature of the message. Typically, an application does not respond to
notification messages from an entry-field control for default text-editing.
For more specialized uses, an application uses notification messages to
perform input filtering.
 
For example, if an application has an entry-field control that is intended
for entering a number, it can use the WM_CONTROL message with the EN_CHANGE
notification code to check the contents after each new character is entered.
This tells a user that an inappropriate character has been entered.
 
On a deeper level, an application can use EN_SETFOCUS and EN_KILLFOCUS
notification codes with the WM_CONTROL message to toggle the input filtering
that occurs before the character messages are sent to the entry-field
control. An application can use conditional code in its main-event loop to
filter incoming WM_CHAR messages whenever the entry-field control has the
focus. By intercepting WM_CHAR messages before they are dispatched using the
WinDispatchMsg function, an application can prevent inappropriate characters
from reaching the entry-field control. You might also want to apply special
interpretation to certain keystrokes, such as the ENTER key, as long as the
entry-field control has the focus.
 
The application can also use the EM_SETREADONLY and EM_QUERYREADONLY
messages to set or determine the read-only state of a field.  If the field
is read-only, it may not be modified.
 
The EM_SETINSERTMODE message can be used to toggle the insertion mode
between overstrike and insert.
 
Changing the State of an Entry-Field Control
 
You can set or retrieve text in an entry-field control window by calling the
WinSetWindowText or WinQueryWindowText function. To retrieve the text for
the current selection, an application first calls the WinQueryWindowText
function to retrieve the contents, and then sends an EM_QUERYSEL message to
retrieve the offsets to the first and last character of the text selection.
These offsets are used to retrieve selected text from the entire text.
 
Edit fields containing numerical values can be set or queried by calling the
WinSetDlgItemShort or WinQueryDlgItemShort function and passing the
entry-field ID and the parent window. The WinSetDlgItemShort function
converts a signed or unsigned integer into a text string and sets the field
text with it. The WinQueryDlgItemShort function converts the entry-field
text to a signed or unsigned integer and returns the value in a specified
variable.
 
An application can set or query the selection range, although the
entry-field control automatically handles selection changes in response to
user input in keeping with the standard user-interface guidelines. However,
it can be useful to have an application select the entire text prior to
cutting or pasting to the system clipboard.
 
Communicating with the System Clipboard
 
Entry-field controls respond to messages designed to simplify transferring
data to and from the system clipboard. These messages support the standard
cut, copy, clear, and paste operations defined by the standard
user-interface guidelines. All clipboard messages for entry-field controls
use the CF_TEXT clipboard-data format. See the summary section at the end of
this topic for a description of each message.
 
Default Entry-Field Behavior
 
This section describes all the messages specifically handled by the
predefined entry-field control-window class.
 
Message               Description
────────────────────────────────────────────────────────────────────────────
WM_CREATE             Validate the requested style and set the window text.
 
WM_DESTROY            Free the memory used for the window text.
 
WM_BUTTON1DOWN        Set the mouse capture and keyboard focus to the
                      entry-field and prepare to track the mouse during
                      WM_MOUSEMOVE messages.
 
WM_BUTTON1DBLCLK      Set the mouse capture and keyboard focus to the
                      entry-field and prepare to track the mouse during
                      WM_MOUSEMOVE messages.
 
WM_BUTTON1UP          Release the mouse capture.
 
WM_BUTTON2DOWN        Return TRUE to prevent this message from being
                      processed further.
 
WM_BUTTON3DOWN        Return TRUE to prevent this message from being
                      processed further.
 
WM_PAINT              Draw the entry-field control and text.
 
WM_CHAR               Handle key events according to the standard
                      user-interface guidelines.
 
WM_SETSELECTION       Invert the current selection range.
 
WM_SETFOCUS           If gaining the focus, create a cursor and send to the
                      owner window a WM_CONTROL message with the
                      EN_SETFOCUS control code. If losing the focus, destroy
                      the current cursor and send to the owner window a
                      WM_CONTROL message with the EN_KILLFOCUS control
                      code.
 
WM_QUERYDLGCODE       Return the predefined DLGC_ENTRYFIELD constant.
 
WM_QUERYWINDOWPARAMS  Return the requested window parameters.
 
WM_SETWINDOWPARAMS    Set the specified window parameters, redraw the
                      control, and send to the owner window a WM_CONTROL
                      message with the EN_CHANGE control code.
 
WM_MOUSEMOVE          If the mouse button is down, track the text selection.
                      If the mouse button is up, set the mouse pointer to
                      the default arrow shape.
 
WM_ENABLE             Invalidate the entire entry-field control window,
                      causing a WM_PAINT message to be sent to the control.
 
WM_TIMER              Blink the insertion point if the control has the
                      focus. Scroll the text, if necessary, while extending
                      a selection to text not visible in the window.
 
WM_ADJUSTWINDOWPOS    Change the rectangle for the control size to adjust
                      for the margin if the control has the ES_MARGIN
                      style.
 
EM_QUERYREADONLY      Determine if an entry field is read-only
 
EM_SETREADONLY        Set an entry field to read-only mode.
 
EM_SETINSERTMODE      Toggle the insertion mode between insert and
                      overstrike.
 
EM_QUERYFIRSTCHAR     Return the offset to the first character visible at
                      the left edge of 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. Returns TRUE if
                      successful, or FALSE if it is not.
 
EM_QUERYCHANGED       Returns TRUE if the text has changed since the last
                      EM_QUERYCHANGED message.
 
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_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, FALSE if it is not. Failure
                      causes a WM_CONTROL message with the EM_MEMERROR
                      control code to be sent to the owner window.
 
EM_CUT                Copies the current text selection to the system
                      clipboard in CF_TEXT format and deletes the selection
                      from the control window.
 
EM_COPY               Copies the current text selection to the system
                      clipboard in CF_TEXT format.
 
EM_CLEAR              Deletes the current text 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.
 
 
                                      ♦