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"
26 #include "gioenumtypes.h"
29 * SECTION:gnotification
30 * @short_description: User Notifications (pop up messages)
33 * #GNotification is a mechanism for creating a notification to be shown
34 * to the user -- typically as a pop-up notification presented by the
35 * desktop environment shell.
37 * The key difference between #GNotification and other similar APIs is
38 * that, if supported by the desktop environment, notifications sent
39 * with #GNotification will persist after the application has exited,
40 * and even across system reboots.
42 * Since the user may click on a notification while the application is
43 * not running, applications using #GNotification should be able to be
44 * started as a D-Bus service, using #GApplication.
46 * User interaction with a notification (either the default action, or
47 * buttons) must be associated with actions on the application (ie:
48 * "app." actions). It is not possible to route user interaction
49 * through the notification itself, because the object will not exist if
50 * the application is autostarted as a result of a notification being
53 * A notification can be sent with g_application_send_notification().
61 * This structure type is private and should only be accessed using the
67 typedef GObjectClass GNotificationClass;
76 GNotificationPriority priority;
78 gchar *default_action;
79 GVariant *default_action_target;
89 G_DEFINE_TYPE (GNotification, g_notification, G_TYPE_OBJECT);
92 button_free (gpointer data)
94 Button *button = data;
96 g_free (button->label);
97 g_free (button->action_name);
99 g_variant_unref (button->target);
101 g_slice_free (Button, button);
105 g_notification_dispose (GObject *object)
107 GNotification *notification = G_NOTIFICATION (object);
109 g_clear_object (¬ification->icon);
111 G_OBJECT_CLASS (g_notification_parent_class)->dispose (object);
115 g_notification_finalize (GObject *object)
117 GNotification *notification = G_NOTIFICATION (object);
119 g_free (notification->title);
120 g_free (notification->body);
121 g_free (notification->default_action);
122 if (notification->default_action_target)
123 g_variant_unref (notification->default_action_target);
124 g_ptr_array_free (notification->buttons, TRUE);
126 G_OBJECT_CLASS (g_notification_parent_class)->finalize (object);
130 g_notification_class_init (GNotificationClass *klass)
132 GObjectClass *object_class = G_OBJECT_CLASS (klass);
134 object_class->dispose = g_notification_dispose;
135 object_class->finalize = g_notification_finalize;
139 g_notification_init (GNotification *notification)
141 notification->buttons = g_ptr_array_new_full (2, button_free);
145 * g_notification_new:
146 * @title: the title of the notification
148 * Creates a new #GNotification with @title as its title.
150 * After populating @notification with more details, it can be sent to
151 * the desktop shell with g_application_send_notification(). Changing
152 * any properties after this call will not have any effect until
153 * resending @notification.
155 * Returns: a new #GNotification instance
160 g_notification_new (const gchar *title)
162 GNotification *notification;
164 g_return_val_if_fail (title != NULL, NULL);
166 notification = g_object_new (G_TYPE_NOTIFICATION, NULL);
167 notification->title = g_strdup (title);
173 * g_notification_get_title:
174 * @notification: a #GNotification
176 * Gets the title of @notification.
178 * Returns: the title of @notification
183 g_notification_get_title (GNotification *notification)
185 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
187 return notification->title;
191 * g_notification_set_title:
192 * @notification: a #GNotification
193 * @title: the new title for @notification
195 * Sets the title of @notification to @title.
200 g_notification_set_title (GNotification *notification,
203 g_return_if_fail (G_IS_NOTIFICATION (notification));
204 g_return_if_fail (title != NULL);
206 g_free (notification->title);
208 notification->title = g_strdup (title);
212 * g_notification_get_body:
213 * @notification: a #GNotification
215 * Gets the current body of @notification.
217 * Returns: (allow-none): the body of @notification
222 g_notification_get_body (GNotification *notification)
224 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
226 return notification->body;
230 * g_notification_set_body:
231 * @notification: a #GNotification
232 * @body: (allow-none): the new body for @notification, or %NULL
234 * Sets the body of @notification to @body.
239 g_notification_set_body (GNotification *notification,
242 g_return_if_fail (G_IS_NOTIFICATION (notification));
243 g_return_if_fail (body != NULL);
245 g_free (notification->body);
247 notification->body = g_strdup (body);
251 * g_notification_get_icon:
252 * @notification: a #GNotification
254 * Gets the icon currently set on @notification.
256 * Returns: (transfer none): the icon associated with @notification
261 g_notification_get_icon (GNotification *notification)
263 g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
265 return notification->icon;
269 * g_notification_set_icon:
270 * @notification: a #GNotification
271 * @icon: the icon to be shown in @notification, as a #GIcon
273 * Sets the icon of @notification to @icon.
278 g_notification_set_icon (GNotification *notification,
281 g_return_if_fail (G_IS_NOTIFICATION (notification));
283 if (notification->icon)
284 g_object_unref (notification->icon);
286 notification->icon = g_object_ref (icon);
290 * g_notification_get_priority:
291 * @notification: a #GNotification
293 * Returns the priority of @notification
297 GNotificationPriority
298 g_notification_get_priority (GNotification *notification)
300 g_return_val_if_fail (G_IS_NOTIFICATION (notification), G_NOTIFICATION_PRIORITY_NORMAL);
302 return notification->priority;
306 * g_notification_set_urgent:
307 * @notification: a #GNotification
308 * @urgent: %TRUE if @notification is urgent
310 * Deprecated in favor of g_notification_set_priority().
315 g_notification_set_urgent (GNotification *notification,
318 g_return_if_fail (G_IS_NOTIFICATION (notification));
320 g_notification_set_priority (notification, G_NOTIFICATION_PRIORITY_URGENT);
324 * g_notification_set_priority:
325 * @notification: a #GNotification
326 * @priority: a #GNotificationPriority
328 * Sets the priority of @notification to @priority. See
329 * #GNotificationPriority for possible values.
332 g_notification_set_priority (GNotification *notification,
333 GNotificationPriority priority)
335 g_return_if_fail (G_IS_NOTIFICATION (notification));
337 notification->priority = priority;
341 * g_notification_add_button:
342 * @notification: a #GNotification
343 * @label: label of the button
344 * @detailed_action: a detailed action name
346 * Adds a button to @notification that activates the action in
347 * @detailed_action when clicked. That action must be an
348 * application-wide action (starting with "app."). If @detailed_action
349 * contains a target, the action will be activated with that target as
352 * See g_action_parse_detailed_name() for a description of the format
353 * for @detailed_action.
358 g_notification_add_button (GNotification *notification,
360 const gchar *detailed_action)
364 GError *error = NULL;
366 g_return_if_fail (detailed_action != NULL);
368 if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
370 g_warning ("%s: %s", G_STRFUNC, error->message);
371 g_error_free (error);
375 g_notification_add_button_with_target_value (notification, label, action, target);
379 g_variant_unref (target);
383 * g_notification_add_button_with_target: (skip)
384 * @notification: a #GNotification
385 * @label: label of the button
386 * @action: an action name
387 * @target_format: (allow-none): a #GVariant format string, or %NULL
388 * @...: positional parameters, as determined by @target_format
390 * Adds a button to @notification that activates @action when clicked.
391 * @action must be an application-wide action (it must start with "app.").
393 * If @target_format is given, it is used to collect remaining
394 * positional parameters into a #GVariant instance, similar to
395 * g_variant_new(). @action will be activated with that #GVariant as its
401 g_notification_add_button_with_target (GNotification *notification,
404 const gchar *target_format,
408 GVariant *target = NULL;
412 va_start (args, target_format);
413 target = g_variant_new_va (target_format, NULL, &args);
417 g_notification_add_button_with_target_value (notification, label, action, target);
421 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
422 * @notification: a #GNotification
423 * @label: label of the button
424 * @action: an action name
425 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
427 * Adds a button to @notification that activates @action when clicked.
428 * @action must be an application-wide action (it must start with "app.").
430 * If @target is non-%NULL, @action will be activated with @target as
436 g_notification_add_button_with_target_value (GNotification *notification,
443 g_return_if_fail (G_IS_NOTIFICATION (notification));
444 g_return_if_fail (label != NULL);
445 g_return_if_fail (action != NULL && g_action_name_is_valid (action));
447 if (!g_str_has_prefix (action, "app."))
449 g_warning ("%s: action '%s' does not start with 'app.'."
450 "This is unlikely to work properly.", G_STRFUNC, action);
453 button = g_slice_new0 (Button);
454 button->label = g_strdup (label);
455 button->action_name = g_strdup (action);
458 button->target = g_variant_ref_sink (target);
460 g_ptr_array_add (notification->buttons, button);
464 * g_notification_get_n_buttons:
465 * @notification: a #GNotification
467 * Returns: the amount of buttons added to @notification.
470 g_notification_get_n_buttons (GNotification *notification)
472 return notification->buttons->len;
476 * g_notification_get_button:
477 * @notification: a #GNotification
478 * @index: index of the button
479 * @label: (): return location for the button's label
480 * @action: (): return location for the button's associated action
481 * @target: (): return location for the target @action should be
484 * Returns a description of a button that was added to @notification
485 * with g_notification_add_button().
487 * @index must be smaller than the value returned by
488 * g_notification_get_n_buttons().
491 g_notification_get_button (GNotification *notification,
499 button = g_ptr_array_index (notification->buttons, index);
502 *label = g_strdup (button->label);
505 *action = g_strdup (button->action_name);
508 *target = button->target ? g_variant_ref (button->target) : NULL;
512 * g_notification_get_button_with_action:
513 * @notification: a #GNotification
514 * @action: an action name
516 * Returns the index of the button in @notification that is associated
517 * with @action, or -1 if no such button exists.
520 g_notification_get_button_with_action (GNotification *notification,
525 for (i = 0; i < notification->buttons->len; i++)
529 button = g_ptr_array_index (notification->buttons, i);
530 if (g_str_equal (action, button->action_name))
539 * g_notification_get_default_action:
540 * @notification: a #GNotification
541 * @action: (allow-none): return location for the default action
542 * @target: (allow-none): return location for the target of the default action
544 * Gets the action and target for the default action of @notification.
546 * Returns: %TRUE if @notification has a default action
549 g_notification_get_default_action (GNotification *notification,
553 if (notification->default_action == NULL)
557 *action = g_strdup (notification->default_action);
561 if (notification->default_action_target)
562 *target = g_variant_ref (notification->default_action_target);
571 * g_notification_set_default_action:
572 * @notification: a #GNotification
573 * @detailed_action: a detailed action name
575 * Sets the default action of @notification to @detailed_action. This
576 * action is activated when the notification is clicked on.
578 * The action in @detailed_action must be an application-wide action (it
579 * must start with "app."). If @detailed_action contains a target, the
580 * given action will be activated with that target as its parameter.
581 * See g_action_parse_detailed_name() for a description of the format
582 * for @detailed_action.
584 * When no default action is set, the application that the notification
585 * was sent on is activated.
590 g_notification_set_default_action (GNotification *notification,
591 const gchar *detailed_action)
595 GError *error = NULL;
597 if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
599 g_warning ("%s: %s", G_STRFUNC, error->message);
600 g_error_free (error);
604 g_notification_set_default_action_and_target_value (notification, action, target);
608 g_variant_unref (target);
612 * g_notification_set_default_action_and_target: (skip)
613 * @notification: a #GNotification
614 * @action: an action name
615 * @target_format: (allow-none): a #GVariant format string, or %NULL
616 * @...: positional parameters, as determined by @target_format
618 * Sets the default action of @notification to @action. This action is
619 * activated when the notification is clicked on. It must be an
620 * application-wide action (it must start with "app.").
622 * If @target_format is given, it is used to collect remaining
623 * positional parameters into a #GVariant instance, similar to
624 * g_variant_new(). @action will be activated with that #GVariant as its
627 * When no default action is set, the application that the notification
628 * was sent on is activated.
633 g_notification_set_default_action_and_target (GNotification *notification,
635 const gchar *target_format,
639 GVariant *target = NULL;
643 va_start (args, target_format);
644 target = g_variant_new_va (target_format, NULL, &args);
648 g_notification_set_default_action_and_target_value (notification, action, target);
652 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
653 * @notification: a #GNotification
654 * @action: an action name
655 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
657 * Sets the default action of @notification to @action. This action is
658 * activated when the notification is clicked on. It must be an
659 * application-wide action (start with "app.").
661 * If @target is non-%NULL, @action will be activated with @target as
664 * When no default action is set, the application that the notification
665 * was sent on is activated.
670 g_notification_set_default_action_and_target_value (GNotification *notification,
674 g_return_if_fail (G_IS_NOTIFICATION (notification));
675 g_return_if_fail (action != NULL && g_action_name_is_valid (action));
677 if (!g_str_has_prefix (action, "app."))
679 g_warning ("%s: action '%s' does not start with 'app.'."
680 "This is unlikely to work properly.", G_STRFUNC, action);
683 g_free (notification->default_action);
684 g_clear_pointer (¬ification->default_action_target, g_variant_unref);
686 notification->default_action = g_strdup (action);
689 notification->default_action_target = g_variant_ref_sink (target);
693 g_notification_serialize_button (Button *button)
695 GVariantBuilder builder;
697 g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
699 g_variant_builder_add (&builder, "{sv}", "label", g_variant_new_string (button->label));
700 g_variant_builder_add (&builder, "{sv}", "action", g_variant_new_string (button->action_name));
703 g_variant_builder_add (&builder, "{sv}", "target", button->target);
705 return g_variant_builder_end (&builder);
709 g_notification_get_priority_nick (GNotification *notification)
711 GEnumClass *enum_class;
715 enum_class = g_type_class_ref (G_TYPE_NOTIFICATION_PRIORITY);
716 value = g_enum_get_value (enum_class, g_notification_get_priority (notification));
717 nick = g_variant_new_string (value->value_nick);
718 g_type_class_unref (enum_class);
724 * g_notification_serialize:
726 * Serializes @notification into an floating variant of type a{sv}.
728 * Returns: the serialized @notification as a floating variant.
731 g_notification_serialize (GNotification *notification)
733 GVariantBuilder builder;
735 g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
737 if (notification->title)
738 g_variant_builder_add (&builder, "{sv}", "title", g_variant_new_string (notification->title));
740 if (notification->body)
741 g_variant_builder_add (&builder, "{sv}", "body", g_variant_new_string (notification->body));
743 if (notification->icon)
745 GVariant *serialized_icon;
747 if ((serialized_icon = g_icon_serialize (notification->icon)))
749 g_variant_builder_add (&builder, "{sv}", "icon", serialized_icon);
750 g_variant_unref (serialized_icon);
754 g_variant_builder_add (&builder, "{sv}", "priority", g_notification_get_priority_nick (notification));
756 if (notification->default_action)
758 g_variant_builder_add (&builder, "{sv}", "default-action",
759 g_variant_new_string (notification->default_action));
761 if (notification->default_action_target)
762 g_variant_builder_add (&builder, "{sv}", "default-action-target",
763 notification->default_action_target);
766 if (notification->buttons->len > 0)
768 GVariantBuilder actions_builder;
771 g_variant_builder_init (&actions_builder, G_VARIANT_TYPE ("aa{sv}"));
773 for (i = 0; i < notification->buttons->len; i++)
775 Button *button = g_ptr_array_index (notification->buttons, i);
776 g_variant_builder_add (&actions_builder, "@a{sv}", g_notification_serialize_button (button));
779 g_variant_builder_add (&builder, "{sv}", "buttons", g_variant_builder_end (&actions_builder));
782 return g_variant_builder_end (&builder);