Edit fields

An edit control is a rectangular control window typically used in a dialog box to permit the user to enter and edit text by typing on the keyboard.

Edit controls support both the Unicode character set in which characters are two bytes, and ANSI character sets in which characters are one byte.

Edit Control Features

An edit control is selected and receives the input focus when a user clicks the mouse inside it or presses the TAB key. After it is selected, the edit control displays its text (if any) and a flashing caret that indicates the insertion point. The user can then enter text, move the insertion point, or select text to be edited by using the keyboard or the mouse. An edit control can send notification messages to its parent window in the form of WM_COMMAND messages. A parent window can send messages to an edit control in a dialog box by calling the SendDlgItemMessage function.

A combo box is a control that combines much of the functionality of an edit control and a list box. In a combo box, the edit control displays the current selection and the list box presents options a user can select. For more information about combo boxes, see Combo Boxes .

Styles

1. Border: Wether it has a black line for a border or not.
2. Uppercase: Whether it should convert all input to uppercase or not
3. Lowercase: Similar to above.
4. Password: Controls with this style do not show what the user types, just an asterisk.
5. Visible selection means whether the control will retain its selection even if it looses the focus. Normally, edit controls do not show the selection when they do not have the focus;
6. Horz/Vert scroll. Not very useful unless the edit field is multiline.
7. Want carriage return: Whether the return key is processed by the control or passed to the dialog procedure.
8. Translate PCchar set. Useful only if you have old DOS software with other code page in it.
9. Multi-line: Whether the control can hold several lines.
10. Number means that the control will only accept characters between 0 and 9. No minus sign is allowed, nor floating point notation.
11. Read only means that the user can only see the data displayed but not change it.
12. Automatic scroll means that the control will display a sliding window when the data is greater than the screen dimensions of the control.
13. Text alignment: Either left to right (default) or right to left (oriental languages).

The Text Buffer

The system stores edit control text in a buffer and copies it to the control, as necessary.

Allocating a Text Buffer

When the system creates an edit control, it automatically creates a text buffer, sets its initial size, and increases the size as necessary. The size can be up to a predefined limit of approximately 32 kilobyte (KB) for single-line edit controls. Because this limit can change, it is called a soft limit. An application can set a hard limit to the buffer size by sending an EM_SETLIMITTEXT message to the edit control. If the buffer exceeds either limit, the system sends the application an EN_ERRSPACE message. An application can retrieve the current text limit by sending an EM_GETLIMITTEXT message.

The system typically creates an edit control buffer in a dialog box, using memory outside the application's data segment. An application can suppress this default allocation behavior and create the buffer from its local heap by using the DS_LOCALEDIT style (see "Dialog Box Template Styles" in About Dialog Boxes ) when creating the edit control. An application that uses the DS_LOCALEDIT style is responsible for all buffer allocations. To make the initial allocation, an application can call the LocalAlloc function and pass the returned buffer handle to the edit control by sending it an EM_SETHANDLE message. To make subsequent allocations (in response to an EN_ERRSPACE message, for example), an application should save the current buffer content (if necessary) and obtain a new buffer as follows.

To save the current buffer and obtain a new one:

1. Retrieve the handle of the memory currently allocated for the text in a multiline edit control by sending the control an EM_GETHANDLE message.
2. Free the buffer by calling the LocalFree function.
3. Obtain a new buffer (and buffer handle) by calling LocalAlloc.
4. Give the buffer handle to the system by sending the control an EM_SETHANDLE message.

The EM_SETHANDLE and EM_GETHANDLE messages apply only to multiline edit controls.

An application that uses the default allocation behavior (that is, does not use the DS_LOCALEDIT style (see "Dialog Box Template Styles" in About Dialog Boxes)) must not send EM_SETHANDLE and EM_GETHANDLE messages to the edit control.

Sending an EM_SETHANDLE message has several side effects: it clears the undo flag (making the EM_CANUNDO message return zero), it clears the modify flag (making the EM_GETMODIFY message return zero), and it redraws the edit control window.

Initializing a Text Buffer

An application can initialize or reinitialize an edit control's text buffer by calling the SetDlgItemText function. An application can retrieve the content of a text buffer by calling the GetDlgItemText function.

Making a Text Buffer Readonly

For each edit control, the system maintains a read-only flag that indicates whether the control's text is read-write (the default) or read-only. An application can set the read-write flag or the read-only flag for the text by sending the control an EM_SETREADONLY message. To determine whether an edit control is read-only, an application can call the GetWindowLong function using the GWL_STYLE constant. The EM_SETREADONLY message applies to both single-line and multiline edit controls.

Changing the Formatting Rectangle

The visibility of an edit control's text is governed by the dimensions of its window rectangle and its formatting rectangle. The window rectangle is the client area of the window containing the edit control. The formatting rectangle is a construct maintained by the system for formatting the text displayed in the window rectangle. When an edit control is first displayed, the two rectangles are identical on the screen. An application can make the formatting rectangle larger than the window rectangle (thereby limiting the visibility of the edit control's text) or smaller than the window rectangle (thereby creating extra white space around the text).

An application can set the coordinates of an edit control's formatting rectangle by sending it an EM_SETRECT message. The EM_SETRECT message also automatically redraws the edit control's text. To establish the coordinates of the formatting rectangle without redrawing the control's text, an application can send the control an EM_SETRECTNP message. To retrieve the coordinates of the formatting rectangle, an application can send the control an EM_GETRECT message. These messages apply to multiline edit controls only.

Edit Control Notification Messages

The user makes editing requests by using the keyboard and mouse. The system sends each request to the edit control's parent window in the form of a WM_COMMAND message. The message includes the edit control identifier in the low-order word of the wParam parameter, the handle of the edit control in the lParam parameter, and an edit control notification message corresponding to the user's action in the high-order word of the wParam parameter.

An application should examine each notification message and respond appropriately. The following table lists each edit control notification message and the action that generates it.

In addition, the system sends a WM_CTLCOLOREDIT message to an edit control's parent window before the edit control is drawn. This message contains a handle of the edit control's display context (DC) and a handle of the child window. The parent window can use these handles to change the edit control's text and background colors.