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_UNDEFIEND: Closed by undefined/reserved reasons.
100 *
101 * The reason for which the notification has been closed.
102 *
103 * Since: 0.8.0
104 */
105typedef enum
106{
107 NOTIFY_CLOSED_REASON_UNSET = -1,
108 NOTIFY_CLOSED_REASON_EXPIRED = 1,
109 NOTIFY_CLOSED_REASON_DISMISSED = 2,
110 NOTIFY_CLOSED_REASON_API_REQUEST = 3,
111 NOTIFY_CLOSED_REASON_UNDEFIEND = 4,
112} NotifyClosedReason;
113
114/**
115 * NotifyActionCallback:
116 * @notification: a #NotifyActionCallback notification
117 * @action: (transfer none): The activated action name
118 * @user_data: (nullable) (transfer none): User provided data
119 *
120 * An action callback function.
121 */
122typedef void (*NotifyActionCallback) (NotifyNotification *notification,
123 char *action,
124 gpointer user_data);
125
126/**
127 * NOTIFY_ACTION_CALLBACK:
128 * @func: The function to cast.
129 *
130 * A convenience macro for casting a function to a [callback@ActionCallback].
131 *
132 * This is much like [func@GObject.CALLBACK].
133 */
134#define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))
135
136NotifyNotification *notify_notification_new (const char *summary,
137 const char *body,
138 const char *icon);
139
140gboolean notify_notification_update (NotifyNotification *notification,
141 const char *summary,
142 const char *body,
143 const char *icon);
144
145gboolean notify_notification_show (NotifyNotification *notification,
146 GError **error);
147
148void notify_notification_set_timeout (NotifyNotification *notification,
149 gint timeout);
150
151void notify_notification_set_category (NotifyNotification *notification,
152 const char *category);
153
154void notify_notification_set_urgency (NotifyNotification *notification,
155 NotifyUrgency urgency);
156
157void notify_notification_set_image_from_pixbuf (NotifyNotification *notification,
158 GdkPixbuf *pixbuf);
159
160#ifndef LIBNOTIFY_DISABLE_DEPRECATED
161void notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
162 GdkPixbuf *icon);
163
164void notify_notification_set_hint_int32 (NotifyNotification *notification,
165 const char *key,
166 gint value);
167void notify_notification_set_hint_uint32 (NotifyNotification *notification,
168 const char *key,
169 guint value);
170
171void notify_notification_set_hint_double (NotifyNotification *notification,
172 const char *key,
173 gdouble value);
174
175void notify_notification_set_hint_string (NotifyNotification *notification,
176 const char *key,
177 const char *value);
178
179void notify_notification_set_hint_byte (NotifyNotification *notification,
180 const char *key,
181 guchar value);
182
183void notify_notification_set_hint_byte_array (NotifyNotification *notification,
184 const char *key,
185 const guchar *value,
186 gsize len);
187#endif
188
189void notify_notification_set_hint (NotifyNotification *notification,
190 const char *key,
191 GVariant *value);
192
193void notify_notification_set_app_name (NotifyNotification *notification,
194 const char *app_name);
195
196void notify_notification_set_app_icon (NotifyNotification *notification,
197 const char *app_icon);
198
199void notify_notification_clear_hints (NotifyNotification *notification);
200
201void notify_notification_add_action (NotifyNotification *notification,
202 const char *action,
203 const char *label,
204 NotifyActionCallback callback,
205 gpointer user_data,
206 GFreeFunc free_func);
207
208const char *notify_notification_get_activation_token (NotifyNotification *notification);
209
210GAppLaunchContext *notify_notification_get_activation_app_launch_context (NotifyNotification *notification);
211
212void notify_notification_clear_actions (NotifyNotification *notification);
213gboolean notify_notification_close (NotifyNotification *notification,
214 GError **error);
215
216gint notify_notification_get_closed_reason (const NotifyNotification *notification);
217
218G_END_DECLS
219