If you are unfamiliar with SwingX, please read our SwingX introductory tutorial. SwingX introduces a lot of new components to Swing, and this tutorial will cover the busy label. The latest build of SwingX (after 0.9.1 milestone release) has some significant, and much needed, changes implemented by Jan Haderka.
What is a busy label?
Here’s an example of a busy icon that you will find in all kinds of apps: . The icon is meant to depict a task that is currently executing, that is of indeterminate length. The task may take 10 minutes or 10 seconds, there’s no way of knowing, and the user can’t really have an expectation of how long to wait.
SwingX provides an implementation of this functionality in the form of JXBusyLabel and BusyPainter. You can use the busy label just like you would a normal JXLabel, except that you can add a Painter to it, which controls the painting and animation of the busy label itself.
SwingX milestone 0.9.1
If you are using v0.9.1 milestone release, then you will still have JXBusyLabel, but a lot of the functionality described in this tutorial will not be available to you. For that you should download the latest build of the SwingX API. Not to worry, a build that works is included in the project files that you can download at the end of this tutorial.
Source code example
In the following example, I’m going to create 2 JXBusyLabel components, that I will place in a JXPanel. One will work with older SwingX releases (the simple label) and the complex label will require newer SwingX release (after 0.9.1). Here’s what it looks like:
This example creates 2 busy labels, one simple, and the other complex. The simple busy label will work with older versions of SwingX (0.9.1), but the complex one requires later builds. Both the busy labels start out disabled, and as you can see from the screenshot, they blend into the background when they are disabled. When you click on the “start/stop” button, it enables the labels, and calls setBusy(true) on them. This causes them to start spinning and getting animated. When you click on the button again, the setBusy(false) method is called, stopping the animation; they are still enabled, just not animated.
Simple busy label
Here’s the code to create a simple JXBusyLabel:
The code is very straightforward. It’s just like creating a simple JLabel. Note that it’s not possible to set the size of this JXBusyLabel using this constructor. In fact, this is one of the reasons you should use the latest build of SwingX, which adds a new constructor and lots more functionality to this component. Using this code results in a busy label that looks like this:
Complex busy label
Here’s the code to create a more complex JXBusyLabel:
There are a couple of things to note about this code:
- When you create the JXBusyLabel, you can pass a Dimension object to it, to specify the size of the busy label.
- In order to change the default look of the busy label, you have to leverage the BusyPainter class, which actually controls what the busy label looks like (background and highlight colors, shape of the label innards, etc), and how it animates (animation speed, etc). The good news is that you don’t have to code this by hand! Jan Haderka has been gracious enough to provide a program that allows you to configure all of this visually, and then it just spits out the code you need to insert in your program! Here’s a link to his program (JNLP launcher). Read more about this utility on his blog post. I recommend that you play with Jan’s program and try different things; you will be surprised the different kinds of busy labels you can come up with… it’s limited by your imagination.
- You can change the colors used by the busy painter using setBaseColor() and setHighlightColor(). The base color is the “background” color of the busy label, and the highlight color is what gets painted over it periodically. So if you use a base color of light blue, and highlight color of orange, you get something like this:
Rest of the code
In addition to the busy labels, there’s another JXLabel used in this example that uses a painter and an icon:
Here’s the code that makes this possible:
There are a few things to note about this code:
- To lean more about how the Images enumeration works, check out this tutorial where it’s introduced.
- I used HTML to set the text of this label, so that I could insert a line break.
- The painter used to render the background of this label uses a simple 2 stop linear gradient.
- I used an EmptyBorder around the label to give it more space around the text and image.
Complete source listing
There are a few things to note about this code:
- A JXPanel is used to contain all the components (labels, buttons, etc). and it’s transparency is set to 70% opaque, 30% clear. That’s why the sample program has a very muted/soft look to it.
- Be sure to launch your program in the Swing EDT and not the thread that’s running through your main() method.
- A call to JFrame’s setLocationRelativeTo(null) centers the JFrame on your computer screen.
Source code download
To download the IDEA projects for this tutorial’s source code example, click here.
Comments and feedback
To share your thoughts on this tutorial, please click here.