Open source Java projects: Balloontip for Java

Add balloon tips to your Swing GUIs

1 2 3 4 Page 2
Page 2 of 4

The GUI presents labels, two radio buttons for determining the balloon tip's border (rounded or edged -- the rounded-border version is shown in Figure 2), and a text field. It also presents a balloon tip when you enter exactly five characters in the text field.

As you experiment with BalloonTipTestDrive, you will notice that the balloon tip disappears when you enter more than five characters in the text field. Backspacing to five characters causes the balloon tip to reappear.

The balloon tip also disappears when the text field loses focus. Focus is lost when you select a radio button or the balloon tip's Close button. Focus is also lost when you minimize and restore the application (at least under XP) or select another running application's main window.

Explore the balloontip API

Use balloontip's borders with other Swing components
Because RoundedBalloonBorder and EdgedBalloonBorder implement the javax.swing.border.Border interface and are marked public, you can use these classes to establish borders (via JComponent's public void setBorder(Border border) method) for other Swing components.

A balloon tip is an instance of the net.java.balloontip.BalloonTip class. This class subclasses JPanel, uses a JLabel component to render balloon tip contents, and uses a JButton component (whose action listener hides the balloon tip) as the Close button.

BalloonTip internally works with two other classes located in the same package: RoundedBalloonBorder and EdgedBalloonBorder. These classes are used to establish a border for the balloon tip.

Methods for creating balloon tip components

The BalloonTip class presents a small API consisting of six methods. Two of these methods are factory methods for creating balloon tip components. The factory method for creating a rounded balloon tip has the signature shown in Listing 2.

Listing 2. createRoundedBalloonTip(...)

public static BalloonTip createRoundedBalloonTip(Component attachedComponent, 
                                                 Color borderColor, 
                                                 Color fillColor,
                                                 int borderWidth, 
                                                 int horizontalOffset, 
                                                 int verticalOffset,
                                                 int arcWidth, 
                                                 int arcHeight, 
                                                 boolean useCloseButton)

The attachedComponent parameter identifies the component to which the balloon tip is associated. Whenever the balloon tip is made visible, it will appear in close proximity to the component, as previously illustrated in Figure 2.

Watch out for NullPointerExceptions!
A NullPointerException is thrown if attachedComponent does not have a JDialog, JFrame, or JInternalFrame ancestor -- each factory method calls an internal method that adds the balloon tip to JDialog's JFrame's, or JInternalFrame's layered pane.

The borderColor and fillColor parameters identify the colors used to paint the border and interior of the balloon tip. The arguments passed to these parameters are forwarded to the RoundedBalloonBorder and EdgedBalloonBorder classes, which take care of painting.

The next five parameters identify the number of pixels between the border and the balloon tip contents, the length and location of the tip's triangular anchor (which points to the associated component), and the size of the border's rounded corners. Figure 3 clarifies these parameters (image courtesy of Bernhard Pauler).

Illustration of the parameters for a rounded balloon tip layout.
Figure 3. Rounded balloon tip layout (click for a larger image)

The final useCloseButton parameter determines whether or not a close button appears on the balloon tip. Pass true to this parameter to display this button. If the button is present, clicking it hides the balloon tip.

The second factory method is somewhat simpler than the first one. Because this latter method is responsible for creating balloon tips without rounded corners, it does not require arcWidth and arcHeight parameters. Its signature is shown in Listing 3.

Listing 3. createEdgedBalloonTip(...)

public static BalloonTip createEdgedBalloonTip(Component attachedComponent, 
                                               Color borderColor, 
                                               Color fillColor,
                                               int borderWidth, 
                                               int horizontalOffset, 
                                               int verticalOffset, 
                                               boolean useCloseButton)

This method's parameters are equivalent to the same-named parameters in the first factory method. The only difference between these factory methods is that the latter method creates a narrower border with square corners. This alternative border's layout is shown in Figure 4 (image courtesy of Bernhard Pauler).

Illustration of the parameters for an edged balloon tip layout.
Figure 4. Edged balloon tip layout (click for a larger image)

The following excerpt from BalloonTipTestDrive.java shows how the example application uses these factory methods to create its rounded and edged balloon tips -- a factory method is invoked when its associated radio button is selected.

Listing 4. Creating rounded and edged balloon tips

BalloonTip balloonTip;

// ...

if (buttonForRoundedLook.isSelected()) {
    balloonTip = BalloonTip.createRoundedBalloonTip(textField, Color.BLACK, new Color(255, 255, 225), 
                                                    10, 15, 20, 7, 7, true);
} 
else 
if (buttonForEdgedLook.isSelected()) {
    balloonTip = BalloonTip.createEdgedBalloonTip(textField, Color.BLACK, new Color(255, 255, 225), 
                                                  10, 15, 20, true);
}
1 2 3 4 Page 2
Page 2 of 4