BBC BASIC Programmers' Reference

Setting an edit box cue banner

by Richard Russell, March 2009

Windows Vista and later have the capability of displaying a cue banner in an edit control; this is a line of 'greyed out' text which can be used to prompt the user for the information he is expected to enter in that box. For example if the edit control receives a search string, the cue banner may read “Enter search text here”. When the user clicks in the box, the text goes away and he can type his entry as usual.

This facility is easily accessed using one or other of the procedures listed below. The first is for an edit control within a dialogue box, and the second is for a stand-alone edit control:

        DEF PROCdlgsetcuebanner(hdlg%, id%, cue$)
        LOCAL wc% : DIM wc% LOCAL 2*LEN(cue$)+2 : wc% = wc% + 1 AND -2
        EM_SETCUEBANNER = &1501
        SYS "MultiByteToWideChar", 0, 0, cue$, -1, wc%, LEN(cue$)
        SYS "SendDlgItemMessage", hdlg%, id%, EM_SETCUEBANNER, 0, wc%
        ENDPROC
 
        DEF PROCsetcuebanner(hedit%, cue$)
        LOCAL wc% : DIM wc% LOCAL 2*LEN(cue$)+2 : wc% = wc% + 1 AND -2
        EM_SETCUEBANNER = &1501
        SYS "MultiByteToWideChar", 0, 0, cue$, -1, wc%, LEN(cue$)
        SYS "SendMessage", hedit%, EM_SETCUEBANNER, 0, wc%
        ENDPROC

Simply call the appropriate procedure once your edit control has been created. For example to provide this facility in the DLGDEMO example program add the following code after the call to PROC_showdialog(), but note that other changes are also necessary (see below):

        PROCdlgsetcuebanner(!dlg%, 101, "Type text here")

There are a number of conditions which must be met for a cue banner to be used:

Since the cue disappears once the edit control has the input focus, the control must not be the one which initially receives focus (usually the first listed in the dialogue template). In the case of DLGDEMO that means moving the PROC_editbox to later in the list.
The edit control must not contain any initial text, so in the case of DLGDEMO the initial text Text box must be deleted.
'Windows XP visual styles' must be enabled, so when compiling your program ensure that option is selected. For the same reason, the facility won't work if you execute your program using BBCWRUN (e.g. by double-clicking on the .BBC file) unless a suitable manifest is present.
You cannot set a cue banner on a multiline edit control or a Rich Edit control.