Project Info

This library is platform independent, it will run wherever there's a Java Virtual Machine.

Requirements:

Project Author

Paulo Roberto Massa Cereda

(São Paulo, Brazil)

Contact info is in the bottom of the page.

Project Status

  • Stable - 1.3
  • Development - 1.4

You can find both releases in the project page at Project Kenai or SourceForge.net.

Documentation

Click here to browse the online documentation.

Hosting

SourceForge.net

Project Kenai

Special Thanks

I'd like to say a special thanks to the the following projects and their contributors:

Sorry if I forgot anyone or any project in particular.

Trivia

Sometimes, you need more than just an idea. You need a name. What name should I call this new notification library? That question haunted me for some time.

One day, I was watching Blackadder, one of my favorite series. It was the second episode of the fourth season, named Corporal Punishment. It was about Captain Blackadder receiving numerous calls to the wrong number before finally having a call with orders to advance. He avoids going over the top by pretending the line is breaking up. He then throws away a telegram ordering him to advance on the grounds that it is wrongly addressed to "Catpain Blackudder" and also shoots a carrier pigeon (here's the hint!) relaying a message to go over the top. Upon inspection of the pigeon's message, however, it turns out that shooting carrier pigeons has become an offence punishable by court-martial, and Blackadder simply decides to eat the evidence for lunch.

After watching that, I had no doubt about the name I should give to the notification library: J (from Java) + Carrier + Pigeon. It really fits like a glove.

We didn't receive any messages, and Captain Blackadder did not shoot this delicious plump-breasted pigeon!

Speckled Jim + JCarrierPigeon = Epic win.

Release history

Release 1.3 includes more code improvements from the previous versions and a new notification queue manager in replacement of the multiple window support.

Release 1.2 brings more code improvements and optimization - some methods were entirely rewritten - and a new possibility of changing the speed of the notification effects.

Release 1.1 features code improvements from the previous release and full support of javax.swing.JWindow objects.

Release 1.0 is the proud first stable release of the JCarrierPigeon library, with full support of javax.swing.JFrame objects.

News Feed

You can receive news on commits, updates and releases. Just click the following link.


News Feed
Click here if you want to receive news on stable releases and tracking forums.

Be sure to setup your news reader correctly.

Disclaimer

This website is hosted at SourceForge.net.

Java is a registered trademark of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

No pigeons were harmed during the making and development of this library.

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.

This is the design view in NetBeans. Easy as pie. Hmmm pie...

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.

Running the example. The notification is being displayed at the bottom right of the screen.

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!

JCarrierPigeon on Windows JCarrierPigeon on Linux JCarrierPigeon on MacOSX

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.

Download the compiled code. 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.
Download the compiled code. 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";
Pirate Twitter Bird. You can also follow me in Twitter, if you want. Cheers!