Subpages: 1. Labels and buttons overview
2. Custom buttons: part I - Transparent buttons
3. Custom buttons: part II - Polygonal buttons
4. Custom buttons: part III - Tooltip management
5.4 Custom buttons: part III - Tooltip management
In this section we'll discuss how to implement custom management of tooltips in a Swing application. If you're completely satisfied with the default ToolTipManager provided with Swing, you can skip this section. But there may be situations when this default implementation is not satisfactory, as in our example above using non-rectangular components.
We will construct our own version of a tooltip manager to display a tooltip window if the mouse cursor rests over some point inside the button's area longer than a specified time interval. It will be displayed for a speecified amount of time and, to avoid annoying the user, we will then hide the tooltip window until the mouse cursor moves to a new position. In designing our tooltip manager we will take a different approach than that taken by Swing's default ToolTipManager (see section 5.4). Instead of using three different Timers, we will use just one. This involves tracking more information, but is slightly more efficient by avoiding the handling of multiple ActionEvents.
Figure 5.11 Polygonal buttons with custom tooltip manager.
<<file figure5-11.gif>>
The Code: ButtonApplet3.java
see \Chapter5\6
import java.applet.*;
import java.awt.*;
import java.awt.event.*;
import java.net.*;
import java.util.*;
import javax.swing.*;
import javax.swing.border.*;
import javax.swing.event.*;
public class ButtonApplet3 extends JApplet
{
protected ToolTipManager m_manager;
public ButtonApplet3() {}
public synchronized void init() {
// unchanged code from section 5.3
m_manager = new ToolTipManager(this);
PolygonButton.m_toolTip = m_manager.m_toolTip;
getContentPane().setLayout(null);
getContentPane().add(bigLabel);
bigLabel.setBounds(0, 0, bigImage.getIconWidth(),
bigImage.getIconHeight());
}
// unchanged code from section 5.3
}
class PolygonButton extends JComponent
implements MouseListener, MouseMotionListener
{
// unchanged code from section 5.3
public static JToolTip m_toolTip;
protected void setState(boolean active) {
m_active = active;
repaint();
if (active) {
if (m_currentButton != null)
m_currentButton.setState(false);
m_parent.setCursor(Cursor.getPredefinedCursor(
Cursor.HAND_CURSOR));
m_parent.showStatus(m_sUrl);
if (m_toolTip != null)
m_toolTip.setTipText(m_text);
}
else {
m_currentButton = null;
m_parent.setCursor(Cursor.getPredefinedCursor(
Cursor.DEFAULT_CURSOR));
m_parent.showStatus("");
if (m_toolTip != null)
m_toolTip.setTipText(null);
}
}
}
class MyToolTipManager extends MouseMotionAdapter
implements ActionListener
{
protected Timer m_timer;
protected int m_lastX = -1;
protected int m_lastY = -1;
protected boolean m_moved = false;
protected int m_counter = 0;
public JToolTip m_toolTip = new JToolTip();
ToolTipManager(JApplet parent) {
parent.addMouseMotionListener(this);
m_toolTip.setTipText(null);
parent.getContentPane().add(m_toolTip);
m_toolTip.setVisible(false);
m_timer = new Timer(1000, this);
m_timer.start();
}
public void mouseMoved(MouseEvent e) {
m_moved = true;
m_counter = -1;
m_lastX = e.getX();
m_lastY = e.getY();
if (m_toolTip.isVisible()) {
m_toolTip.setVisible(false);
m_toolTip.getParent().repaint();
}
}
public void actionPerformed(ActionEvent e) {
if (m_moved || m_counter==0 || m_toolTip.getTipText()==null) {
if (m_toolTip.isVisible())
m_toolTip.setVisible(false);
m_moved = false;
return;
}
if (m_counter < 0) {
m_counter = 4;
m_toolTip.setVisible(true);
Dimension d = m_toolTip.getPreferredSize();
m_toolTip.setBounds(m_lastX, m_lastY+20,
d.width, d.height);
}
m_counter--;
}
}
Understanding the Code
Class ButtonApplet3
This class requires very few modifications from ButtonApplet2 in the last section. It declares and creates MyToolTipManager m_manager and passes a this reference to it:
m_manager = new MyToolTipManager(this);
As you will see below, our MyToolTipManager class manages a publically accessible JToolTip, m_toolTip. MyToolTipManager itself is not intended to provide any meaningful content to this tooltip. Rather, this is to be done by other components, in our case, by the PolygonButtons. Thus, our PolygonButton class declares a static reference to a JToolTip component. Whenever a button becomes active, this JToolTip's text will be assigned to that of the active button. So, when we create our instance of MyToolTipManager, we assign its publically accessible JToolTip as our Polygon class's static JToolTip (which is also publically accessible):
PolygonButton.m_toolTip = m_manager.m_toolTip;
Thus, there will only be one JToolTip instance in existance for the lifetime of this applet, and both MyToolTipManager and our PolygonButtons have control over it.
Class PolygonButton
As we've mentioned above, this class now declares the static variable: JToolTip m_toolTip. Class PolygonButton does not initialize this reference. However, this reference is checked during PolygonButton activation in the setState() method. If m_toolTip is not null (set to point to a valid tooltip window by some outer class--which, in our example, is done in the ButtonApplet3 init() method shown above), the setTipText() method is invoked to set the proper text while the mouse cursor hovers over the button.
Class MyToolTipManager
This class represents a custom tooltip manager which is free from assumption of the rectangularity of its child components. It extends the MouseMotionAdapter class and implements the ActionListener interface to work as both a MouseMotionListener and ActionListener. Six instance variables are declared:
Timer m_timer: our managing timer.
int m_lastX, m_lastY: the last coordinates of the mouse cursor--reassigned each time the mouse is moved.
boolean m_moved: flag indicating that the mouse cursor has moved.
int m_counter: time ticks counter managing the tooltip's time to live (see below).
JToolTip m_toolTip: the tooltip component to be displayed.
The constructor of the MyToolTipManager class takes a reference to the parenting JApplet as a parameter and registers itself as a MouseMotionListener on this component. Then it creates the JToolTip m_toolTip component and adds it to the applet's content pane. m_tooltip is set invisible, using setVisible(false), and can then be used by any interested class by repositioning it and calling setVisible(true). Finally a Timer with a 1000 ms delay time is created and started.
The mouseMoved() method will be invoked when the mouse cursor moves over the applet's pane. It sets the m_moved flag to true, m_counter to -1, and stores the coordinates of the mouse cursor. Then this method hides the tooltip component if is visible.
The actionPerformed() method is called when the Timer fires events (see 2.6 for details). It implements the logic of displaying/hiding the tooltip window based on two instance variables: m_moved and m_counter:
if (m_moved || m_counter==0 || m_toolTip.getTipText()==null) {
if (m_toolTip.isVisible())
m_toolTip.setVisible(false);
m_moved = false;
return;
}
The above block of code is invoked when any one of the following statements are true:
1. Mouse cursor has been moved since the last time tick.
2. Counter has reached zero.
3. No tooltip text is set.
In any of these cases, the tooltip component is hidden (if previously visible), and the m_moved flag is set to false. Note that the m_counter variable remains unchanged.
if (m_counter < 0) {
m_counter = 4;
m_toolTip.setVisible(true);
Dimension d = m_toolTip.getPreferredSize();
m_toolTip.setBounds(m_lastX, m_lastY+20,
d.width, d.height);
}
This block of code is responsible for displaying the tooltip component. It will be executed only when m_counter is equal to -1 (set by mouseMoved()), and the m_moved flag is false (cleared by the previous code fragment). m_counter is set to four which determines the amount of time the tooltip will be displayed (4000ms in this example). Then we make the tooltip component visible and place it at the current mouse location with a vertical offset approximately equal to the mouse cursor's height. Note that this construction provides an arbitrary time delay between when mouse motion stops and the tooltip is displayed.
The last line of code in the actionPerformed() method is m_counter--, which decrements the counter each time tick until it reaches 0. As we saw above, once it reaches 0 the tooltip will be hidden.
Note: The actual delay time may vary from 1000ms to 2000 ms since the mouse movements and time ticks are not synchronized. A more accurate and complex implementation could start a new timer after each mouse movement, as is done in Swing's ToolTipManager.
The following table illustrates how the m_counter and m_moved variables control this behavior.
Timer m_moved m_counter m_counter Comment
tick flag before after
0 false 0 0
1 true -1 -1 Mouse moved between 0-th and 1-st ticks
2 false -1 4 Tool tip is displayed
3 false 4 3
4 false 3 2
5 false 2 1
6 false 1 0
7 false 0 0 Tool tip is hidden
8 false 0 0 Waiting for the next mouse move
Running the Code
Figure 5.11 shows ButtonApplet3 running in Netscape Navigator 4.05 with the Java Plug-in. You can use the same HTML file as presented in the previous section. Move the mouse cursor over some non-rectangular component and note how it displays the proper tooltip message. This tooltip disappears after a certain amount of time or when the mouse is moved to a new location.
RSS feed Java FAQ News