[Next] [Previous ] Chapter17
[Contents ] [Chapter 16: Buttons ] [Chapter 18: Multiline Edit Controls ]

Entry Fields

The entry field is perhaps one of the most widely used controls, with possible contenders being the button and the list box (see Figure 17.1). It provides the capability to receive a single line of input as well as to display text as if it were a scrollable static text field. It is also useful for just that: reading or displaying a single line of text. Entry fields are simple controls; multiline edit controls (MLEs) which are discussed in Chapter 18, should be used in situations where more complex functionality is required. Simplicity in function does have its advantages, as the entry field also is probably one of the easiest controls to write code for.
Entry fields
Figure 17.1 Entry fields.
The entry field does lack some capabilities that would be very nice to have. For example, being able to accept only certain types of text, having a fully functional picture string capability ('a la COBOL), and being able to force all text to be upper- or lowercase would be handy. Chapter 27 addresses the issue of adding function to an existing control and illustrates its concepts by an example that allows numeric input only in an entry field.

Entry Field Basics

Table 17.1 shows the various styles available for the entry field.

Table 17.1 Entry Field Styles
Style  Description
ES_LEFT Text is left justified.
ES_CENTER
 Text is center justified.
ES_RIGHT
 Text is right justified.
ES_AUTOSCROLL
 Text is scrolled as the cursor moves beyond the visible portion of the entry field.
ES_MARGIN
 A margin is drawn around the entry field.
ES_AUTOTAB
 When the maximum number of characters has been entered, the input focus is passed to the next control with the WS_TABSTOP style.
ES_READONLY
 Text is not modifiable.
ES_COMMAND
 The entry is denoted a command entry field. The help Manager uses this to provide help for the contents of the field, should the user request it. There should be only one entry field per window with this style.
ES_UNREADABLE
 Text is displayed as a string of asterisks ( '*' ), one per character of actual text.
ES_AUTOSIZE
 The entry field will size itself automatically to insure that the text fits within the visible portion of the control.
ES_ANY
 The entry field can contain single- and double-byte characters. If the text is converted from an ASCII code to an EBCDIC code page, there may be an overrun in the converted text. Contrast this with ES_MIXED, where this is not allowed.
ES_SBCS
 Text is comprised of single-byte characters only.
ES_DBCS
 Text is comprised of double-byte characters only.
ES_MIXED
 Text can contain either single- or double-byte characters, which may later be converted to or from an ASCII code page from or to EDCDIC code page.
Table 17.1 shows that numerous possibilities exist for creating entry fields. The ES_READONLY style is especially handy for displaying long strings of text for which there is no space; the ES_UNREADABLE is useful for getting information such as passwords from the user in cases where a passerby should not be able to - at a casual glance - perceive the contents.
The entry field is, again, an uncomplicated control; sometimes this leads to inconsistencies with other controls. For example (this applies to buttons also), the WinSetWindowText function is used to set the contents of an entry field.
BOOL    APIENTRY WinSetWindowText(HWND hwndWindow, PCSZ  pszText);
hwndWindow is the handle of the entry field to set the text of, and pszText is a pointer to the text.  The inconsistency is that, as we will be seen in other controls, text is usually set - and queried - through messages. However, why overcomplicated things unnecessarily ?
As we implied, the text also is queried through a function - the WinQueryWindowText function.
LONG    APIENTRY WinQueryWindowText(HWND hwndWindow,
                                    LONG cchBufferMax,
                                    PCH pchBuffer);
Again, hwndWindow is the handle of the entry field we are querying. cchBufferMax specifies the size of the buffer, and pszBuffer points to the receiving buffer. A companion function is helpful here; WinQueryWindowTextLength returns the length of the window text.
LONG    APIENTRY WinQueryWindowTextLength(HWND hwndWindow);
It takes a single parameter - hwndWindow - which indicates the window to be queried.
It should be noted that the default maximum text length of an entry field is only  32 bytes. While this may be large enough for most instances, at times a different length might be preferred - to limit the field to 5 characters for a Zip code or increase it to 256 for a file name, for example. This is accomplished by sending the entry field an EM_SETTEXTLIMIT message; passing the maximum number of characters in the first parameter will do the trick.

Gotcha!

The limit in the EM_SELECTTEXTLIMIT message should not include the terminating null character, but the extra byte should be allotted when calling WinQueryWindowText and 1 should be added to WinQueryWindowTextLength. An interesting point is that, while there is a message for setting the limit, there is no message for querying the limit. This querying can be accomplished using a voodoo incarnation of the WM_QUERYWINDOWPARAMS message, but that seems to be a lot of work for something so simple.

Selection Basics

Many operations in Presentation Manager programming deal with selected items. IBM's Common User Access (CUA) guidelines define a set of different attributes that an object can have, and being selected is one of them. A selected object is an object on which an action is to be performed.

Selections have two defining characteristics - an anchor point and a cursor point. The  anchor point is the place where the selection begins; the selection continues until it reaches the cursor point, which is where the input cursor is at any given time.

Selections can be performed using either the mouse or the keyboard. Using keyboard, the arrow keys are used to move the cursor to the desired anchor point; then the arrow keys are used while holding down either shift key to expand and contract the text selection. Selecting with the mouse can be done in two ways: swipe selection and shift-click selection.

Swiping is the method by which the mouse is moved to the desired position, the first mouse button is pressed and held, and the mouse is moved over the items to be selected. This is similar in action to direct manipulation, but the intention is different. Shift-click selection is closer to using the keyboard; the mouse is clicked at the desired anchor point and then clicked again while the shift key is held down to set the cursor point and thus the selected text.

When something is selected, it is given selection emphasis, and this is usually conveyed by displaying selected items in reverse;  this is true for entry fields. Specifically for entry fields (and a few other controls, as we'll see in other chapters) once a selection of text is selected, it can be manipulated. For example, any keypress replaces the selected text with the key pressed. If something is pasted from the clipboard, which is discussed in the next section, it replaces the selected text.
For the programmer, fortunately, two important messages refer to selections - EM_SETSEL and EM_QUERYSEK; the former sets the current selection and the latter queries the current selection is, if one exists. See Appendix A for specifics of each message.

The Entry Field and the Clipboard

No engineer can do without one; it is indispensable in meetings when a person needs to write and there is no table. A clipboard is what we are referring to. For those who do not know what it is, it is a piece of compressed wood - usually slightly larger than a sheet of paper - with a metal clip on top to hold papers in place when it is written on. Most, if not all, windowing systems have a beast of the same name, although (usually) the purpose is a bit different: A clipboard in a GUI environment is used for the temporary placement of data so that it may be copied to other places, whether in the same application that placed the data there or not.

From the viewpoint of an entry field, there are three interfaces to the clipboard, all via messages. The EM_CUT message removes the selected text and places it on the clipboard. The EM_COPY message copies the selected text onto clipboard, but the text remains in the entry field. The EM_PASTE message copies the date from the clipboard and inserts it either at the current cursor position or, if there is selected text in the entry field, replaces the currently selected text. Again, see Appendix A for specifics of each message.

And Other Things

Already we have a control that is quite usable. However, IBM provided some additional functionality. Two of these are read only and unreadable data, and they are specified by the two window styles ES_READONLY and ES_UNREADABLE.

The effect of ES_READONLY is rather obvious - it prevents the user from changing the contents of the entry field. Text may be selected and copied to the clipboard, but it may not be cut from the entry field, nor may other text be pasted into the entry field. The need for this is evident when text of an indeterminable length must be displayed on a fixed amount of screen "real estate". Using an entry field allows the text to be placed in required space, because it can be scrolled so that entire text can be viewed.
The implementation of ES_UNREADABLE is difficult to fathom. While the purpose is evident - to prevent the contents from being viewed - the method by which this is achieved is not. Currently, each character is displayed as an asterisk; this is a poor choice, since the most frequent application of ES_UNREADABLE is for computer passwords, where using an asterisk eliminates the need to guess how many letters are in the value. A programmer who needs to provide secure access should not use the ES_UNREADABLE style.

ENTRY - Entry Field Samples

The following application displays some entry fields with different styles. The point is not to demonstrate any particular piece of code, for entry field is very simple-minded; its purpose is to show the effects of the various styles that entry field can have.

ENTRY.C
ENTRY.RC
ENTRY.H
ENTRY.MAK
ENTRY.DEF  

[Next] [ Previous ]    Chapter17
[Contents ] [Chapter 16: Buttons ] [Chapter18: Multiline Edit Controls ]