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
.
Since: 2.40
g_notification_set_title ()
void
g_notification_set_title (GNotification *notification,
const gchar *title);
Sets the title of notification
to title
.
Since: 2.40
g_notification_set_body ()
void
g_notification_set_body (GNotification *notification,
const gchar *body);
Sets the body of notification
to body
.
Since: 2.40
g_notification_set_icon ()
void
g_notification_set_icon (GNotification *notification,
GIcon *icon);
Sets the icon of notification
to icon
.
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.
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]
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]
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
.
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]
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]
Since: 2.40