Notifications
Sending Notification Bubbles with GLib.Notification
By now you've probably already seen the notification bubbles that appear on the top right of the screen. Notifications are a way to provide updates about the state of your app. For example, they can inform you that a long running background process has been completed or a new message has arrived. In this section we are going to show you just how to get them to work in your app.
Making Preparations
Create a new Gtk.Application
complete with a desktop launcher file, packaging, etc. You can review this in Our First App.
In your .desktop
file, add the line X-GNOME-UsesNotifications=true
to the end of the file. This is what will make your app appear in System Settings so that notification preferences can be set.
Sending Notifications
In your Application.vala
file, in the activate ()
function, create a new Gtk.Button
and add it to a Gtk.Box
with some margins. Then set that box as the child widget for your app's main window.
Finally, connect to the clicked ()
signal of that button, and create a new Notification
with body text, and then send it with send_notification ()
.
Now build and run your app, and click the "Notify" button. Congratulations, you've learned how to send notifications!
Badge Icons
Notifications will automatically contain your app's icon, but you can add additional context by setting a badge icon. Right after the line containing var notification = New Notification
, add:
Build and run your app again, and press the "Notify" button. As you can see, the notification now has a smaller badged icon placed over your app's icon. Using this method, you can set the icon to any of the named icons shipped with elementary OS.
You can browse the full set of named icons using the Icon Browser app, available in AppCenter.
Buttons
You can also add buttons to notifications that will trigger actions defined in the app
namespace. To add a button, first define an action in your Application class as we did in the actions section.
Now, we can add a button to the notification with a label and the action ID.
Build and run your app again, and press the "Notify" button. Notice that the notification now has a button with the label "Quit" and clicking it will close your app.
Remember that SimpleAction
s added in the Application
class with add_action ()
are automatically added in the app
namespace. Notifications can't trigger actions defined in other namespaces like win
.
Priority
Notifications also have priority. When a notification is set as URGENT
it will stay on the screen until either you interact with it, or your application withdraws it. To make an urgent notification, use the set_priority ()
function
URGENT
notifications should really only be used on the most extreme cases. There are also other notification priorities.
Replace
We now know how to send a notification, but what if you need to update it with new information? Thanks to the id
argument of the send_notification ()
function, we can replace a notification with a matching ID. This ID can be anything you like.
Make a new button with the label "Replace" that sends a new notification, this time with an ID. This button will replace a notification with a matching ID when clicked, instead of sending a new notification.
Build and run your app again. Click on the buttons, first on "Notify", then "Replace". See how the "Notify" button sends a new notification each time it's clicked, but the "Replace" button replaces the contents of the same notification when it's clicked.
Review
Let's review what all we've learned:
We built an app that sends notifications.
Notifications automatically get our app's icon, but we can also add a badge icon
We can add buttons that trigger actions in the
app
namespaceNotifications can have a priority which affects their behavior
We can replace outdated notifications by setting a replaces ID
If you're having trouble, you can view the full example code here on GitHub. You can learn more from GLib.Notification
reference documentation.
Last updated