Differential D20265 Diff 57643 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 notifications.
117		*
118		* Default is true.
119		*/
120		Q_PROPERTY(bool showNotifications READ showNotifications WRITE setShowNotifications NOTIFY showNotificationsChanged)
121
122		/**
123		* Whether to show application jobs.
124		*
125		* Default is false.
126		*/
127		Q_PROPERTY(bool showJobs READ showJobs WRITE setShowJobs NOTIFY showJobsChanged)
128
129		/**
130		* The notification urgency types the model should contain.
131		*
132		* Default is all urgencies: low, normal, critical.
133		*/
134		Q_PROPERTY(Urgencies urgencies READ urgencies WRITE setUrgencies NOTIFY urgenciesChanged)
135
136		/**
137		* The sort mode for notifications.
138		*
139		* Default is strictly by date created/updated.
140		*/
141		Q_PROPERTY(SortMode sortMode READ sortMode WRITE setSortMode NOTIFY sortModeChanged)
142
143		/**
144		* The group mode for notifications.
145		*
146		* Default is ungrouped.
147		*/
148		Q_PROPERTY(GroupMode groupMode READ groupMode WRITE setGroupMode NOTIFY groupModeChanged)
149
150		/**
151		* How many notifications are shown in each group.
152		*
153		* You can expand a group by setting the IsGroupExpandedRole to true.
154		*
155		* Default is 0, which means no limit.
156		*/
157		Q_PROPERTY(int groupLimit READ groupLimit WRITE setGroupLimit NOTIFY groupLimitChanged)
158
159		/**
160		* Whether to automatically show notifications that are unread.
161		*
162		* This is any notification that was created or updated after the value of @c lastRead.
163		*/
164		Q_PROPERTY(bool expandUnread READ expandUnread WRITE setExpandUnread NOTIFY expandUnreadChanged)
165
166		/**
167		* The number of notifications in the model
168		*/
169		Q_PROPERTY(int count READ count NOTIFY countChanged)
170
171		/**
172		* The number of active, i.e. non-expired notifications
173		*/
174		Q_PROPERTY(int activeNotificationsCount READ activeNotificationsCount NOTIFY activeNotificationsCountChanged)
175
176		/**
177		* The number of inactive, i.e. non-expired notifications
178		*/
179		Q_PROPERTY(int expiredNotificationsCount READ expiredNotificationsCount NOTIFY expiredNotificationsCountChanged)
180
181		/**
182		* The time when the user last could read the notifications.
183		* This is typically reset whenever the list of notifications is opened and is used to determine
184		* the @c unreadNotificationsCount
185		*/
186		Q_PROPERTY(QDateTime lastRead READ lastRead WRITE setLastRead RESET resetLastRead NOTIFY lastReadChanged)
187
188		/**
189		* The number of notifications added since lastRead
190		*
191		* This can be used to show a "n unread notifications" label
192		*/
193		Q_PROPERTY(int unreadNotificationsCount READ unreadNotificationsCount NOTIFY unreadNotificationsCountChanged)
194
195		/**
196		* The number of active jobs
197		*/
198		Q_PROPERTY(int activeJobsCount READ activeJobsCount NOTIFY activeJobsCountChanged)
199		/**
200		* The combined percentage of all jobs.
201		*
202		* This is the average of all percentages and could can be used to show
203		* a global progress bar.
204		*/
205		Q_PROPERTY(int jobsPercentage READ jobsPercentage NOTIFY jobsPercentageChanged)
206
207		public:
208		explicit Notifications(QObject *parent = nullptr);
209		~Notifications() override;
210
211		enum Roles {
212		IdRole = Qt::UserRole + 1, ///< A notification identifier. This can be uint notification ID or string application job source.
	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		SummaryRole = Qt::DisplayRole, ///< The notification summary.
214		ImageRole = Qt::DecorationRole, ///< The notification main image, which is not the application icon. Only valid for pixmap icons.
215
216		IsGroupRole = Qt::UserRole + 2, ///< Whether the item is a group
217		GroupChildrenCountRole, ///< The number of children in a group.
218		ExpandedGroupChildrenCountRole, ///< The number of children in a group that are expanded.
	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		IsGroupExpandedRole, ///< Whether the group is expanded, this role is writable.
220
221		IsInGroupRole, ///< Whether the notification is currently inside a group.
222		TypeRole, ///< The type of model entry, either NotificationType or JobType.
223		CreatedRole, ///< When the notification was first created.
224		UpdatedRole, ///< When the notification was last updated, invalid when it hasn't been updated.
225
226		BodyRole, ///< The notification body text.
227		IconNameRole, ///< The notification main icon name, which is not the application icon. Only valid for icon names, if a URL supplied, it is loaded and exposed as ImageRole instead.
228
229		DesktopEntryRole, ///< The desktop entry (without .desktop suffix, e.g. org.kde.spectacle) of the application that sent the notification.
230		NotifyRcNameRole, ///< The notifyrc name (e.g. spectaclerc) of the application that sent the notification.
231
232		ApplicationNameRole, ///< The user-visible name of the application (e.g. Spectacle)
233		ApplicationIconNameRole, ///< The icon name of the application
234		DeviceNameRole, ///< The name of the device the notification originally came from, if it was proxied through a sync service like KDE Connect
235
236		// Jobs
237		JobStateRole, ///< The state of the job, either JobStateJopped, JobStateSuspended, or JobStateRunning.
238		PercentageRole, ///< The percentage of the job. Use @c jobsPercentage to get a global percentage for all jobs.
239		JobErrorRole, ///< The error id of the job, zero in case of no error.
240		SuspendableRole, ///< Whether the job can be suspended @sa suspendJob
241		KillableRole, ///< Whether the job can be killed/canceled @sa killJob
242		JobDetailsRole, ///< A pointer to a Job item itself containing more detailed information about the job
243
244		ActionNamesRole, ///< The IDs of the actions, excluding the default and settings action, e.g. [action1, action2]
245		ActionLabelsRole, ///< The user-visible labels of the actions, excluding the default and settings action, e.g. ["Accept", "Reject"]
246		HasDefaultActionRole, ///< Whether the notification has a default action, which is one that is invoked when the popup itself is clicked
247		DefaultActionLabelRole, ///< The user-visible label of the default action, typically not shown as the popup itself becomes clickable
248
249		UrlsRole, ///< A list of URLs associated with the notification, e.g. a path to a screenshot that was just taken or image received
250
251		UrgencyRole, ///< The notification urgency, either LowUrgency, NormalUrgency, or CriticalUrgency. Jobs do not have an urgency.
252		TimeoutRole, ///< The timeout for the notification in milliseconds. 0 means the notification should not timeout, -1 means a sensible default should be applied.
253
254		ConfigurableRole, ///< Whether the notification can be configured because a desktopEntry or notifyRcName is known, or the notification has a setting action. @sa configure
255		ConfigureActionLabelRole, ///< The user-visible label for the settings action
256		ClosableRole, ///< Whether the item can be closed. Notifications are always closable, jobs are only when in JobStateStopped.
257
258		ExpiredRole, ///< The notification timed out and closed. Actions on it cannot be invoked anymore.
259		DismissedRole ///< The notification got temporarily hidden by the user but could still be interacted with.
260		};
261		Q_ENUM(Roles)
262
263		/**
264		* The type of model item.
265		*/
266		enum Type {
267		NoType,
268		NotificationType, ///< This item represents a notification.
269		JobType ///< This item represents an application job.
270		};
271		Q_ENUM(Type)
272
273		/**
274		* The notification urgency.
275		*
276		* @note jobs do not have an urgency, yet still might be above normal urgency notifications.
277		*/
278		enum Urgency {
279		// these don't match the spec's value
280		LowUrgency = 1 << 0, ///< The notification has low urgency, it is not important and may not be shown or added to a history.
281		NormalUrgency = 1 << 1, ///< The notification has normal urgency. This is also the default if no urgecny is supplied.
282		CriticalUrgency = 1 << 2
283		};
284		Q_ENUM(Urgency)
285		Q_DECLARE_FLAGS(Urgencies, Urgency)
286		Q_FLAG(Urgencies)
287
288		/**
289		* Which items should be cleared in a call to @c clear
290		*/
291		enum ClearFlag {
292		ClearExpired = 1 << 1,
293		// TODO more
294		};
295		Q_ENUM(ClearFlag)
296		Q_DECLARE_FLAGS(ClearFlags, ClearFlag)
297		Q_FLAG(ClearFlags)
298
299		/**
300		* The state an application job is in.
301		*/
302		enum JobState {
303		JobStateStopped, ///< The job is stopped. It has either finished (error is 0) or failed (error is not 0)
304		JobStateRunning, ///< The job is currently running.
305		JobStateSuspended ///< The job is currentl paused
306		};
307		Q_ENUM(JobState)
308
309		/**
310		* The sort mode for the model.
311		*/
312		enum SortMode {
313		SortByDate = 0, ///< Sort notifications strictly by the date they were updated or created.
314		// should this be flags? SortJobsFirst \| SortByUrgency \| ...?
315		SortByTypeAndUrgency ///< Sort notifications taking into account their type and urgency. The order is (descending): Critical, jobs, Normal, Low.
316		};
317		Q_ENUM(SortMode)
318
319		/**
320		* The group mode for the model.
321		*/
322		enum GroupMode {
323		GroupDisabled = 0,
324		//GroupApplicationsTree, // TODO make actual tree
325		GroupApplicationsFlat
326		};
327		Q_ENUM(GroupMode)
328
329		int limit() const;
330		void setLimit(int limit);
331
332		bool showExpired() const;
333		void setShowExpired(bool show);
334
335		bool showDismissed() const;
336		void setShowDismissed(bool show);
337
338		QStringList blacklistedDesktopEntries() const;
339		void setBlacklistedDesktopEntries(const QStringList &blacklist);
340
341		QStringList blacklistedNotifyRcNames() const;
342		void setBlacklistedNotifyRcNames(const QStringList &blacklist);
343
344		QStringList whitelistedDesktopEntries() const;
345		void setWhitelistedDesktopEntries(const QStringList &whitelist);
346
347		QStringList whitelistedNotifyRcNames() const;
348		void setWhitelistedNotifyRcNames(const QStringList &whitelist);
349
350		bool showNotifications() const;
351		void setShowNotifications(bool showNotifications);
352
353		bool showJobs() const;
354		void setShowJobs(bool showJobs);
355
356		Urgencies urgencies() const;
357		void setUrgencies(Urgencies urgencies);
358
359		SortMode sortMode() const;
360		void setSortMode(SortMode sortMode);
361
362		GroupMode groupMode() const;
363		void setGroupMode(GroupMode groupMode);
364
365		int groupLimit() const;
366		void setGroupLimit(int limit);
367
368		bool expandUnread() const;
369		void setExpandUnread(bool expand);
370
371		int count() const;
372
373		int activeNotificationsCount() const;
374		int expiredNotificationsCount() const;
375
376		QDateTime lastRead() const;
377		void setLastRead(const QDateTime &lastRead);
378		void resetLastRead();
379
380		int unreadNotificationsCount() const;
381
382		int activeJobsCount() const;
383		int jobsPercentage() const;
384
385		/**
386		* Convert the given QModelIndex into a QPersistentModelIndex
387		*/
388		Q_INVOKABLE QPersistentModelIndex makePersistentModelIndex(const QModelIndex &idx) const;
389
390		/**
391		* @brief Expire a notification
392		*
393		* Closes the notification in response to its timeout running out.
394		*
395		* Call this if you have an implementation that handles the timeout itself
396		* by having called @c stopTimeout
397		*
398		* @sa stopTimeout
399		*/
400		Q_INVOKABLE void expire(const QModelIndex &idx);
401		/**
402		* @brief Close a notification
403		*
404		* Closes the notification in response to the user explicitly closing it.
405		*
406		* When the model index belongs to a group, the entire group is closed.
407		*/
408		Q_INVOKABLE void close(const QModelIndex &idx);
409		/**
410		* @brief Configure a notification
411		*
412		* This will invoke the settings action, if available, otherwise open the
413		* kcm_notifications KCM for configuring the respective application and event.
414		*/
415		Q_INVOKABLE void configure(const QModelIndex &idx); // TODO pass ctx for transient handling
416		/**
417		* @brief Invoke the default notification action
418		*
419		* Invokes the action that should be triggered when clicking
420		* the notification bubble itself.
421		*/
422		Q_INVOKABLE void invokeDefaultAction(const QModelIndex &idx);
423		/**
424		* @brief Invoke a notification action
425		*
426		* Invokes the action with the given actionId on the notification.
427		* For invoking the default action, i.e. the one that is triggered
428		* when clicking the notification bubble, use invokeDefaultAction
429		*/
430		Q_INVOKABLE void invokeAction(const QModelIndex &idx, const QString &actionId);
431
432		/**
433		* @brief Start automatic timeout of notifications
434		*
435		* Call this if you no longer handle the timeout yourself.
436		*
437		* @sa stopTimeout
438		*/
439		Q_INVOKABLE void startTimeout(const QModelIndex &idx);
440
441		Q_INVOKABLE void startTimeout(uint notificationId);
442		/**
443		* @brief Stop the automatic timeout of notifications
444		*
445		* Call this if you have an implementation that handles the timeout itself
446		* taking into account e.g. whether the user is currently interacting with
447		* the notification to not close it under their mouse. Call @c expire
448		* once your custom timer has run out.
449		*
450		* @sa expire
451		*/
452		Q_INVOKABLE void stopTimeout(const QModelIndex &idx);
453
454		/**
455		* @brief Suspend a job
456		*/
457		Q_INVOKABLE void suspendJob(const QModelIndex &idx);
458		/**
459		* @brief Resume a job
460		*/
461		Q_INVOKABLE void resumeJob(const QModelIndex &idx);
462		/**
463		* @brief Kill a job
464		*/
465		Q_INVOKABLE void killJob(const QModelIndex &idx);
466
467		/**
468		* @brief Clear notifications
469		*
470		* Removes the notifications matching th ClearFlags from the model.
471		* This can be used for e.g. a "Clear History" action.
472		*/
473		Q_INVOKABLE void clear(ClearFlags flags);
474
475		/**
476		* Returns a model index pointing to the group of a notification.
477		*/
478		Q_INVOKABLE QModelIndex groupIndex(const QModelIndex &idx) const;
479
480		Q_INVOKABLE void collapseAllGroups();
481
482		QVariant data(const QModelIndex &index, int role) const override;
483		bool setData(const QModelIndex &index, const QVariant &value, int role) override;
484		int rowCount(const QModelIndex &parent = QModelIndex()) const override;
485		QHash<int, QByteArray> roleNames() const override;
486
487		bool filterAcceptsRow(int source_row, const QModelIndex &source_parent) const override;
488		bool lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const override;
489
490		signals:
491		void limitChanged();
492		void showExpiredChanged();
493		void showDismissedChanged();
494		void blacklistedDesktopEntriesChanged();
495		void blacklistedNotifyRcNamesChanged();
496		void whitelistedDesktopEntriesChanged();
497		void whitelistedNotifyRcNamesChanged();
498		void showNotificationsChanged();
499		void showJobsChanged();
500		void urgenciesChanged();
501		void sortModeChanged();
502		void groupModeChanged();
503		void groupLimitChanged();
504		void expandUnreadChanged();
505		void countChanged();
506		void activeNotificationsCountChanged();
507		void expiredNotificationsCountChanged();
508		void lastReadChanged();
509		void unreadNotificationsCountChanged();
510		void activeJobsCountChanged();
511		void jobsPercentageChanged();
512
513		protected:
514		void classBegin() override;
515		void componentComplete() override;
516
517		private:
518		class Private;
519		QScopedPointer<Private> d;
520
521		};
522
523		} // namespace NotificationManager
524
525		Q_DECLARE_OPERATORS_FOR_FLAGS(NotificationManager::Notifications::Urgencies)