KNotifications

knotification.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2005-2006 Olivier Goffart <ogoffart at kde.org>
4  SPDX-FileCopyrightText: 2013-2015 Martin Klapetek <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KNOTIFICATION_H
10 #define KNOTIFICATION_H
11 
12 #include <knotifications_export.h>
13 
14 #include <QList>
15 #include <QObject>
16 #include <QPair>
17 #include <QPixmap>
18 #include <QUrl>
19 #include <QVariant>
20 
21 #include <memory>
22 
23 class QWidget;
24 
26 
27 /**
28  * @class KNotification knotification.h KNotification
29  *
30  * KNotification is the main class for creating notifications.
31  */
32 class KNOTIFICATIONS_EXPORT KNotification : public QObject
33 {
34  Q_OBJECT
35  /**
36  * @copydoc setEventId
37  * @since 5.88
38  */
39  Q_PROPERTY(QString eventId READ eventId WRITE setEventId NOTIFY eventIdChanged)
40  /**
41  * @copydoc setTitle
42  * @since 5.88
43  */
44  Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged)
45  /**
46  * @copydoc setText
47  * @since 5.88
48  */
49  Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
50  /**
51  * @copydoc setIconName
52  * @since 5.88
53  */
54  Q_PROPERTY(QString iconName READ iconName WRITE setIconName NOTIFY iconNameChanged)
55  /**
56  * @copydoc setDefaultAction
57  * @since 5.88
58  */
59  Q_PROPERTY(QString defaultAction READ defaultAction WRITE setDefaultAction NOTIFY defaultActionChanged)
60  /**
61  * @copydoc setActions
62  * @since 5.88
63  */
64  Q_PROPERTY(QStringList actions READ actions WRITE setActions NOTIFY actionsChanged)
65  /**
66  * @copydoc setFlags
67  * @since 5.88
68  */
69  Q_PROPERTY(NotificationFlags flags READ flags WRITE setFlags NOTIFY flagsChanged)
70  /**
71  * @copydoc setComponentName
72  * @since 5.88
73  */
74  Q_PROPERTY(QString componentName READ componentName WRITE setComponentName NOTIFY componentNameChanged)
75  /**
76  * @copydoc setUrls
77  * @since 5.88
78  */
79  Q_PROPERTY(QList<QUrl> urls READ urls WRITE setUrls NOTIFY urlsChanged)
80  /**
81  * @copydoc setUrgency
82  * @since 5.88
83  */
84  Q_PROPERTY(Urgency urgency READ urgency WRITE setUrgency NOTIFY urgencyChanged)
85  /**
86  * @copydoc setAutoDelete
87  * @since 5.88
88  */
89  Q_PROPERTY(bool autoDelete READ isAutoDelete WRITE setAutoDelete NOTIFY autoDeleteChanged)
90  /**
91  * @since 5.90
92  */
93  Q_PROPERTY(QString xdgActivationToken READ xdgActivationToken NOTIFY xdgActivationTokenChanged)
94  /**
95  * @copydoc setHint
96  * @since 5.101
97  */
98  Q_PROPERTY(QVariantMap hints READ hints WRITE setHints NOTIFY hintsChanged)
99 
100 public:
101  /**
102  * Sometimes the user may want different notifications for the same event,
103  * depending the source of the event. Example, you want to be notified for mails
104  * that arrive in your folder "personal inbox" but not for those in "spam" folder
105  *
106  * A notification context is a pair of two strings.
107  * The first string is a key from what the context is. example "group" or
108  * "filter" (not translated).
109  * The second is the id of the context. In our example, the group id or the
110  * filter id in the applications.
111  * These strings are the ones present in the config file, and are in theory not
112  * shown in the user interface.
113  *
114  * The order of contexts in the list is is important, the most important context
115  * should be placed first. They are processed in that order when the notification occurs.
116  *
117  * @see event
118  */
120  typedef QList<Context> ContextList;
121 
122  /**
123  * @see NotificationFlags
124  */
126  /**
127  * When the notification is activated, raise the notification's widget.
128  *
129  * This will change the desktop, raise the window, and switch to the tab.
130  * @todo doesn't work yet
131  */
132  RaiseWidgetOnActivation = 0x01,
133 
134  /**
135  * The notification will be automatically closed after a timeout. (this is the default)
136  */
137  CloseOnTimeout = 0x00,
138 
139  /**
140  * The notification will NOT be automatically closed after a timeout.
141  * You will have to track the notification, and close it with the
142  * close function manually when the event is done, otherwise there will be a memory leak
143  */
144  Persistent = 0x02,
145 
146  /**
147  * The notification will be automatically closed if the widget() becomes
148  * activated.
149  *
150  * If the widget is already activated when the notification occurs, the
151  * notification will be closed after a small timeout.
152  *
153  * This only works if the widget is the toplevel widget
154  * @todo make it work with tabulated widget
155  */
156  CloseWhenWidgetActivated = 0x04,
157 
158  /**
159  * The audio plugin will loop the sound until the notification is closed
160  */
161  LoopSound = 0x08,
162 
163  /**
164  * Sends a hint to Plasma to skip grouping for this notification
165  *
166  * @since 5.18
167  */
168  SkipGrouping = 0x10,
169 
170  /**
171  * @internal
172  * The event is a standard kde event, and not an event of the application
173  */
174  DefaultEvent = 0xF000,
175 
176  };
177 
178  /**
179  * Stores a combination of #NotificationFlag values.
180  */
183 
184  /**
185  * default events you can use in the event function
186  */
188  Notification,
189  Warning,
190  Error,
191  Catastrophe,
192  };
193 
194  /**
195  * The urgency of a notification.
196  *
197  * @since 5.58
198  * @sa setUrgency
199  */
200  enum Urgency {
201  DefaultUrgency = -1,
202  LowUrgency = 10,
203  NormalUrgency = 50,
204  HighUrgency = 70,
205  CriticalUrgency = 90,
206  };
207  Q_ENUM(Urgency)
208 
209 #if KNOTIFICATIONS_ENABLE_DEPRECATED_SINCE(5, 75)
210  /**
211  * Create a new notification.
212  *
213  * You have to use sendEvent to show the notification.
214  *
215  * The pointer is automatically deleted when the event is closed.
216  *
217  * Make sure you use one of the NotificationFlags CloseOnTimeOut or
218  * CloseWhenWidgetActivated, if not,
219  * you have to close the notification yourself.
220  *
221  * @param eventId is the name of the event
222  * @param widget is a widget where the notification reports to
223  * @param flags is a bitmask of NotificationFlag
224  * @deprecated Since 5.75, use other constructor and call setWidget() explicitly
225  */
226  KNOTIFICATIONS_DEPRECATED_VERSION(5, 75, "Use other constructor and call setWidget() explicitly")
227  explicit KNotification(const QString &eventId, QWidget *widget, const NotificationFlags &flags = CloseOnTimeout);
228 #endif
229 
230  /**
231  * Create a new notification.
232  *
233  * You have to use sendEvent to show the notification.
234  *
235  * The pointer is automatically deleted when the event is closed.
236  *
237  * The NotificationFlags is set to CloseOnTimeout.
238  *
239  * @param eventId is the name of the event
240  * @since 5.75
241  */
242  inline explicit KNotification(const QString &eventId)
243  : KNotification(eventId, CloseOnTimeout, nullptr)
244  {
245  }
246  // TODO KF6: remove thic constructor, in favour of other non-deprecated constructor
247  // It is a helper constructor for software binary compatibility of code which called the
248  // deprecated constructor so far due to it's second parameter "widget" having had
249  // a default nullptr value.
250 
251  /**
252  * Create a new notification.
253  *
254  * You have to use sendEvent to show the notification.
255  *
256  * The pointer is automatically deleted when the event is closed.
257  *
258  * Make sure you use one of the NotificationFlags CloseOnTimeOut or
259  * CloseWhenWidgetActivated, if not,
260  * you have to close the notification yourself.
261  *
262  * @since 4.4
263  *
264  * @param eventId is the name of the event
265  * @param flags is a bitmask of NotificationFlag
266  * @param parent parent object
267  */
268  explicit KNotification(const QString &eventId, const NotificationFlags &flags, QObject *parent = nullptr);
269  // TODO KF6: pass flags by value instead of reference, set CloseOnTimeout as default value
270 
271  ~KNotification() override;
272 
273  /**
274  * @brief the widget associated to the notification
275  *
276  * If the widget is destroyed, the notification will be automatically canceled.
277  * If the widget is activated, the notification will be automatically closed if the NotificationFlags specify that
278  *
279  * When the notification is activated, the widget might be raised.
280  * Depending on the configuration, the taskbar entry of the window containing the widget may blink.
281  */
282  QWidget *widget() const;
283 
284  /**
285  * Set the widget associated to the notification.
286  * The notification is reparented to the new widget.
287  * \see widget()
288  * @param widget the new widget
289  */
290  void setWidget(QWidget *widget);
291 
292  /**
293  * @return the name of the event
294  */
295  QString eventId() const;
296  /**
297  * Set the event id, if not already passed to the constructor.
298  * @since 5.88
299  */
300  void setEventId(const QString &eventId);
301 
302  /**
303  * @return the notification title
304  * @see setTitle
305  * @since 4.3
306  */
307  QString title() const;
308 
309  /**
310  * Set the title of the notification popup.
311  * If no title is set, the application name will be used.
312  *
313  * @param title The title of the notification
314  * @since 4.3
315  */
316  void setTitle(const QString &title);
317 
318  /**
319  * @return the notification text
320  * @see setText
321  */
322  QString text() const;
323 
324  /**
325  * Set the notification text that will appear in the popup.
326  *
327  * In Plasma workspace, the text is shown in a QML label which uses Text.StyledText,
328  * ie. it supports a small subset of HTML entities (mostly just formatting tags)
329  *
330  * If the notifications server does not advertise "body-markup" capability,
331  * all HTML tags are stripped before sending it to the server
332  *
333  * @param text The text to display in the notification popup
334  */
335  void setText(const QString &text);
336 
337  /**
338  * \return the icon shown in the popup
339  * \see setIconName
340  * \since 5.4
341  */
342  QString iconName() const;
343 
344  /**
345  * Set the icon that will be shown in the popup.
346  *
347  * @param icon the icon
348  * @since 5.4
349  */
350  void setIconName(const QString &icon);
351 
352  /**
353  * \return the pixmap shown in the popup
354  * \see setPixmap
355  */
356  QPixmap pixmap() const;
357  /**
358  * Set the pixmap that will be shown in the popup. If you want to use an icon from the icon theme use setIconName instead.
359  *
360  * @param pix the pixmap
361  */
362  void setPixmap(const QPixmap &pix);
363 
364  /**
365  * @return the default action, or an empty string if not set
366  * @since 5.31
367  */
368  QString defaultAction() const;
369 
370  /**
371  * Set a default action that will be triggered when the notification is
372  * activated (typically, by clicking on the notification popup). The default
373  * action should raise a window belonging to the application that sent it.
374  *
375  * The string will be used as a label for the action, so ideally it should
376  * be wrapped in i18n() or tr() calls.
377  *
378  * The visual representation of actions depends on the notification server.
379  * In Plasma and Gnome desktops, the actions are performed by clicking on
380  * the notification popup, and the label is not presented to the user.
381  *
382  *
383  * @param action Label of the default action. The label might or might not
384  * be displayed to the user by the notification server, depending on the
385  * implementation. Passing an empty string disables the default action.
386  * @since 5.31
387  */
388  void setDefaultAction(const QString &defaultAction);
389 
390  /**
391  * @return the list of actions
392  */
393  // KF6: Rename to "additionalActions"?
394  QStringList actions() const;
395 
396  /**
397  * Set the list of actions shown in the popup. The strings passed
398  * in that QStringList will be used as labels for those actions,
399  * so ideally they should be wrapped in i18n() or tr() calls.
400  * In Plasma workspace, these will be shown as buttons inside
401  * the notification popup.
402  *
403  * The visual representation of actions however depends
404  * on the notification server
405  *
406  * @param actions List of strings used as action labels
407  */
408  // KF6: Rename to "setAdditionalActions"?
409  void setActions(const QStringList &actions);
410 
411  /**
412  * @return the inline reply action.
413  * @since 5.81
414  */
415  KNotificationReplyAction *replyAction() const;
416 
417  /**
418  * @brief Add an inline reply action to the notification.
419  *
420  * On supported platforms this lets the user type a reply to a notification,
421  * such as replying to a chat message, from the notification popup, for example:
422  *
423  * @code{.cpp}
424  * KNotification *notification = new KNotification(QStringLiteral("notification"));
425  * ...
426  * auto replyAction = std::make_unique<KNotificationReplyAction>(i18nc("@action:button", "Reply"));
427  * replyAction->setPlaceholderText(i18nc("@info:placeholder", "Reply to Dave..."));
428  * QObject::connect(replyAction.get(), &KNotificationReplyAction::replied, [](const QString &text) {
429  * qDebug() << "you replied with" << text;
430  * });
431  * notification->setReplyAction(std::move(replyAction));
432  * @endcode
433  *
434  * @param replyAction the reply action to set
435  * @since 5.81
436  */
437  void setReplyAction(std::unique_ptr<KNotificationReplyAction> replyAction);
438 
439  /**
440  * @return the list of contexts, see KNotification::Context
441  */
442  ContextList contexts() const;
443  /**
444  * set the list of contexts, see KNotification::Context
445  *
446  * The list of contexts must be set before calling sendEvent;
447  */
448  void setContexts(const ContextList &contexts);
449  /**
450  * append a context at the list of contexts, see KNotification::Context
451  * @param context the context which is added
452  */
453  void addContext(const Context &context);
454  /**
455  * @overload
456  * @param context_key is the key of the context
457  * @param context_value is the value of the context
458  */
459  void addContext(const QString &context_key, const QString &context_value);
460 
461  /**
462  * @return the notification flags.
463  */
464  NotificationFlags flags() const;
465 
466  /**
467  * Set the notification flags.
468  * These must be set before calling sendEvent()
469  */
470  void setFlags(const NotificationFlags &flags);
471 
472  /**
473  * Returns the component name used to determine the location of the configuration file.
474  * @since 5.88
475  */
476  QString componentName() const;
477  /**
478  * The componentData is used to determine the location of the config file.
479  *
480  * If no componentName is set, the app name is used by default
481  *
482  * @param componentName the new component name
483  */
484  void setComponentName(const QString &componentName);
485 
486  /**
487  * URLs associated with this notification
488  * @since 5.29
489  */
490  QList<QUrl> urls() const;
491 
492  /**
493  * Sets URLs associated with this notification
494  *
495  * For example, a screenshot application might want to provide the
496  * URL to the file that was just taken so the notification service
497  * can show a preview.
498  *
499  * @note This feature might not be supported by the user's notification service
500  *
501  * @param urls A list of URLs
502  * @since 5.29
503  */
504  void setUrls(const QList<QUrl> &urls);
505 
506  /**
507  * The urgency of the notification.
508  * @since 5.58
509  */
510  Urgency urgency() const;
511 
512  /**
513  * Sets the urgency of the notification.
514  *
515  * This defines the importance of the notification. For example,
516  * a track change in a media player would be a low urgency.
517  * "You have new mail" would be normal urgency. "Your battery level
518  * is low" would be a critical urgency.
519  *
520  * Use critical notifications with care as they might be shown even
521  * when giving a presentation or when notifications are turned off.
522  *
523  * @param urgency The urgency.
524  * @since 5.58
525  */
526  void setUrgency(Urgency urgency);
527 
528  /**
529  * @internal
530  * the id given by the notification manager
531  */
532  int id();
533 
534  /**
535  * @internal
536  * appname used for the D-Bus object
537  */
538  QString appName() const;
539 
540  /**
541  * Returns whether this notification object will be automatically deleted after closing.
542  * @since 5.88
543  */
544  bool isAutoDelete() const;
545  /**
546  * Sets whether this notification object will be automatically deleted after closing.
547  * This is on by default for C++, and off by default for QML.
548  * @since 5.88
549  */
550  void setAutoDelete(bool autoDelete);
551 
552  /**
553  * Returns the activation token to use to activate a window.
554  * @since 5.90
555  */
556  QString xdgActivationToken() const;
557 
558 Q_SIGNALS:
559 #if KNOTIFICATIONS_ENABLE_DEPRECATED_SINCE(5, 76)
560  /**
561  * Emitted only when the default activation has occurred
562  * @deprecated Since 5.67, use defaultActivated() instead
563  */
564  KNOTIFICATIONS_DEPRECATED_VERSION_BELATED(5, 76, 5, 67, "Use defaultActivated() instead")
565  void activated(); // clazy:exclude=overloaded-signal
566 #endif
567 
568  /**
569  * Emitted when the default action has been activated.
570  * @since 5.67
571  */
572  void defaultActivated();
573 
574  /**
575  * Emitted when an action has been activated.
576  *
577  * The parameter passed by the signal is the index of the action
578  * in the QStringList set by setActions() call.
579  *
580  * @param action will be 0 if the default action was activated, or the index of the action in the actions QStringList
581  */
582  void activated(unsigned int action); // clazy:exclude=overloaded-signal
583 
584  /**
585  * Convenience signal that is emitted when the first action is activated.
586  */
587  void action1Activated();
588 
589  /**
590  * \overload
591  */
592  void action2Activated();
593 
594  /**
595  * \overload
596  */
597  void action3Activated();
598 
599  /**
600  * Emitted when the notification is closed.
601  *
602  * Can be closed either by the user clicking the close button,
603  * the timeout running out or when an action was triggered.
604  */
605  void closed();
606 
607  /**
608  * The notification has been ignored
609  */
610  void ignored();
611 
612  /**
613  * Emitted when @c eventId changed.
614  * @since 5.88
615  */
616  void eventIdChanged();
617  /**
618  * Emitted when @c title changed.
619  * @since 5.88
620  */
621  void titleChanged();
622  /**
623  * Emitted when @c text changed.
624  * @since 5.88
625  */
626  void textChanged();
627  /**
628  * Emitted when @c iconName changed.
629  * @since 5.88
630  */
631  void iconNameChanged();
632  /**
633  * Emitted when @c defaultAction changed.
634  * @since 5.88
635  */
636  void defaultActionChanged();
637  /**
638  * Emitted when @c actions changed.
639  * @since 5.88
640  */
641  void actionsChanged();
642  /**
643  * Emitted when @p flags changed.
644  * @since 5.88
645  */
646  void flagsChanged();
647  /**
648  * Emitted when @p componentName changed.
649  * @since 5.88
650  */
651  void componentNameChanged();
652  /**
653  * Emitted when @p urls changed.
654  * @since 5.88
655  */
656  void urlsChanged();
657  /**
658  * Emitted when @p urgency changed.
659  * @since 5.88
660  */
661  void urgencyChanged();
662  /**
663  * Emitted when @p autoDelete changed.
664  * @since 5.88
665  */
666  void autoDeleteChanged();
667  /**
668  * Emitted when @p xdgActivationToken changes.
669  * @since 5.90
670  */
671  void xdgActivationTokenChanged();
672  /**
673  * Emitted when @p hints changes.
674  * @since 5.101
675  */
676  void hintsChanged();
677 
678 public Q_SLOTS:
679  /**
680  * @brief Activate the action specified action
681  * If the action is zero, then the default action is activated
682  */
683  void activate(unsigned int action = 0);
684 
685  /**
686  * Close the notification without activating it.
687  *
688  * This will delete the notification.
689  */
690  void close();
691 
692 #if KNOTIFICATIONS_ENABLE_DEPRECATED_SINCE(5, 67)
693  /**
694  * @brief Raise the widget.
695  * This will change the desktop, activate the window, and the tab if needed.
696  * @deprecated since 5.67, use QWindow raise + requestActivate instead.
697  */
698  KNOTIFICATIONS_DEPRECATED_VERSION(5, 67, "Use QWindow raise + requestActivate instead")
699  void raiseWidget();
700 #endif
701 
702  /**
703  * The notification will automatically be closed if all presentations are finished.
704  * if you want to show your own presentation in your application, you should use this
705  * function, so it will not be automatically closed when there is nothing to show.
706  *
707  * Don't forget to deref, or the notification may be never closed if there is no timeout.
708  *
709  * @see deref
710  */
711  void ref();
712  /**
713  * Remove a reference made with ref(). If the ref counter hits zero,
714  * the notification will be closed and deleted.
715  *
716  * @see ref
717  */
718  void deref();
719 
720  /**
721  * Send the notification to the server.
722  *
723  * This will cause all the configured plugins to execute their actions on this notification
724  * (eg. a sound will play, a popup will show, a command will be executed etc).
725  */
726  void sendEvent();
727 
728  /**
729  * @internal
730  * update the texts, the icon, and the actions of one existing notification
731  */
732  void update();
733 
734  /**
735  * @since 5.57
736  * Adds a custom hint to the notification. Those are key-value pairs that can be interpreted by the respective notification backend to trigger additional,
737  * non-standard features.
738  * @param hint the hint's key
739  * @param value the hint's value
740  */
741  Q_INVOKABLE void setHint(const QString &hint, const QVariant &value);
742 
743  /**
744  * @since 5.57
745  * Returns the custom hints set by setHint()
746  */
747  QVariantMap hints() const;
748 
749  /**
750  * @since 5.101
751  * Set custom hints on the notification.
752  * @sa setHint
753  */
754  void setHints(const QVariantMap &hints);
755 
756 private:
757  friend class KNotificationManager;
758  struct Private;
759  std::unique_ptr<Private> const d;
760 
761 protected:
762  /**
763  * reimplemented for internal reasons
764  */
765  bool eventFilter(QObject *watched, QEvent *event) override;
766  static QString standardEventToEventId(StandardEvent event);
767  static QString standardEventToIconName(StandardEvent event);
768 
769 public:
770  /**
771  * @brief emit an event
772  *
773  * This method creates the KNotification, setting every parameter, and fire the event.
774  * You don't need to call sendEvent
775  *
776  * A popup may be displayed or a sound may be played, depending the config.
777  *
778  * @return a KNotification . You may use that pointer to connect some signals or slot.
779  * the pointer is automatically deleted when the event is closed.
780  *
781  * Make sure you use one of the CloseOnTimeOut or CloseWhenWidgetActivated, if not,
782  * you have to close yourself the notification.
783  *
784  * @param eventId is the name of the event
785  * @param title is title of the notification to show in the popup.
786  * @param text is the text of the notification to show in the popup.
787  * @param pixmap is a picture which may be shown in the popup.
788  * @param widget is a widget where the notification reports to
789  * @param flags is a bitmask of NotificationFlag
790  * @param componentName used to determine the location of the config file. by default, appname is used
791  * @since 4.4
792  */
793  static KNotification *event(const QString &eventId,
794  const QString &title,
795  const QString &text,
796  const QPixmap &pixmap = QPixmap(),
797  QWidget *widget = nullptr,
798  const NotificationFlags &flags = CloseOnTimeout,
799  const QString &componentName = QString());
800 
801  /**
802  * @brief emit a standard event
803  *
804  * @overload
805  *
806  * This will emit a standard event
807  *
808  * @param eventId is the name of the event
809  * @param text is the text of the notification to show in the popup.
810  * @param pixmap is a picture which may be shown in the popup.
811  * @param widget is a widget where the notification reports to
812  * @param flags is a bitmask of NotificationFlag
813  * @param componentName used to determine the location of the config file. by default, plasma_workspace is used
814  */
815  static KNotification *event(const QString &eventId,
816  const QString &text = QString(),
817  const QPixmap &pixmap = QPixmap(),
818  QWidget *widget = nullptr,
819  const NotificationFlags &flags = CloseOnTimeout,
820  const QString &componentName = QString());
821 
822  /**
823  * @brief emit a standard event
824  *
825  * @overload
826  *
827  * This will emit a standard event
828  *
829  * @param eventId is the name of the event
830  * @param text is the text of the notification to show in the popup
831  * @param pixmap is a picture which may be shown in the popup
832  * @param widget is a widget where the notification reports to
833  * @param flags is a bitmask of NotificationFlag
834  */
835  static KNotification *event(StandardEvent eventId,
836  const QString &text = QString(),
837  const QPixmap &pixmap = QPixmap(),
838  QWidget *widget = nullptr,
839  const NotificationFlags &flags = CloseOnTimeout);
840 
841  /**
842  * @brief emit a standard event
843  *
844  * @overload
845  *
846  * This will emit a standard event
847  *
848  * @param eventId is the name of the event
849  * @param title is title of the notification to show in the popup.
850  * @param text is the text of the notification to show in the popup
851  * @param pixmap is a picture which may be shown in the popup
852  * @param widget is a widget where the notification reports to
853  * @param flags is a bitmask of NotificationFlag
854  * @since 4.4
855  */
856  static KNotification *event(StandardEvent eventId,
857  const QString &title,
858  const QString &text,
859  const QPixmap &pixmap,
860  QWidget *widget = nullptr,
861  const NotificationFlags &flags = CloseOnTimeout);
862 
863  /**
864  * @brief emit a standard event with the possibility of setting an icon by icon name
865  *
866  * @overload
867  *
868  * This will emit a standard event
869  *
870  * @param eventId is the name of the event
871  * @param title is title of the notification to show in the popup.
872  * @param text is the text of the notification to show in the popup
873  * @param iconName a Freedesktop compatible icon name to be shown in the popup
874  * @param widget is a widget where the notification reports to
875  * @param flags is a bitmask of NotificationFlag
876  * @param componentName used to determine the location of the config file. by default, plasma_workspace is used
877  * @since 5.4
878  */
879  static KNotification *event(const QString &eventId,
880  const QString &title,
881  const QString &text,
882  const QString &iconName,
883  QWidget *widget = nullptr,
884  const NotificationFlags &flags = CloseOnTimeout,
885  const QString &componentName = QString());
886 
887  /**
888  * @brief emit a standard event with the possibility of setting an icon by icon name
889  *
890  * @overload
891  *
892  * This will emit a standard event with a custom icon
893  *
894  * @param eventId the type of the standard (not app-defined) event
895  * @param title is title of the notification to show in the popup.
896  * @param text is the text of the notification to show in the popup
897  * @param iconName a Freedesktop compatible icon name to be shown in the popup
898  * @param widget is a widget where the notification reports to
899  * @param flags is a bitmask of NotificationFlag
900  * @since 5.9
901  */
902  static KNotification *event(StandardEvent eventId,
903  const QString &title,
904  const QString &text,
905  const QString &iconName,
906  QWidget *widget = nullptr,
907  const NotificationFlags &flags = CloseOnTimeout);
908 
909  /**
910  * @brief emit a standard event
911  *
912  * @overload
913  *
914  * This will emit a standard event with its standard icon
915  *
916  * @param eventId the type of the standard (not app-defined) event
917  * @param title is title of the notification to show in the popup.
918  * @param text is the text of the notification to show in the popup
919  * @param widget is a widget where the notification reports to
920  * @param flags is a bitmask of NotificationFlag
921  * @since 5.9
922  */
923  static KNotification *
924  event(StandardEvent eventId, const QString &title, const QString &text, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout);
925 
926  /**
927  * This is a simple substitution for QApplication::beep()
928  *
929  * @param reason a short text explaining what has happened (may be empty)
930  * @param widget the widget the notification refers to
931  */
932  static void beep(const QString &reason = QString(), QWidget *widget = nullptr);
933 
934  // prevent warning
935  using QObject::event;
936 };
937 
938 Q_DECLARE_OPERATORS_FOR_FLAGS(KNotification::NotificationFlags)
939 
940 #endif
Q_PROPERTY(...)
Q_ENUM(...)
Q_SLOTSQ_SLOTS
void ref()
Urgency
The urgency of a notification.
void deref()
virtual bool eventFilter(QObject *watched, QEvent *event)
virtual bool event(QEvent *e)
QCA_EXPORT QString appName()
KNotification(const QString &eventId)
Create a new notification.
Q_SIGNALSQ_SIGNALS
Q_FLAG(...)
StandardEvent
default events you can use in the event function
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 03:49:39 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.