[ Next ] [ Previous ] | Chapter 17 |
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.
![]() |
Figure 17.1 Entry fields. |
Table 17.1 shows the various styles available for the entry field.
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. |
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. |
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.
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.
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.
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 ] | Chapter 17 |