Differential D20265 Diff 55470 libnotificationmanager/notifications.h

Changeset View

Standalone View

libnotificationmanager/notifications.h

This file was added.

1		/*
2		* Copyright 2019 Kai Uwe Broulik <kde@privat.broulik.de>
3		*
4		* This library is free software; you can redistribute it and/or
5		* modify it under the terms of the GNU Lesser General Public
6		* License as published by the Free Software Foundation; either
7		* version 2.1 of the License, or (at your option) version 3, or any
8		* later version accepted by the membership of KDE e.V. (or its
9		* successor approved by the membership of KDE e.V.), which shall
10		* act as a proxy defined in Section 6 of version 3 of the license.
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, see <http://www.gnu.org/licenses/>.
19		*/
20
21		#pragma once
22
23		#include <QSortFilterProxyModel>
24		#include <QQmlParserStatus>
25
26		#include <QScopedPointer>
27
28		#include "notificationmanager_export.h"
29
30		namespace NotificationManager
31		{
32
33		/**
34		* @brief A model with notifications and jobs
35		*
36		* This model contains application notifications as well as jobs
37		* and lets you apply fine-grained filter, sorting, and grouping rules.
38		*
39		* @author Kai Uwe Broulik <kde@privat.broulik.de>
40		**/
41		class NOTIFICATIONMANAGER_EXPORT Notifications : public QSortFilterProxyModel, public QQmlParserStatus
42		{
43		Q_OBJECT
44		Q_INTERFACES(QQmlParserStatus)
45
46		/**
47		* The number of notifications the model should at most contain.
48		*
49		* Default is 0, which is no limit.
50		*/
51		Q_PROPERTY(int limit READ limit WRITE setLimit NOTIFY limitChanged)
52
53		/**
54		* Whether to show expired notifications.
55		*
56		* Expired notifications are those that timed out, i.e. ones that were not explicitly
57		* closed or acted upon by the user, nor revoked by the issuing application.
58		*
59		* An expired notification has its actions removed.
60		*
61		* Default is false.
62		*/
63		Q_PROPERTY(bool showExpired READ showExpired WRITE setShowExpired NOTIFY showExpiredChanged)
64
65		/**
66		* Whether to show dismissed notifications.
67		*
68		* Dismissed notifications are those that are temporarily hidden by the user.
69		* This can e.g. be a copy job that has its popup closed but still continues in the background.
70		*
71		* Default is false.
72		*/
73		Q_PROPERTY(bool showDismissed READ showDismissed WRITE setShowDismissed NOTIFY showDismissedChanged)
74
75		/**
76		* A list of desktop entries for which no notifications should be shown.
77		*
78		* If the same desktop entry is present in both blacklist and whitelist,
79		* the blacklist takes precedence, i.e. the notification is not shown.
80		*/
81		Q_PROPERTY(QStringList blacklistedDesktopEntries READ blacklistedDesktopEntries WRITE setBlacklistedDesktopEntries NOTIFY blacklistedDesktopEntriesChanged)
82
83		/**
84		* A list of notifyrc names for which no notifications should be shown.
85		*
86		* If the same notifyrc name is present in both blacklist and whitelist,
87		* the blacklist takes precedence, i.e. the notification is not shown.
88		*/
89		Q_PROPERTY(QStringList blacklistedNotifyRcNames READ blacklistedNotifyRcNames WRITE setBlacklistedNotifyRcNames NOTIFY blacklistedNotifyRcNamesChanged)
90
91		/**
92		* A list of desktop entries for which notifications should be shown.
93		*
94		* This bypasses any filtering for urgency.
95		*
96		* If the same desktop entry is present in both whitelist and blacklist,
97		* the blacklist takes precedence, i.e. the notification is not shown.
98		*
99		* Default is empty list, which means normal filtering is applied.
100		*/
101		Q_PROPERTY(QStringList whitelistedDesktopEntries READ whitelistedDesktopEntries WRITE setWhitelistedDesktopEntries NOTIFY whitelistedDesktopEntriesChanged)
102
103		/**
104		* A list of notifyrc names for which notifications should be shown.
105		*
106		* This bypasses any filtering for urgency.
107		*
108		* If the same notifyrc name is present in both whitelist and blacklist,
109		* the blacklist takes precedence, i.e. the notification is not shown.
110		*
111		* Default is empty list, which means normal filtering is applied.
112		*/
113		Q_PROPERTY(QStringList whitelistedNotifyRcNames READ whitelistedNotifyRcNames WRITE setWhitelistedNotifyRcNames NOTIFY whitelistedNotifyRcNamesChanged)
114
115		/**
116		* Whether to show application jobs.
117		*/
118		Q_PROPERTY(bool showJobs READ showJobs WRITE setShowJobs NOTIFY showJobsChanged)
119
120		/**
121		* The notification urgency types the model should contain.
122		*
123		* Default is all urgencies: low, normal, critical.
124		*/
125		Q_PROPERTY(Urgencies urgencies READ urgencies WRITE setUrgencies NOTIFY urgenciesChanged)
126
127		/**
128		* The sort mode for notifications.
129		*
130		* Default is strictly by date created/updated.
131		*/
132		Q_PROPERTY(SortMode sortMode READ sortMode WRITE setSortMode NOTIFY sortModeChanged)
133
134		/**
135		* The group mode for notifications.
136		*
137		* Default is ungrouped.
138		*/
139		Q_PROPERTY(GroupMode groupMode READ groupMode WRITE setGroupMode NOTIFY groupModeChanged)
140
141		/**
142		* How many notifications are shown in each group.
143		*
144		* You can expand a group by setting the IsGroupExpandedRole to true.
145		*
146		* Default is 0, which means no limit.
147		*/
148		Q_PROPERTY(int groupLimit READ groupLimit WRITE setGroupLimit NOTIFY groupLimitChanged)
149
150		/**
151		* The number of notifications in the model
152		*/
153		Q_PROPERTY(int count READ count NOTIFY countChanged)
154
155		/**
156		* The number of active, i.e. non-expired notifications
157		*/
158		Q_PROPERTY(int activeNotificationsCount READ activeNotificationsCount NOTIFY activeNotificationsCountChanged)
159
160		/**
161		* The number of inactive, i.e. non-expired notifications
162		*/
163		Q_PROPERTY(int expiredNotificationsCount READ expiredNotificationsCount NOTIFY expiredNotificationsCountChanged)
164
165		/**
166		* The time when the user last could read the notifications.
167		* This is typically reset whenever the list of notifications is opened and is used to determine
168		* the @c unreadNotificationsCount
169		*/
170		Q_PROPERTY(QDateTime lastRead READ lastRead WRITE setLastRead RESET resetLastRead NOTIFY lastReadChanged)
171
172		/**
173		* The number of notifications added since lastRead
174		*
175		* This can be used to show a "n unread notifications" label
176		*/
177		Q_PROPERTY(int unreadNotificationsCount READ unreadNotificationsCount NOTIFY unreadNotificationsCountChanged)
178
179		/**
180		* The number of active jobs
181		*/
182		Q_PROPERTY(int activeJobsCount READ activeJobsCount NOTIFY activeJobsCountChanged)
183		/**
184		* The combined percentage of all jobs.
185		*
186		* This is the average of all percentages and could can be used to show
187		* a global progress bar.
188		*/
189		Q_PROPERTY(int jobsPercentage READ jobsPercentage NOTIFY jobsPercentageChanged)
190
191		public:
192		explicit Notifications(QObject *parent = nullptr);
193		~Notifications() override;
194
195		enum Roles {
196		IdRole = Qt::UserRole + 1, ///< A notification identifier. This can be uint notification ID or string application job source.
197		SummaryRole = Qt::DisplayRole, ///< The notification summary.
198		ImageRole = Qt::DecorationRole, ///< The notification main image, which is not the application icon. Only valid for pixmap icons.
199
200		IsGroupRole = Qt::UserRole + 2, ///< Whether the item is a group
201		GroupChildrenCountRole, ///< The number of children in a group.
202		IsGroupExpandedRole, ///< Whether the group is expanded, this role is writable.
203
204		IsInGroupRole, ///< Whether the notification is currently inside a group.
205		TypeRole, ///< The type of model entry, either NotificationType or JobType.
206		CreatedRole, ///< When the notification was first created.
207		UpdatedRole, ///< When the notification was last updated, invalid when it hasn't been updated.
208
209		BodyRole, ///< The notification body text.
210		IconNameRole, ///< The notification main icon, which is not the application icon. Only valid for icon names.
211
212		DesktopEntryRole, ///< The desktop entry (without .desktop suffix, e.g. org.kde.spectacle) of the application that sent the notification.
	heinUnsubmitted Done I recommend making this Q_ENUM and registering it; with libtm it turned out that it's useful to be able to call data() with a role from QML sometimes. hein: I recommend making this Q_ENUM and registering it; with libtm it turned out that it's useful to…
	broulikAuthorUnsubmitted Done I did exactly that in a later commit that isn't on Phab, sorry :) broulik: I did exactly that in a later commit that isn't on Phab, sorry :)
213		NotifyRcNameRole, ///< The notifyrc name (e.g. spectaclerc) of the application that sent the notification.
214
215		ApplicationNameRole, ///< The user-visible name of the application (e.g. Spectacle)
216		ApplicationIconNameRole, ///< The icon name of the application
217		DeviceNameRole, ///< The name of the device the notification originally came from, if it was proxied through a sync service like KDE Connect
218
	heinUnsubmitted Not Done This is a bit unusual, I assume it's because you're flattening back out so you don't want rowCount/canFetchMore? hein: This is a bit unusual, I assume it's because you're flattening back out so you don't want…
	broulikAuthorUnsubmitted Not Done I guess. I use it for showing an expand button with "show n more" written on it broulik: I guess. I use it for showing an expand button with "show n more" written on it
219		// Jobs
220		JobStateRole, ///< The state of the job, either JobStateJopped, JobStateSuspended, or JobStateRunning.
221		PercentageRole, ///< The percentage of the job. Use @c jobsPercentage to get a global percentage for all jobs.
222		ErrorRole, ///< The error id of the job, zero in case of no error.
223		ErrorTextRole, ///< The user-visible error string of the job, empty in case of no error.
224		SuspendableRole, ///< Whether the job can be suspended @sa suspendJob
225		KillableRole, ///< Whether the job can be killed/canceled @sa killJob
226		JobDetailsRole, ///< A pointer to a JobDetails item containing more detailed information about the job
227
228		ActionNamesRole, ///< The IDs of the actions, excluding the default and settings action, e.g. [action1, action2]
229		ActionLabelsRole, ///< The user-visible labels of the actions, excluding the default and settings action, e.g. ["Accept", "Reject"]
230		HasDefaultActionRole, ///< Whether the notification has a default action, which is one that is invoked when the popup itself is clicked
231		DefaultActionLabelRole, ///< The user-visible label of the default action, typically not shown as the popup itself becomes clickable
232
233		UrlsRole, ///< A list of URLs associated with the notification, e.g. a path to a screenshot that was just taken or image received
234
235		UrgencyRole, ///< The notification urgency, either LowUrgency, NormalUrgency, or CriticalUrgency. Jobs do not have an urgency.
236		TimeoutRole, ///< The timeout for the notification in milliseconds. 0 means the notification should not timeout, -1 means a sensible default should be applied.
237
238		ConfigurableRole, ///< Whether the notification can be configured because a desktopEntry or notifyRcName is known, or the notification has a setting action. @sa configure
239		ConfigureActionLabelRole, ///< The user-visible label for the settings action
240		ClosableRole, ///< Whether the item can be closed. Notifications are always closable, jobs are only when in JobStateStopped.
241
242		ExpiredRole, ///< The notification timed out and closed. Actions on it cannot be invoked anymore.
243		DismissedRole ///< The notification got temporarily hidden by the user but could still be interacted with.
244		};
245
246		/**
247		* The type of model item.
248		*/
249		enum Type {
250		NoType,
251		NotificationType, ///< This item represents a notification.
252		JobType ///< This item represents an application job.
253		};
254		Q_ENUM(Type)
255
256		/**
257		* The notification urgency.
258		*
259		* @note jobs do not have an urgency, yet still might be above normal urgency notifications.
260		*/
261		enum Urgency {
262		// these don't match the spec's value
263		LowUrgency = 1 << 0, ///< The notification has low urgency, it is not important and may not be shown or added to a history.
264		NormalUrgency = 1 << 1, ///< The notification has normal urgency. This is also the default if no urgecny is supplied.
265		CriticalUrgency = 1 << 2
266		};
267		Q_ENUM(Urgency)
268		Q_DECLARE_FLAGS(Urgencies, Urgency)
269		Q_FLAG(Urgencies)
270
271		/**
272		* Which items should be cleared in a call to @c clear
273		*/
274		enum ClearFlag {
275		ClearExpired = 1 << 1,
276		// TODO more
277		};
278		Q_ENUM(ClearFlag)
279		Q_DECLARE_FLAGS(ClearFlags, ClearFlag)
280		Q_FLAG(ClearFlags)
281
282		/**
283		* The state an application job is in.
284		*/
285		enum JobState {
286		JobStateStopped, ///< The job is stopped. It has either finished (error is 0) or failed (error is not 0)
287		JobStateRunning, ///< The job is currently running.
288		JobStateSuspended ///< The job is currentl paused
289		};
290		Q_ENUM(JobState)
291
292		/**
293		* The sort mode for the model.
294		*/
295		enum SortMode {
296		SortByDate = 0, ///< Sort notifications strictly by the date they were updated or created.
297		// should this be flags? SortJobsFirst \| SortByUrgency \| ...?
298		SortByTypeAndUrgency ///< Sort notifications taking into account their type and urgency. The order is (descending): Critical, jobs, Normal, Low.
299		};
300		Q_ENUM(SortMode)
301
302		/**
303		* The group mode for the model.
304		*/
305		enum GroupMode {
306		GroupDisabled = 0,
307		//GroupApplicationsTree, // TODO make actual tree
308		GroupApplicationsFlat
309		};
310		Q_ENUM(GroupMode)
311
312		int limit() const;
313		void setLimit(int limit);
314
315		bool showExpired() const;
316		void setShowExpired(bool show);
317
318		bool showDismissed() const;
319		void setShowDismissed(bool show);
320
321		QStringList blacklistedDesktopEntries() const;
322		void setBlacklistedDesktopEntries(const QStringList &blacklist);
323
324		QStringList blacklistedNotifyRcNames() const;
325		void setBlacklistedNotifyRcNames(const QStringList &blacklist);
326
327		QStringList whitelistedDesktopEntries() const;
328		void setWhitelistedDesktopEntries(const QStringList &whitelist);
329
330		QStringList whitelistedNotifyRcNames() const;
331		void setWhitelistedNotifyRcNames(const QStringList &whitelist);
332
333		bool showJobs() const;
334		void setShowJobs(bool showJobs);
335
336		Urgencies urgencies() const;
337		void setUrgencies(Urgencies urgencies);
338
339		SortMode sortMode() const;
340		void setSortMode(SortMode sortMode);
341
342		GroupMode groupMode() const;
343		void setGroupMode(GroupMode groupMode);
344
345		int groupLimit() const;
346		void setGroupLimit(int limit);
347
348		int count() const;
349
350		int activeNotificationsCount() const;
351		int expiredNotificationsCount() const;
352
353		QDateTime lastRead() const;
354		void setLastRead(const QDateTime &lastRead);
355		void resetLastRead();
356
357		int unreadNotificationsCount() const;
358
359		int activeJobsCount() const;
360		int jobsPercentage() const;
361
362		/**
363		* @brief Expire a notification
364		*
365		* Closes the notification in response to its timeout running out.
366		*
367		* Call this if you have an implementation that handles the timeout itself
368		* by having called @c stopTimeout
369		*
370		* @sa stopTimeout
371		*/
372		Q_INVOKABLE void expire(const QModelIndex &idx);
373		/**
374		* @brief Close a notification
375		*
376		* Closes the notification in response to the user explicitly closing it.
377		*
378		* When the model index belongs to a group, the entire group is closed.
379		*/
380		Q_INVOKABLE void close(const QModelIndex &idx);
381		/**
382		* @brief Configure a notification
383		*
384		* This will invoke the settings action, if available, otherwise open the
385		* kcm_notifications KCM for configuring the respective application and event.
386		*/
387		Q_INVOKABLE void configure(const QModelIndex &idx); // TODO pass ctx for transient handling
388		/**
389		* @brief Invoke the default notification action
390		*
391		* Invokes the action that should be triggered when clicking
392		* the notification bubble itself.
393		*/
394		Q_INVOKABLE void invokeDefaultAction(const QModelIndex &idx);
395		/**
396		* @brief Invoke a notification action
397		*
398		* Invokes the action with the given actionId on the notification.
399		* For invoking the default action, i.e. the one that is triggered
400		* when clicking the notification bubble, use invokeDefaultAction
401		*/
402		Q_INVOKABLE void invokeAction(const QModelIndex &idx, const QString &actionId);
403
404		/**
405		* @brief Start automatic timeout of notifications
406		*
407		* Call this if you no longer handle the timeout yourself.
408		*
409		* @sa stopTimeout
410		*/
411		Q_INVOKABLE void startTimeout(const QModelIndex &idx);
412
413		Q_INVOKABLE void startTimeout(uint notificationId);
414		/**
415		* @brief Stop the automatic timeout of notifications
416		*
417		* Call this if you have an implementation that handles the timeout itself
418		* taking into account e.g. whether the user is currently interacting with
419		* the notification to not close it under their mouse. Call @c expire
420		* once your custom timer has run out.
421		*
422		* @sa expire
423		*/
424		Q_INVOKABLE void stopTimeout(const QModelIndex &idx);
425
426		/**
427		* @brief Suspend a job
428		*/
429		Q_INVOKABLE void suspendJob(const QModelIndex &idx);
430		/**
431		* @brief Resume a job
432		*/
433		Q_INVOKABLE void resumeJob(const QModelIndex &idx);
434		/**
435		* @brief Kill a job
436		*/
437		Q_INVOKABLE void killJob(const QModelIndex &idx);
438
439		/**
440		* @brief Clear notifications
441		*
442		* Removes the notifications matching th ClearFlags from the model.
443		* This can be used for e.g. a "Clear History" action.
444		*/
445		Q_INVOKABLE void clear(ClearFlags flags);
446
447		QVariant data(const QModelIndex &index, int role/* = Qt::DisplayRole*/) const override;
448		bool setData(const QModelIndex &index, const QVariant &value, int role) override;
449		int rowCount(const QModelIndex &parent = QModelIndex()) const override;
450		QHash<int, QByteArray> roleNames() const override;
451
452		bool filterAcceptsRow(int source_row, const QModelIndex &source_parent) const override;
453		bool lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const override;
454
455		signals:
456		void limitChanged();
457		void showExpiredChanged();
458		void showDismissedChanged();
459		void blacklistedDesktopEntriesChanged();
460		void blacklistedNotifyRcNamesChanged();
461		void whitelistedDesktopEntriesChanged();
462		void whitelistedNotifyRcNamesChanged();
463		void showJobsChanged();
464		void urgenciesChanged();
465		void sortModeChanged();
466		void groupModeChanged();
467		void groupLimitChanged();
468		void countChanged();
469		void activeNotificationsCountChanged();
470		void expiredNotificationsCountChanged();
471		void lastReadChanged();
472		void unreadNotificationsCountChanged();
473		void activeJobsCountChanged();
474		void jobsPercentageChanged();
475
476		protected:
477		void classBegin() override;
478		void componentComplete() override;
479
480		private:
481		class Private;
482		QScopedPointer<Private> d;
483
484		};
485
486		} // namespace NotificationManager
487
488		Q_DECLARE_OPERATORS_FOR_FLAGS(NotificationManager::Notifications::Urgencies)