GNOME.org

GNotification

GNotification — User Notifications (pop up messages)

Functions

GNotification * g_notification_new ()
void g_notification_set_title ()
void g_notification_set_body ()
void g_notification_set_icon ()
void g_notification_set_priority ()
void g_notification_set_urgent ()
void g_notification_set_default_action ()
void g_notification_set_default_action_and_target ()
void g_notification_set_default_action_and_target_value ()
void g_notification_add_button ()
void g_notification_add_button_with_target ()
void g_notification_add_button_with_target_value ()

Types and Values

  GNotification
enum GNotificationPriority

Object Hierarchy

    GEnum
    ╰── GNotificationPriority
    GObject
    ╰── GNotification

Includes

#include <gio/gio.h>

Description

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

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 g_application_send_notification().

Functions

g_notification_new ()

GNotification *
g_notification_new (const gchar *title);

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

the title of the notification

  

Returns

a new GNotification instance

Since: 2.40

g_notification_set_title ()

void
g_notification_set_title (GNotification *notification,
                          const gchar *title);

Sets the title of notification to title .

Parameters

notification

a GNotification

  

title

the new title for notification

 

Since: 2.40

g_notification_set_body ()

void
g_notification_set_body (GNotification *notification,
                         const gchar *body);

Sets the body of notification to body .

Parameters

notification

a GNotification

  

body

the new body for notification , or NULL.

[nullable]

Since: 2.40

g_notification_set_icon ()

void
g_notification_set_icon (GNotification *notification,
                         GIcon *icon);

Sets the icon of notification to icon .

Parameters

notification

a GNotification

  

icon

the icon to be shown in notification , as a GIcon

  

Since: 2.40

g_notification_set_priority ()

void
g_notification_set_priority (GNotification *notification,
                             GNotificationPriority priority);

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

Parameters

notification

a GNotification

  

priority

a GNotificationPriority

  

g_notification_set_urgent ()

void
g_notification_set_urgent (GNotification *notification,
                           gboolean urgent);

g_notification_set_urgent has been deprecated since version 2.42 and should not be used in newly-written code.

Since 2.42, this has been deprecated in favour of g_notification_set_priority().

Deprecated in favor of g_notification_set_priority().

Parameters

notification

a GNotification

  

urgent

TRUE if notification is urgent

  

Since: 2.40

g_notification_set_default_action ()

void
g_notification_set_default_action (GNotification *notification,
                                   const gchar *detailed_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.

Parameters

notification

a GNotification

  

detailed_action

a detailed action name

  

Since: 2.40

g_notification_set_default_action_and_target ()

void
g_notification_set_default_action_and_target
                               (GNotification *notification,
                                const gchar *action,
                                const gchar *target_format,
                                ...);

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.

[skip]

Parameters

notification

a GNotification

  

action

an action name

  

target_format

a GVariant format string, or NULL.

[nullable]

...

positional parameters, as determined by target_format

 

Since: 2.40

g_notification_set_default_action_and_target_value ()

void
g_notification_set_default_action_and_target_value
                               (GNotification *notification,
                                const gchar *action,
                                GVariant *target);

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

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

[rename-to g_notification_set_default_action_and_target]

Parameters

notification

a GNotification

  

action

an action name

  

target

a GVariant to use as action 's parameter, or NULL.

[nullable]

Since: 2.40

g_notification_add_button ()

void
g_notification_add_button (GNotification *notification,
                           const gchar *label,
                           const gchar *detailed_action);

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

notification

a GNotification

  

label

label of the button

  

detailed_action

a detailed action name

  

Since: 2.40

g_notification_add_button_with_target ()

void
g_notification_add_button_with_target (GNotification *notification,
                                       const gchar *label,
                                       const gchar *action,
                                       const gchar *target_format,
                                       ...);

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.

[skip]

Parameters

notification

a GNotification

  

label

label of the button

  

action

an action name

  

target_format

a GVariant format string, or NULL.

[nullable]

...

positional parameters, as determined by target_format

 

Since: 2.40

g_notification_add_button_with_target_value ()

void
g_notification_add_button_with_target_value
                               (GNotification *notification,
                                const gchar *label,
                                const gchar *action,
                                GVariant *target);

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

[rename-to g_notification_add_button_with_target]

Parameters

notification

a GNotification

  

label

label of the button

  

action

an action name

  

target

a GVariant to use as action 's parameter, or NULL.

[nullable]

Since: 2.40

Types and Values

GNotification

typedef struct _GNotification GNotification;

This structure type is private and should only be accessed using the public APIs.

Since: 2.40

enum GNotificationPriority

Priority levels for GNotifications.

Members

G_NOTIFICATION_PRIORITY_NORMAL

the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations)

  

G_NOTIFICATION_PRIORITY_LOW

for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather

  

G_NOTIFICATION_PRIORITY_HIGH

for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms)

  

G_NOTIFICATION_PRIORITY_URGENT

for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings)

  

Since: 2.42

Generated by GTK-Doc V1.33.1