# Notifications
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](https://docs.elementary.io/develop/writing-apps/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.
{% code title="myapp.desktop" %}
```ini
[Desktop Entry]
Version=1.0
Type=Application
[...]
X-GNOME-UsesNotifications=true
```
{% endcode %}
## Sending Notifications
In your `Application.vala` file, in the `activate ()` function, create a new [`Gtk.Button`](https://valadoc.org/gtk4/Gtk.Button.html) and add it to a [`Gtk.Box`](https://valadoc.org/gtk4/Gtk.Box.html) with some margins. Then set that box as the child widget for your app's main window.
Finally, connect to the [`clicked ()`](https://valadoc.org/gtk4/Gtk.Button.clicked.html) signal of that button, and create a new `Notification` with body text, and then send it with [`send_notification ()`](https://valadoc.org/gio-2.0/GLib.Application.send_notification.html).
{% code title="Application.vala" %}
```vala
protected override void activate () {
var notify_button = new Gtk.Button.with_label ("Notify");
var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 12) {
margin_top = 12,
margin_end = 12,
margin_bottom = 12,
margin_start = 12
};
box.append (notify_button);
var headerbar = new Gtk.HeaderBar () {
show_title_buttons = true
};
var main_window = new Gtk.ApplicationWindow (this) {
child = box,
title = "MyApp",
titlebar = headerbar
};
main_window.present ();
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
send_notification (null, notification);
});
}
```
{% endcode %}
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:
```vala
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
notification.set_icon (new ThemedIcon ("process-completed"));
send_notification (null, notification);
});
```
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.
{% hint style="info" %}
You can browse the full set of named icons using the [Icon Browser](https://appcenter.elementary.io/io.elementary.iconbrowser/) app, available in AppCenter.
{% endhint %}
## 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](https://docs.elementary.io/develop/apis/actions).
{% code title="Application.vala" %}
```vala
public override void startup () {
base.startup ();
var quit_action = new SimpleAction ("quit", null);
add_action (quit_action);
quit_action.activate.connect (quit);
}
```
{% endcode %}
Now, we can add a button to the notification with a label and the action ID.
```vala
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
notification.add_button ("Quit", "app.quit");
send_notification (null, notification);
});
```
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.
{% hint style="info" %}
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`.
{% endhint %}
## Default Action
You may have noticed that when you click on a new notification, a new window pops up. This is happening because the notification has a default action that is executed when the user clicks on it. If you don't set it, it will `activate` your application, where we create a new window and present it.
You can change the default action using [`set_default_action ()`](https://valadoc.org/gio-2.0/GLib.Notification.set_default_action.html). The default action has to be in the `app` namespace. If you are unsure what that means, see [the actions section](https://docs.elementary.io/develop/apis/actions).
```vala
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
notification.set_default_action ("app.quit");
send_notification (null, notification);
});
```
If you want to avoid creating a new window every time your application is activated, you need to check if there is a window in [`Gtk.Application.active_window`](https://valadoc.org/gtk4/Gtk.Application.active_window.html) and present it instead.
{% code title="Application.vala" %}
```vala
protected override void activate () {
if (active_window != null) {
active_window.present ();
return;
}
var notify_button = new Gtk.Button.with_label ("Notify");
var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 12) {
margin_top = 12,
margin_end = 12,
margin_bottom = 12,
margin_start = 12
};
box.append (notify_button);
var headerbar = new Gtk.HeaderBar () {
show_title_buttons = true
};
main_window = new Gtk.ApplicationWindow (this) {
child = box,
title = "MyApp",
titlebar = headerbar
};
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
send_notification (null, notification);
});
main_window.present ();
}
```
{% endcode %}
## 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 ()`](https://valadoc.org/gio-2.0/GLib.Notification.set_priority.html) function
```vala
notify_button.clicked.connect (() => {
var notification = new Notification ("Hello World");
notification.set_body ("This is my first notification!");
notification.set_priority (NotificationPriority.URGENT);
send_notification (null, notification);
});
```
`URGENT` notifications should really only be used on the most extreme cases. There are also [other notification priorities](https://valadoc.org/gio-2.0/GLib.NotificationPriority).
## 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 ()`](https://valadoc.org/gio-2.0/GLib.Application.send_notification.html) 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.
```vala
protected override void activate () {
var notify_button = new Gtk.Button.with_label ("Notify");
var replace_button = new Gtk.Button.with_label ("Replace");
var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 12) {
margin_top = 12,
margin_end = 12,
margin_bottom = 12,
margin_start = 12
};
box.append (notify_button);
box.append (replace_button);
[...]
replace_button.clicked.connect (() => {
var notification = new Notification ("Hello Again");
notification.set_body ("This is my second Notification!");
send_notification ("update", 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](#sending-notifications).
* Notifications automatically get our app's icon, but we can also [add a badge icon](#badge-icons)
* We can [add buttons](#buttons) that trigger actions in the `app` namespace
* Notifications can have a [priority](#priority) which affects their behavior
* We can [replace outdated notifications](#replace) by setting a replaces ID
{% hint style="info" %}
If you're having trouble, you can view the full example code [here on GitHub.](https://github.com/vala-lang/examples/tree/glib-notification) You can learn more from `GLib.Notification` [reference documentation](https://valadoc.org/gio-2.0/GLib.Notification.html).
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.elementary.io/develop/apis/notifications.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
