Edytuj

Udostępnij za pośrednictwem

Edit Control Text Operations

  • Artykuł

The system automatically processes all user-initiated text operations and notifies the application when the operations are completed.

The following topics discuss user-initiated text operations and the application's response:

Selecting an Edit Control

The user can select an edit control by clicking it with the mouse or by pressing the TAB key to move to it. The tabbing method is part of a predefined keyboard interface that the system provides. For a complete description of this interface, see Dialog Boxes. When the user selects an edit control, the system gives the control the keyboard focus (see "Keyboard Focus and Activation" in About Keyboard Input) and highlights its text by using reverse video.

Setting and Retrieving Text

An application can set the text of an edit control by using the SetWindowText function, the SetDlgItemText function, or by sending the control a WM_SETTEXT message.

To retrieve all text from an edit control, first use the GetWindowTextLength function or the WM_GETTEXTLENGTH message to determine the size of buffer needed to contain the text. Next, retrieve the text by using the GetWindowText function, the GetDlgItemText function, or the WM_GETTEXT message.

Selecting Text

After selecting an edit control, the user can select text in the control by using the mouse or the keyboard. An application can retrieve the starting and ending character positions of the current selection in an edit control by sending the control an EM_GETSEL message. The return value for the ending position is one greater than the last character in the selection (that is, the position of the first character following the last selected character).

An application can also select text in an edit control by sending the control an EM_SETSEL message with the starting and ending character indexes for the selection. For example, the application can use EM_SETSEL with EM_REPLACESEL to delete text from an edit control.

These three messages apply to both single-line and multiline edit controls.

Replacing Text

An application can replace selected text in an edit control by sending the control an EM_REPLACESEL message with a pointer to the replacement text. If there is no current selection, EM_REPLACESEL inserts the replacement text at the insertion point. The application may receive an EN_ERRSPACE notification code if the replacement text exceeds the available memory. This message applies to both single-line and multiline edit controls.

An application can use EM_REPLACESEL to replace part of an edit control's text or the SetDlgItemText function to replace all of it.

Changing the Font Used by an Edit Control

An application can change the font that an edit control uses by sending the WM_SETFONT message. Most applications do this while processing the WM_INITDIALOG message. Changing the font does not change the size of the edit control; applications that send the WM_SETFONT message may have to retrieve the font metrics for the text and recalculate the size of the edit control. For more information about fonts and font metrics, see Fonts and Text.

Cut Copy Paste and Clear Operations

There are four messages for moving text between an edit control and the clipboard. The WM_COPY message copies the current selection (if any) from an edit control to the clipboard without deleting it from the edit control. The WM_CUT message deletes the current selection (if any) in the edit control and copies the deleted text to the clipboard. The WM_CLEAR message deletes the current selection (if any) from an edit control, but does not copy it to the clipboard (unless the user pressed the SHIFT key). The WM_PASTE message copies text from the clipboard into an edit control at the insertion point. These four messages apply to both single-line and multiline edit controls.

Microsoft Windows NT 4.0 and later: An edit control includes a built-in context menu that makes it easy for the user to move text between the edit control and the clipboard. The context menu appears when the user right-clicks the control. The commands in the context menu include Undo, Cut, Copy, Paste, Delete, and Select All.

Modifying Text

The user can select, delete, or move text in an edit control. The system maintains an internal flag for each edit control indicating whether the content of the control has been modified. The system clears this flag when it creates the control and sets the flag whenever the text in the control is modified. An application can retrieve the modification flag by sending the control an EM_GETMODIFY message. The application can then set or clear the modification flag by sending the control an EM_SETMODIFY message. These messages apply to both single-line and multiline edit controls.

Limiting User Entered Text

The default limit to the amount of text a user can enter in an edit control is 32 KB. An application can change the default limit by sending the control an EM_SETLIMITTEXT message. This message sets a hard limit to the number of bytes the user can enter into an edit control, but affects neither text that is already in the control when the message was sent nor text copied to the control by the SetDlgItemText function or the WM_SETTEXT message. For example, suppose that the application uses the SetDlgItemText function to place 500 bytes in an edit control, and the user also enters 500 bytes (1,000 bytes total). If the application then sends an EM_SETLIMITTEXT message limiting user-entered text to 300 bytes, the 1,000 bytes already in the edit control remain there, and the user cannot add any more text. On the other hand, if the application sends an EM_SETLIMITTEXT message limiting user-entered text to 1,300 bytes, the 1,000 bytes remain, but the user can add 300 more bytes.

When the user reaches the character limit of an edit control, the system sends the application a WM_COMMAND message containing an EN_MAXTEXT notification code. This notification code does not mean that memory has been exhausted, but that the limit for user-entered text has been reached; the user cannot enter any more text. To change this limit, an application must send the control a new EM_SETLIMITTEXT message with a higher limit.

As an example of the use of EM_SETLIMITTEXT and EN_MAXTEXT, suppose that the application must limit the user to no more than four characters in an edit control. The application would use EM_SETLIMITTEXT to specify a four-character limit. If the user tried to enter a fifth character, the system would send an EN_MAXTEXT notification code to the application.

Character and Line Operations

There are several messages that return information about the characters and lines in an edit control. Most of the messages return an index, usually a zero-based number, to refer to a character or line. For example, in a single-line edit control that contains n characters, the line index is zero and the characters are indexed from zero to n-1. In a multiline edit control that contains m lines and n characters, the lines are indexed from zero to m-1, and the characters are indexed from zero to n-1. Note that character indexing ignores line breaks.

An application can determine the number of characters in an edit control by sending the WM_GETTEXTLENGTH message to the edit control. This message returns the length, in characters (not including the terminating null character), of the text in a single-line or multiline edit control. The EM_LINELENGTH message returns the length, in characters, of a line specified by the character index of a character in the line. The returned length does not include any selected characters. An application can use these messages in a single-line or multiline edit control.

The EM_GETFIRSTVISIBLELINE message returns the zero-based index of the uppermost visible line in a multiline edit control, or the zero-based index of the first visible character in a single-line edit control. An application can copy a line from an edit control to a buffer by sending the EM_GETLINE message to the edit control. The line is specified by its line index and the first word of the receiving buffer contains the maximum number of bytes to be copied to the buffer. The return value is the number of bytes copied. This message can also be used in a single-line or multiline edit control.

There are unique messages available to return the information about a line in a multiline edit control. The EM_GETLINECOUNT message returns the number of lines in an edit control. The EM_LINEFROMCHAR message returns the index of the line containing a specified character index. The EM_LINEINDEX message returns the index of the first character in a specified line.

Scrolling Text in an Edit Control

To implement scrolling in an edit control, you can use the automatic scrolling styles discussed in Edit Control Types and Styles, or you can explicitly add scroll bars to the edit control. To add a horizontal scroll bar, use the style WS_HSCROLL; to add a vertical scroll bar, use the style WS_VSCROLL. An edit control with scroll bars processes its own scroll bar messages. For detailed information about adding scroll bars to edit controls, see Scroll Bars.

The system provides three messages that an application can send to an edit control with scroll bars. The EM_LINESCROLL message can scroll a multiline edit control both vertically and horizontally. The lParam parameter specifies the number of lines to scroll vertically starting from the current line and the wParam parameter specifies the number of characters to scroll horizontally, starting from the current character. The edit control does not acknowledge horizontal scrolling messages if it has the ES_CENTER or ES_RIGHT style. The EM_LINESCROLL message applies to multiline edit controls only.

The EM_SCROLL message scrolls a multiline edit control vertically. The wParam parameter specifies the scrolling action. The EM_SCROLL message applies to multiline edit controls only. EM_SCROLL has the same effect as the WM_VSCROLL message.

The EM_SCROLLCARET message scrolls the caret into view in an edit control.

Setting Tab Stops and Margins

An application can set tab stops in a multiline edit control by using the EM_SETTABSTOPS message. (The default for a tab stop is eight characters.) When an application adds text to the edit control, tab characters in the text automatically generate space up to the next tab stop. The EM_SETTABSTOPS message does not automatically cause the system to redraw the text. To do that, an application can call the InvalidateRect function. The EM_SETTABSTOPS message applies to multiline edit controls only.

An application can set the width of the left and right margins for an edit control by using the EM_SETMARGINS message. After sending this message, the system redraws the edit control to reflect the new margin settings. An application can retrieve the width of the left or right margin by sending the EM_GETMARGINS message. By default, the edit control margins are set just wide enough to accommodate the largest character horizontal overhang (negative ABC widths) for the current font being used in the edit control.

Concealing User Input

An application can use a password character in an edit control to conceal user input. When a password character is set, it is displayed in place of each character the user types. When a password character is removed, the control displays the characters the user types. If the application creates a single-line edit control using the style ES_PASSWORD, the default password character is an asterisk (*). An application can use the EM_SETPASSWORDCHAR message to remove or define a different password character and the EM_GETPASSWORDCHAR message to retrieve the current password character. These messages apply to single-line edit controls only.

Using Integers

There are two integer-conversion functions for edit controls designed to contain numbers only. The SetDlgItemInt function creates the string representation of a specified integer (signed or unsigned) and sends the string to an edit control. SetDlgItemInt returns no value. The GetDlgItemInt function creates an integer (signed or unsigned) from its string representation in an edit control. GetDlgItemInt returns the integer (or an error value).

Undoing Text Operations

Every edit control maintains an undo flag that indicates whether an application can reverse or undo the most recent operation on the edit control (undoing a text deletion, for example). The edit control sets the undo flag to indicate that the operation can be undone and resets it to indicate that the operation cannot be undone. An application can determine the setting of the undo flag by sending the control an EM_CANUNDO message.

An application can undo the most recent operation by sending the control an EM_UNDO message. An operation can be undone provided no other edit control operation occurs first. For example, the user can delete text, replace the text (undo the deletion), and then delete the text again (undo the replacement). The EM_UNDO message applies to both single-line and multiline edit controls and always works for single-line edit controls.

An application can reset an edit control's undo flag by sending the control an EM_EMPTYUNDOBUFFER message. The system automatically resets the undo flag whenever an edit control receives an EM_SETHANDLE or WM_SETTEXT message. The SetDlgItemText function sends a WM_SETTEXT message.

Handling Wordwrap and Line Breaks

An application can use Wordwrap functions with multiline edit controls to locate the word or word fragment that should be wrapped to the next line. Using the default Wordwrap function provided by the system, lines always end at the spaces between words. An application can specify its own Wordwrap function by supplying an EditWordBreakProc Wordwrap function and sending the edit control an EM_SETWORDBREAKPROC message. An application can retrieve the address of the current Wordwrap function by sending the control an EM_GETWORDBREAKPROC message.

An application may direct a multiline edit control to add or remove a soft line break character (two carriage returns and a line feed) automatically at the end of wrapped-text lines. An application can turn this feature on or off by sending the edit control an EM_FMTLINES message. This message applies only to multiline edit controls and does not affect a line that ends with a hard line break (one carriage return and a line feed entered by the user). Also in multiline edit controls, an application can specify the ES_WANTRETURN style to request that the system insert a carriage return when the user presses the ENTER key in the edit control.

Retrieving Points and Characters

To determine the character closest to a specified point in the client area of an edit control, send the EM_CHARFROMPOS message to the control. The message returns the character index and line index of the character nearest the point. Similarly, you can retrieve the client area coordinates of a specified character by sending the EM_POSFROMCHAR message. The message returns the x and y coordinates of the upper-left corner of the specified character.

Autocompletion of Strings

Autocompletion expands strings that have been partially entered in an edit control into complete strings. For example, when a user starts to enter a URL in the Address edit control that is embedded in the Windows Internet Explorer toolbar, autocompletion expands the string into one or more complete URLs that are consistent with the existing partial string. A partial URL string such as "mic" might be expanded to "https://www.microsoft.com" or "https://www.microsoft.com/windows". Autocompletion is typically used with edit controls or with controls that have an embedded edit control.

For more information, see the IAutoComplete and IAutoComplete2 interface documentation.

Complex Script in Edit Controls

A complex script is a language whose printed form is not laid out in a simple way. For example, a complex script may allow bidirectional rendering, contextual shaping of glyphs, or combining characters. The standard edit controls have been extended to support multilingual text and complex scripts. This includes not only input and display, but also correct cursor movement over character clusters (in Thai and Devanagari script, for example).

A well-written application receives this support automatically, without modification. Again, you should consider adding support for right-to-left reading order and right alignment. In this case, toggle the extended style flags of the edit control window to control these attributes, as shown in the following example.

// ID_EDITCONTROL is the control ID in the resource file.
HANDLE hWndEdit = GetDlgItem(hDlg, ID_EDITCONTROL);
LONG lAlign = GetWindowLong(hWndEdit, GWL_EXSTYLE) ;

// To toggle alignment
lAlign ^= WS_EX_RIGHT ;

// To toggle reading order
lAlign ^= WS_EX_RTLREADING ;

After setting the lAlign value, enable the new display by setting the extended style of the edit control window as follows.

// This assumes your edit control is in a dialog box. If not, 
// get the edit control handle from another source.

SetWindowLong(hWndEdit, GWL_EXSTYLE, lAlign);
InvalidateRect(hWndEdit, NULL, FALSE);

Uniscribe is another set of functions that provide fine control for processing complex scripts. For more information, see Uniscribe.