The library

JCarrierPigeon is a small library written in Java that provides notification features to any javax.swing.JFrame or javax.swing.JWindow object. It currently supports multiple notifications through a notification queue manager. In order to achieve a greater effect, it's highly recommended to remove the window border of the provided javax.swing.JFrame. You don't need to worry about removing borders if you are using javax.swing.JWindow, since it has no borders at all.

License

This library is licensed under the New BSD License. I want to call your attention to the fact that the New BSD License has been verified as a GPL-compatible free software license by the Free Software Foundation, and has been vetted as an open source license by the Open Source Initiative.

Features

JCarrierPigeon has some nice features, including:

• Easy setup and use, no complicated procedures.
• Full support of javax.swing.JFrame and inherited classes.
• Full support of javax.swing.JWindow and inherited classes.
• Multiple notifications support.
• Very small library, less than 60kb, yet powerful.
• 100% pure Java library. No external system calls.

Neat!

Usage

JCarrierPigeon is very easy to use. The only requirement is a javax.swing.JFrame or javax.swing.JWindow object that will be the notification itself. I came up with this method in order to give freedom to the developer, so be sure you write a nice notification. I strongly recommend you to remove the borders of your javax.swing.JFrame object. No worries if you are using javax.swing.JWindow.

Consider the following class ExampleFrame extending javax.swing.JFrame. As you can see, the power of Java and object-oriented programming is once again implicit on the code. You may supply any class that inherits javax.swing.JFrame and you'll be just fine. I created this class in NetBeans.

As I said before, the only requirement is to ensure this class extends javax.swing.JFrame. Nothing more is needed.

public class ExampleFrame extends javax.swing.JFrame {

	...

}

Once we have our ExampleFrame done, it's time to create a notification. First of all, be sure to include the Timing Framework library in your classpath. And of course, include the JCarrierPigeon library as well.

ExampleFrame window = new ExampleFrame();
Notification note = new Notification(window, WindowPosition.BOTTOMRIGHT, 25, 25, 1000);
NotificationQueue queue = new NotificationQueue();
queue.add(note);

Wait a minute, is that it?! Yeah, plain and simple. It's the good old K.I.S.S. design principle: "Keep it simple, stupid". Now let's take a look on the parameters of the Notification class constructor methods:

public Notification(JFrame window, WindowPosition windowPosition, int borderX, int borderY, int duration)
public Notification(JWindow window, WindowPosition windowPosition, int borderX, int borderY, int duration)

• window is the window to act as a notification. Just keep in mind the provided javax.swing.JFrame or javax.swing.JWindow object is disposed after the notification being displayed. By the way, remove the borders in order to achieve a greater effect.
• windowPosition is the window position on screen. You may choose one amongst four states, each one representing the screen corners.
• borderX is the distance in pixels the window must keep from the X axis border. If the notification is right-aligned, this border will be from the right side, and so forth. Usually 50 pixels or less is an acceptable value for this parameter.
• borderY is the distance in pixels the window must keep from the Y axis border. If the notification is aligned from the top, this border will be from the top itself, and so forth. Usually 50 pixels or less is an acceptable value for this parameter.
• duration is the notification display duration in milliseconds. So if you want 2 seconds, you need to multiply it by 1000; 2 seconds times 1000 = 2000 milliseconds.

Those are pretty simple parameters. No complicated procedures involved.

From version 1.3 of JCarrierPigeon on, multiple window support is replaced by a notification queue system, where only a single notification is shown per time. We can see this manager in lines 3 and 4 of the previous code. Please note that this notification manager handles the calls for methods of the Notification class. After adding a notification to the queue, there is no need of calling any methods of the notification itself. To add a notification to the queue, we use the add method:

public synchronized void add(Notification notification)

If there is no notifications in the queue, the notification is displayed right after the call of the add method. Otherwise, it will be queued until there is no notifications in display. Please note this is a simple first in first out queue, so no priorities are estabilished when adding notifications.

The following screenshot refers to the execution of our example. With only three lines of code, we created a nice notification for our application.

Some say a picture is worth a thousand words. Then I guess a video may be worth a thousand pictures. The following video shows how the notification looks like. Please note that the speed of the notification effects were slowed down for better viewing and comprehension.

Just in case, if you want to change the speed of the notification effects, you may call the setAnimationSpeed method, overriding the default value:

public void setAnimationSpeed(int milliseconds)

• milliseconds is the notification effects duration in milliseconds. Usually 500 milliseconds or less is an acceptable value for this parameter.

Don't forget to call this method before adding the notification to the queue, and everything will just work fine.

That's it! A nice, easy, small and yet powerful notification library for your Java applications! I hope you like JCarrierPigeon!

Showcase

The following videos show JCarrierPigeon in action. The ExampleFrame class extending javax.swing.JFrame will be used in this demonstration. You probably may notice the windows are also displayed in the taskbar. This is a particularity of the javax.swing.JFrame class, so there's nothing I can do. If you want to avoid this behaviour, I recommend you to use javax.swing.JWindow instead. Have fun!

Choose the following operating system you want to see JCarrierPigeon in action and enjoy!

The following code was used in the Windows video shown above. It's self-explanatory.

NotificationQueue queue = new NotificationQueue();

ExampleFrame window1 = new ExampleFrame();
Notification note1 = new Notification(window1, WindowPosition.BOTTOMRIGHT, 25, 25, 1000);
queue.add(note1);

ExampleFrame window2 = new ExampleFrame();
Notification note2 = new Notification(window2, WindowPosition.BOTTOMRIGHT, 25, 25, 1000);
queue.add(note2);

ExampleFrame window3 = new ExampleFrame();
Notification note3 = new Notification(window3, WindowPosition.BOTTOMRIGHT, 25, 25, 3000);
queue.add(note3);

ExampleFrame window4 = new ExampleFrame();
Notification note4 = new Notification(window4, WindowPosition.BOTTOMRIGHT, 25, 25, 1000);
queue.add(note4);

There you go, easy as pie.

Download

JCarrierPigeon is licensed under the New BSD License. You may download the library in the compiled format or the source code as well.

	If you decide to download the JCarrierPigeon in the compiled format, that is, a jar file, please check the available releases in the project page hosted at SourceForge.net.
	Now, if you want to download the full source code, I kindly ask you to check the available source code repository in the project page hosted at Project Kenai. You may also contribute with code if you want.

Contact

You can contact me through SourceForge.net or Project Kenai. Such websites have internal messaging systems. If you prefer, you can also reach me through electronic mail.

# This is a Python code. Please, run the following
# line in your favorite Python interpreter.
# My e-mail should appear as result of this command.
# Thanks a lot.

"6365726564614075736572732e73662e6e6574".decode("hex")

If you didn't understand the code above, please try these other instructions:

// This is my e-mail. Please, replace the first (#) symbol
// by (@) and the second and third (#) symbols by (.).
// This was made in order to avoid spam. Thanks a lot.

return "cereda # users # sf # net";

You can also follow me in Twitter, if you want. Cheers!