GNotification

As of GLib 2.39, it is no longer necessary to link against libnotify to create notifications in your application, GIO now provides an API for it: GNotification.

Preliminaries

GNotification integrates nicely in the GTK+ application framework. It expects you to use GApplication and GAction. See HowDoI/GtkApplication and HowDoI/GAction for hands-on information about making use of these in your application.

Warning: gnome-shell uses desktop files to find extra information (app icon, name) about the sender of the notification. If you don't have a desktop file whose base name matches the application id, then your notification will not show up.

Anatomy of a notification

A typical notification has a number of ingredients:

  • a one-line title

  • a longer, descriptive message body (optional)

  • an icon (optional)

  • actions, each with a label for use in a button (optional)

  • additionally, notifications may be marked as urgent

Creating a notification

example notification

To send a notification, first create a GNotification object, and add the data for your notification to it:

GNotification *notification;
GFile *file;
GFileIcon *icon;

notification = g_notification_new ("Lunch is ready");
g_notification_set_body (notification, "Today we have pancakes and salad, and fruit and cake for dessert");
file = g_file_new_for_path ("fruitbowl.png");
icon = g_file_icon_new (file);
g_notification_set_icon (notification, G_ICON (icon));
g_object_unref (icon);
g_object_unref (file);

Note that the title should be short; the body can be longer, say a paragraph. The icon may be displayed at a small size (say, 24x24), so choose an icon that is remains readable at small size.

To show your notification to the user, use the GApplication function for this purpose:

g_application_send_notification (application, "lunch-is-ready", notification);
g_object_unref (notification);

You need to provide an id for your notification here. This can be used if you want to make updates to an existing notification: simply send a notification with the same id. Note that the GNotification object does not have to be kept around after sending the notification; you can unref it right away. It is not a 'live' object that is associated with the visible notification.

Adding actions

notification with actions

Often, you want the user to be able to react to the notification in some way, other than just dismissing it. GNotification lets you do this by associating actions with your notification. These will typically be presented as buttons in the popup. One action has a special role, it is the 'default' action that gets activated when the user clicks on the notification, not on a particular button.

g_notification_set_default_action (notification, "app.go-to-lunch");
g_notification_add_button (notification, "5 minutes", "app.reply-5-minutes");
g_notification_add_button (notification, "Order takeout", "app.order-takeout");

The actions are referred to here with their 'app.' prefixed name. This indicates that the actions have to be added to your GApplication. You can learn how to do that in the GAction documentation. You can not use any other actions in GNotifications (window-specific actions with a 'win.' prefix will not work).

Actions with parameters

A common pattern is to pass a 'target' parameter to the action that contains sufficient details about the notification to let your application react in a meaningful way.

As an example, here is how a notification about a newly installed application could provide a launch button:

GNotification *notification;
gchar *title;

title = g_strdup_printf ("%s is now installed", appname);
notification = g_notification_new (title);
g_notification_add_button_with_target (notification, "Launch", "app.launch", "s", appid);

g_application_send_notification (application, "app-installed", notification);

g_object_unref (notification);
g_free (title);

To make this work, your application needs to have a suitable 'launch' action that takes the application id as a string parameter:

static GActionEntry actions[] = {
  { "launch", launch_application, "s", NULL, NULL },
  ...
}

g_action_map_add_action_entries (G_ACTION_MAP (application),
                                 actions, G_N_ELEMENTS (actions),
                                 application);

Persistence

An important advantage of GNotification over libnotify is that its API is designed to enable persistence. What I mean by that is that your application can exit after sending a notification, or the system might even reboot, and your notification is still there, waiting for the user to acknowledge it!

For this to work, you need to enable your application to be D-Bus activated. See HowDoI/DBusApplicationLaunching for details on how to do that.

If your application is D-Bus activatable, the desktop shell will activate it and trigger the correct action when the user interacts with the notification after your application has exited.

Stale notifications

Sometimes, a notification is no longer relevant and should not persist any longer. In those cases, you can explicitly withdraw it, like this:

if (now_is_tea_time ())
  g_application_withdraw_notification (application, "lunch-is-ready");