How to Use Tool Tips

Creating a tool tip for any JComponent is easy. You just use the setToolTipText method to set up a tool tip for the component. For example, to add tool tips to three buttons , you add only three lines of code:

 b1.setToolTipText("Click this button to disable the middle button."); b2.setToolTipText("This middle button does nothing when you click it."); b3.setToolTipText("Click this button to enable the middle button."); 

When the user of the program pauses with the cursor over any of the program's buttons, the tool tip for the button comes up. (See Figure 90.) You can see this by running the ButtonDemo example, which is explained in How to Use Buttons (page 156) and shown in Figure 90.

Figure 90. A tool tip appears when the cursor pauses over any button in ButtonDemo .

For components such as tabbed panes that have multiple parts , it often makes sense to vary the tool-tip text to reflect the part of the component under the cursor. For example, a tabbed pane might use this feature to explain what will happen when you click the tab under the cursor. When you implement a tabbed pane, you can specify the tab-specific tool-tip text in an argument to the addTab or setToolTipTextAt method.

Even in components that have no API for setting part-specific tool-tip text, you can generally do the job yourself. If the component supports renderers, then you can set the tool tip text on a custom renderer. You can find examples of doing this in the table and tree sections. An alternative that works for all JComponent s is creating a subclass of the component and overriding its getToolTipText(MouseEvent) method.

The Tool-Tip API

Most of the API you need to set up tool tips is in the JComponent class, and thus is inherited by most Swing components. More tool-tip API is in individual classes such as JTabbedPane . In general, those APIs are sufficient for specifying and displaying tool tips; you usually don't need to deal directly with the implementing classes, JToolTip ^[199] and ToolTipManager . ^[200]

^[199] JToolTip API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JToolTip.html.

^[200] ToolTipManager API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ToolTipManager.html.

Table 100 lists the JComponent tool tip API. For information on individual components' support for tool tips, see the how-to section for the component in question.

Table 100. Tool-Tip API in JComponent

Method	Purpose
setToolTipText(String)	If the specified string is non-null, then register the component as having a tool tip and makes the tool tip (when displayed) have the specified text. If the argument is null, then this method turns off tool tips for this component.
String getToolTipText()	Return the string that was previously specified with setToolTipText .
String getToolTipText(MouseEvent)	By default, return the same value returned by getToolTipText() . Multi-part components such as JTabbedPane , JTable , and JTree override this method to return a string associated with the mouse event location. For example, each tab in a tabbed pane can have different tool-tip text.
Point getToolTipLocation(MouseEvent)	Get the location (in the receiving component's coordinate system) where the upper left corner of the component's tool tip will appear. The argument is the event that caused the tool tip to be shown. The default return value is null, which tells the Swing system to choose a location.

Examples That Use Tool Tips

This table shows some examples that use tool tips and where those examples are described.

Example	Where Described	Notes
ButtonDemo	This section and How to Use Buttons (page 156)	Uses a tool tip to provide instructions for a button.
IconDemoApplet	How to Use Icons (page 603)	Uses a tool tip in a label to provide name and size information for an image.
TabbedPaneDemo	How to Use Tabbed Panes (page 382)	Uses an argument to the addTab method to specify tool tip text for each tab.
DragFileDemo	How to Use Drag and Drop and Data Transfer (page 545)	Uses an argument to the addTab method to specify tool tip text for each tab ”the name of the file the tab's component displays.
TableRenderDemo	Specifying Tool Tips for Cells (page 407)	Adds tool tip text to a table using a renderer.
TableToolTipsDemo	Specifying Tool Tips for Cells (page 407) , Specifying Tool Tips for Column Headers (page 410)	Adds tool tips to a table using various techniques.
TreeIconDemo2	Customizing a Tree's Display (page 442)	Adds tool tips to a tree using a custom renderer.
ActionDemo	How to Use Actions (page 513)	Adds tool tips to buttons created using Action s.