1/* This file is part of the KDE libraries
2 Copyright (C) 2005-2006 Olivier Goffart <ogoffart at kde.org>
3 Copyright (C) 2013-2015 Martin Klapetek <mklapetek@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KNOTIFICATION_H
21#define KNOTIFICATION_H
22
23#include <knotifications_export.h>
24
25#include <QPixmap>
26#include <QObject>
27#include <QList>
28#include <QPair>
29#include <QUrl>
30
31class QWidget;
32
33/**
34 * @class KNotification knotification.h KNotification
35 *
36 * KNotification is used to notify the user of an event.
37 *
38 * \section Introduction
39 *
40 * There are two main kinds of notifications:
41 *
42 * @li Feedback events:
43 * For notifying the user that he/she just performed an operation, like maximizing a
44 * window. This allows us to play sounds when a dialog appears.
45 * This is an instant notification. It ends automatically after a small timeout.
46 *
47 * @li persistant notifications:
48 * Notify when the user received a new message, or when something else important happened
49 * the user has to know about. This notification has a start and a end. It begins when
50 * the event actually occurs, and finishes when the message is acknowledged or read.
51 *
52 * Example of a persistent notification in an instant messaging application:
53 * The application emits the notification when the message is actually received, and closes it only
54 * when the user has read the message (when the message window has received the focus) using the close() slot.
55 * Persistent notifications must have the Persistent flag.
56 *
57 * By default a notification will use the application name as title, but you
58 * can also provide a brief text in the title and a more precise description in
59 * the body text. This is especially useful for notifications coming from
60 * applications which should be considered "part of the system", like a battery
61 * monitor or a network connection manager.
62 * For example a battery indicator could use "Low Battery" as a title and "Only
63 * 12 minutes left." as a body text.
64 *
65 * In order to perform a notification, you need to create a description file, which contains
66 * default parameters of the notification, and use KNotification::event at the place in the
67 * application code where the notification occurs.
68 * The returned KNotification pointer may be used to connect signals or slots
69 *
70 * \section file The global config file
71 * Your application should install a file called <em>knotifications5/appname.notifyrc</em>
72 * in a QStandardPaths::GenericDataLocation directory.
73 *
74 * The filename must either match QCoreApplication::applicationName or be specified as the
75 * component name to the KNotification object.
76 * @warning Notifications won't be visible otherwise.
77 *
78 * You can do this with the following CMake command:
79 * install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR}))
80 *
81 * This file contains mainly 3 parts
82 * <ol><li>\ref global "Global information"</li>
83 * <li>\ref context "Context information"</li>
84 * <li>\ref events "Definition of individual events"</li></ol>
85 *
86 * \subsection global Global information
87 * The global part looks like that
88 * <pre>
89 [Global]
90 IconName=Filename
91 Comment=Friendly Name of app
92 Name=Name of app
93 * </pre>
94 * The icon filename is just the name, without extension, it's found with the KIconLoader.
95 * The Comment field will be used in KControl to describe the application.
96 * The Name field is optional and may be used as the application name for popup,
97 * if Name is not present, Comment is used instead
98 *
99 * \subsection context Context information
100 *
101 * This part consists of hints for the configuration widget
102 * <pre>
103 [Context/group]
104 Name=Group name
105 Comment=The name of the group for contacts
106
107 [Context/folder]
108 Name=Group name
109 * </pre>
110 * The second part of the groupname is the context identifier.
111 * It should not contain special characters.
112 * The Name field is the one the user will see (and which is translated)
113 *
114 * \subsection events Definition of Events
115 *
116 * The definition of the events forms the most important part of the config file
117 * <pre>
118 [Event/newmail]
119 Name=New email
120 Comment=You have got a new email
121 Contexts=folder,group
122 Action=Sound|Popup
123
124 [Event/contactOnline]
125 Name=Contact goes online
126 Comment=One of your contact has been connected
127 Contexts=group
128 Sound=filetoplay.ogg
129 Action=None
130 Urgency=Low
131 * </pre>
132 * These are the default settings for each notifiable event.
133 * Action is the string representing the action. Actions can be added to
134 * KNotification as plugins, by deriving from KNotificationPlugin.
135 * At the time of writing, the following actions are available: Taskbar,
136 * Sound, Popup, Logfile, TTS, Execute.
137 * Actions can be combined by separating them with '|'.
138 *
139 * Contexts is a comma separated list of possible context for this event.
140 *
141 * Urgency can be any of: Low, Normal, Critical.
142 *
143 * \section userfile The user's config file
144 *
145 * This is an implementation detail, and is described here for your information.
146 *
147 * In the config file, there are two parts: the event configuration, and the context information
148 * \subsection context Context information
149 * These are hints for the configuration dialog. They contain both the internal id of the context, and the user visible string.
150 * <pre>
151 [Context/group]
152 Values=1:Friends,2:Work,3:Family
153 * </pre>
154 * \subsection event Events configuration
155 * This contains the configuration of events for the user.
156 * It contains the same fields as the description file.
157 * The key of groups is in the form
158 * <em>Event/&lt;EventName&gt;/&lt;ContextName&gt;/&lt;ContextValue&gt;</em>
159 * <pre>
160 [Event/contactOnline]
161 Action=Sound
162 Sound=/usr/share/sounds/super.ogg
163
164 [Event/contactOnline/group/1]
165 Action=Popup|Sound
166 * </pre>
167 *
168 * \section example Example of code
169 *
170 * This portion of code will fire the event for the "contactOnline" event
171 *
172 * @code
173 KNotification *notification= new KNotification ( "contactOnline", widget );
174 notification->setText( i18n("The contact <i>%1</i> has gone online", contact->name() );
175 notification->setPixmap( contact->pixmap() );
176 notification->setActions( QStringList( i18n( "Open chat" ) ) );
177
178 foreach( const QString &group , contact->groups() ) {
179 notification->addContext( "group" , group ) ;
180 }
181
182 connect(notification, SIGNAL(activated(unsigned int )), contact , SLOT(slotOpenChat()) );
183
184 notification->sendEvent();
185 * @endcode
186 *
187 * @author Olivier Goffart \<ogoffart at kde.org\>
188 */
189class KNOTIFICATIONS_EXPORT KNotification : public QObject
190{
191 Q_OBJECT
192
193public:
194 /**
195 * Sometimes the user may want different notifications for the same event,
196 * depending the source of the event. Example, you want to be notified for mails
197 * that arrive in your folder "personal inbox" but not for those in "spam" folder
198 *
199 * A notification context is a pair of two strings.
200 * The first string is a key from what the context is. example "group" or
201 * "filter" (not translated).
202 * The second is the id of the context. In our example, the group id or the
203 * filter id in the applications.
204 * These strings are the ones present in the config file, and are in theory not
205 * shown in the user interface.
206 *
207 * The order of contexts in the list is is important, the most important context
208 * should be placed first. They are processed in that order when the notification occurs.
209 *
210 * @see event
211 */
212 typedef QPair<QString, QString> Context;
213 typedef QList< Context > ContextList;
214
215 enum NotificationFlag {
216 /**
217 * When the notification is activated, raise the notification's widget.
218 *
219 * This will change the desktop, raise the window, and switch to the tab.
220 * @todo doesn't work yet
221 */
222 RaiseWidgetOnActivation = 0x01,
223
224 /**
225 * The notification will be automatically closed after a timeout. (this is the default)
226 */
227 CloseOnTimeout = 0x00,
228
229 /**
230 * The notification will NOT be automatically closed after a timeout.
231 * You will have to track the notification, and close it with the
232 * close function manually when the event is done, otherwise there will be a memory leak
233 */
234 Persistent = 0x02,
235
236 /**
237 * The notification will be automatically closed if the widget() becomes
238 * activated.
239 *
240 * If the widget is already activated when the notification occurs, the
241 * notification will be closed after a small timeout.
242 *
243 * This only works if the widget is the toplevel widget
244 * @todo make it work with tabulated widget
245 */
246 CloseWhenWidgetActivated = 0x04,
247
248 /**
249 * The audio plugin will loop the sound until the notification is closed
250 */
251 LoopSound = 0x08,
252
253 /**
254 * Sends a hint to Plasma to skip grouping for this notification
255 *
256 * @since: 5.18
257 */
258 SkipGrouping = 0x10,
259
260 /**
261 * @internal
262 * The event is a standard kde event, and not an event of the application
263 */
264 DefaultEvent = 0xF000
265
266 };
267
268 Q_DECLARE_FLAGS(NotificationFlags, NotificationFlag)
269
270 /**
271 * default events you can use in the event function
272 */
273 enum StandardEvent { Notification, Warning, Error, Catastrophe };
274
275 /**
276 * The urgency of a notification.
277 *
278 * @since 5.58
279 * @sa setUrgency
280 */
281 enum Urgency {
282 DefaultUrgency = -1,
283 LowUrgency = 10,
284 NormalUrgency = 50,
285 HighUrgency = 70,
286 CriticalUrgency = 90
287 };
288
289 /**
290 * Create a new notification.
291 *
292 * You have to use sendEvent to show the notification.
293 *
294 * The pointer is automatically deleted when the event is closed.
295 *
296 * Make sure you use one of the NotificationFlags CloseOnTimeOut or
297 * CloseWhenWidgetActivated, if not,
298 * you have to close the notification yourself.
299 *
300 * @param eventId is the name of the event
301 * @param widget is a widget where the notification reports to
302 * @param flags is a bitmask of NotificationFlag
303 */
304 explicit KNotification(const QString &eventId, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout);
305
306 /**
307 * Create a new notification.
308 *
309 * You have to use sendEvent to show the notification.
310 *
311 * The pointer is automatically deleted when the event is closed.
312 *
313 * Make sure you use one of the NotificationFlags CloseOnTimeOut or
314 * CloseWhenWidgetActivated, if not,
315 * you have to close the notification yourself.
316 *
317 * @since 4.4
318 *
319 * @param eventId is the name of the event
320 * @param flags is a bitmask of NotificationFlag
321 * @param parent parent object
322 */
323 // KDE5: Clean up this mess
324 // Only this constructor should stay with saner argument order and
325 // defaults. Because of binary and source compatibility issues it has to
326 // stay this way for now. The second argument CANNOT have a default
327 // argument. if someone needs a widget associated with the notification he
328 // should use setWidget after creating the object (or some xyz_cast magic)
329 explicit KNotification(const QString &eventId, const NotificationFlags &flags, QObject *parent = nullptr);
330
331 ~KNotification();
332
333 /**
334 * @brief the widget associated to the notification
335 *
336 * If the widget is destroyed, the notification will be automatically canceled.
337 * If the widget is activated, the notification will be automatically closed if the NotificationFlags specify that
338 *
339 * When the notification is activated, the widget might be raised.
340 * Depending on the configuration, the taskbar entry of the window containing the widget may blink.
341 */
342 QWidget *widget() const;
343
344 /**
345 * Set the widget associated to the notification.
346 * The notification is reparented to the new widget.
347 * \see widget()
348 * @param widget the new widget
349 */
350 void setWidget(QWidget *widget);
351
352 /**
353 * @return the name of the event
354 */
355 QString eventId() const;
356
357 /**
358 * @return the notification title
359 * @see setTitle
360 * @since 4.3
361 */
362 QString title() const;
363
364 /**
365 * Set the title of the notification popup.
366 * If no title is set, the application name will be used.
367 *
368 * @param title The title of the notification
369 * @since 4.3
370 */
371 void setTitle(const QString &title);
372
373 /**
374 * @return the notification text
375 * @see setText
376 */
377 QString text() const;
378
379 /**
380 * Set the notification text that will appear in the popup.
381 *
382 * In Plasma workspace, the text is shown in a QML label which uses Text.StyledText,
383 * ie. it supports a small subset of HTML entities (mostly just formatting tags)
384 *
385 * If the notifications server does not advertise "body-markup" capability,
386 * all HTML tags are stripped before sending it to the server
387 *
388 * @param text The text to display in the notification popup
389 */
390 void setText(const QString &text);
391
392 /**
393 * \return the icon shown in the popup
394 * \see setIconName
395 * \since 5.4
396 */
397 QString iconName() const;
398
399 /**
400 * Set the icon that will be shown in the popup.
401 *
402 * @param icon the icon
403 * @since 5.4
404 */
405 void setIconName(const QString &icon);
406
407 /**
408 * \return the pixmap shown in the popup
409 * \see setPixmap
410 */
411 QPixmap pixmap() const;
412 /**
413 * Set the pixmap that will be shown in the popup.
414 *
415 * @param pix the pixmap
416 */
417 void setPixmap(const QPixmap &pix);
418
419 /**
420 * @return the default action, or an empty string if not set
421 * @since 5.31
422 */
423 QString defaultAction() const;
424
425 /**
426 * Set a default action that will be triggered when the notification is
427 * activated (typically, by clicking on the notification popup). The default
428 * action should raise a window belonging to the application that sent it.
429 *
430 * The string will be used as a label for the action, so ideally it should
431 * be wrapped in i18n() or tr() calls.
432 *
433 * The visual representation of actions depends on the notification server.
434 * In Plasma and Gnome desktops, the actions are performed by clicking on
435 * the notification popup, and the label is not presented to the user.
436 *
437 *
438 * @param action Label of the default action. The label might or might not
439 * be displayed to the user by the notification server, depending on the
440 * implementation. Passing an empty string disables the default action.
441 * @since 5.31
442 */
443 void setDefaultAction(const QString &defaultAction);
444
445 /**
446 * @return the list of actions
447 */
448 //KF6: Rename to "additionalActions"?
449 QStringList actions() const;
450
451 /**
452 * Set the list of actions shown in the popup. The strings passed
453 * in that QStringList will be used as labels for those actions,
454 * so ideally they should be wrapped in i18n() or tr() calls.
455 * In Plasma workspace, these will be shown as buttons inside
456 * the notification popup.
457 *
458 * The visual representation of actions however depends
459 * on the notification server
460 *
461 * @param actions List of strings used as action labels
462 */
463 //KF6: Rename to "setAdditionalActions"?
464 void setActions(const QStringList &actions);
465
466 /**
467 * @return the list of contexts, see KNotification::Context
468 */
469 ContextList contexts() const;
470 /**
471 * set the list of contexts, see KNotification::Context
472 *
473 * The list of contexts must be set before calling sendEvent;
474 */
475 void setContexts(const ContextList &contexts);
476 /**
477 * append a context at the list of contexts, see KNotificaiton::Context
478 * @param context the context which is added
479 */
480 void addContext(const Context &context);
481 /**
482 * @overload
483 * @param context_key is the key of the context
484 * @param context_value is the value of the context
485 */
486 void addContext(const QString &context_key, const QString &context_value);
487
488 /**
489 * @return the notification flags.
490 */
491 NotificationFlags flags() const;
492
493 /**
494 * Set the notification flags.
495 * These must be set before calling sendEvent()
496 */
497 void setFlags(const NotificationFlags &flags);
498
499 /**
500 * The componentData is used to determine the location of the config file.
501 *
502 * If no componentName is set, the app name is used by default
503 *
504 * @param componentName the new component name
505 */
506 void setComponentName(const QString &componentName);
507
508 /**
509 * URLs associated with this notification
510 * @since 5.29
511 */
512 QList<QUrl> urls() const;
513
514 /**
515 * Sets URLs associated with this notification
516 *
517 * For example, a screenshot application might want to provide the
518 * URL to the file that was just taken so the notification service
519 * can show a preview.
520 *
521 * @note This feature might not be supported by the user's notification service
522 *
523 * @param urls A list of URLs
524 * @since 5.29
525 */
526 void setUrls(const QList<QUrl> &urls);
527
528 /**
529 * The urgency of the notification.
530 * @since 5.58
531 */
532 Urgency urgency() const;
533
534 /**
535 * Sets the urgency of the notification.
536 *
537 * This defines the importance of the notification. For example,
538 * a track change in a media player would be a low urgency.
539 * "You have new mail" would be normal urgency. "Your battery level
540 * is low" would be a critical urgency.
541 *
542 * Use critical notifications with care as they might be shown even
543 * when giving a presentation or when notifications are turned off.
544 *
545 * @param urgency The urgency.
546 * @since 5.58
547 */
548 void setUrgency(Urgency urgency);
549
550 /**
551 * @internal
552 * the id given by the notification manager
553 */
554 int id();
555
556 /**
557 * @internal
558 * appname used for the D-Bus object
559 */
560 QString appName() const;
561
562Q_SIGNALS:
563 /**
564 * Emitted only when the default activation has occurred
565 */
566 void activated();
567 /**
568 * Emitted when an action has been activated.
569 *
570 * The parameter passed by the signal is the index of the action
571 * in the QStringList set by setActions() call.
572 *
573 * @param action will be 0 if the default action was activated, or the index of the action in the actions QStringList
574 */
575 void activated(unsigned int action);
576
577 /**
578 * Convenience signal that is emitted when the first action is activated.
579 */
580 void action1Activated();
581
582 /**
583 * \overload
584 */
585 void action2Activated();
586
587 /**
588 * \overload
589 */
590 void action3Activated();
591
592 /**
593 * Emitted when the notification is closed.
594 *
595 * Can be closed either by the user clicking the close button,
596 * the timeout running out or when an action was triggered.
597 */
598 void closed();
599
600 /**
601 * The notification has been ignored
602 */
603 void ignored();
604
605public Q_SLOTS:
606 /**
607 * @brief Activate the action specified action
608 * If the action is zero, then the default action is activated
609 */
610 void activate(unsigned int action = 0);
611
612 /**
613 * Close the notification without activating it.
614 *
615 * This will delete the notification.
616 */
617 void close();
618
619 /**
620 * @brief Raise the widget.
621 * This will change the desktop, activate the window, and the tab if needed.
622 */
623 void raiseWidget();
624
625 /**
626 * The notification will automatically be closed if all presentations are finished.
627 * if you want to show your own presentation in your application, you should use this
628 * function, so it will not be automatically closed when there is nothing to show.
629 *
630 * Don't forgot to deref, or the notification may be never closed if there is no timeout.
631 *
632 * @see deref
633 */
634 void ref();
635 /**
636 * Remove a reference made with ref(). If the ref counter hits zero,
637 * the notification will be closed and deleted.
638 *
639 * @see ref
640 */
641 void deref();
642
643 /**
644 * Send the notification to the server.
645 *
646 * This will cause all the configured plugins to execute their actions on this notification
647 * (eg. a sound will play, a popup will show, a command will be executed etc).
648 */
649 void sendEvent();
650
651 /**
652 * @internal
653 * update the texts, the icon, and the actions of one existing notification
654 */
655 void update();
656
657 /**
658 * @since 5.57
659 * Adds a custom hint to the notification. Those are key-value pairs that can be interpreted by the respective notification backend to trigger additional, non-standard features.
660 * @param hint the hint's key
661 * @param value the hint's value
662 */
663 void setHint(const QString &hint, const QVariant &value);
664
665 /**
666 * @since 5.57
667 * Returns the custom hints set by setHint()
668 */
669 QVariantMap hints() const;
670
671private:
672 struct Private;
673 Private *const d;
674
675protected:
676 /**
677 * reimplemented for internal reasons
678 */
679 bool eventFilter(QObject *watched, QEvent *event) override;
680 static QString standardEventToEventId(StandardEvent event);
681 static QString standardEventToIconName(StandardEvent event);
682
683public:
684 /**
685 * @brief emit an event
686 *
687 * This method creates the KNotification, setting every parameter, and fire the event.
688 * You don't need to call sendEvent
689 *
690 * A popup may be displayed or a sound may be played, depending the config.
691 *
692 * @return a KNotification . You may use that pointer to connect some signals or slot.
693 * the pointer is automatically deleted when the event is closed.
694 *
695 * Make sure you use one of the CloseOnTimeOut or CloseWhenWidgetActivated, if not,
696 * you have to close yourself the notification.
697 *
698 * @note the text is shown in a QLabel, you should escape HTML, if needed.
699 *
700 * @param eventId is the name of the event
701 * @param title is title of the notification to show in the popup.
702 * @param text is the text of the notification to show in the popup.
703 * @param pixmap is a picture which may be shown in the popup.
704 * @param widget is a widget where the notification reports to
705 * @param flags is a bitmask of NotificationFlag
706 * @param componentName used to determine the location of the config file. by default, appname is used
707 * @since 4.4
708 */
709 static KNotification *event(const QString &eventId, const QString &title, const QString &text,
710 const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr,
711 const NotificationFlags &flags = CloseOnTimeout,
712 const QString &componentName = QString());
713
714 /**
715 * @brief emit a standard event
716 *
717 * @overload
718 *
719 * This will emit a standard event
720 *
721 * @param eventId is the name of the event
722 * @param text is the text of the notification to show in the popup.
723 * @param pixmap is a picture which may be shown in the popup.
724 * @param widget is a widget where the notification reports to
725 * @param flags is a bitmask of NotificationFlag
726 * @param componentName used to determine the location of the config file. by default, plasma_workspace is used
727 */
728 static KNotification *event(const QString &eventId, const QString &text = QString(),
729 const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr,
730 const NotificationFlags &flags = CloseOnTimeout,
731 const QString &componentName = QString());
732
733 /**
734 * @brief emit a standard event
735 *
736 * @overload
737 *
738 * This will emit a standard event
739 *
740 * @param eventId is the name of the event
741 * @param text is the text of the notification to show in the popup
742 * @param pixmap is a picture which may be shown in the popup
743 * @param widget is a widget where the notification reports to
744 * @param flags is a bitmask of NotificationFlag
745 */
746 static KNotification *event(StandardEvent eventId, const QString &text = QString(),
747 const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr,
748 const NotificationFlags &flags = CloseOnTimeout);
749
750 /**
751 * @brief emit a standard event
752 *
753 * @overload
754 *
755 * This will emit a standard event
756 *
757 * @param eventId is the name of the event
758 * @param title is title of the notification to show in the popup.
759 * @param text is the text of the notification to show in the popup
760 * @param pixmap is a picture which may be shown in the popup
761 * @param widget is a widget where the notification reports to
762 * @param flags is a bitmask of NotificationFlag
763 * @since 4.4
764 */
765 static KNotification *event(StandardEvent eventId, const QString &title, const QString &text,
766 const QPixmap &pixmap, QWidget *widget = nullptr,
767 const NotificationFlags &flags = CloseOnTimeout);
768
769 /**
770 * @brief emit a standard event with the possibility of setting an icon by icon name
771 *
772 * @overload
773 *
774 * This will emit a standard event
775 *
776 * @param eventId is the name of the event
777 * @param title is title of the notification to show in the popup.
778 * @param text is the text of the notification to show in the popup
779 * @param iconName a Freedesktop compatible icon name to be shown in the popup
780 * @param widget is a widget where the notification reports to
781 * @param flags is a bitmask of NotificationFlag
782 * @param componentName used to determine the location of the config file. by default, plasma_workspace is used
783 * @since 5.4
784 */
785 static KNotification *event(const QString &eventId, const QString &title, const QString &text,
786 const QString &iconName, QWidget *widget = nullptr,
787 const NotificationFlags &flags = CloseOnTimeout,
788 const QString &componentName = QString());
789
790 /**
791 * @brief emit a standard event with the possibility of setting an icon by icon name
792 *
793 * @overload
794 *
795 * This will emit a standard event with a custom icon
796 *
797 * @param eventId the type of the standard (not app-defined) event
798 * @param title is title of the notification to show in the popup.
799 * @param text is the text of the notification to show in the popup
800 * @param iconName a Freedesktop compatible icon name to be shown in the popup
801 * @param widget is a widget where the notification reports to
802 * @param flags is a bitmask of NotificationFlag
803 * @since 5.9
804 */
805 static KNotification *event(StandardEvent eventId, const QString &title, const QString &text,
806 const QString &iconName, QWidget *widget = nullptr,
807 const NotificationFlags &flags = CloseOnTimeout);
808
809 /**
810 * @brief emit a standard event
811 *
812 * @overload
813 *
814 * This will emit a standard event with its standard icon
815 *
816 * @param eventId the type of the standard (not app-defined) event
817 * @param title is title of the notification to show in the popup.
818 * @param text is the text of the notification to show in the popup
819 * @param widget is a widget where the notification reports to
820 * @param flags is a bitmask of NotificationFlag
821 * @since 5.9
822 */
823 static KNotification *event(StandardEvent eventId, const QString &title, const QString &text,
824 QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout);
825
826
827 /**
828 * This is a simple substitution for QApplication::beep()
829 *
830 * @param reason a short text explaining what has happened (may be empty)
831 * @param widget the widget the notification refers to
832 */
833 static void beep(const QString &reason = QString(), QWidget *widget = nullptr);
834
835 //prevent warning
836 using QObject::event;
837};
838
839Q_DECLARE_OPERATORS_FOR_FLAGS(KNotification::NotificationFlags)
840
841#endif
842