Using Tooltips on controls

Author	Rui Cruz (and for a part Aart Onkenhout)
Date	10-05-2001

A frequently asked question is: how to show tooltips with PowerBuilder. With this tip comes a user-object (n_tooltip) to achieve this using the tooltip-control that's available via comctl32.dll. The fundamentals of this control are developed by Rui Cruz. A couple of functions I added to it myself. These ones are described in the remainder of this tip.

First Example

Creating a tooltip

You create a Tooltip-Window by just adding it as an instance variable to your, e.g., window. After this you have to register controls you want to be able to use the Tooltip-Window. You can do this by calling:

inv_Tooltip.of_AddTool( DragObject ado_Object, String as_TipText, Integer ai_Flags )

Tooltips with multiple lines (requires version 4.70 or later of comctl32.dll)

If you have a very long text for your tooltip you would like to split it in more than one line. You can do this by sending a TTM_SETMAXTIPWIDTH message. This tells your tooltip-window to split the tooltiptext in more than one line when the length of the text exceeds the width set by this message.

Call of_SetMaxWidth( Long al_MaxWidth ) to accomplish this.

Balloon tooltips (5.80 or later)

By changing the code in the Constructor-event of n_tooltip you can create Tooltips with rounded corners and a stem pointing to the item.

hWndTT = CreateWindowExA( WS_EX_TOPMOST,TOOLTIPS_CLASS,0, TTF_CENTERTIP + TTS_BALLOON + 1, &
CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, &
0, 0, Handle( GetApplication() ), 0 )

Tooltips with another background- or textcolor (4.70 or later)

The functions of_SetTipBkColor and of_SetTipTextColor make it possible to change the backgroundcolor and the textcolor respectively. Just call them with the desired color.

Tooltips with title and an icon (5.80 or later)

By calling of_SetTitle( Integer ai_icon, String as_Title ) you can add a title and, if you wish, an icon. You can use 4 values for ai_Icon:

TTI_NONE ( 0 ), TTI_INFO ( 1 ), TTI_WARNING ( 2 ) or TTI_ERROR ( 3 ).

Your call can look like:

inv_Tooltip.of_SetTitle( inv_Tooltip.TTI_WARNING, "Warning" )

Second example

Tooltips and DataWindows

You can use the tooltip-control with a DataWindow (see the example in the zip-file). However, when the focus is on an editable field the tooltip won't appear because the mousemove-event isn't fired.

Update 29-06-2001

of_RemoveTool

An idea coming from Jim Egan (TeamSybase): add an of_RemoveTool function. To give the user the opportunity to switch tooltips on and off, a new function was added. To switch the tooltip of for a certain control, call of_RemoveTool. Arguments are the control itself and the identity returned by of_AddTool. So, if you want to remove tooltips, you have to remember the identities returned.

Mousemove-event

You don't have to add a mousemove event to every control you add a tooltip for, i.e. when two conditions are met:

	The tool is a control or is defined as a rectangle in the tool's ToolInfo structure.
	The window associated with the tool is in the same thread as the ToolTip control.

If these two conditions are met, messages are relayed automatically to the tooltip control when you set the uFlags field of the ToolInfo structure to TTF_SUBCLASS ( = 16 ).

In other cases, you have to call of_RelayMsg to make mouse-messages be sent to the tooltip control.

Update 25-02-2005

Added coding to show tooltips on a tabular datawindow for every row and column (as I read very often on the PowerBuilder forums).

07-06-2005: Thierry Decamps discovered you have to call of_addtool again after resizing a datawindow otherwise the tooltips won't show up again (i.e. not for all columns). You can add coding for this within the resize event. First call of_RemoveTool then call of_AddTool.

Another addition is the possibility to change delaytimes. There are three delaytimes:

TTDT_AUTOPOP: Retrieve the amount of time the ToolTip window remains visible if the pointer is stationary within a tool's bounding rectangle.
TTDT_INITIAL: Retrieve the amount of time the pointer must remain stationary within a tool's bounding rectangle before the ToolTip window appears.
TTDT_RESHOW: Retrieve the amount of time it takes for subsequent ToolTip windows to appear as the pointer moves from one tool to another.

Use the function of_SetDelayTime( Integer ai_Duration, Integer ai_Milliseconds ) to set each of these times.