BBC BASIC Programmers' Reference

by Richard Russell, May 2009

Tooltips (helpful information displayed in a small box when you 'hover' the mouse over a certain region) are usually associated with toolbars, status bars, dialogue boxes or other Windows controls, and information on such uses can be found at the linked pages. However it is also possible to display tooltips on your main output window.

To do this you first need to perform some declarations and initialisation:

        INSTALL @lib$+"WINLIB5"
 
        WS_POPUP = &80000000
        HWND_TOPMOST = -1
        SWP_NOACTIVATE = &10
        SWP_NOMOVE = &2
        SWP_NOSIZE = &1
        WM_USER = &400
        TTF_SUBCLASS = &10
        TTM_ACTIVATE = WM_USER + 1
        TTM_SETDELAYTIME = WM_USER + 3
        TTM_ADDTOOL = WM_USER + 4
        TTM_NEWTOOLRECT = WM_USER + 6
        TTM_UPDATETIPTEXT = WM_USER + 12
        TTS_ALWAYSTIP = &1
        TTS_NOPREFIX = &2
        TTDT_INITIAL = 3
 
        DIM rc{l%,t%,r%,b%}
        DIM ti{cbSize%, uFlags%, hwnd%, uId%, rect{}=rc{}, hinst%, lpszText%}
 
        hwndTT% = FN_createwindow("tooltips_class32", "", &80000000, &80000000, \
        \         &80000000, &80000000, 0, WS_POPUP OR TTS_NOPREFIX OR TTS_ALWAYSTIP, 0)
        SYS "SetWindowPos", hwndTT%, HWND_TOPMOST, 0, 0, 0, 0, \
        \                   SWP_NOMOVE OR SWP_NOSIZE OR SWP_NOACTIVATE

Each tool is associated with a rectangular region of the window; when the user hovers the mouse over that region the tooltip will be displayed:

        tip$ = "This is a demo tooltip"+CHR$0
        ti.cbSize% = DIM(ti{})
        ti.uFlags% = TTF_SUBCLASS
        ti.hwnd% = @hwnd%
        ti.rect.l% = left%
        ti.rect.r% = right%
        ti.rect.t% = top%
        ti.rect.b% = bottom%
        ti.lpszText% = !^tip$
        SYS "SendMessage", hwndTT%, TTM_ADDTOOL, 0, ti{}

Here left%, right%, top% and bottom% define the rectangle associated with the tooltip; the coordinates are pixels with respect to the top left-hand corner of the window (client area).

If you have more than one region in which you wish a tooltip to be displayed, you can either create multiple tools by duplicating the above code (with a different rectangle and string) or you can dynamically modify the rectangle and string, as follows:

        newtip$ = "This is a new tooltip" + CHR$0
        ti.lpszText% = !^newtip$
        ti.rect.l% = newl%
        ti.rect.r% = newr%
        ti.rect.t% = newt%
        ti.rect.b% = newb%
        SYS "SendMessage", hwndTT%, TTM_UPDATETIPTEXT, 0, ti{}
        SYS "SendMessage", hwndTT%, TTM_NEWTOOLRECT, 0, ti{}

You will need to update the rectangle and tip text when the mouse enters the region of interest. This approach is more appropriate when there are a large number of different tooltip rectangles.

On exit from your program the tooltip window should be closed:

        hwndTT% += 0 : IF hwndTT% PROC_closewindow(hwndTT%) : hwndTT% = 0

This code can most usefully be placed in a 'cleanup' routine called whenever your program terminates, including from the ON CLOSE and ON ERROR handlers.

If your program also calls routines in the WINLIB, WINLIB3, WINLIB5 or MDILIB libraries (in particular, routines which involve subclassing the main output window), you must ensure that the following versions (or later) of those libraries are used: