Table of contents
  1. Usage
    1. Requirements
    2. Getting started
    3. Using BalloonTip
      1. My first balloon tip
      2. Balloon tips with style
      3. Use a JComponent as contents
      4. Tweaking a balloon tip's position
      5. Balloon tips with custom positioners
    4. Other types of balloon tips
      1. CustomBalloonTip
      2. TablecellBalloonTip
    5. Utilities
      1. Timed balloon tips
      2. Fade effects
      3. Balloon tooltips
  2. Development
    1. Importing the project
      1. Eclipse, with Maven support
      2. Eclipse, regular Java project
      3. Maven
      4. Ant
    2. Creating your own BalloonTipStyle
    3. Creating your own BalloonTipPositioner
  3. Release notes
1. Usage
1.1. Requirements
The only requirement to make use of Balloon tip is that you need Java 1.5 or higher.
1.2. Getting started

Thanks for giving Balloon tip a try! You can now spice up your Java Swing applications with the balloon tip components provided in this project.

Before diving in, let's take a quick look at the things that are included in the .zip-file you've just downloaded:

Now that you know what is available in this release, let's get familiar with the features Balloon tip has to offer. The quickest way to do this is to try out the demo application. Simply double-click the balloontip_with_examples_ ... .jar-file to open the demo application.

If this doesn't work, you'll have to open up a console/command-line window and navigate into the Balloon tip-directory.
Just enter the following command to start the demo application: java -jar balloontip-examples ... .jar
(Replace the "..." with the right version number.)

The balloon tip example application
The demo application

Once the application has started, you can start exploring many of Balloon tip's features.
Just toy around with all possible settings and see what happens; this probably is the easiest way to learn the terminology that is used by the Balloon tip API.

Once you're done playing, you may proceed to the next section, which will teach you the basics in creating your own balloon tips.

1.3. Using BalloonTip
1.3.1. My first balloon tip

The BalloonTip class implements a basic balloon tip which is suited for most uses. A BalloonTip instance can attach itself to about any visual component: a JButton, JLabel, JTextField, ... In order to create and show a BalloonTip instance, all you need to do is construct one. Like most components in Swing, the BalloonTip class comes with several constructors.

Starting off with the easiest constructor:

BalloonTip(JComponent attachedComponent, String text)

The first parameter, attachedComponent, is the JComponent you want to attach your balloon tip to. The second parameter, text, simply is the text you want to show inside the balloon tip.
For example, if the attached component were a JButton called myButton and you want the balloon to say "Hello world!", you should write:

BalloonTip myBalloonTip = new BalloonTip(myButton, "Hello world!");

The newly created balloon tip would then look like this:

A BalloonTip attached to a JButton
A BalloonTip attached to a JButton
1.3.2. Balloon tips with style

If you want to have control over the balloon tip's looks, you can try this constructor:

BalloonTip(JComponent attachedComponent, String text, BalloonTipStyle style, boolean useCloseButton)

The parameter useCloseButton is easy: If true, a working close button is shown.
The style parameter is more interesting; a BalloonTipStyle defines the balloon tip's looks. Several different styles can be found in the package net.java.balloontip.styles. As an example, I'll make a BalloonTip with the simplest style, the EdgedBalloonStyle, which gives the balloon tip sharp corners:

BalloonTipStyle edgedLook = new EdgedBalloonStyle(Color.WHITE, Color.BLUE);
BalloonTip myBalloonTip = new BalloonTip(myButton, "Hello world!", edgedLook, true);

Now we'll get something looking like this:

A BalloonTip with an EdgedBalloonStyle
A BalloonTip with an EdgedBalloonStyle, which gives the balloon its sharp corners, a white background color and a blue border
1.3.3. Use a JComponent as contents

Balloon tips can also contain other components beside just text. In fact, just about any JComponent can serve as the contents of a balloon tip.
The following constructor allows you to add a JComponent as the contents of a balloon tip:

BalloonTip(JComponent attachedComponent, JComponent contents, BalloonTipStyle style, boolean useCloseButton)

For example, you could set a balloon tip's contents to a JTable:

BalloonTipStyle edgedLook = new EdgedBalloonStyle(Color.WHITE, Color.BLUE);
BalloonTip myBalloonTip = new BalloonTip(myButton, new JTable(3,2), edgedLook, true);

This creates the following result:

A BalloonTip with an EdgedBalloonStyle
A BalloonTip with a JTable as its contents
Tip: If you use components such as a JPanel or JTabbedPane, you can build entire interactive user interfaces inside a balloon tip. (Why yes, you can even attach balloon tips to the components inside a balloon tip!)
1.3.4. Tweaking a balloon tip's position

If you also need control over the balloon tip's position, you can use the following constructor:

BalloonTip(JComponent attachedComponent, JComponent contents, BalloonTipStyle style, Orientation orientation, AttachLocation attachLocation, int horizontalOffset, int verticalOffset, boolean useCloseButton)

This constructor has four new parameters:

  • orientation: Determines whether you want the tip of the balloon on the left or right side of the balloon, and whether the balloon itself should be above or below the attached component
  • attachLocation: Should the balloon tip align itself with the attached component? Or should it put the balloon's tip on a fixed location? (e.g. fix the balloon's tip in the center of the attached component)
  • horizontalOffset: The amount of space (in pixels) between the balloon's left (or right) side and the tip of the balloon
  • verticalOffset: The amount of space (in pixels) between the balloon's bottom (or top) side and the tip of the balloon

In order to clarify the horizontalOffset and verticalOffset parameters a bit better, have a look at this picture:

The horizontal and vertical offset of a BalloonTip
The horizontal and vertical offset of a BalloonTip

Here's a snippet of code that creates a balloon tip using this constructor:

BalloonTipStyle edgedLook = new EdgedBalloonStyle(Color.WHITE, Color.BLUE);
BalloonTip myBalloonTip = new BalloonTip(myButton, new JLabel("Hello world!"), edgedLook, Orientation.RIGHT_BELOW, AttachLocation.ALIGNED, 40, 20, false);

This snippet will produce the following picture:

A BalloonTip with Orientation.RIGHT_BELOW and AttachLocation.ALIGNED
A BalloonTip with Orientation.RIGHT_BELOW and AttachLocation.ALIGNED
1.3.5. Balloon tips with custom positioners

Finally, if you want full control over your balloon tip, use this constructor:

BalloonTip(JComponent attachedComponent, JComponent contents, BalloonTipStyle style, BalloonTipPositioner positioner, boolean useCloseButton)

Even though this constructor has fewer parameters than the previous one from section 1.3.4, it is more powerful. This is because of the positioner parameter. A BalloonTipPositioner defines the way a balloon tip should behave. More specifically: it determines where a balloon tip should position itself, whether the balloon tip should flip, what happens when the balloon tip collides with something, ...
What the previous constructors actually did was simply instantiating the appropriate BalloonTipPositioner for you. However, this constructor will allow you to supply your own instance of BalloonTipPositioner. Here's another example snippet that produces exactly the same result as the example in the previous section:

BalloonTipStyle edgedLook = new EdgedBalloonStyle(Color.WHITE, Color.BLUE);
BalloonTipPositioner rightBelowPositioner = new Right_Below_Positioner(40, 20);
BalloonTip myBalloonTip = new BalloonTip(myButton, "Hello world!", edgedLook, rightBelowPositioner, false);

This concludes the basic usage of BalloonTip. The other methods BalloonTip has to offer should now be quite straightforward to use. If you require more information, you can always refer to the project's Javadoc.

1.4. Other types of balloon tips
1.4.1. CustomBalloonTip

The CustomBalloonTip is just like a regular BalloonTip, but you can attach it to a rectangular shape within a component, instead of attaching it to the entire component.

This can be very useful in case you're creating your own JComponent, such as a timeline or a calendar.

An application with a custom JComponent that displays a timeline; it has a CustomBalloonTip attached to it
An application with a custom JComponent that displays a timeline; it has a CustomBalloonTip attached to it

Just take a look at this snippet of code, which was used in the demo application, just to see how it works:

// Create a custom JComponent that draws a huge white canvas with a small blue rectangle in it
final Rectangle customOffset = new Rectangle(640, 320, 50, 16);
final JComponent customComponent = new JComponent() {
protected void paintComponent(Graphics g) {
Rectangle clip = g.getClipBounds();
g.setColor(Color.WHITE);
g.fillRect(clip.x, clip.y, clip.width, clip.height);
g.setColor(Color.BLUE);
g.fillRect(customOffset.x, customOffset.y, customOffset.width, customOffset.height);
}
};
customComponent.setPreferredSize(new Dimension(1280, 640));

// Now create the CustomBalloonTip, such that it attaches itself to the blue rectangle
customBalloon = new CustomBalloonTip(customComponent,
"I'm a CustomBalloonTip!",
customOffset,
new EdgedBalloonStyle(Color.WHITE, Color.BLUE),
BalloonTip.Orientation.LEFT_ABOVE,
BalloonTip.AttachLocation.ALIGNED,
20, 20,
false);
1.4.2. TablecellBalloonTip

A TablecellBalloonTip is a balloon tip that attaches itself to a JTable cell. The TablecellBalloonTip is very similar to a CustomBalloonTip: Instead of specifying a rectangular offset, you specify a cell row and column. The row and column will determine which table cell the balloon tip should attach itself to.

1.5. Utilities
1.5.1. Timed balloon tips

Any balloon tip can be automatically closed after a certain period of time using the TimingUtils class. Here's an example:

BalloonTip balloonTip = new BalloonTip(someComponent, "I will dissapear in 3 seconds.");
// Now make the balloon tip disappear in 3000 milliseconds
TimingUtils.showTimedBalloon(balloonTip, 3000);
1.5.2. Fade effects

The FadingUtils class allows you to add a simple linear fade-in or fade-out effect to balloon tips. An example:

BalloonTip balloonTip = new BalloonTip(someComponent, "I will fade in over 300 ms.");
// Perform a fade-in effect lasting 300 ms, at 24 frames per second and trigger finishedAction once the effect has finished
FadingUtils.fadeInBalloon(balloonTip, finishedAction, 300, 24);
Tip: If you desire something more complex than a linear function, you could quite easily implement your own fade effects using the setOpacity method of BalloonTip in combination with, for example, timingframework.
1.5.3. Balloon tooltips

You can turn any balloon tip into a tooltip with the ToolTipUtilsclass. If you hover over the attached component, the balloon tip will show up after an initial delay and then stay visible until the mouse no longer hovers over the component or a timeout occurs, just like a regular tooltip. A quick example:

tooltipBalloon = new BalloonTip(someComponent, "I'm a balloon tooltip!");
// Now convert this balloon tip to a tooltip, such that the tooltip shows up after 500 milliseconds and stays visible for 3000 milliseconds
ToolTipUtils.balloonToToolTip(tooltipBalloon, 500, 3000);

2. Development
2.1. Importing the project
2.1.1. Eclipse, with Maven support

Because Balloon tip is suited for use with Maven, it's quite easy to import it as a Maven project into Eclipse. This can be done as follows:

  1. In order to import Maven projects into Eclipse, you'll need a plugin such as m2eclipse; install this first.
  2. If you haven't already done so, download and unzip the latest Balloon tip release from https://balloontip.dev.java.net.
  3. In Eclipse, go to "File" > "Import".
  4. Select "Maven" > "Existing Maven Projects".
  5. Click "Next".
  6. Click the "Browse" button next to "Root directory:" and select the "src" directory from the unpacked Balloon tip release.
  7. Click "Finish". The m2eclipse plugin will import Balloon tip as 3 different projects: balloontip, balloontip-examples and balloontip-parent:
    • balloontip: This is the most important project, as it contains all functionality of Balloon tip.
    • balloontip-examples: This project contains a few examples that demonstrate Balloon tip's functionality.
    • balloontip-parent: This parent project just groups balloontip and balloontip-examples. All Maven goals that are executed on balloontip-parent will be executed on both balloontip and balloontip-examples.
  8. All done! If all went well, you should be able to run net.java.balloontip.examples.complete.CompleteExample or any of the other supplied examples in the balloontip-examples project.

It doesn't matter much if you're not familiar with Maven; you can use the balloontip and balloontip-examples projects just like they were regular Java projects. The only difference with regular projects is that Maven projects have the added bonus of Maven's functionality, which is now at your disposal.

2.1.2. Eclipse, regular Java project

You can import Balloon tip as a regular Java project by following these steps:

  1. If you haven't already done so, download and unzip the latest Balloon tip release from https://balloontip.dev.java.net/.
  2. In Eclipse, create a new empty Java project:
    • Go to "File" > "New" > "Java Project".
    • Type a project name and click "Finish".
  3. Now go to "File" > "Import".
  4. Select "General" > "Archive File" and click "Next".
  5. Click "Browse" and choose the balloontip-examples- ... .jar file.
  6. Click "Finish".
  7. In the Package Explorer, expand your new project and drag the "net" folder into the "src" folder.
  8. All done! If all went well, you should be able to run net.java.balloontip.examples.complete.CompleteExample or any of the other supplied examples.
2.1.3. Maven

Balloon tip comes with its set of Maven POM files; you can use them as follows:

  1. If you haven't already done so, download and unzip the latest Balloon tip release from https://balloontip.dev.java.net/.
  2. Using your command-line-interface, navigate to the "src" folder.
  3. You're now located inside the balloontip-parent module; it contains two submodules: balloontip and balloontip-examples. To produce a .jar file for each module, run the command mvn package.
  4. If all went well, you should now be able to run the example application by executing src/balloontip-examples/target/balloontip-examples- ... .jar
2.1.4. Ant

While Balloon tip doesn't come with any Ant build files, it's quite easy to automatically generate them if you have Maven installed:

  1. If you haven't already done so, download and unzip the latest Balloon tip release from https://balloontip.dev.java.net/.
  2. Using your command-line-interface, navigate to the "src" folder.
  3. Run the command mvn ant:ant to generate Ant build files for Balloon tip. (You'll need Maven to be able to execute this command.)
  4. After Maven has successfully generated Ant build files, you'll be able to run the usual set of Ant tasks: compile, jar, javadoc, clean, ...
2.2. Creating your own BalloonTipStyle

Creating a new balloon tip style is fairly easy if you're a bit familiar with Java's Graphics API. To start making your own balloon tip style, you should extend the BalloonTipStyle class. In this class, you should at least override these two methods:

getBorderInsets is a method that determines where the actual contents of the balloon tip (the text, the close button, ...) should go. (If you're familiar with Cascading Style Sheets (CSS), you should think of getBorderInsets as a method that returns the padding of your balloon tip.) What you should do is return an Insets object, which holds four integers. To determine these four, take a look at this picture:

These four values are needed by getBorderInsets
These four values are needed by getBorderInsets

Suppose the green rectangle in the above picture represents where the contents of the balloon tip should come. The implementation of getBorderInsets then looks like this:

return new Insets(top, left, bottom, right);

The second method you should implement, paintBorder, draws the balloon tip on a Graphics instance. You've got a couple of different values to work with here. The obvious ones are the x, y, width and height-parameters. x and y determine the top-left coordinate of your drawing canvas, whereas width and height obviously represent the width and height of the drawing canvas.
Beside these parameters, you should also take into account the current values of the fields in BalloonTipStyle: horizontalOffset, verticalOffset, flipX and flipY. The meaning of these fields should become clear when looking at this image:

A BalloonTipStyle should respect the current values of horizontalOffset, verticalOffset, flipX and flipY
A BalloonTipStyle should respect the current values of horizontalOffset, verticalOffset, flipX and flipY

Keep in mind that you must take into account flipX and flipY when implementing getBorderInsets, as they have their effect on border insets!

Apart from getBorderInsets and paintBorder, you may also want to override the methods getMinimalHorizontalOffset and isBorderOpaque. Override getMinimalHorizontalOffset to define the minimum value of the horizontal offset. You may want to do this if your balloon tip starts to look funny if you go below (or above) a certain horizontal offset. Balloon tip positioners will then respect the minimum horizontal offset you've defined. Secondly, you should override isBorderOpaque if you wish to use transparency effects. If so, simply make the method return false and you're allowed to use transparent colors.

Apart from all of the above, there really is nothing else to know about balloon tip styles. However, I did assume you are familiar with the Java Graphics API. If you're not, I recommend you to take a couple of tutorials (such as http://java.sun.com/docs/books/tutorial/2d/index.html), or take a look at the code of the existing styles in Balloon tip.

2.3. Creating your own BalloonTipPositioner

The task of a balloon tip positioner is to define the behaviour of a balloon tip. This means it controls the position of the balloon tip, the horizontal and vertical offset of the balloon tip and whether the balloon tip should be flipped or not. The best way to learn how to create your own BalloonTipPositioner is by looking at an example. The following example demonstrates a very simple positioner that will place the balloon tip at a fixed location relative to the attached component:


public class SimpleTipPositioner extends BalloonTipPositioner {
int x = 0; // Current X-coordinate of the top-left corner of the bounding box around the balloon tip
int y = 0; // Current Y-coordinate of the top-left corner of the bounding box around the balloon tip

/* The balloon tip will call this method every time it wants to re-draw itself.
* The parameter of this function, attached, is the Rectangle that the balloon tip should attach itself to. */
public void determineAndSetLocation(Rectangle attached) {
/* Calculate the coordinates of the top-left corner of the bounding box around the balloon tip
* This positioner will place the balloon tip above the attached Rectangle. */
x = attached.x;
y = attached.y - balloonTip.getPreferredSize().height;

// Now move the balloon tip to the position we've just calculated
balloonTip.setBounds(x, y, balloonTip.getPreferredSize().width, balloonTip.getPreferredSize().height);
balloonTip.validate();
}

/* This method should return the location of the balloon's tip */
public Point getTipLocation() {
/* You may use the last position calculated in determineAndSetLocation to calculate the tip's location.
* The fields x and y now contain the position of the top-left corner of the bounding box of the balloon tip. */
return new Point(x + 20, y + balloonTip.getPreferredSize().height);
}

/* Whenever a balloon tip's style is changed (This includes setting it for the first time..), this method is called.
* Within this method, the positioner should take care of properly setting up this new style. */
protected void onStyleChange() {
balloonTip.getStyle().setHorizontalOffset(20);
balloonTip.getStyle().setVerticalOffset(20);
balloonTip.getStyle().flipX(false);
balloonTip.getStyle().flipY(false);

}
}

Using this positioner will produce the following result:

A BalloonTip with a simple custom-made BalloonTipPositioner
A BalloonTip with a simple custom-made BalloonTipPositioner

Here's the same picture once more, but this time it also shows the various variables that were used:

The variables that were used when calculating the balloon tip's position
The variables that were used when calculating the balloon tip's position

This image may also prove useful; it shows the different settings of the balloon tip's style:

Don't forget to set these variables of the balloon tip's style: horizontalOffset, verticalOffset, flipX and flipY
Don't forget to set these variables of the balloon tip's style: horizontalOffset, verticalOffset, flipX and flipY

After examining this example, you can conclude that:

Lastly, a couple of pointers that you may find useful:

While this particular example did not produce anything spectacular, you can do some neat things with your own balloon tip positioner. You could implement a positioner that, for example: always puts the balloon's tip in the center, or tries to avoid overlapping with some other components, or tries to never move the balloon tip outside a certain area, or ...

3. Release notes