Description

Gnome::Gio::Notification 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 Gnome::Gio::Notification and other similar APIs is that, if supported by the desktop environment, notifications sent with Gnome::Gio::Notification 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 Gnome::Gio::Notification should be able to be started as a D-Bus service, using Gnome::Gio::Notification.

In order for Gnome::Gio::Notification to work, the application must have installed a `.desktop` file. For example:

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 .newnotification() in class Gnome::Gio::Application.

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 .send-notification() in class Gnome::Gio::Application.

Uml Diagram

Class initialization

new

:native-object

Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object() :$native-object! )

new-notification

Creates a new Gnome::Gio::Notification with $title as its title.

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

method new-notification ( Str $title --> Gnome::Gio::Notification \)

• $title; the title of the notification.

Methods

add-button

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 g_action_parse_detailed_name() for a description of the format for $detailed-action.

method add-button ( Str $label, Str $detailed-action )

• $label; label of the button.

• $detailed-action; a detailed action name.

add-button-with-target This function is not yet available

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

If $target-format is given, it is used to collect remaining positional parameters into a Gnome::Glib::N-Variant instance, similar to g_variant_new(). $action will be activated with that Gnome::Glib::N-Variant as its parameter.

method add-button-with-target ( Str $label, Str $action, Str $target-format, … )

• $label; label of the button.

• $action; an action name.

• $target-format; a Gnome::Glib::N-Variant format string, or undefined.

• …; …. Note that each argument must be specified as a type followed by its value!

add-button-with-target-value

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-undefined, $action will be activated with $target as its parameter.

method add-button-with-target-value ( Str $label, Str $action, N-Object $target )

• $label; label of the button.

• $action; an action name.

• $target; a Gnome::Glib::N-Variant to use as $action's parameter, or undefined

set-body

Sets the body of $notification to $body.

method set-body ( Str $body )

• $body; the new body for $notification, or undefined.

set-category

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](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).

method set-category ( Str $category )

• $category; the category for $notification, or undefined for no category.

set-default-action

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 g_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.

method set-default-action ( Str $detailed-action )

• $detailed-action; a detailed action name.

set-default-action-and-target This function is not yet available

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 (it must start with "app.").

If $target-format is given, it is used to collect remaining positional parameters into a Gnome::Glib::N-Variant instance, similar to g_variant_new(). $action will be activated with that Gnome::Glib::N-Variant as its parameter.

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

method set-default-action-and-target ( Str $action, Str $target-format, … )

• $action; an action name.

• $target-format; a Gnome::Glib::N-Variant format string, or undefined.

• …; …. Note that each argument must be specified as a type followed by its value!

set-default-action-and-target-value

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-undefined, $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.

method set-default-action-and-target-value ( Str $action, N-Object $target )

• $action; an action name.

• $target; a Gnome::Glib::N-Variant to use as $action's parameter, or undefined

set-icon

Sets the icon of $notification to $icon.

method set-icon ( N-Object() $icon )

• $icon; the icon to be shown in $notification, as a Gnome::Gio::R-Icon.

set-priority

Sets the priority of $notification to $priority. See Gnome::Gio::T-ioenums for possible values.

method set-priority ( GNotificationPriority $priority )

• $priority; a Gnome::Gio::T-ioenums.

set-title

Sets the title of $notification to $title.

method set-title ( Str $title )

• $title; the new title for $notification.

set-urgent

Note: The native version of this routine is deprecated in gio-lib() since version 2.42

Deprecated in favor of .set-priority().

method set-urgent ( Bool() $urgent )

• $urgent; True if $notification is urgent.