RazorAutostartEntry => LxQt::AutostartEntry
[lxde/liblxqt.git] / razornotification.h
CommitLineData
f2cde75a
AM
1/* BEGIN_COMMON_COPYRIGHT_HEADER
2 * (c)LGPL2+
3 *
4 * Razor - 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 RAZORNOTIFICATION_H
26#define RAZORNOTIFICATION_H
27
c5fe3700 28#include <QtCore/QStringList>
f2cde75a
AM
29
30class RazorNotificationPrivate;
31
c5fe3700 32/**
8d6a9984 33 * \brief Libnotify-style desktop notifications
c5fe3700 34 *
8d6a9984 35 * Spec: http://developer.gnome.org/notification-spec
c5fe3700 36 */
f2cde75a
AM
37class RazorNotification : public QObject
38{
39 Q_OBJECT
40public:
8d6a9984
AM
41 /*!
42 * \brief RazorNotification is an object that represents a single notification.
43 * \param summary Summary text briefly describing the notification (required by the spec)
44 */
6deb51c9 45 RazorNotification(const QString& summary = QString(), QObject* parent = 0);
f2cde75a
AM
46 ~RazorNotification();
47
da24150b
AM
48 enum CloseReason
49 {
50 //! The notification expired.
51 Expired = 1,
52 //! The notification was dismissed by the user.
53 Dismissed = 2,
8d6a9984 54 //! The notification was closed by a call to close().
da24150b
AM
55 ForceClosed = 3,
56 //! Undefined/reserved reasons.
57 Unknown = 4
58 };
59
60 enum Urgency
61 {
62 UrgencyLow = 0,
63 UrgencyNormal = 1,
64 UrgencyCritical = 2
65 };
66
6deb51c9
AM
67 struct ServerInfo
68 {
69 //! The product name of the server.
70 QString name;
71 //! The vendor name. For example, "razor-qt.org"
72 QString vendor;
73 //! The server's version number.
74 QString version;
75 //! The specification version the server is compliant with.
76 QString specVersion;
77 };
78
c5fe3700
AM
79 /*!
80 * \brief Set the summary text briefly describing the notification
81 */
82 void setSummary(const QString& summary);
83
84 /*!
85 * \brief Set the detailed body text
86 */
87 void setBody(const QString& body);
88
89 /*!
8d6a9984 90 * \brief Set an icon to display
c5fe3700
AM
91 * \param iconName Name of the icon
92 */
93 void setIcon(const QString& iconName);
94
95 /*!
8d6a9984
AM
96 * \brief Set action buttons for the notification. Whenever an action is
97 * activated, the actionActivated() signal is emitted with the list
98 * index of the activated action.
c5fe3700
AM
99 * \param actions List of action button titles
100 * \param defaultAction Index of the default action which gets activated
101 * when the notification body is clicked
8d6a9984 102 * \sa actionActivated()
c5fe3700
AM
103 */
104 void setActions(const QStringList& actions, int defaultAction = -1);
105
106 /*!
107 * \brief Set the timeout for the notification
da24150b 108 * \param timeout Milliseconds for timeout, or zero to never time out.
c5fe3700
AM
109 */
110 void setTimeout(int timeout);
111
112 /*!
8d6a9984
AM
113 * \brief Set notification hint.
114 * \note For description of Hints, see http://developer.gnome.org/notification-spec/#hints
115 * \note For D-Bus-to-Qt mappings, see https://qt-project.org/doc/qdbustypesystem.html
116 * \param hint Hint name
117 * \param value The hint data
da24150b 118 */
6deb51c9 119 void setHint(const QString& hint, const QVariant& value);
da24150b
AM
120
121 /*!
122 * \brief Set the "urgency" hint
123 * \param urgency
124 */
125 void setUrgencyHint(Urgency urgency);
126
127 /*!
128 * \brief Remove all hints that were set
8d6a9984 129 * \sa setHint()
da24150b
AM
130 */
131 void clearHints();
132
133 /*!
6deb51c9
AM
134 * \brief returns a list of optional capabilities supported by the server.
135 * For the list, see http://developer.gnome.org/notification-spec/#commands
136 */
137 QStringList getCapabilities();
138
139 /*!
140 * \brief Returns information about the notifications server
141 */
142 const ServerInfo serverInfo();
143
144 /*!
8d6a9984
AM
145 * \brief Convenience function to create and display a notification for the most common
146 * cases. For anything more complex, create a RazorNotification object, set the
147 * desired properties and call update(). (That's what this does internally.)
148 * \sa RazorNotification()
c5fe3700
AM
149 */
150 static void notify(const QString& summary,
151 const QString& body = QString(),
152 const QString& iconName = QString()
153 );
f2cde75a 154
c5fe3700
AM
155public slots:
156 /*!
157 * \brief Display the notification or update it if it's already visible
158 */
159 void update();
160
161 /*!
162 * \brief Causes a notification to be forcefully closed and removed from the user's view.
163 * It can be used, for example, in the event that what the notification pertains to
164 * is no longer relevant, or to cancel a notification with no expiration time.
165 */
166 void close();
167
f2cde75a 168signals:
c5fe3700
AM
169 /*!
170 * \brief Emitted when the notification is closed
171 * \param reason How notification was closed
172 */
f2cde75a
AM
173 void notificationClosed(CloseReason reason);
174
c5fe3700
AM
175 /*!
176 * \brief Emitted when an action button is activated.
177 * \param actionNumber Index of the actions array for the activated button.
8d6a9984 178 * \sa setActions()
c5fe3700 179 */
da24150b 180 void actionActivated(int actionNumber);
c5fe3700 181
f2cde75a
AM
182private:
183 Q_DECLARE_PRIVATE(RazorNotification)
184 RazorNotificationPrivate* const d_ptr;
185};
186
187#endif // RAZORNOTIFICATION_H