1/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*-
2 *
3 * Copyright (C) 2006 Christian Hammond
4 * Copyright (C) 2006 John Palmieri
5 * Copyright (C) 2010 Red Hat, Inc.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
21 */
22
23#pragma once
24
25#include <glib.h>
26#include <glib-object.h>
27#include <gdk-pixbuf/gdk-pixbuf.h>
28
29G_BEGIN_DECLS
30
31/**
32 * NOTIFY_EXPIRES_DEFAULT:
33 *
34 * The default expiration time on a notification.
35 */
36#define NOTIFY_EXPIRES_DEFAULT -1
37
38/**
39 * NOTIFY_EXPIRES_NEVER:
40 *
41 * The notification never expires.
42 *
43 * It stays open until closed by the calling API or the user.
44 */
45#define NOTIFY_EXPIRES_NEVER 0
46
47#define NOTIFY_TYPE_NOTIFICATION (notify_notification_get_type ())
48
49G_DECLARE_DERIVABLE_TYPE (NotifyNotification, notify_notification, NOTIFY, NOTIFICATION, GObject);
50
51/**
52 * NotifyNotification:
53 *
54 * A passive pop-up notification.
55 *
56 * #NotifyNotification represents a passive pop-up notification. It can
57 * contain summary text, body text, and an icon, as well as hints specifying
58 * how the notification should be presented. The notification is rendered
59 * by a notification daemon, and may present the notification in any number
60 * of ways. As such, there is a clear separation of content and presentation,
61 * and this API enforces that.
62 */
63
64struct _NotifyNotificationClass
65{
66 GObjectClass parent_class;
67
68 /* Signals */
69 void (*closed) (NotifyNotification *notification);
70};
71
72
73/**
74 * NotifyUrgency:
75 * @NOTIFY_URGENCY_LOW: Low urgency. Used for unimportant notifications.
76 * @NOTIFY_URGENCY_NORMAL: Normal urgency. Used for most standard notifications.
77 * @NOTIFY_URGENCY_CRITICAL: Critical urgency. Used for very important notifications.
78 *
79 * The urgency level of the notification.
80 */
81typedef enum
82{
83 NOTIFY_URGENCY_LOW,
84 NOTIFY_URGENCY_NORMAL,
85 NOTIFY_URGENCY_CRITICAL,
86
87} NotifyUrgency;
88
89
90/**
91 * NotifyClosedReason:
92 * @NOTIFY_CLOSED_REASON_UNSET: Notification not closed.
93 * @NOTIFY_CLOSED_REASON_EXPIRED: Timeout has expired.
94 * @NOTIFY_CLOSED_REASON_DISMISSED: It has been dismissed by the user.
95 * @NOTIFY_CLOSED_REASON_API_REQUEST: It has been closed by a call to
96 * [method@NotifyNotification.close].
97 * @NOTIFY_CLOSED_REASON_UNDEFIEND: Closed by undefined/reserved reasons.
98 *
99 * The reason for which the notification has been closed.
100 *
101 * Since: 0.8.0
102 */
103typedef enum
104{
105 NOTIFY_CLOSED_REASON_UNSET = -1,
106 NOTIFY_CLOSED_REASON_EXPIRED = 1,
107 NOTIFY_CLOSED_REASON_DISMISSED = 2,
108 NOTIFY_CLOSED_REASON_API_REQUEST = 3,
109 NOTIFY_CLOSED_REASON_UNDEFIEND = 4,
110} NotifyClosedReason;
111
112/**
113 * NotifyActionCallback:
114 * @notification: a #NotifyActionCallback notification
115 * @action: (transfer none): The activated action name
116 * @user_data: (nullable) (transfer none): User provided data
117 *
118 * An action callback function.
119 */
120typedef void (*NotifyActionCallback) (NotifyNotification *notification,
121 char *action,
122 gpointer user_data);
123
124/**
125 * NOTIFY_ACTION_CALLBACK:
126 * @func: The function to cast.
127 *
128 * A convenience macro for casting a function to a [callback@ActionCallback].
129 *
130 * This is much like [func@GObject.CALLBACK].
131 */
132#define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))
133
134NotifyNotification *notify_notification_new (const char *summary,
135 const char *body,
136 const char *icon);
137
138gboolean notify_notification_update (NotifyNotification *notification,
139 const char *summary,
140 const char *body,
141 const char *icon);
142
143gboolean notify_notification_show (NotifyNotification *notification,
144 GError **error);
145
146void notify_notification_set_timeout (NotifyNotification *notification,
147 gint timeout);
148
149void notify_notification_set_category (NotifyNotification *notification,
150 const char *category);
151
152void notify_notification_set_urgency (NotifyNotification *notification,
153 NotifyUrgency urgency);
154
155void notify_notification_set_image_from_pixbuf (NotifyNotification *notification,
156 GdkPixbuf *pixbuf);
157
158#ifndef LIBNOTIFY_DISABLE_DEPRECATED
159void notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
160 GdkPixbuf *icon);
161
162void notify_notification_set_hint_int32 (NotifyNotification *notification,
163 const char *key,
164 gint value);
165void notify_notification_set_hint_uint32 (NotifyNotification *notification,
166 const char *key,
167 guint value);
168
169void notify_notification_set_hint_double (NotifyNotification *notification,
170 const char *key,
171 gdouble value);
172
173void notify_notification_set_hint_string (NotifyNotification *notification,
174 const char *key,
175 const char *value);
176
177void notify_notification_set_hint_byte (NotifyNotification *notification,
178 const char *key,
179 guchar value);
180
181void notify_notification_set_hint_byte_array (NotifyNotification *notification,
182 const char *key,
183 const guchar *value,
184 gsize len);
185#endif
186
187void notify_notification_set_hint (NotifyNotification *notification,
188 const char *key,
189 GVariant *value);
190
191void notify_notification_set_app_name (NotifyNotification *notification,
192 const char *app_name);
193
194void notify_notification_set_app_icon (NotifyNotification *notification,
195 const char *app_icon);
196
197void notify_notification_clear_hints (NotifyNotification *notification);
198
199void notify_notification_add_action (NotifyNotification *notification,
200 const char *action,
201 const char *label,
202 NotifyActionCallback callback,
203 gpointer user_data,
204 GFreeFunc free_func);
205
206const char *notify_notification_get_activation_token (NotifyNotification *notification);
207
208GAppLaunchContext *notify_notification_get_activation_app_launch_context (NotifyNotification *notification);
209
210void notify_notification_clear_actions (NotifyNotification *notification);
211gboolean notify_notification_close (NotifyNotification *notification,
212 GError **error);
213
214gint notify_notification_get_closed_reason (const NotifyNotification *notification);
215
216G_END_DECLS
217