Ubuntu Wiki

Ubuntu 9.04 and later use a new notification server, Notify OSD, to present notification bubbles that follow the freedesktop.org Desktop Notifications Specification. These are the notifications produced using the org.freedesktop.Notifications DBus interface, or by using the terminal command notify-send.

Notify OSD takes the place of notification-daemon, and its presentation of notification bubbles differs in several ways. So if you have written software that assumes notifications will always be presented by notification-daemon, you may need to adjust your code to be more compatible with Notify OSD and with the Desktop Notifications Specification in general..

Layout cases (with examples in C, Python and C#)

Everything not listed as a valid layout will lead to a "no-layout"-case (results in an empty notification-bubble). Also using non-existing (stock-)icon-names results in empty notification-bubbles. Common caues for the latter could be that the user has not set "Human" as the icon-theme and a notification is trying to use one of the new icon-name (see icons). The comment header of each sourcecode example contains compilation and run instructions. NOTE: The C#-examples don't format and display in thie MoinMoin wiki. You can only download them directly to your harddisk. Sorry for the inconvenience!

Icon-Summary-Body

example: IM-message

• example in C

• example in Python

• example in C#

Icon-Summary

example: Wifi connection lost

• example in C

• example in Python

• example in C#

Summary-Body

example: a very simple notification-bubble

• example in C

• example in Python

• example in C#

Summary-only

This layout-case works, but is strongly discouraged. Avoid it if you can.

• example in C

• example in Python

• example in C#

Concatenating related notification bubbles

For IM-clients (like pidgin) you can use the append-hint ("append"). For code examples in C, C# and Python please see notify-osd trunk (bzr branch lp:notify-osd). You will find the append-hint-example in notify-osd/examples. The Python one is the most current.

How to update an existing notification-bubble

Current configuration does not allow embedding of the file update-notifications.ogg because of its mimetype audio/ogg.: update-notifications.ogg

If you need to update the contents of an existing notification (remember the notification could have been not displayed yet or already been shown and closed) you can to that by keeping the object of you inital notification around and just use the update functionality of libnotify. For code examples in C, C# and Python please see notify-osd trunk (bzr branch lp:notify-osd). You will find the update-notifications in notify-osd/examples. The Python one is the most current.

Help! No libnotify bindings for language X

If your program is not in written in C, Python or C# and there are no language bindings for libnotify available for your language of choice, you can still fall back to using the command-line tool "notify-send" (provided by the package: libnotify-bin) to trigger a notification. But be aware that you do not have access to all available features (e.g. you cannot make use of the append-hint or simply update an existing bubble). Furthermore your language does need to provide some system() call or method, which allows you to spawn external commands.

Here's a list of the four layout-cases you can achieve by just using the command-line tool "notify-send":

• Icon-Summary-Body

notify-send "Cole Raby" "Hey pal, what's up with the party next weekend? Will you join me and Anna?" -i notification-message-im

• Icon-Summary

notify-send "WiFi connection lost" -i notification-network-wireless-disconnected

• Summary-Body

notify-send "Totem" "This is a superfluous notification"

• Summary-only

notify-send "Summary-only"

Things to avoid when using Notify-OSD

Notification actions

Because notification bubbles float on top of all other windows, and usually appear without warning, Notify OSD allows click-through. Hovering over a bubble makes it transparent, and you can click — or drag to or from — anything underneath the bubble. This avoids accidental clicks on bubbles or items inside them, and removes the need to close a bubble manually before working with anything underneath it (two problems common to notification balloons in Windows and Growl notifications in Mac OS X).

So Notify OSD bubbles cannot be clicked on themselves, nor can they contain buttons that can be clicked: in the terminology of the Desktop Notifications Specification, they do not accept actions. (This also means you no longer need to rush to click on something in a notification bubble before the bubble disappears.) This is explicitly allowed by the specification: “Some servers may not support user interaction at all, or may not support the concept of being able to ‘invoke’ a notification.” But to avoid breaking software that has assumed and relies on the existence of actions, Notify OSD presents any notification that uses them as an alert box instead of a bubble.

There are several ways to avoid actions producing unwanted alert boxes with Notify OSD. Which approach is best for you depends on what you are using the buttons for.

• If the only button is “Do not show me this again” or similar, consider eliminating the notification entirely, or making it more obvious how to turn notifications on or off within the application’s interface.
• If the actions are for letting you read or reply to a human message (for example, an instant message or a status update), consider integrating your application with Ubuntu’s messaging menu. (Guidelines for doing this will be available soon.)
• If the buttons are for acting on a recurring type of event (such as a download), consider instead using a window that lists the events, possibly with the date and time of each. Depending on their urgency, this window may request attention when one of these events happens.

• If the notification exists only to invite you to open another window, consider opening that window unfocused directly, instead of showing the notification.

• If the notification provides an extra access point for a function that is already easy to access from elsewhere in the software, consider making the actions conditional on whether the notification server advertises that it accepts actions in general.

See the notification design guidelines for more detailed advice about choosing between notification bubbles and other notification mechanisms.

To detect whether a server accepts actions in general, use the org.freedesktop.Notifications.GetCapabilities command. In this example, “Previous” and “Next” actions are added to a notification if the notification server accepts actions.

C example code:

capabilities = notify_get_server_caps();
if(capabilities != NULL) {
    for(c = capabilities; c != NULL; c = c->next) {
        if(strcmp((char*)c->data, "actions") == 0 ) {
            accepts_actions = TRUE;
            break;
        }
    }
    g_list_foreach(capabilities, (GFunc)g_free, NULL);
    g_list_free(capabilities);
}

/* Adds "Previous" and "Next" buttons in the notification if allowed. */
if(accepts_actions) {
    notify_notification_add_action(
        notification, "previous", _("Previous"), Prev, (gpointer*) p_intf, NULL);
    notify_notification_add_action(
        notification, "next", _("Next"), Next, (gpointer*) p_intf, NULL );
}

Python example code:

caps = pynotify.get_server_caps()

if caps and 'actions' in caps:
    #Adds "Previous" and "Next" buttons in the notification if allowed.
    notification.add_action("previous", "Previous", Prev)
    notification.add_action("next", "Next", Next)

C# example code:

bool accepts_actions = Notifications.Global.Capabilities != null &&
                       Notifications.Global.Capabilities.Contains("actions");
if (accepts_actions) {
    nf.AddAction ("previous", Catalog.GetString("Previous"), OnSongPrevious);
    nf.AddAction ("next", Catalog.GetString("Next"), OnSongPrevious);
}

Non-expiring notifications

Because there is nothing in a Notify OSD bubble that responds to clicks or keypresses, there is no way it can be closed manually. Therefore, every bubble closes by itself after a timeout. This timeout is based on the length of the bubble’s text; Notify OSD does not use the expire_timeout parameter.

Some programs specify an expire_timeout of 0 to produce notifications that never close by themselves, assuming that they can be closed manually as they can in notification-daemon. Because this is usually done for a message that requires response or acknowledgement, Notify OSD presents it as an alert box rather than as a bubble.

• If a notification does not actually need response or acknowledgement, you can avoid it appearing as an alert box by setting the expire_timeout to the default value of -1.

• If a notification does need response or acknowledgement, consider presenting it using another mechanism, such as a more carefully designed alert box, or a placard embedded into a relevant window. See the notification design guidelines for more detailed advice about choosing between notification bubbles and other notification mechanisms.

Truncated text

To prevent a notification bubble from obscuring too much of the screen, Notify OSD limits a bubble’s width to 18 ems, its title text to three lines, and its body text to ten lines. Text longer than this is elided, indicated by an ellipsis (“…”) at the end of the title text or before the last eight lines of body text.

If your program frequently sends notifications with more text than this, consider either reducing the length of the notifications, or using a different mechanism to present them (such as a window that lists them and allows browsing and search).