bump year
[lxde/liblxqt.git] / lxqtnotification.h
CommitLineData
f2cde75a
AM
1/* BEGIN_COMMON_COPYRIGHT_HEADER
2 * (c)LGPL2+
3 *
b9223fe7 4 * LXQt - a lightweight, Qt based, desktop toolset
f2cde75a
AM
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
0e4fbf35
AS
25#ifndef LXQTNOTIFICATION_H
26#define LXQTNOTIFICATION_H
f2cde75a 27
7303ea20 28#include <QObject>
2d13fe11 29#include <QStringList>
f9cba1ba 30#include "lxqtglobals.h"
f2cde75a 31
f05ba5af 32namespace LXQt
0e4fbf35
AS
33{
34
35class NotificationPrivate;
f2cde75a 36
c5fe3700 37/**
8d6a9984 38 * \brief Libnotify-style desktop notifications
c5fe3700 39 *
8d6a9984 40 * Spec: http://developer.gnome.org/notification-spec
c5fe3700 41 */
f9cba1ba 42class LXQT_API Notification : public QObject
f2cde75a
AM
43{
44 Q_OBJECT
45public:
8d6a9984 46 /*!
0e4fbf35 47 * \brief Notification is an object that represents a single notification.
8d6a9984
AM
48 * \param summary Summary text briefly describing the notification (required by the spec)
49 */
0e4fbf35
AS
50 Notification(const QString& summary = QString(), QObject* parent = 0);
51 ~Notification();
f2cde75a 52
da24150b
AM
53 enum CloseReason
54 {
55 //! The notification expired.
56 Expired = 1,
57 //! The notification was dismissed by the user.
58 Dismissed = 2,
8d6a9984 59 //! The notification was closed by a call to close().
da24150b
AM
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
6deb51c9
AM
72 struct ServerInfo
73 {
74 //! The product name of the server.
75 QString name;
d34ff6ea 76 //! The vendor name. For example, "lxde-qt.org"
6deb51c9
AM
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
c5fe3700
AM
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 /*!
8d6a9984 95 * \brief Set an icon to display
c5fe3700
AM
96 * \param iconName Name of the icon
97 */
98 void setIcon(const QString& iconName);
99
100 /*!
8d6a9984
AM
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.
c5fe3700
AM
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
8d6a9984 107 * \sa actionActivated()
c5fe3700
AM
108 */
109 void setActions(const QStringList& actions, int defaultAction = -1);
110
111 /*!
112 * \brief Set the timeout for the notification
da24150b 113 * \param timeout Milliseconds for timeout, or zero to never time out.
c5fe3700
AM
114 */
115 void setTimeout(int timeout);
116
117 /*!
8d6a9984
AM
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
da24150b 123 */
6deb51c9 124 void setHint(const QString& hint, const QVariant& value);
da24150b
AM
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
8d6a9984 134 * \sa setHint()
da24150b
AM
135 */
136 void clearHints();
137
138 /*!
6deb51c9
AM
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 /*!
8d6a9984 150 * \brief Convenience function to create and display a notification for the most common
0e4fbf35 151 * cases. For anything more complex, create a Notification object, set the
8d6a9984 152 * desired properties and call update(). (That's what this does internally.)
0e4fbf35 153 * \sa Notification()
c5fe3700
AM
154 */
155 static void notify(const QString& summary,
156 const QString& body = QString(),
157 const QString& iconName = QString()
158 );
f2cde75a 159
c5fe3700
AM
160public 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
f2cde75a 173signals:
c5fe3700
AM
174 /*!
175 * \brief Emitted when the notification is closed
176 * \param reason How notification was closed
177 */
f05ba5af 178 void notificationClosed(LXQt::Notification::CloseReason reason);
f2cde75a 179
c5fe3700
AM
180 /*!
181 * \brief Emitted when an action button is activated.
182 * \param actionNumber Index of the actions array for the activated button.
8d6a9984 183 * \sa setActions()
c5fe3700 184 */
da24150b 185 void actionActivated(int actionNumber);
c5fe3700 186
f2cde75a 187private:
0e4fbf35
AS
188 Q_DECLARE_PRIVATE(Notification)
189 NotificationPrivate* const d_ptr;
f2cde75a
AM
190};
191
f05ba5af 192} // namespace LXQt
0e4fbf35 193#endif // LXQTNOTIFICATION_H