This method sets the "cue" text for an edit control. Cue text provides a visual hint to the user as to the purpose of the edit control. When the dialog is first shown to the user the cue text will be displayed, (provided there is no text in the edit control's buffer.)
The cue text is colored a light grey to distinguish it from regular text. When the edit control gains the focus, Windows dismisses the cue text automatically. When the control loses focus, Windows will again display the cue text, if the entry control is empty. Once the user has entered text in the edit control, the cue is no longer displayed. If the user deletes the text, then the cue is once again displayed when the edit control does not have the focus.
Note: Only single-line edit controls will display cue text. You can not use cue text with a multi-line edit control.
This method is only available on Windows XP or later operating systems. If the method is used on an unsupported operating system, -4 is returned.
The only argument is:
The text to be displayed to the user as a cue. The maximum length of the text string is 255 characters.
The return value will be one of the following:
The value is the negated Operating System Error code. The absolute value of the return can be used to look up the error reason in the Windows documentation.
The operating system does not support this method. Windows XP or later is required.
The text argument is too long for this method, or there is an (internal) problem converting the text string to Unicode.
There is an (internal) problem with the dialog or the dialog handle.
There is an (internal) problem with the resource ID or window handle of the edit control.
The method succeeded.
The method failed.
For an example see the ShowBalloon example.