Class: Gio::Notification

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Overview

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 [classGio.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
[ctorGio.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 [methodGio.Application.send_notification].

Instance Method Summary collapse

Constructor Details

#initialize(title) ⇒ Gio::Notification

Creates a new #GNotification 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.

Parameters:

  • title (String) —

    the title of the notification

Instance Method Details

#add_button(label, detailed_action) ⇒ nil

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.

Parameters:

  • label (String) —

    label of the button

  • detailed_action (String) —

    a detailed action name

Returns:

  • (nil)

#add_button_with_target(label, action, target_format, array) ⇒ nil

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 #GVariant instance, similar to
g_variant_new(). action will be activated with that #GVariant as its
parameter.

Parameters:

  • label (String) —

    label of the button

  • action (String) —

    an action name

  • target_format (String) —

    a #GVariant format string, or nil

  • array (Array) —

    positional parameters, as determined by target_format

Returns:

  • (nil)

#add_button_with_target_value(label, action, target) ⇒ nil

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

Parameters:

  • label (String) —

    label of the button

  • action (String) —

    an action name

  • target (GLib::Variant) —

    a #GVariant to use as action's parameter, or nil

Returns:

  • (nil)

#body=(body) ⇒ nil

Sets the body of notification to body.

Parameters:

  • body (String) —

    the new body for notification, or nil

Returns:

  • (nil)

#category=(category) ⇒ nil

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 (String) —

    the category for notification, or nil for no category

Returns:

  • (nil)

#default_action=(detailed_action) ⇒ nil

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.

Parameters:

  • detailed_action (String) —

    a detailed action name

Returns:

  • (nil)

#icon=(icon) ⇒ nil

Sets the icon of notification to icon.

Parameters:

  • icon (Gio::Icon) —

    the icon to be shown in notification, as a #GIcon

Returns:

  • (nil)

#priority=(priority) ⇒ nil

Sets the priority of notification to priority. See
GNotification::Priority for possible values.

Parameters:

Returns:

  • (nil)

#set_default_action_and_target(action, target_format, array) ⇒ nil

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 #GVariant instance, similar to
g_variant_new(). action will be activated with that #GVariant as its
parameter.

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

Parameters:

  • action (String) —

    an action name

  • target_format (String) —

    a #GVariant format string, or nil

  • array (Array) —

    positional parameters, as determined by target_format

Returns:

  • (nil)

#set_default_action_and_target_value(action, target) ⇒ nil

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-nil, 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 (String) —

    an action name

  • target (GLib::Variant) —

    a #GVariant to use as action's parameter, or nil

Returns:

  • (nil)

#title=(title) ⇒ nil

Sets the title of notification to title.

Parameters:

  • title (String) —

    the new title for notification

Returns:

  • (nil)

#urgent=(urgent) ⇒ nil

Deprecated in favor of g_notification_set_priority().

Parameters:

  • urgent (Boolean) —

    true if notification is urgent

Returns:

  • (nil)