27.3 Tooltips

You have probably already seen several examples of using basic tooltips with components such as JButton and JLabel. The following classes give you access to much more of the tooltip system in case you need to develop something beyond simple text tips.

27.3.1 The ToolTipManager Class

This class manages the tooltips for an application. Following the singleton pattern, any given virtual machine will have, at most, one ToolTipManager at any time a new instance is created when the class is loaded. (Of course, you're already familiar with Design Patterns by Gamma et al., right?) You can retrieve the current manager using the ToolTipManager.sharedInstance( ) method.

27.3.1.1 Properties

The ToolTipManager properties shown in Table 27-3 give you control over the delays (in milliseconds) involved in showing tooltips and determines whether or not tooltips are even active. The enabled property determines whether or not tooltips are active. The dismissDelay property determines how long a tooltip remains on the screen if you don't do something to dismiss it manually (such as move the mouse outside the component's borders). The initialDelay property determines how long the mouse must rest inside a component before the tooltip pops up, and reshowDelay determines how long you must wait after leaving a component before the same tooltip shows up again when you reenter the component. (These properties are used by a timer whose delays are triggered by mouse events.) If the lightWeightPopupEnabled property is true, all-Java tooltips are used. A false value indicates native tooltips should be used.

Table 27-3. ToolTipManager properties

Property	Data type	get	is	set	Default value
dismissDelay	int	·		·	4000
enabled	boolean		·	·	true
initialDelay	int	·		·	750
lightWeightPopupEnabled	boolean		·	·	true
reshowDelay	int	·		·	500

27.3.1.2 Miscellaneous methods

If need be, you can manually register or unregister components with the manager. Normally this is done using the JComponent.setToolTipText( ) method for the component itself. If you pass in a non-null tip string, the component is registered. If you pass in a null tip string, the component is unregistered. The VSX2 example in Chapter 17 shows off how to use these methods in detail, but the synopsis is:

ToolTipManager.sharedInstance( ).registerComponent(yourComponent);

public void registerComponent(JComponent component)

Register component with the ToolTipManager to make sure that its tips get shown after an appropriate mouse event occurs.

public static ToolTipManager sharedInstance( )

Return the ToolTipManager singleton. You use this to get access to the manager and change its delay properties. For example, you could cut the initial delay to 250 milliseconds like this:

ToolTipManager.sharedInstance( ).setInitialDelay(250);

public void unregisterComponent(JComponent component)

Unregister component from the ToolTipManager. Tooltips are no longer shown for this component.

27.3.2 The JToolTip Class

Of course, the whole purpose of having a tooltip manager is to manage tooltips. The tooltips themselves are simple popups containing a short, descriptive string that often shows up if you let your mouse cursor rest over a component. They are embodied here in the JToolTip class. JToolTip is a fairly simple class, thanks to the MVC architecture in place for Swing. All it really needs to know is what text to display and who to display it for. With SDK 1.4, JToolTip can take advantage of the same HTML formatting as the JLabel class. See Chapter 4 for all the details.

If you want to display something besides text, you can create your own subclass of JToolTip and render just about anything you want. (Recall that JToolTip extends from JComponent.) To make your custom tooltip available, you'll also need to subclass the component to which you want to add your tip and override the createToolTip( ) method to return an instance of your tip.

27.3.2.1 Properties

The properties that support the JToolTip class are shown in Table 27-4. The component property determines which component this tip applies to. The tipText property contains the text to display for the tip. Both of these properties are currently stored in package-private variables.

Table 27-4. JToolTip properties

Property	Data type	get	is	set	Default value
accessibleContext	AccessibleContext	·			JToolTip.AccessibleJToolTip( )
component	Component	·		·	null
tipText	String	·		·	null
UIb, o	ToolTipUI	·		·	From L&F
UIClassIDo	String	·			"ToolTipUI"
bbound, ooverridden

27.3.2.2 Constructor

The JToolTip class has only one constructor:

public JToolTip( )

Create a new JToolTip object with no text or component association.