Skip to content

Gio.Notification

class — extends GObject.Object

GNotification is a mechanism for creating a notification to be shown to the user — typically as a pop-up notification presented by the desktop environment shell.

The key difference between GNotification and other similar APIs is that, if supported by the desktop environment, notifications sent with GNotification will persist after the application has exited, and even across system reboots.

Since the user may click on a notification while the application is not running, applications using GNotification should be able to be started as a D-Bus service, using Application.

In order for GNotification to work, the application must have installed a .desktop file. For example: 

[Desktop Entry]
Name=Test Application
Comment=Description of what Test Application does
Exec=gnome-test-application
Icon=org.gnome.TestApplication
Terminal=false
Type=Application
Categories=GNOME;GTK;TestApplication Category;
StartupNotify=true
DBusActivatable=true
X-GNOME-UsesNotifications=true

The X-GNOME-UsesNotifications key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel.

The .desktop file must be named as org.gnome.TestApplication.desktop, where org.gnome.TestApplication is the ID passed to Application.new.

User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: app. actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked.

A notification can be sent with Application.send_notification.

In Windows, notification actions are unsupported, when sending the notification a warning will be printed if a default action or action buttons were added.

Constructors

new

@classmethod
def new(cls, title: str) -> Notification

Creates a new Notification with title as its title.

After populating notification with more details, it can be sent to the desktop shell with Application.send_notification. Changing any properties after this call will not have any effect until resending notification.

Parameters:

  • title — the title of the notification

Methods

add_button

def add_button(self, label: str, detailed_action: str) -> None

Adds a button to notification that activates the action in detailed_action when clicked. That action must be an application-wide action (starting with "app."). If detailed_action contains a target, the action will be activated with that target as its parameter.

See Action.parse_detailed_name for a description of the format for detailed_action.

Parameters:

  • label — label of the button
  • detailed_action — a detailed action name

add_button_with_target

def add_button_with_target(self, label: str, action: str, target: GLib.Variant | None = ...) -> None

Adds a button to notification that activates action when clicked. action must be an application-wide action (it must start with "app.").

If target is non-None, action will be activated with target as its parameter.

Parameters:

  • label — label of the button
  • action — an action name
  • target — a GLib.Variant to use as action's parameter, or None

set_body

def set_body(self, body: str | None = ...) -> None

Sets the body of notification to body.

Parameters:

  • body — the new body for notification, or None

set_category

def set_category(self, category: str | None = ...) -> None

Sets the type of notification to category. Categories have a main type like email, im or device and can have a detail separated by a ., e.g. im.received or email.arrived. Setting the category helps the notification server to select proper feedback to the user.

Standard categories are listed in the specification.

Parameters:

  • category — the category for notification, or None for no category

set_default_action

def set_default_action(self, detailed_action: str) -> None

Sets the default action of notification to detailed_action. This action is activated when the notification is clicked on.

The action in detailed_action must be an application-wide action (it must start with "app."). If detailed_action contains a target, the given action will be activated with that target as its parameter. See Action.parse_detailed_name for a description of the format for detailed_action.

When no default action is set, the application that the notification was sent on is activated.

Parameters:

  • detailed_action — a detailed action name

set_default_action_and_target

def set_default_action_and_target(self, action: str, target: GLib.Variant | None = ...) -> None

Sets the default action of notification to action. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app.").

If target is non-None, action will be activated with target as its parameter. If target is floating, it will be consumed.

When no default action is set, the application that the notification was sent on is activated.

Parameters:

  • action — an action name
  • target — a GLib.Variant to use as action's parameter, or None

set_icon

def set_icon(self, icon: Icon) -> None

Sets the icon of notification to icon.

Parameters:

  • icon — the icon to be shown in notification, as a Icon

set_priority

def set_priority(self, priority: NotificationPriority | int) -> None

Sets the priority of notification to priority. See NotificationPriority for possible values.

Parameters:

set_title

def set_title(self, title: str) -> None

Sets the title of notification to title.

Parameters:

  • title — the new title for notification

set_urgent

def set_urgent(self, urgent: bool) -> None

:::warning Deprecated since 2.42 This API is deprecated. :::

Deprecated in favor of Notification.set_priority.

Parameters:

  • urgent — True if notification is urgent