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
- The Text Buffer
- 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
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.
- Retrieve the handle of the memory currently allocated for the text in a multiline edit control by sending the control an EM_GETHANDLE message.
- Free the buffer by calling the LocalFree function.
- Obtain a new buffer (and buffer handle) by calling LocalAlloc.
- 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.
| Notification code | User action |
|---|---|
| EN_CHANGE | The user has modified text in an edit control. The system updates the display before sending this notification code (unlike EN_UPDATE). |
| EN_ERRSPACE | The edit control cannot allocate enough memory to meet a specific request. |
| EN_HSCROLL | The user has clicked the edit control's horizontal scroll bar. The system sends this notification code before updating the screen. |
| EN_KILLFOCUS | The user has selected another control. |
| EN_MAXTEXT | While inserting text, the user has exceeded the specified number of characters for the edit control. Insertion has been truncated. This notification code is also sent either when an edit control does not have the ES_AUTOHSCROLL style and the number of characters to be inserted exceeds the width of the edit control or when an edit control does not have the ES_AUTOVSCROLL style and the total number of lines to be inserted exceeds the height of the edit control. |
| EN_SETFOCUS | The user has selected this edit control. |
| EN_UPDATE | The user has altered the text in the edit control and the system is about to display the new text. The system sends this notification code after formatting the text, but before displaying it, so that the application can resize the edit control window. |
| EN_VSCROLL | The user has clicked the edit control's vertical scroll bar or has scrolled the mouse wheel over the edit control. The system sends this notification code before updating the screen. |
| EN_SEARCHWEB | The user has clicked the 'Search the web' context menu entry. The system sends this notification after it launched the browser. |
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.
| Message | Default action |
|---|---|
| EM_CANUNDO | Returns TRUE if the edit control operation can be undone. |
| EM_CHARFROMPOS | Returns the character index and line index of the character nearest the specified point. |
| EM_EMPTYUNDOBUFFER | Empties the undo buffer and sets the undo flag retrieved by the EM_CANUNDO message to FALSE. The system automatically clears the undo flag whenever the edit control receives a WM_SETTEXT or EM_SETHANDLE message. |
| EM_FMTLINES | Adds or removes soft line-break characters (two carriage returns and a line feed) to the ends of wrapped lines in a multiline edit control. It is not processed by single-line edit controls. |
| EM_GETFIRSTVISIBLELINE | Returns the zero-based index of the first visible character in a single-line edit control or the zero-based index of the uppermost visible line in a multiline edit control. |
| EM_GETHANDLE | Returns a handle identifying the buffer containing the multiline edit control's text. It is not processed by single-line edit controls. |
| EM_GETLIMITTEXT | Returns the current text limit, in characters. |
| EM_GETLINE | Copies characters in a single-line edit control to a buffer and returns the number of characters copied. In a multiline edit control, retrieves a line of text from the control and returns the number of characters copied. |
| EM_GETLINECOUNT | Returns the number of lines in the edit control. |
| EM_GETMARGINS | Returns the widths of the left and right margins. |
| EM_GETMODIFY | Returns a flag indicating whether the content of an edit control has been modified. |
| EM_GETPASSWORDCHAR | Returns the character that edit controls use in conjunction with the ES_PASSWORD style. |
| EM_GETRECT | Returns the coordinates of the formatting rectangle in an edit control. |
| EM_GETSEL | Returns the starting and ending character positions of the current selection in the edit control. |
| EM_GETTHUMB | Returns the position of the scroll box in the vertical scroll bar in a multiline edit control. |
| EM_GETWORDBREAKPROC | Returns the address of the current Wordwrap function in an edit control. |
| EM_LINEFROMCHAR | Returns the zero-based number of the line in a multiline edit control that contains a specified character index. This message is the reverse of the EM_LINEINDEX message. It is not processed by single-line edit controls. |
| EM_LINEINDEX | Returns the character of a line in a multiline edit control. This message is the reverse of the EM_LINEFROMCHAR message. It is not processed by single-line edit controls. |
| EM_LINELENGTH | Returns the length, in characters, of a single-line edit control. In a multiline edit control, returns the length, in characters, of a specified line. |
| EM_LINESCROLL | Scrolls the text vertically in a single-line edit control or horizontally in a multiline edit control (when the control has the ES_LEFT style). The lParam parameter specifies the number of lines to scroll vertically, starting from the current line. The wParam parameter specifies the number of characters to scroll horizontally, starting from the current character. |
| EM_POSFROMCHAR | Returns the client coordinates of the specified character. |
| EM_REPLACESEL | Replaces the current selection with the text in an application-supplied buffer, sends the parent window EN_UPDATE and EN_CHANGE notification codes, and updates the undo buffer. |
| EM_SCROLL | Scrolls the text vertically in a multiline edit control. This message is equivalent to sending a WM_VSCROLL message to the edit control. It is not processed by single-line edit controls. |
| EM_SCROLLCARET | Scrolls the caret into view in an edit control. |
| EM_SETFONT | Unsupported. |
| EM_SETHANDLE | Sets a handle to the memory used as a text buffer, empties the undo buffer, resets the scroll positions to zero, and redraws the window. |
| EM_SETLIMITTEXT | Sets the maximum number of characters the user may enter in the edit control. For single-line edit controls, this value is either 0x7FFFFFFE or the value of the wParam parameter, whichever is smaller. For multiline edit controls, this value is either 1 or the value of the wParam parameter, whichever is smaller. |
| EM_SETMARGINS | Sets the widths of the left and right margins, and redraws the edit control to reflect the new margins. |
| EM_SETMODIFY | Sets or clears the modification flag to indicate whether the edit control has been modified. |
| EM_SETPASSWORDCHAR | Defines the character that edit controls use in conjunction with the ES_PASSWORD style. |
| EM_SETREADONLY | Sets or removes the read-only style (ES_READONLY) in an edit control. |
| EM_SETRECT | Sets the formatting rectangle for the multiline edit control and redraws the window. It is not processed by single-line edit controls. |
| EM_SETRECTNP | Sets the formatting rectangle for the multiline edit control but does not redraw the window. It is not processed by single-line edit controls. |
| EM_SETSEL | Selects a range of characters in the edit control by setting the starting and ending positions to be selected. |
| EM_SETTABSTOPS | Sets tab-stop positions in the multiline edit control. It is not processed by single-line edit controls. |
| EM_SETWORDBREAKPROC | Replaces the default Wordwrap function with an application-defined Wordwrap function. |
| EM_UNDO | Removes any text that was just inserted or inserts any deleted characters and sets the selection to the inserted text. If necessary, sends the EN_UPDATE and EN_CHANGE notification codes to the parent window. |
| WM_CHAR | Writes a character to the single-line edit control and sends the EN_UPDATE and EN_CHANGE notification codes to the parent window. Writes a character to the multiline edit control. Handles the accelerator keys for standard functions, such as CTRL+C for copying and CTRL+V for pasting. In multiline edit controls, also processes TAB, and CTRL+TAB keystrokes to move among the controls in a dialog box and to insert tabs into multiline edit controls. Uses the MessageBeep function for illegal characters. |
| WM_CLEAR | Clears the current selection, if any, in an edit control. If there is no current selection, deletes the character to the right of the caret. If the user presses the SHIFT key, this cuts the selection to the clipboard, or deletes the character to the left of the caret when there is no selection. If the user presses the CTRL key, this deletes the selection, or deletes to the end of the line when there is no selection. |
| WM_COPY | Copies text to the clipboard unless the style is ES_PASSWORD, in which case the message returns zero. |
| WM_CREATE | Creates the edit control and notifies the parent window with TRUE for success or 1 for failure. |
| WM_CUT | Cuts the selection to the clipboard, or deletes the character to the left of the cursor if there is no selection. |
| WM_ENABLE | Causes the rectangle to be redrawn in gray for single-line edit controls. Returns the enabled state for single-line and multiline edit controls. |
| WM_ERASEBKGND | Fills the multiline edit control window with the current color of the edit control. |
| WM_GETDLGCODE | Returns the following values: DLGC_WANTCHARS, DLGC_HASSETSEL, and DLGC_WANTARROWS. In multiline edit controls, it also returns DLGC_WANTALLKEYS. If the user presses ALT+BACKSPACE, it also returns DLGC_WANTMESSAGE. |
| WM_GETFONT | Returns the handle of the font being used by the control, or NULL if the control uses the system font. |
| WM_GETTEXT | Copies the specified number of characters to a buffer and returns the number of characters copied. |
| WM_GETTEXTLENGTH | Returns the length, in characters, of the text in an edit control. The length does not include the null- terminating character. |
| WM_HSCROLL | Scrolls the text in a multiline edit control horizontally and handles scroll box movement. |
| WM_KEYDOWN | Performs standard processing of the virtual-key codes. |
| WM_KILLFOCUS | Removes the keyboard focus of an edit control window, destroys the caret, hides the current selection, and notifies the parent window that the edit control has lost the focus. |
| WM_LBUTTONDBLCLK | Clears the current selection and selects the word under the cursor. If the SHIFT key is depressed, extends the selection to the word under the cursor. |
| WM_LBUTTONDOWN | Changes the current insertion point. If the SHIFT key is depressed, extends the selection to the position of the cursor. In multiline edit controls, also sets the timer to automatically scroll when the user holds down the mouse button outside the multiline edit control window. |
| WM_LBUTTONUP | Releases the mouse capture and sets the text insertion point in the single-line edit control. In a multiline edit control, also terminates the timer set in the WM_LBUTTONDOWN message. |
| WM_MOUSEMOVE | Changes the current selection in the single-line edit control, if the mouse button is down. In a multiline edit controls, also sets the timer to automatically scroll if the user holds down the mouse button outside the multiline edit control window. |
| WM_NCCREATE | Pointer to the CREATESTRUCT structure for the window. This message is sent to the WM_CREATE message when a window is first created. |
| WM_NCDESTROY | Frees all memory associated with the edit control window, including the text buffer, undo buffer, tab-stop buffer, and highlight brush. |
| WM_PAINT | Erases the background, fills the window with the current color of the edit control window, draws the border (if any), sets the font and draws any text, and shows the text-insertion caret. |
| WM_PASTE | Pastes text from the clipboard into the edit control window at the caret position. |
| WM_SETFOCUS | Sets the keyboard focus of an edit control window (shows the current selection, if it was hidden, and creates the caret). |
| WM_SETFONT | Sets the font and optionally redraws the edit control. |
| WM_SETTEXT | Copies text to the single-line edit control, notifies the parent window when there is insufficient memory, empties the undo buffer, and sends the EN_UPDATE and EN_CHANGE notification codes to the parent window. In multiline edit controls, also rewraps the lines (if necessary) and sets the scroll positions. |
| WM_SIZE | Sets the size of the edit control window, ensuring that the size accommodates the height and width of a character. |
| WM_SYSCHAR | Returns TRUE if the user presses ALT+BACKSPACE; otherwise takes no action. |
| WM_SYSKEYDOWN | Undoes the last action if the user presses ALT+BACKSPACE; otherwise takes no action. |
| WM_TIMER | Scrolls the text in the edit control window if the user holds down the mouse button outside the multiline edit control window. |
| WM_UNDO | Removes any text that was just inserted or inserts any deleted characters and sets the selection to the inserted text. If necessary, sends the EN_UPDATE and EN_CHANGE notification codes to the parent window. |
| WM_VSCROLL | Scrolls a multiline edit control vertically and handles scroll box movement. It is not processed by single-line edit controls. |
The predefined edit control window procedure passes all other messages to the DefWindowProc function for default processing.