About Edit Controls

An edit control is a rectangular control window typically used in a dialog box to enable the user to enter and edit text.

Edit controls support both the Unicode character set in which characters are two bytes, and ANSI character sets in which characters are one byte. For more information about Unicode and ANSI character sets, see Unicode and Character Sets.

Rich edit controls support many features not available in system edit controls. For more information, see Rich Edit Controls.

The following topics are discussed in this overview.

• Edit Control Features
• Edit Control Types and Styles
  • Multiline Style
  • Scrolling Styles
  • Alignment Styles
  • Text and Input Styles
  • Visual Styles
• The Text Buffer
  • Allocating a Text Buffer
  • Initializing a Text Buffer
  • Making a Text Buffer Read-only
• Changing the Formatting Rectangle
• Edit Control Notification Messages
• Edit Control Default Message Processing

Edit Control Features

When it is selected, an edit control displays a blinking 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 sends notification codes to its parent window in the form of WM_COMMAND messages. For more information about messages from an edit control, see Edit Control Notification Messages. A parent window can send messages to an edit control in a dialog box by calling the SendDlgItemMessage function. Some messages can also be sent by using predefined macros.

The system provides both single-line edit controls and multiline edit controls. Edit controls belong to the EDIT window class.

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.

Many developers use the dialog boxes provided in the common dialog box library (Comdlg32.dll) to perform tasks that otherwise might require customized edit controls. For information about common dialog boxes, see Common Dialog Box Library.

Edit Control Types and Styles

An individual edit control can have several styles at the same time. Most developers use tools to develop dialog boxes, and so may not need to specify edit control styles explicitly. If an application creates an edit control using the CreateWindow or CreateWindowEx function, however, it must specify these edit control styles. For a table of edit control styles, see Edit Control Styles.

Every edit control specifies a combination of style values that define the appearance and features of the edit control. The style values can establish the appearance of a single-line or multiline edit control; align the text in the control; and determine how, and even if, text appears in the edit control.

Multiline Style

There are two line styles for edit controls. The default is a single-line edit control. An application can also create a multiline edit control by using the ES_MULTILINE style.

Scrolling Styles

The ES_AUTOHSCROLL style tells the edit control to scroll the text horizontally, when necessary, as the user enters text. If this style is not specified, the edit control cannot scroll horizontally. For single-line edit controls without ES_AUTOHSCROLL, only the characters that fill the visible area of the control are accepted. For multiline edit controls without ES_AUTOHSCROLL, the text wraps to the next line when the user enters more text than can be displayed on a single line. If ES_AUTOHSCROLL is specified for a multiline edit control, the control scrolls horizontally when the user enters more text than can be displayed on a single line; the text will not wrap.

ES_AUTOHSCROLL is automatically applied to a left-aligned, multiline edit control that has a WS_HSCROLL style. In other words, any left-aligned, multiline edit control that has a horizontal scroll bar automatically scrolls horizontally.

ES_AUTOHSCROLL is ignored by a multiline edit control that is not left-aligned. Centered and right-aligned multiline edit controls cannot be horizontally scrolled

The ES_AUTOVSCROLL style tells the edit control to scroll the text vertically when the user enters more text than can be displayed in the edit control. This style only applies to multiline edit controls. If this style is not specified for a multiline edit control, the edit control will not accept the input when more text is entered than can be displayed.

Alignment Styles

There are three styles that cause the system to align the text in an edit control. The ES_LEFT, ES_CENTER, and ES_RIGHT styles determine whether text is aligned on the left, center, or right, respectively. Right-aligned and centered multiline edit controls cannot have the ES_AUTOHSCROLL style; that is, they cannot scroll horizontally.

Although it is not possible to change the alignment style of an edit control dynamically, the following techniques can be used to work around this restriction:

• Create multiple edit controls, one for each style the application needs, and to switch between them as required.
• Create a new edit control with the desired style as it is needed and switch to the new control.

Text and Input Styles

An application can use styles to specify how the edit control displays text. The ES_LOWERCASE style causes all uppercase characters entered into the edit control to be converted to lowercase. Similarly, the ES_UPPERCASE style cause all lowercase characters to be converted to uppercase.

For more information about character sets, see Unicode and Character Sets.

The ES_NUMBER style restricts input to digits only in the edit control.

The ES_READONLY style changes the edit control to read-only status.

The ES_PASSWORD style displays all characters in a single-line edit control as asterisks. An application can define a different character to display by using the EM_SETPASSWORDCHAR message, as described later in this topic.

If an edit control is from Comctl32.dll version 6, a black circle is the default character for the ES_PASSWORD style. In edit controls from previous versions of the common controls, the default character is an asterisk.

The ES_OEMCONVERT style causes text entered into the edit control to be converted from the Windows characters set to the OEM character set and then back to Windows characters set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the edit control to OEM characters. ES_OEMCONVERT is most useful for edit controls that contain file names that will be used on file systems that do not support Unicode.

For a multiline edit control in a dialog box, the ES_WANTRETURN style causes the control to insert a carriage return when the user presses the ENTER key while entering text. If this style is not specified, pressing the ENTER key has the same effect as pressing the default push button in the dialog box. Without ES_WANTRETURN, the user must press CTRL+ENTER to insert a carriage return. For information on Wordwrap and line breaks, see Handling Wordwrap and Line Breaks.

Visual Styles

The ES_NOHIDESEL style causes the selected text to remain highlighted when the edit control does not have the focus. Without this style, the selected text loses the highlighting when the control loses focus.

By default, an edit control has no border. To give it one, an application can use the WS_BORDER window style.

To use visual styles with edit controls, an application must include a manifest and must call InitCommonControls at the beginning of the program. For information on visual styles, see Visual Styles. For information on manifests, see Enabling Visual Styles.

The Text Buffer

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

The following topics discuss how the system allocates and initializes the buffer and changes its characteristics:

• Allocating a Text Buffer
• Initializing a Text Buffer
• Making a Text Buffer Read-only

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 notification code. 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 notification code, 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, follow this procedure.

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 Read-only

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 code corresponding to the user's action in the high-order word of the wParam parameter.

An application should examine the notification codes accompanying each notification message and respond appropriately. The following table lists each edit control notification code 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.

Edit Control Default Message Processing

The window procedure for the predefined edit control window class carries out default processing for all messages that the edit control procedure does not process. When the edit control procedure returns FALSE for any message, the predefined window procedure checks the messages and carries out the following default actions.

The predefined edit control window procedure passes all other messages to the DefWindowProc function for default processing.