Tooltips v0606

From EuWiki

Tooltips are small borderless windows that appear when the mouse hovers over (some part of) a control. The library provides basic management tools. Some extended functionality is available depending on the OS version. If looking at some API documentation, you must be aware that Windows call "tooltip control" the tooltip manager, not the individual tooltip. And yet, tooltips are controls: they are windows, which have a handle. Only when a very fine degree of control is needed should one interfere directly with a tooltip window.

Some demo program show how to define and set tooltips, like display.exw,EX03.EXW.

Contents 1 Setting a tooltip 2 Setting Tooltip characteristics 3 The Tooltip manager control 4 Getting information

Setting a tooltip

Use setHint(control_id,text) to set the tooltip text for a control. text is either a string or a routine id. In the latter case, the routine will be called whenever the toomtip need displaying, with the following arguùents:

1. The id of the control for which a tip text is required;
2. The expected width used to display the tip.

The callback function should return either a string or a pair {string,new_width}. See the tooltip_dynamic.exw demo program for an instance of using this facility.

When creating a control, the caption may be passed as a pair; the second element of the pair is a tooltip text or callback id. See for instance the TooTip.exw demo program. For toolbar or rebar band buttons, which usually show no text, the supplied caption is used as a tooltip.

Setting a tooltip text to "" causes the tooltip window not to display.

You may use setHintEx(control_id,text,flags) to add some tweaks. When flags is 0, this call is equivalent to setHint(). Available flags are (check for OS support; unsupported flags are ignores:

TTF_ABSOLUTE

Version 4.70 and later. Positions the ToolTip window at the same coordinates provided by TTM_TRACKPOSITION. This flag must be used with the TTF_TRACK flag.

TTF_CENTERTIP

Centers the ToolTip window below the tool for which the toomitip displays.

TTF_IDISHWND

Indicates that the uId member is the window handle to the tool. If this flag is not set, uId is the tool's identifier.

TTF_PARSELINKS

Version 6.0 and later. Indicates that links in the tooltip text should be parsed.

Note that Comctl32.dll version 6 is not redistributable but it is included in Microsoft Windows XP or later. To use Comctl32.dll version 6, specify it in a manifest. For more information on manifests, see Using Windows XP Visual Styles.

TTF_RTLREADING

Indicates that the ToolTip text will be displayed in the opposite direction to the text in the parent window.

TTF_SUBCLASS

Indicates that the ToolTip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. If this flag is not set, you must use the TTM_RELAYEVENT message to forward messages to the ToolTip control. For a list of messages that a ToolTip control processes, see TTM_RELAYEVENT.

TTF_TRACK

Version 4.70 and later. Positions the ToolTip window next to the tool to which it corresponds and moves the window according to coordinates supplied by the TTM_TRACKPOSITION messages. You must activate this type of tool using the TTM_TRACKACTIVATE message.

TTF_TRANSPARENT

Version 4.70 and later. Causes the ToolTip control to forward mouse event messages to the parent window. This is limited to mouse events that occur within the bounds of the ToolTip window.

TTF_BITMAP

Tooltip displays a bitmap: Not supported by the library.

Some of the flags are low level enough not to be used in normal programming, but they exist though.

The text of a tooltip may contain the "\r\n" sequence to force a line break.

Setting Tooltip characteristics

The width of a tooltip window can be adjusted by calling setHintWidth(control_id,new_width). This returns the current width. The default width is 80 characters in the current tooltip font. The hintwidth.exw demo program shows what it can achieve. The tooltip display window width, in pixels, for a control can be returned by getControlInfo() using the undocumented parameter CONTROLINFO_tooltipwid.

The font used to display the tooltips can be set using setHintFont(face_name,point_size,attributes), like for setFont(). The default values are MS Sans Serif, 8pt, Normal.

The Tooltip manager control

There exist a control type called Tooltip, and you can create such controls - the library automatically creates one for you -. Since a manager may handle any number of tools, this ability has little practical use.

You can use the manageTooltip(TM_id,flag) to se the current manager to TM_id and enable it (flag=w32True) or disable it (flag=w32False). The id of the previous tooltip manager is tryutnrd.

When creating a manager, the following styles are available:

TTS_ALWAYSTIP

Indicates that the ToolTip control appears when the cursor is on a tool, even if the ToolTip control's owner window is inactive. Without this style, the ToolTip appears only when the tool's owner window is active.

TTS_BALLOON

Version 5.80. Indicates that the ToolTip control has the appearance of a cartoon "balloon," with rounded corners and a stem pointing to the item.

TTS_NOANIMATE;

Version 5.80. Disables sliding ToolTip animation on Microsoft Windows 98 and Windows 2000 systems. This style is ignored on earlier systems.

TTS_NOFADE

Version 5.80. Disables fading ToolTip animation on Windows 2000 systems. This style is ignored on earlier Microsoft Windows NT systems, and on Windows 95 and Windows 98.

TTS_NOPREFIX

Prevents the system from stripping the ampersand character from a string. Without this style, the system automatically strips ampersand characters. This allows an application to use the same string as both a menu item and as text in a ToolTip control.

TTS_USEVISUALSTYLE

Use themed hyperlinks.

Getting information

The only facility the library provides is the hitTestTT() function. It checks whether the mouse is over a control that has a tooltip. If so, the id of the control is returned, else 0.