2 * Copyright © 2013 Lars Uebernickel
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 * Authors: Lars Uebernickel <lars@uebernic.de>
22 #include "gnotification-private.h"
23 #include "gdbusutils.h"
28 * SECTION:gnotification
29 * @short_description: User Notifications (pop up messages)
32 * #GNotification is a mechanism for creating a notification to be shown
33 * to the user -- typically as a pop-up notification presented by the
34 * desktop environment shell.
36 * The key difference between #GNotification and other similar APIs is
37 * that, if supported by the desktop environment, notifications sent
38 * with #GNotification will persist after the application has exited,
39 * and even across system reboots.
41 * Since the user may click on a notification while the application is
42 * not running, applications using #GNotification should be able to be
43 * started as a D-Bus service, using #GApplication.
45 * User interaction with a notification (either the default action, or
46 * buttons) must be associated with actions on the application (ie:
47 * "app." actions). It is not possible to route user interaction
48 * through the notification itself, because the object will not exist if
49 * the application is autostarted as a result of a notification being
52 * A notification can be sent with g_application_send_notification().
60 * This structure type is private and should only be accessed using the
66 typedef GObjectClass GNotificationClass;
77 gchar *default_action;
78 GVariant *default_action_target;
88 G_DEFINE_TYPE (GNotification, g_notification, G_TYPE_OBJECT);
91 button_free (gpointer data)
93 Button *button = data;
95 g_free (button->label);
96 g_free (button->action_name);
98 g_variant_unref (button->target);
100 g_slice_free (Button, button);
104 g_notification_dispose (GObject *object)
106 GNotification *notification = G_NOTIFICATION (object);
108 g_clear_object (¬ification->icon);
110 G_OBJECT_CLASS (g_notification_parent_class)->dispose (object);
114 g_notification_finalize (GObject *object)
116 GNotification *notification = G_NOTIFICATION (object);
118 g_free (notification->title);
119 g_free (notification->body);
120 g_free (notification->default_action);
121 if (notification->default_action_target)
122 g_variant_unref (notification->default_action_target);
123 g_ptr_array_free (notification->buttons, TRUE);
125 G_OBJECT_CLASS (g_notification_parent_class)->finalize (object);
129 g_notification_class_init (GNotificationClass *klass)
131 GObjectClass *object_class = G_OBJECT_CLASS (klass);
133 object_class->dispose = g_notification_dispose;
134 object_class->finalize = g_notification_finalize;
138 g_notification_init (GNotification *notification)
140 notification->buttons = g_ptr_array_new_full (2, button_free);
144 * g_notification_new:
145 * @title: the title of the notification
147 * Creates a new #GNotification with @title as its title.
149 * After populating @notification with more details, it can be sent to
150 * the desktop shell with g_application_send_notification(). Changing
151 * any properties after this call will not have any effect until
152 * resending @notification.
154 * Returns: a new #GNotification instance
159 g_notification_new (const gchar *title)
161 GNotification *notification;
163 g_return_val_if_fail (title != NULL, NULL);
165 notification = g_object_new (G_TYPE_NOTIFICATION, NULL);
166 notification->title = g_strdup (title);
172 * g_notification_get_title:
173 * @notification: a #GNotification
175 * Gets the title of @notification.
177 * Returns: the title of @notification
182 g_notification_get_title (GNotification *notification)
184 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
186 return notification->title;
190 * g_notification_set_title:
191 * @notification: a #GNotification
192 * @title: the new title for @notification
194 * Sets the title of @notification to @title.
199 g_notification_set_title (GNotification *notification,
202 g_return_if_fail (G_IS_NOTIFICATION (notification));
203 g_return_if_fail (title != NULL);
205 g_free (notification->title);
207 notification->title = g_strdup (title);
211 * g_notification_get_body:
212 * @notification: a #GNotification
214 * Gets the current body of @notification.
216 * Returns: (allow-none): the body of @notification
221 g_notification_get_body (GNotification *notification)
223 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
225 return notification->body;
229 * g_notification_set_body:
230 * @notification: a #GNotification
231 * @body: (allow-none): the new body for @notification, or %NULL
233 * Sets the body of @notification to @body.
238 g_notification_set_body (GNotification *notification,
241 g_return_if_fail (G_IS_NOTIFICATION (notification));
242 g_return_if_fail (body != NULL);
244 g_free (notification->body);
246 notification->body = g_strdup (body);
250 * g_notification_get_icon:
251 * @notification: a #GNotification
253 * Gets the icon currently set on @notification.
255 * Returns: (transfer none): the icon associated with @notification
260 g_notification_get_icon (GNotification *notification)
262 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
264 return notification->icon;
268 * g_notification_set_icon:
269 * @notification: a #GNotification
270 * @icon: the icon to be shown in @notification, as a #GIcon
272 * Sets the icon of @notification to @icon.
277 g_notification_set_icon (GNotification *notification,
280 g_return_if_fail (G_IS_NOTIFICATION (notification));
282 if (notification->icon)
283 g_object_unref (notification->icon);
285 notification->icon = g_object_ref (icon);
289 * g_notification_get_urgent:
290 * @notification: a #GNotification
292 * Returns %TRUE if @notification is marked as urgent.
297 g_notification_get_urgent (GNotification *notification)
299 g_return_val_if_fail (G_IS_NOTIFICATION (notification), FALSE);
301 return notification->urgent;
305 * g_notification_set_urgent:
306 * @notification: a #GNotification
307 * @urgent: %TRUE if @notification is urgent
309 * Sets or unsets whether @notification is marked as urgent.
314 g_notification_set_urgent (GNotification *notification,
317 g_return_if_fail (G_IS_NOTIFICATION (notification));
319 notification->urgent = urgent;
323 * g_notification_add_button:
324 * @notification: a #GNotification
325 * @label: label of the button
326 * @detailed_action: a detailed action name
328 * Adds a button to @notification that activates the action in
329 * @detailed_action when clicked. That action must be an
330 * application-wide action (starting with "app."). If @detailed_action
331 * contains a target, the action will be activated with that target as
334 * See g_action_parse_detailed_name() for a description of the format
335 * for @detailed_action.
340 g_notification_add_button (GNotification *notification,
342 const gchar *detailed_action)
346 GError *error = NULL;
348 g_return_if_fail (detailed_action != NULL);
350 if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
352 g_warning ("%s: %s", G_STRFUNC, error->message);
353 g_error_free (error);
357 g_notification_add_button_with_target_value (notification, label, action, target);
361 g_variant_unref (target);
365 * g_notification_add_button_with_target: (skip)
366 * @notification: a #GNotification
367 * @label: label of the button
368 * @action: an action name
369 * @target_format: (allow-none): a #GVariant format string, or %NULL
370 * @...: positional parameters, as determined by @target_format
372 * Adds a button to @notification that activates @action when clicked.
373 * @action must be an application-wide action (it must start with "app.").
375 * If @target_format is given, it is used to collect remaining
376 * positional parameters into a #GVariant instance, similar to
377 * g_variant_new(). @action will be activated with that #GVariant as its
383 g_notification_add_button_with_target (GNotification *notification,
386 const gchar *target_format,
390 GVariant *target = NULL;
394 va_start (args, target_format);
395 target = g_variant_new_va (target_format, NULL, &args);
399 g_notification_add_button_with_target_value (notification, label, action, target);
403 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
404 * @notification: a #GNotification
405 * @label: label of the button
406 * @action: an action name
407 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
409 * Adds a button to @notification that activates @action when clicked.
410 * @action must be an application-wide action (it must start with "app.").
412 * If @target is non-%NULL, @action will be activated with @target as
418 g_notification_add_button_with_target_value (GNotification *notification,
425 g_return_if_fail (G_IS_NOTIFICATION (notification));
426 g_return_if_fail (label != NULL);
427 g_return_if_fail (action != NULL && g_action_name_is_valid (action));
429 if (!g_str_has_prefix (action, "app."))
431 g_warning ("%s: action '%s' does not start with 'app.'."
432 "This is unlikely to work properly.", G_STRFUNC, action);
435 button = g_slice_new0 (Button);
436 button->label = g_strdup (label);
437 button->action_name = g_strdup (action);
440 button->target = g_variant_ref_sink (target);
442 g_ptr_array_add (notification->buttons, button);
446 * g_notification_get_n_buttons:
447 * @notification: a #GNotification
449 * Returns: the amount of buttons added to @notification.
452 g_notification_get_n_buttons (GNotification *notification)
454 return notification->buttons->len;
458 * g_notification_get_button:
459 * @notification: a #GNotification
460 * @index: index of the button
461 * @label: (): return location for the button's label
462 * @action: (): return location for the button's associated action
463 * @target: (): return location for the target @action should be
466 * Returns a description of a button that was added to @notification
467 * with g_notification_add_button().
469 * @index must be smaller than the value returned by
470 * g_notification_get_n_buttons().
473 g_notification_get_button (GNotification *notification,
481 button = g_ptr_array_index (notification->buttons, index);
484 *label = g_strdup (button->label);
487 *action = g_strdup (button->action_name);
490 *target = button->target ? g_variant_ref (button->target) : NULL;
494 * g_notification_get_button_with_action:
495 * @notification: a #GNotification
496 * @action: an action name
498 * Returns the index of the button in @notification that is associated
499 * with @action, or -1 if no such button exists.
502 g_notification_get_button_with_action (GNotification *notification,
507 for (i = 0; i < notification->buttons->len; i++)
511 button = g_ptr_array_index (notification->buttons, i);
512 if (g_str_equal (action, button->action_name))
521 * g_notification_get_default_action:
522 * @notification: a #GNotification
523 * @action: (allow-none): return location for the default action
524 * @target: (allow-none): return location for the target of the default action
526 * Gets the action and target for the default action of @notification.
528 * Returns: %TRUE if @notification has a default action
531 g_notification_get_default_action (GNotification *notification,
535 if (notification->default_action == NULL)
539 *action = g_strdup (notification->default_action);
543 if (notification->default_action_target)
544 *target = g_variant_ref (notification->default_action_target);
553 * g_notification_set_default_action:
554 * @notification: a #GNotification
555 * @detailed_action: a detailed action name
557 * Sets the default action of @notification to @detailed_action. This
558 * action is activated when the notification is clicked on.
560 * The action in @detailed_action must be an application-wide action (it
561 * must start with "app."). If @detailed_action contains a target, the
562 * given action will be activated with that target as its parameter.
563 * See g_action_parse_detailed_name() for a description of the format
564 * for @detailed_action.
566 * When no default action is set, the application that the notification
567 * was sent on is activated.
572 g_notification_set_default_action (GNotification *notification,
573 const gchar *detailed_action)
577 GError *error = NULL;
579 if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
581 g_warning ("%s: %s", G_STRFUNC, error->message);
582 g_error_free (error);
586 g_notification_set_default_action_and_target_value (notification, action, target);
590 g_variant_unref (target);
594 * g_notification_set_default_action_and_target: (skip)
595 * @notification: a #GNotification
596 * @action: an action name
597 * @target_format: (allow-none): a #GVariant format string, or %NULL
598 * @...: positional parameters, as determined by @target_format
600 * Sets the default action of @notification to @action. This action is
601 * activated when the notification is clicked on. It must be an
602 * application-wide action (it must start with "app.").
604 * If @target_format is given, it is used to collect remaining
605 * positional parameters into a #GVariant instance, similar to
606 * g_variant_new(). @action will be activated with that #GVariant as its
609 * When no default action is set, the application that the notification
610 * was sent on is activated.
615 g_notification_set_default_action_and_target (GNotification *notification,
617 const gchar *target_format,
621 GVariant *target = NULL;
625 va_start (args, target_format);
626 target = g_variant_new_va (target_format, NULL, &args);
630 g_notification_set_default_action_and_target_value (notification, action, target);
634 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
635 * @notification: a #GNotification
636 * @action: an action name
637 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
639 * Sets the default action of @notification to @action. This action is
640 * activated when the notification is clicked on. It must be an
641 * application-wide action (start with "app.").
643 * If @target is non-%NULL, @action will be activated with @target as
646 * When no default action is set, the application that the notification
647 * was sent on is activated.
652 g_notification_set_default_action_and_target_value (GNotification *notification,
656 g_return_if_fail (G_IS_NOTIFICATION (notification));
657 g_return_if_fail (action != NULL && g_action_name_is_valid (action));
659 if (!g_str_has_prefix (action, "app."))
661 g_warning ("%s: action '%s' does not start with 'app.'."
662 "This is unlikely to work properly.", G_STRFUNC, action);
665 g_free (notification->default_action);
666 g_clear_pointer (¬ification->default_action_target, g_variant_unref);
668 notification->default_action = g_strdup (action);
671 notification->default_action_target = g_variant_ref_sink (target);
675 g_notification_serialize_button (Button *button)
677 GVariantBuilder builder;
679 g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
681 g_variant_builder_add (&builder, "{sv}", "label", g_variant_new_string (button->label));
682 g_variant_builder_add (&builder, "{sv}", "action", g_variant_new_string (button->action_name));
685 g_variant_builder_add (&builder, "{sv}", "target", button->target);
687 return g_variant_builder_end (&builder);
691 * g_notification_serialize:
693 * Serializes @notification into an floating variant of type a{sv}.
695 * Returns: the serialized @notification as a floating variant.
698 g_notification_serialize (GNotification *notification)
700 GVariantBuilder builder;
702 g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
704 if (notification->title)
705 g_variant_builder_add (&builder, "{sv}", "title", g_variant_new_string (notification->title));
707 if (notification->body)
708 g_variant_builder_add (&builder, "{sv}", "body", g_variant_new_string (notification->body));
710 if (notification->icon)
712 GVariant *serialized_icon;
714 if ((serialized_icon = g_icon_serialize (notification->icon)))
716 g_variant_builder_add (&builder, "{sv}", "icon", serialized_icon);
717 g_variant_unref (serialized_icon);
721 g_variant_builder_add (&builder, "{sv}", "urgent", g_variant_new_boolean (notification->urgent));
723 if (notification->default_action)
725 g_variant_builder_add (&builder, "{sv}", "default-action",
726 g_variant_new_string (notification->default_action));
728 if (notification->default_action_target)
729 g_variant_builder_add (&builder, "{sv}", "default-action-target",
730 notification->default_action_target);
733 if (notification->buttons->len > 0)
735 GVariantBuilder actions_builder;
738 g_variant_builder_init (&actions_builder, G_VARIANT_TYPE ("aa{sv}"));
740 for (i = 0; i < notification->buttons->len; i++)
742 Button *button = g_ptr_array_index (notification->buttons, i);
743 g_variant_builder_add (&actions_builder, "@a{sv}", g_notification_serialize_button (button));
746 g_variant_builder_add (&builder, "{sv}", "buttons", g_variant_builder_end (&actions_builder));
749 return g_variant_builder_end (&builder);