* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Authors: Lars Uebernickel <lars@uebernic.de>
*/
#include "gdbusutils.h"
#include "gicon.h"
#include "gaction.h"
+#include "gioenumtypes.h"
+
+/**
+ * SECTION:gnotification
+ * @short_description: User Notifications (pop up messages)
+ * @include: gio/gio.h
+ *
+ * #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().
+ *
+ * Since: 2.40
+ **/
+
+/**
+ * GNotification:
+ *
+ * This structure type is private and should only be accessed using the
+ * public APIs.
+ *
+ * Since: 2.40
+ **/
typedef GObjectClass GNotificationClass;
gchar *title;
gchar *body;
- GIcon *image;
- gboolean urgent;
+ GIcon *icon;
+ GNotificationPriority priority;
GPtrArray *buttons;
gchar *default_action;
GVariant *default_action_target;
{
GNotification *notification = G_NOTIFICATION (object);
- g_clear_object (¬ification->image);
+ g_clear_object (¬ification->icon);
G_OBJECT_CLASS (g_notification_parent_class)->dispose (object);
}
return notification;
}
-/**
+/*< private >
* g_notification_get_title:
* @notification: a #GNotification
*
/**
* g_notification_set_title:
* @notification: a #GNotification
- * title: the new title for @notification
+ * @title: the new title for @notification
*
* Sets the title of @notification to @title.
*
notification->title = g_strdup (title);
}
-/**
+/*< private >
* g_notification_get_body:
* @notification: a #GNotification
*
notification->body = g_strdup (body);
}
-/**
- * g_notification_get_image:
+/*< private >
+ * g_notification_get_icon:
* @notification: a #GNotification
*
- * Gets the image currently set on @notification.
+ * Gets the icon currently set on @notification.
*
- * Returns: (transfer none): the image associated with @notification
+ * Returns: (transfer none): the icon associated with @notification
*
* Since: 2.40
*/
GIcon *
-g_notification_get_image (GNotification *notification)
+g_notification_get_icon (GNotification *notification)
{
g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
- return notification->image;
+ return notification->icon;
}
/**
- * g_notification_set_image:
+ * g_notification_set_icon:
* @notification: a #GNotification
- * @image: the image to be shown in @notification, as a #GIcon
+ * @icon: the icon to be shown in @notification, as a #GIcon
*
- * Sets the image of @notification to @image.
+ * Sets the icon of @notification to @icon.
*
* Since: 2.40
*/
void
-g_notification_set_image (GNotification *notification,
- GIcon *image)
+g_notification_set_icon (GNotification *notification,
+ GIcon *icon)
{
g_return_if_fail (G_IS_NOTIFICATION (notification));
- if (notification->image)
- g_object_unref (notification->image);
+ if (notification->icon)
+ g_object_unref (notification->icon);
- notification->image = g_object_ref (image);
+ notification->icon = g_object_ref (icon);
}
-/**
- * g_notification_get_urgent:
+/*< private >
+ * g_notification_get_priority:
* @notification: a #GNotification
*
- * Returns %TRUE if @notification is marked as urgent.
+ * Returns the priority of @notification
*
- * Since: 2.40
+ * Since: 2.42
*/
-gboolean
-g_notification_get_urgent (GNotification *notification)
+GNotificationPriority
+g_notification_get_priority (GNotification *notification)
{
- g_return_val_if_fail (G_IS_NOTIFICATION (notification), FALSE);
+ g_return_val_if_fail (G_IS_NOTIFICATION (notification), G_NOTIFICATION_PRIORITY_NORMAL);
- return notification->urgent;
+ return notification->priority;
}
/**
* @notification: a #GNotification
* @urgent: %TRUE if @notification is urgent
*
- * Sets or unsets whether @notification is marked as urgent.
+ * Deprecated in favor of g_notification_set_priority().
*
* Since: 2.40
*/
{
g_return_if_fail (G_IS_NOTIFICATION (notification));
- notification->urgent = urgent;
+ g_notification_set_priority (notification, G_NOTIFICATION_PRIORITY_URGENT);
+}
+
+/**
+ * g_notification_set_priority:
+ * @notification: a #GNotification
+ * @priority: a #GNotificationPriority
+ *
+ * Sets the priority of @notification to @priority. See
+ * #GNotificationPriority for possible values.
+ */
+void
+g_notification_set_priority (GNotification *notification,
+ GNotificationPriority priority)
+{
+ g_return_if_fail (G_IS_NOTIFICATION (notification));
+
+ notification->priority = priority;
}
/**
* @notification: a #GNotification
* @label: label of the button
* @action: an action name
- * @target_format: (allow-none): a GVariant format string, or %NULL
- * @...: positional parameters, as determined by @format_string
+ * @target_format: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @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
+ * positional parameters into a #GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that #GVariant as its
* parameter.
*
* Since: 2.40
* @notification: a #GNotification
* @label: label of the button
* @action: an action name
- * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
*
* Adds a button to @notification that activates @action when clicked.
* @action must be an application-wide action (it must start with "app.").
* g_notification_set_default_action_and_target: (skip)
* @notification: a #GNotification
* @action: an action name
- * @target_format: (allow-none): a GVariant format string, or %NULL
- * @...: positional parameters, as determined by @format_string
+ * @target_format: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @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
+ * 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
* g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
* @notification: a #GNotification
* @action: an action name
- * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
*
* 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_format is given, it is used to collect remaining
- * positional parameters into a GVariant instance, similar to
- * g_variant_new().
- *
* If @target is non-%NULL, @action will be activated with @target as
* its parameter.
*
if (target)
notification->default_action_target = g_variant_ref_sink (target);
}
+
+static GVariant *
+g_notification_serialize_button (Button *button)
+{
+ GVariantBuilder builder;
+
+ g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
+
+ g_variant_builder_add (&builder, "{sv}", "label", g_variant_new_string (button->label));
+ g_variant_builder_add (&builder, "{sv}", "action", g_variant_new_string (button->action_name));
+
+ if (button->target)
+ g_variant_builder_add (&builder, "{sv}", "target", button->target);
+
+ return g_variant_builder_end (&builder);
+}
+
+static GVariant *
+g_notification_get_priority_nick (GNotification *notification)
+{
+ GEnumClass *enum_class;
+ GEnumValue *value;
+ GVariant *nick;
+
+ enum_class = g_type_class_ref (G_TYPE_NOTIFICATION_PRIORITY);
+ value = g_enum_get_value (enum_class, g_notification_get_priority (notification));
+ nick = g_variant_new_string (value->value_nick);
+ g_type_class_unref (enum_class);
+
+ return nick;
+}
+
+/*< private >
+ * g_notification_serialize:
+ *
+ * Serializes @notification into an floating variant of type a{sv}.
+ *
+ * Returns: the serialized @notification as a floating variant.
+ */
+GVariant *
+g_notification_serialize (GNotification *notification)
+{
+ GVariantBuilder builder;
+
+ g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
+
+ if (notification->title)
+ g_variant_builder_add (&builder, "{sv}", "title", g_variant_new_string (notification->title));
+
+ if (notification->body)
+ g_variant_builder_add (&builder, "{sv}", "body", g_variant_new_string (notification->body));
+
+ if (notification->icon)
+ {
+ GVariant *serialized_icon;
+
+ if ((serialized_icon = g_icon_serialize (notification->icon)))
+ {
+ g_variant_builder_add (&builder, "{sv}", "icon", serialized_icon);
+ g_variant_unref (serialized_icon);
+ }
+ }
+
+ g_variant_builder_add (&builder, "{sv}", "priority", g_notification_get_priority_nick (notification));
+
+ if (notification->default_action)
+ {
+ g_variant_builder_add (&builder, "{sv}", "default-action",
+ g_variant_new_string (notification->default_action));
+
+ if (notification->default_action_target)
+ g_variant_builder_add (&builder, "{sv}", "default-action-target",
+ notification->default_action_target);
+ }
+
+ if (notification->buttons->len > 0)
+ {
+ GVariantBuilder actions_builder;
+ guint i;
+
+ g_variant_builder_init (&actions_builder, G_VARIANT_TYPE ("aa{sv}"));
+
+ for (i = 0; i < notification->buttons->len; i++)
+ {
+ Button *button = g_ptr_array_index (notification->buttons, i);
+ g_variant_builder_add (&actions_builder, "@a{sv}", g_notification_serialize_button (button));
+ }
+
+ g_variant_builder_add (&builder, "{sv}", "buttons", g_variant_builder_end (&actions_builder));
+ }
+
+ return g_variant_builder_end (&builder);
+}