DISPLAYING ELEMENT-LEVEL TOOL TIPS FOR SWING COMPONENTS

DISPLAYING ELEMENT-LEVEL TOOL TIPS FOR SWING COMPONENTS

Tool tips are those little popup windows that appear when you rest your mouse pointer over a control such as a button or list. All Swing components support tool tips. To establish a tool tip for a control, call setToolTipText() for the component. When a user rests the mouse pointer over the control, the tool tip automatically appears. Typically, you want one text string for an entire component. But there can be times when you want the text to be more flexible. For instance, in the case of a JList, JTree, or JTable component, you might want to display tool tip text based on which list entry, tree node, or table cell the mouse pointer is over. How can you customize the text?

There are two ways you can create custom tool tips for these Swing components. You can customize the control and override the public String getToolTipText(MouseEvent event) method, or you can customize the renderer for the control and let the renderer deal with the tool tips.

If you decide to override the getToolTipText() method, you have to understand that the passed-in MouseEvent contains the mouse coordinates over the control. It is your responsibility to determine what element the cursor is on. Then, you have to look up the appropriate tool tip text for the element and return that text. You must then manually register the component with the ToolTipManager. If you called the setToolTipText() method for the control, a call to the registerComponent() method of ToolTipManager would have been done for you, but because you don't need to call setToolTipText(), you must do the registration yourself.

Here's an example that demonstrates this first approach. The example uses the keys for the system properties (such as java.runtime.name) as the list entries. The example uses the property values (such as Java 2, Runtime Environment, Standard Edition) as the tool tip text for those entries.

    
    import java.awt.*;
    import java.awt.event.*;
    import java.util.*;
    import javax.swing.*;

    public class ListTest extends JList {

      DefaultListModel model;
      Properties tipProps;

      public ListTest(Properties props) {
        model = new DefaultListModel();
        setModel(model);
        ToolTipManager.sharedInstance().registerComponent(
                                             this);

        tipProps = props;
        Enumeration enum = props.propertyNames();
        while (enum.hasMoreElements()) {
          model.addElement(enum.nextElement());
        }
      }
      public String getToolTipText(MouseEvent event) {
        Point p = event.getPoint();
        int location = locationToIndex(p);
        String key = (String)model.getElementAt(
                                            location);
        String tip = tipProps.getProperty(key);
        return tip;
      }
      public static void main (String args[]) {
        JFrame frame = new JFrame("Custom Tips");
        frame.setDefaultCloseOperation(
                                JFrame.EXIT_ON_CLOSE);
        Properties props = System.getProperties();
        ListTest list = new ListTest(props);
        JScrollPane scrollPane = new JScrollPane(list);
        frame.getContentPane().add(scrollPane);
        frame.setSize(300, 300);
        frame.show();
      }
    }

If you decide instead to customize the cell renderer, you have to do a little more work at first, but you don't have to determine what element is under the mouse at run time. If you find that the tool tips are hardly used, though, this extra work might not be necessary. That's because getting cell renderers happens frequently, and the tool tip setup happens every time the cell is rendered. It might be better to use the first mechanism. Essentially, what it involves is calling the setToolTipText() method for the cell renderer.

Here's an example that demonstrates the cell renderer approach. The example is taken from the book "John Zukowski's Definitive Guide to Swing for Java 2, Second Edition" published by Apress.

First the renderer: this code essentially reuses a DefaultTreeCellRenderer as the renderer, setting its tip text.

    import javax.swing.*;
    import javax.swing.tree.*;
    import java.awt.*;
    import java.util.*;

    public class ToolTipTreeCellRenderer 
        implements TreeCellRenderer {
      DefaultTreeCellRenderer renderer = 
        new DefaultTreeCellRenderer();
      Dictionary tipTable;

      public ToolTipTreeCellRenderer (
                             Dictionary tipTable) {
        this.tipTable = tipTable;
      }

      public Component getTreeCellRendererComponent(
          JTree tree, Object value, boolean selected, 
          boolean expanded, boolean leaf, int row, 
          boolean hasFocus) {
        renderer.getTreeCellRendererComponent(
          tree, value, selected, expanded, leaf, row, 
                                            hasFocus);
        if (value != null) {
          Object tipKey;
          if (
             value instanceof DefaultMutableTreeNode) {
             tipKey = 
              ((DefaultMutableTreeNode)value).getUserObject();
          } else {
            tipKey = tree.convertValueToText(value, 
              selected, expanded, leaf, row, hasFocus);
          }
          Object tip = tipTable.get(tipKey);
          if (tip != null) {
            renderer.setToolTipText(tip.toString());
          } else {
            renderer.setToolTipText(null);
          }
        }
        return renderer;
      }
    }

The test program then just registers the tree with the ToolTipManager and registers the renderer. There is no need to subclass JTree. Like the JList example, the system properties are used for the component elements. In this case, the tree is only one level deep.

    import javax.swing.*;
    import javax.swing.tree.*;
    import java.awt.*;
    import java.util.*;

    public class TreeTips {
      public static void main(String args[]) {
        JFrame frame = new JFrame("Custom Tree Tips");
        frame.setDefaultCloseOperation(
                                 JFrame.EXIT_ON_CLOSE);
        Properties props = System.getProperties();
        JTree tree = new JTree(props);
        ToolTipManager.sharedInstance().registerComponent(
                                                 tree);
        TreeCellRenderer renderer = 
                    new ToolTipTreeCellRenderer(props);
        tree.setCellRenderer(renderer);
        JScrollPane scrollPane = new JScrollPane(tree);
        frame.getContentPane().add(
                      scrollPane, BorderLayout.CENTER);
        frame.setSize(300, 150);
        frame.setVisible(true);
      }
    }

<!-- Black Horizontal Line Begins Here -->