Open source Java projects: Balloontip for Java

Add balloon tips to your Swing GUIs

1 2 3 4 Page 3
Page 3 of 4

Methods for configuring balloon tip components

Three of the remaining BalloonTip methods configure the balloon tip in terms of the underlying label's text, icon, and icon-text gap. These methods are described below:

  • public void setText(String text) specifies the balloon tip's text. Because this method invokes JLabel's setText() method, HTML can be used.
  • public void setIcon(Icon icon) specifies the balloon tip's icon. This method invokes JLabel's setIcon() method.
  • public void setIconTextGap(int iconTextGap) specifies how many pixels separate the icon from the text. This method invokes JLabel's setIconTextGap() method.

The BalloonTipTestDrive.java excerpt below uses setText(), setIcon(), and setIconTextGap() to configure a balloon tip with Nice! You inserted 5 characters! as its text, infoicon.gif as its icon, and 10 as its icon-text gap:

balloonTip.setText("Nice! You inserted 5 characters!");
balloonTip.setIcon(new ImageIcon(BalloonTipTestDrive.class.getResource
  ("/net/java/balloontip/images/infoicon.gif")));
balloonTip.setIconTextGap(10);

The final BalloonTip method, which is described below, determines the balloon tip's visibility and (if the balloon tip is about to be displayed) its above and left-aligned position relative to its attached component:

  • public void setVisible(boolean show) shows or hides the balloon tip. If true is passed, the balloon tip's position is established prior to being made visible.

This method is demonstrated by two BalloonTipTestDrive.java excerpts. The first excerpt installs a key listener on the text field to determine whether to show or hide a balloon tip on each key release. The balloon tip will only be shown if exactly five characters are present in the text field.

Listing 5. textField.addKeyListener(new KeyAdapter()

textField.addKeyListener(new KeyAdapter() {
  public void keyReleased(KeyEvent e) {
     if (textField.getText().length() == 5) {
         balloonTip.setVisible(true);
     } else {
         balloonTip.setVisible(false);
     }
  }
});

The second excerpt installs a focus listener on the text field to hide the balloon tip when this component loses the focus. A side effect of this listener is that it prevents the action listener of the balloon tip's Close button from being invoked to hide the balloon tip.

Listing 6. textField.addFocusListener(new FocusAdapter()

textField.addFocusListener(new FocusAdapter() {
  public void focusLost(FocusEvent e) {
     balloonTip.setVisible(false);
  }
});

When are balloon tips useful?

Suppose your GUI prevents users from shifting focus away from the current text field until an appropriate value is entered. To avoid user confusion when the focus shift fails, the GUI can show a balloon tip reminding the user to enter an appropriate value. Check out Figure 5 for an example.

A balloon tip used for notification.
Figure 5. Balloon tips are great for reminding the user to enter correct input

Figure 5 reveals the user having entered 0 into the top text field, and having attempted to switch focus to the bottom text field. Because 0 is not an appropriate value, the focus shift is prevented and a balloon tip is shown to remind the user to enter something valid.

The GUI in Figure 5 is created by VerifyAge1 -- see this article's code archive (in the Resources section) for the application's source code. The source code excerpt in Listing 7 shows how VerifyAge1 uses the balloontip API to integrate a balloon tip into its GUI.

Listing 7. integrating a balloon tip into a GUI

// Create the upper half of the GUI.

pnl = new JPanel (new FlowLayout (FlowLayout.LEFT));
pnl.setBorder (BorderFactory.createEmptyBorder (75, 0, 0, 0));
pnl.add (new JLabel ("Enter your age (1 - 130):"));
final JTextField txtAgeIn = new JTextField (10);
pnl.add (txtAgeIn);

txtAgeIn.addFocusListener (new FocusAdapter ()
                           {
                               public void focusLost (FocusEvent fe)
                               {
                                  // Copy age from upper text field to
                                  // lower text field when upper text
                                  // field loses the focus.

                                  txtAgeOut.setText (txtAgeIn.getText ());
                               }
                           });

// txtAgeIn's input verifier prevents focus from shifting away from this
// text field until the verify() method returns true.

txtAgeIn.setInputVerifier (new InputVerifier ()
                           {
                               public boolean verify (JComponent com)
                               {
                                  JTextField txt = (JTextField) com;
                                  try
                                  {
                                     // Parse digit characters from text
                                     // field into an integer.

                                     int value =
                                     Integer.parseInt (txt.getText ());

                                     // Integer out of range.

                                     if (value <= 0 || value > 130)
                                     {  
                                         bt.setVisible (true);
                                         return false;
                                     }
                                  }
                                  catch (NumberFormatException nfe)
                                  {     
                                     // Non-digit characters detected.

                                     bt.setVisible (true);
                                     return false;
                                  }

                                  // Input is valid. It's okay to yield
                                  // focus.
                                          
                                  bt.setVisible (false);
                                  return true;                                 
                               }
                           });

getContentPane ().add (pnl, BorderLayout.NORTH);

bt = BalloonTip.createRoundedBalloonTip (txtAgeIn, Color.BLACK,
                                         new Color (255, 255, 225), 10,
                                         15, 20, 7, 7, false);
bt.setText ("Enter 1 - 130");
bt.setVisible (false);

This code fragment creates the GUI's top text field and its associated balloon tip. An input verifier is attached to the text field to prevent a focus shift when the verifier's public boolean verify(JComponent com) method returns false.

1 2 3 4 Page 3
Page 3 of 4