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
29#include <libnotify/notification-hints.h>
30
31G_BEGIN_DECLS
32
33/**
34 * NOTIFY_EXPIRES_DEFAULT:
35 *
36 * The default expiration time on a notification.
37 */
38#define NOTIFY_EXPIRES_DEFAULT -1
39
40/**
41 * NOTIFY_EXPIRES_NEVER:
42 *
43 * The notification never expires.
44 *
45 * It stays open until closed by the calling API or the user.
46 */
47#define NOTIFY_EXPIRES_NEVER 0
48
49#define NOTIFY_TYPE_NOTIFICATION (notify_notification_get_type ())
50
51G_DECLARE_DERIVABLE_TYPE (NotifyNotification, notify_notification, NOTIFY, NOTIFICATION, GObject);
52
53/**
54 * NotifyNotification:
55 *
56 * A passive pop-up notification.
57 *
58 * #NotifyNotification represents a passive pop-up notification. It can
59 * contain summary text, body text, and an icon, as well as hints specifying
60 * how the notification should be presented. The notification is rendered
61 * by a notification daemon, and may present the notification in any number
62 * of ways. As such, there is a clear separation of content and presentation,
63 * and this API enforces that.
64 */
65
66struct _NotifyNotificationClass
67{
68 GObjectClass parent_class;
69
70 /* Signals */
71 void (*closed) (NotifyNotification *notification);
72};
73
74
75/**
76 * NotifyUrgency:
77 * @NOTIFY_URGENCY_LOW: Low urgency. Used for unimportant notifications.
78 * @NOTIFY_URGENCY_NORMAL: Normal urgency. Used for most standard notifications.
79 * @NOTIFY_URGENCY_CRITICAL: Critical urgency. Used for very important notifications.
80 *
81 * The urgency level of the notification.
82 */
83typedef enum
84{
85 NOTIFY_URGENCY_LOW,
86 NOTIFY_URGENCY_NORMAL,
87 NOTIFY_URGENCY_CRITICAL,
88
89} NotifyUrgency;
90
91
92/**
93 * NotifyClosedReason:
94 * @NOTIFY_CLOSED_REASON_UNSET: Notification not closed.
95 * @NOTIFY_CLOSED_REASON_EXPIRED: Timeout has expired.
96 * @NOTIFY_CLOSED_REASON_DISMISSED: It has been dismissed by the user.
97 * @NOTIFY_CLOSED_REASON_API_REQUEST: It has been closed by a call to
98 * [method@NotifyNotification.close].
99 * @NOTIFY_CLOSED_REASON_UNDEFINED: Closed by undefined/reserved reasons.
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_UNDEFINED = 4,
110
111 NOTIFY_CLOSED_REASON_UNDEFIEND
112 __attribute__((__deprecated__(
113 "Use 'NOTIFY_CLOSED_REASON_UNDEFINED' instead"))) = 4,
114} NotifyClosedReason;
115
116/**
117 * NotifyActionCallback:
118 * @notification: a #NotifyActionCallback notification
119 * @action: (transfer none): The activated action name
120 * @user_data: (nullable) (transfer none): User provided data
121 *
122 * An action callback function.
123 */
124typedef void (*NotifyActionCallback) (NotifyNotification *notification,
125 char *action,
126 gpointer user_data);
127
128/**
129 * NOTIFY_ACTION_CALLBACK:
130 * @func: The function to cast.
131 *
132 * A convenience macro for casting a function to a [callback@ActionCallback].
133 *
134 * This is much like [func@GObject.CALLBACK].
135 */
136#define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))
137
138NotifyNotification *notify_notification_new (const char *summary,
139 const char *body,
140 const char *icon);
141
142gboolean notify_notification_update (NotifyNotification *notification,
143 const char *summary,
144 const char *body,
145 const char *icon);
146
147gboolean notify_notification_show (NotifyNotification *notification,
148 GError **error);
149
150void notify_notification_set_timeout (NotifyNotification *notification,
151 gint timeout);
152
153void notify_notification_set_category (NotifyNotification *notification,
154 const char *category);
155
156void notify_notification_set_urgency (NotifyNotification *notification,
157 NotifyUrgency urgency);
158
159void notify_notification_set_image_from_pixbuf (NotifyNotification *notification,
160 GdkPixbuf *pixbuf);
161
162#ifndef LIBNOTIFY_DISABLE_DEPRECATED
163void notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
164 GdkPixbuf *icon);
165
166void notify_notification_set_hint_int32 (NotifyNotification *notification,
167 const char *key,
168 gint value);
169void notify_notification_set_hint_uint32 (NotifyNotification *notification,
170 const char *key,
171 guint value);
172
173void notify_notification_set_hint_double (NotifyNotification *notification,
174 const char *key,
175 gdouble value);
176
177void notify_notification_set_hint_string (NotifyNotification *notification,
178 const char *key,
179 const char *value);
180
181void notify_notification_set_hint_byte (NotifyNotification *notification,
182 const char *key,
183 guchar value);
184
185void notify_notification_set_hint_byte_array (NotifyNotification *notification,
186 const char *key,
187 const guchar *value,
188 gsize len);
189#endif
190
191void notify_notification_set_hint (NotifyNotification *notification,
192 const char *key,
193 GVariant *value);
194
195void notify_notification_set_app_name (NotifyNotification *notification,
196 const char *app_name);
197
198void notify_notification_set_app_icon (NotifyNotification *notification,
199 const char *app_icon);
200
201void notify_notification_clear_hints (NotifyNotification *notification);
202
203void notify_notification_add_action (NotifyNotification *notification,
204 const char *action,
205 const char *label,
206 NotifyActionCallback callback,
207 gpointer user_data,
208 GFreeFunc free_func);
209
210const char *notify_notification_get_activation_token (NotifyNotification *notification);
211
212GAppLaunchContext *notify_notification_get_activation_app_launch_context (NotifyNotification *notification);
213
214void notify_notification_clear_actions (NotifyNotification *notification);
215gboolean notify_notification_close (NotifyNotification *notification,
216 GError **error);
217
218gint notify_notification_get_closed_reason (const NotifyNotification *notification);
219
220G_END_DECLS
221