Applies to: desktop apps only
Sets the title or text of a control in a dialog box.
Syntax
BOOL WINAPI SetDlgItemText( __in HWND hDlg, __in int nIDDlgItem, __in LPCTSTR lpString );
Parameters
- hDlg [in]
-
Type: HWND
A handle to the dialog box that contains the control.
- nIDDlgItem [in]
-
Type: int
The control with a title or text to be set.
- lpString [in]
-
Type: LPCTSTR
The text to be copied to the control.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The SetDlgItemText function sends a WM_SETTEXT message to the specified control.
Examples
For an example, see Using List Boxes.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | SetDlgItemTextW (Unicode) and SetDlgItemTextA (ANSI) |
See also
- Reference
- GetDlgItemInt
- GetDlgItemText
- SetDlgItemInt
- WM_SETTEXT
- Conceptual
- Dialog Boxes
Send comments about this topic to Microsoft
Build date: 2/10/2012
For an edit control that updates while it is focused, typically by a timer or an up/down (spin) control, this behaviour is annoying. Even for read-only edit boxes, because users cannot copy its text to the clipboard. Therefore, the selection should be saved and restored around the SetDlgItemText() call. See EM_GETSEL, EM_SETSEL.
Precautions are required when string length is changing:
- For an integer number display, the selection should be constant counted from end of string.
- For a float-point number display, the selection should be constant counted from decimal point.
- In other cases, it depends on where the string is changing (before, within, or after the selection), so you should keep the start and end of selection between the same characters of string.
Remaining problem: Users can expand selections to left or to right. Doing this selection save/restore procedure, the caret (expansion mark) jumps to the right end of selection, so a user can only expand to (or shrink from) right side in this case. There is IMHO no known procedure to get or set the side of expansion mark.
SetWindowText(GetDlgItem(hDlg,nIDDlgItem),lpString);
For edit controls, this function sends EN_CHANGE and EN_UPDATE, regardless whether text is changing or not, so measures must be taken when you handle these notifications to update other edit controls in a circular fashion, i.e. distinct this from true user input. (Following applies to real-world-scenario single-GUI-thread applications.)
A good solution for coping with this problem is using one timer for every edit control (using the same ID is a good idea). On EN_CHANGE, simply call SetTimer(hDlg, LOWORD(wParam), delay_you_want, NULL). On WM_TIMER, don't forget KillTimer(hDlg, wParam) to make it non-periodic, and handle user input on ID base. Furthermore, after every SetDlgItemText(hDlg, id, str), call KillTimer(hDlg, id) to make this change non-signaling, in contrast to true user input when no KillTimer() is in effect.
Another solution is setting a global-alike BOOL variable (e.g. called IgnoreEnChange) before SetDlgItemText(), and clearing afterwards. Notifications arrive in recursive fashion while SetDlgItemText() is in progress.
To reduce flicker, call this function only when text is really changing. The function GetDlgItemText() doesn't flicker, so it's a good idea to compare the new with the old string for controls that update frequently.
This function can set the text for the following dialog elements:- Buttons (push-buttons, checkmarks, radio checks, group boxes - One ampersand (&) indicate underlined hotkey)
- Statics (the text should fit into the rectangle defined in your Resource Editor - One ampersand (&) indicate underlined hotkey if not turned off)
- Edit controls (both single-line and multi-line)
- Combo Boxes that have an editable input line
- Self-made controls that handle WM_SETTEXT meaningful