Home

Welcome to the DS Desktop Notify wiki! In the following page you will see how to make the best out of this library for displaying notifications in your desktop.

Importing DS Desktop Notify to your project

So far only .jar builds are available for this library, unfortunately. I am figuring out ways to get this project submitted to a repository, so you can expect releases for Maven in the future (most likely for a 1.0 release). In the meantime, registering the library manually in your PC and linking from there or simply adding the compiled .jar file as dependency the old-fashioned way are your best options.

Usage

As of v0.91 there are several ways to create and display notifications using DS Desktop Notify.

Through DesktopNotify.showDesktopMessage() methods

The class DesktopNotify provides by default a series of static methods that might look quite reminiscent of JOptionPane's showMessageDialog() methods, and those work indeed in the same fashion, allowing to easily create notifications while delegating their control fully to the underlying system.

These are some examples on their usage:

DesktopNotify.showDesktopMessage("Title", "This is a message.", DesktopNotify.INFORMATION);

DesktopNotify.showDesktopMessage("Title", "Watch this notification while you can!", DesktopNotify.DEFAULT, 5000);

DesktopNotify.showDesktopMessage("Error", "Task %id% failed successfully!", DesktopNotify.WARNING, 0,
        (evt) -> { System.out.println("OOF!"); });

DesktopNotify.showDesktopMessage("Very custom notification",
        "DS Desktop Notify includes everything you see in this box.\nAnd who knows? Maybe even more!",
        DesktopNotify.INFORMATION, yourOwnIcon, (evt) -> { System.out.println("Action!"); }, 15000);

Through a NotificationBuilder

While notification objects can't be directly instantiated, you can use a NotificationBuilder to build your very own notification and keep control of it. It works like most other builders, with chainable methods you can use to define only the properties you are interested into. This way of creating notifications is way more flexible than the use of those static methods from above and supports more properties on an individual basis, although it is still fairly straightforward.

DesktopNotify notification = new NotificationBuilder().setTitle("Title").setMessage("This is a message.")
        .setType(DesktopNotify.INFORMATION).setTheme(NotifyTheme.Light).build();
// [...]
notification.show();

You can also keep your NotificationBuilder with you and reuse some of the values set in it later, in order to create new notifications and display them.

NotificationBuilder builder = new NotificationBuilder().setTitle("System Notification").setTheme(NotifyTheme.Light);
// [...]
builder.setMessage("You got new mail!").setType(DesktopNotify.INFORMATION).build().show();
// [...]
builder.setMessage("Hard disc D:\ is running out of space!").setType(DesktopNotify.WARNING)
        .setAction((evt) -> { MyApplication.launchCleanupCenter(); }).build().show();

You can empty your builder's contents in any moment using the reset() method. There is also a buildAndReset() method if you don't feel like calling build() in order to get your notification and then resetting your builder in the next statement.

As a Service

In v0.90 a third way of displaying notifications was added: notification services. These are hosted in a given JVM process, and they can dispatch notifications submitted from not only the same virtual machine but others too, and even from processes that have nothing to do with Java at all. There are two ways to get this to work:

Through NotifyService

The NotifyService makes it possible to centralize control and display notifications in a single process for the current host, either physical or virtual. This way, several Java applications can share one queue of notifications, even if they are running in different JVM processes.

Usage of this service is pretty straightforward, although the supported options are quite limited, this to ensure compatibility across different processes.

NotifyService service = NotifyService.get(); //Connect to the service, or start it
service.postNotification("Some title", "A message", DesktopNotify.INFORMATION, DesktopNotify.LEFT_TO_RIGHT, 0, "dark");

That is pretty much everything this method supports so far. You can always set to null any parameters you don't want to use.

Under the hood the service is just listening on a local socket, so depending on the presence of such service, when you call NotifyService.get() you will either host this service through a NotifyServer, or connect to it through a NotifyClient. For this reason, holding onto the received instance of NotifyService for too long is not recommended, specially when you get a client; just poll for it with NotifyService.get() whenever you need it instead, so any process can take turns in displaying the notifications if for some reason it comes down to that.

You can stop the service if you are hosting it but don't feel like doing so anymore by calling close() on your received service object.

Through the command line

In addition to the NotifyService class, external processes can submit their own notifications to the service by running the built .jar in the command line. This can be done from non-Java applications and even through scripts. The usage looks like this:

java -jar DS-Desktop-Notify.jar -t "This is a title" -m "This is a message" -p 1
java -jar DS-Desktop-Notify.jar -m "This is quite a long message, with several lines although no title.\n\nEven several paragraphs!" -p 7
java -jar DS-Desktop-Notify.jar -t "Success" -m "All tasks have been completed!" -p 7 -e light

You can also take advantage of this mechanism to run DS Desktop Notify as a standalone process:

java -jar DS-Desktop-Notify.jar -h start

The CLI supports everything seen in NotifyService.postNotification(), the available commands are the following:

• -t or --title: The title to display.
• -m or --message: The message to display.
• -p or -type: The notification type [0~8]. See DesktopNotify.java.
• -a or --align: The layout orientation [0,1]. See DesktopNotify.java.
• -o or --timeout: The notification timeout, in milliseconds
• -e or --theme: The theme to display, either light or dark.
• -h or --host: For taking control of the service in your host. You can ask for it to start or stop.
• -v or --version: For displaying the version of the build you have started.

Any ideas for new functionality or improving what exists will be gladly listened to and considered, so please let me know if you have any.