Settings: unify duplicated code
[lxde/liblxqt.git] / lxqtnotification.h
1 /* BEGIN_COMMON_COPYRIGHT_HEADER
2 * (c)LGPL2+
3 *
4 * LXQt - a lightweight, Qt based, desktop toolset
5 * http://razor-qt.org
6 *
7 * Copyright (C) 2012 Alec Moskvin <alecm@gmx.com>
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
13
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 *
23 * END_COMMON_COPYRIGHT_HEADER */
24
25 #ifndef LXQTNOTIFICATION_H
26 #define LXQTNOTIFICATION_H
27
28 #include <QObject>
29 #include <QStringList>
30 #include "lxqtglobals.h"
31
32 namespace LXQt
33 {
34
35 class NotificationPrivate;
36
37 /**
38 * \brief Libnotify-style desktop notifications
39 *
40 * Spec: http://developer.gnome.org/notification-spec
41 */
42 class LXQT_API Notification : public QObject
43 {
44 Q_OBJECT
45 public:
46 /*!
47 * \brief Notification is an object that represents a single notification.
48 * \param summary Summary text briefly describing the notification (required by the spec)
49 */
50 Notification(const QString& summary = QString(), QObject* parent = 0);
51 ~Notification();
52
53 enum CloseReason
54 {
55 //! The notification expired.
56 Expired = 1,
57 //! The notification was dismissed by the user.
58 Dismissed = 2,
59 //! The notification was closed by a call to close().
60 ForceClosed = 3,
61 //! Undefined/reserved reasons.
62 Unknown = 4
63 };
64
65 enum Urgency
66 {
67 UrgencyLow = 0,
68 UrgencyNormal = 1,
69 UrgencyCritical = 2
70 };
71
72 struct ServerInfo
73 {
74 //! The product name of the server.
75 QString name;
76 //! The vendor name. For example, "lxde-qt.org"
77 QString vendor;
78 //! The server's version number.
79 QString version;
80 //! The specification version the server is compliant with.
81 QString specVersion;
82 };
83
84 /*!
85 * \brief Set the summary text briefly describing the notification
86 */
87 void setSummary(const QString& summary);
88
89 /*!
90 * \brief Set the detailed body text
91 */
92 void setBody(const QString& body);
93
94 /*!
95 * \brief Set an icon to display
96 * \param iconName Name of the icon
97 */
98 void setIcon(const QString& iconName);
99
100 /*!
101 * \brief Set action buttons for the notification. Whenever an action is
102 * activated, the actionActivated() signal is emitted with the list
103 * index of the activated action.
104 * \param actions List of action button titles
105 * \param defaultAction Index of the default action which gets activated
106 * when the notification body is clicked
107 * \sa actionActivated()
108 */
109 void setActions(const QStringList& actions, int defaultAction = -1);
110
111 /*!
112 * \brief Set the timeout for the notification
113 * \param timeout Milliseconds for timeout, or zero to never time out.
114 */
115 void setTimeout(int timeout);
116
117 /*!
118 * \brief Set notification hint.
119 * \note For description of Hints, see http://developer.gnome.org/notification-spec/#hints
120 * \note For D-Bus-to-Qt mappings, see https://qt-project.org/doc/qdbustypesystem.html
121 * \param hint Hint name
122 * \param value The hint data
123 */
124 void setHint(const QString& hint, const QVariant& value);
125
126 /*!
127 * \brief Set the "urgency" hint
128 * \param urgency
129 */
130 void setUrgencyHint(Urgency urgency);
131
132 /*!
133 * \brief Remove all hints that were set
134 * \sa setHint()
135 */
136 void clearHints();
137
138 /*!
139 * \brief returns a list of optional capabilities supported by the server.
140 * For the list, see http://developer.gnome.org/notification-spec/#commands
141 */
142 QStringList getCapabilities();
143
144 /*!
145 * \brief Returns information about the notifications server
146 */
147 const ServerInfo serverInfo();
148
149 /*!
150 * \brief Convenience function to create and display a notification for the most common
151 * cases. For anything more complex, create a Notification object, set the
152 * desired properties and call update(). (That's what this does internally.)
153 * \sa Notification()
154 */
155 static void notify(const QString& summary,
156 const QString& body = QString(),
157 const QString& iconName = QString()
158 );
159
160 public slots:
161 /*!
162 * \brief Display the notification or update it if it's already visible
163 */
164 void update();
165
166 /*!
167 * \brief Causes a notification to be forcefully closed and removed from the user's view.
168 * It can be used, for example, in the event that what the notification pertains to
169 * is no longer relevant, or to cancel a notification with no expiration time.
170 */
171 void close();
172
173 signals:
174 /*!
175 * \brief Emitted when the notification is closed
176 * \param reason How notification was closed
177 */
178 void notificationClosed(LXQt::Notification::CloseReason reason);
179
180 /*!
181 * \brief Emitted when an action button is activated.
182 * \param actionNumber Index of the actions array for the activated button.
183 * \sa setActions()
184 */
185 void actionActivated(int actionNumber);
186
187 private:
188 Q_DECLARE_PRIVATE(Notification)
189 NotificationPrivate* const d_ptr;
190 };
191
192 } // namespace LXQt
193 #endif // LXQTNOTIFICATION_H