KNotification

#include <KNotification>

Inheritance diagram for KNotification:

Public Types

typedef QPair< QString, QStringContext
 
typedef QList< ContextContextList
 
enum  NotificationFlag {
  RaiseWidgetOnActivation = 0x01, CloseOnTimeout = 0x00, Persistent = 0x02, CloseWhenWidgetActivated = 0x04,
  LoopSound = 0x08, SkipGrouping = 0x10, DefaultEvent = 0xF000
}
 
typedef QFlags< NotificationFlagNotificationFlags
 
enum  StandardEvent { Notification, Warning, Error, Catastrophe }
 
enum  Urgency {
  DefaultUrgency = -1, LowUrgency = 10, NormalUrgency = 50, HighUrgency = 70,
  CriticalUrgency = 90
}
 

Signals

void action1Activated ()
 
void action2Activated ()
 
void action3Activated ()
 
void activated ()
 
void activated (unsigned int action)
 
void closed ()
 
void defaultActivated ()
 
void ignored ()
 

Public Slots

void activate (unsigned int action=0)
 
void close ()
 
void deref ()
 
QVariantMap hints () const
 
void raiseWidget ()
 
void ref ()
 
void sendEvent ()
 
void setHint (const QString &hint, const QVariant &value)
 
void update ()
 

Public Member Functions

 KNotification (const QString &eventId, QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout)
 
 KNotification (const QString &eventId, const NotificationFlags &flags, QObject *parent=nullptr)
 
QStringList actions () const
 
void addContext (const Context &context)
 
void addContext (const QString &context_key, const QString &context_value)
 
QString appName () const
 
ContextList contexts () const
 
QString defaultAction () const
 
QString eventId () const
 
NotificationFlags flags () const
 
QString iconName () const
 
int id ()
 
QPixmap pixmap () const
 
void setActions (const QStringList &actions)
 
void setComponentName (const QString &componentName)
 
void setContexts (const ContextList &contexts)
 
void setDefaultAction (const QString &defaultAction)
 
void setFlags (const NotificationFlags &flags)
 
void setIconName (const QString &icon)
 
void setPixmap (const QPixmap &pix)
 
void setText (const QString &text)
 
void setTitle (const QString &title)
 
void setUrgency (Urgency urgency)
 
void setUrls (const QList< QUrl > &urls)
 
void setWidget (QWidget *widget)
 
QString text () const
 
QString title () const
 
Urgency urgency () const
 
QList< QUrlurls () const
 
QWidgetwidget () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Static Public Member Functions

static void beep (const QString &reason=QString(), QWidget *widget=nullptr)
 
static KNotificationevent (const QString &eventId, const QString &title, const QString &text, const QPixmap &pixmap=QPixmap(), QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout, const QString &componentName=QString())
 
static KNotificationevent (const QString &eventId, const QString &text=QString(), const QPixmap &pixmap=QPixmap(), QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout, const QString &componentName=QString())
 
static KNotificationevent (StandardEvent eventId, const QString &text=QString(), const QPixmap &pixmap=QPixmap(), QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout)
 
static KNotificationevent (StandardEvent eventId, const QString &title, const QString &text, const QPixmap &pixmap, QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout)
 
static KNotificationevent (const QString &eventId, const QString &title, const QString &text, const QString &iconName, QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout, const QString &componentName=QString())
 
static KNotificationevent (StandardEvent eventId, const QString &title, const QString &text, const QString &iconName, QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout)
 
static KNotificationevent (StandardEvent eventId, const QString &title, const QString &text, QWidget *widget=nullptr, const NotificationFlags &flags=CloseOnTimeout)
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 

Protected Member Functions

bool eventFilter (QObject *watched, QEvent *event) override
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Static Protected Member Functions

static QString standardEventToEventId (StandardEvent event)
 
static QString standardEventToIconName (StandardEvent event)
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Public Attributes inherited from QObject
typedef QObjectList
 

Detailed Description

KNotification is used to notify the user of an event.

Introduction

There are two main kinds of notifications:

  • Feedback events: For notifying the user that he/she just performed an operation, like maximizing a window. This allows us to play sounds when a dialog appears. This is an instant notification. It ends automatically after a small timeout.
  • persistant notifications: Notify when the user received a new message, or when something else important happened the user has to know about. This notification has a start and a end. It begins when the event actually occurs, and finishes when the message is acknowledged or read.

Example of a persistent notification in an instant messaging application: The application emits the notification when the message is actually received, and closes it only when the user has read the message (when the message window has received the focus) using the close() slot. Persistent notifications must have the Persistent flag.

By default a notification will use the application name as title, but you can also provide a brief text in the title and a more precise description in the body text. This is especially useful for notifications coming from applications which should be considered "part of the system", like a battery monitor or a network connection manager. For example a battery indicator could use "Low Battery" as a title and "Only 12 minutes left." as a body text.

In order to perform a notification, you need to create a description file, which contains default parameters of the notification, and use KNotification::event at the place in the application code where the notification occurs. The returned KNotification pointer may be used to connect signals or slots

The global config file

Your application should install a file called knotifications5/appname.notifyrc in a QStandardPaths::GenericDataLocation directory. On Android, this path is qrc:/knotifications5/.

The filename must either match QCoreApplication::applicationName or be specified as the component name to the KNotification object.

Warning
Notifications won't be visible otherwise.

You can do this with the following CMake command: install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR}))

This file contains mainly 3 parts

  1. Global information
  2. Context information
  3. Definition of individual events

Global information

The global part looks like that

        [Global]
        IconName=Filename
        Comment=Friendly Name of app
        Name=Name of app

The icon filename is just the name, without extension, it's found with the KIconLoader. The Comment field will be used in KControl to describe the application. The Name field is optional and may be used as the application name for popup, if Name is not present, Comment is used instead

Context information

This part consists of hints for the configuration widget

        [Context/group]
        Name=Group name
        Comment=The name of the group for contacts
        [Context/folder]
        Name=Group name
 

The second part of the groupname is the context identifier. It should not contain special characters. The Name field is the one the user will see (and which is translated)

Definition of Events

The definition of the events forms the most important part of the config file

        [Event/newmail]
        Name=New email
        Comment=You have got a new email
        Contexts=folder,group
        Action=Sound|Popup
        [Event/contactOnline]
        Name=Contact goes online
        Comment=One of your contact has been connected
        Contexts=group
        Sound=filetoplay.ogg
        Action=None
        Urgency=Low
 

These are the default settings for each notifiable event. Action is the string representing the action. Actions can be added to KNotification as plugins, by deriving from KNotificationPlugin. At the time of writing, the following actions are available: Taskbar, Sound, Popup, Logfile, TTS, Execute. Actions can be combined by separating them with '|'.

Contexts is a comma separated list of possible context for this event.

Urgency can be any of: Low, Normal, Critical.

The user's config file

This is an implementation detail, and is described here for your information.

In the config file, there are two parts: the event configuration, and the context information

Context information

These are hints for the configuration dialog. They contain both the internal id of the context, and the user visible string.

        [Context/group]
        Values=1:Friends,2:Work,3:Family
 

Events configuration

This contains the configuration of events for the user. It contains the same fields as the description file. The key of groups is in the form Event/<EventName>/<ContextName>/<ContextValue>

        [Event/contactOnline]
        Action=Sound
        Sound=/usr/share/sounds/super.ogg
        [Event/contactOnline/group/1]
        Action=Popup|Sound

Minimal Example

This portion of code will fire the event for the "contactOnline" event

KNotification *notification= new KNotification ( "contactOnline", widget );
notification->setText( i18n("The contact <i>%1</i> has gone online", contact->name() );
notification->setPixmap( contact->pixmap() );
notification->setActions( QStringList( i18n( "Open chat" ) ) );
const auto groups = contact->groups();
for ( const QString &group : groups ) {
notification->addContext( "group" , group ) ;
}
connect(notification, SIGNAL(activated(unsigned int )), contact , SLOT(slotOpenChat()) );
notification->sendEvent();
Author
Olivier Goffart <ogoffart at kde.org>

Definition at line 181 of file knotification.h.

Member Typedef Documentation

Sometimes the user may want different notifications for the same event, depending the source of the event.

Example, you want to be notified for mails that arrive in your folder "personal inbox" but not for those in "spam" folder

A notification context is a pair of two strings. The first string is a key from what the context is. example "group" or "filter" (not translated). The second is the id of the context. In our example, the group id or the filter id in the applications. These strings are the ones present in the config file, and are in theory not shown in the user interface.

The order of contexts in the list is is important, the most important context should be placed first. They are processed in that order when the notification occurs.

See also
event

Definition at line 204 of file knotification.h.

Stores a combination of NotificationFlag values.

Definition at line 266 of file knotification.h.

Member Enumeration Documentation

See also
NotificationFlags
Enumerator
RaiseWidgetOnActivation 

When the notification is activated, raise the notification's widget.

This will change the desktop, raise the window, and switch to the tab.

Todo:
doesn't work yet
CloseOnTimeout 

The notification will be automatically closed after a timeout.

(this is the default)

Persistent 

The notification will NOT be automatically closed after a timeout.

You will have to track the notification, and close it with the close function manually when the event is done, otherwise there will be a memory leak

CloseWhenWidgetActivated 

The notification will be automatically closed if the widget() becomes activated.

If the widget is already activated when the notification occurs, the notification will be closed after a small timeout.

This only works if the widget is the toplevel widget

Todo:
make it work with tabulated widget
LoopSound 

The audio plugin will loop the sound until the notification is closed.

SkipGrouping 

Sends a hint to Plasma to skip grouping for this notification.

Since
5.18
DefaultEvent 

The event is a standard kde event, and not an event of the application

Definition at line 210 of file knotification.h.

default events you can use in the event function

Definition at line 271 of file knotification.h.

The urgency of a notification.

Since
5.58
See also
setUrgency

Definition at line 279 of file knotification.h.

Constructor & Destructor Documentation

KNotification::KNotification ( const QString eventId,
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout 
)
explicit

Create a new notification.

You have to use sendEvent to show the notification.

The pointer is automatically deleted when the event is closed.

Make sure you use one of the NotificationFlags CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close the notification yourself.

Parameters
eventIdis the name of the event
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag

Definition at line 61 of file knotification.cpp.

KNotification::KNotification ( const QString eventId,
const NotificationFlags flags,
QObject parent = nullptr 
)
explicit

Create a new notification.

You have to use sendEvent to show the notification.

The pointer is automatically deleted when the event is closed.

Make sure you use one of the NotificationFlags CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close the notification yourself.

Since
4.4
Parameters
eventIdis the name of the event
flagsis a bitmask of NotificationFlag
parentparent object

Definition at line 72 of file knotification.cpp.

Member Function Documentation

void KNotification::action1Activated ( )
signal

Convenience signal that is emitted when the first action is activated.

void KNotification::action2Activated ( )
signal

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void KNotification::action3Activated ( )
signal

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QStringList KNotification::actions ( ) const
Returns
the list of actions

Definition at line 182 of file knotification.cpp.

void KNotification::activate ( unsigned int  action = 0)
slot

Activate the action specified action If the action is zero, then the default action is activated.

Definition at line 289 of file knotification.cpp.

void KNotification::activated ( )
signal

Emitted only when the default activation has occurred.

void KNotification::activated ( unsigned int  action)
signal

Emitted when an action has been activated.

The parameter passed by the signal is the index of the action in the QStringList set by setActions() call.

Parameters
actionwill be 0 if the default action was activated, or the index of the action in the actions QStringList
void KNotification::addContext ( const Context context)

append a context at the list of contexts, see KNotificaiton::Context

Parameters
contextthe context which is added

Definition at line 228 of file knotification.cpp.

void KNotification::addContext ( const QString context_key,
const QString context_value 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
context_keyis the key of the context
context_valueis the value of the context

Definition at line 233 of file knotification.cpp.

QString KNotification::appName ( ) const

appname used for the D-Bus object

Definition at line 462 of file knotification.cpp.

void KNotification::beep ( const QString reason = QString(),
QWidget widget = nullptr 
)
static

This is a simple substitution for QApplication::beep()

Parameters
reasona short text explaining what has happened (may be empty)
widgetthe widget the notification refers to

Definition at line 439 of file knotification.cpp.

void KNotification::close ( )
slot

Close the notification without activating it.

This will delete the notification.

Definition at line 313 of file knotification.cpp.

void KNotification::closed ( )
signal

Emitted when the notification is closed.

Can be closed either by the user clicking the close button, the timeout running out or when an action was triggered.

KNotification::ContextList KNotification::contexts ( ) const
Returns
the list of contexts, see KNotification::Context

Definition at line 218 of file knotification.cpp.

QString KNotification::defaultAction ( ) const
Returns
the default action, or an empty string if not set
Since
5.31

Definition at line 213 of file knotification.cpp.

void KNotification::defaultActivated ( )
signal

Emitted when the default action has been activated.

Since
5.67
void KNotification::deref ( )
slot

Remove a reference made with ref().

If the ref counter hits zero, the notification will be closed and deleted.

See also
ref

Definition at line 429 of file knotification.cpp.

KNotification * KNotification::event ( const QString eventId,
const QString title,
const QString text,
const QPixmap pixmap = QPixmap(),
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout,
const QString componentName = QString() 
)
static

emit an event

This method creates the KNotification, setting every parameter, and fire the event. You don't need to call sendEvent

A popup may be displayed or a sound may be played, depending the config.

Returns
a KNotification . You may use that pointer to connect some signals or slot. the pointer is automatically deleted when the event is closed.

Make sure you use one of the CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close yourself the notification.

Note
the text is shown in a QLabel, you should escape HTML, if needed.
Parameters
eventIdis the name of the event
titleis title of the notification to show in the popup.
textis the text of the notification to show in the popup.
pixmapis a picture which may be shown in the popup.
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
componentNameused to determine the location of the config file. by default, appname is used
Since
4.4

Definition at line 364 of file knotification.cpp.

KNotification * KNotification::event ( const QString eventId,
const QString text = QString(),
const QPixmap pixmap = QPixmap(),
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout,
const QString componentName = QString() 
)
static

emit a standard event

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event

Parameters
eventIdis the name of the event
textis the text of the notification to show in the popup.
pixmapis a picture which may be shown in the popup.
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
componentNameused to determine the location of the config file. by default, plasma_workspace is used

Definition at line 378 of file knotification.cpp.

KNotification * KNotification::event ( StandardEvent  eventId,
const QString text = QString(),
const QPixmap pixmap = QPixmap(),
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout 
)
static

emit a standard event

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event

Parameters
eventIdis the name of the event
textis the text of the notification to show in the popup
pixmapis a picture which may be shown in the popup
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag

Definition at line 391 of file knotification.cpp.

KNotification * KNotification::event ( StandardEvent  eventId,
const QString title,
const QString text,
const QPixmap pixmap,
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout 
)
static

emit a standard event

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event

Parameters
eventIdis the name of the event
titleis title of the notification to show in the popup.
textis the text of the notification to show in the popup
pixmapis a picture which may be shown in the popup
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
Since
4.4

Definition at line 384 of file knotification.cpp.

KNotification * KNotification::event ( const QString eventId,
const QString title,
const QString text,
const QString iconName,
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout,
const QString componentName = QString() 
)
static

emit a standard event with the possibility of setting an icon by icon name

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event

Parameters
eventIdis the name of the event
titleis title of the notification to show in the popup.
textis the text of the notification to show in the popup
iconNamea Freedesktop compatible icon name to be shown in the popup
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
componentNameused to determine the location of the config file. by default, plasma_workspace is used
Since
5.4

Definition at line 397 of file knotification.cpp.

KNotification * KNotification::event ( StandardEvent  eventId,
const QString title,
const QString text,
const QString iconName,
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout 
)
static

emit a standard event with the possibility of setting an icon by icon name

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event with a custom icon

Parameters
eventIdthe type of the standard (not app-defined) event
titleis title of the notification to show in the popup.
textis the text of the notification to show in the popup
iconNamea Freedesktop compatible icon name to be shown in the popup
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
Since
5.9

Definition at line 412 of file knotification.cpp.

KNotification * KNotification::event ( StandardEvent  eventId,
const QString title,
const QString text,
QWidget widget = nullptr,
const NotificationFlags flags = CloseOnTimeout 
)
static

emit a standard event

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will emit a standard event with its standard icon

Parameters
eventIdthe type of the standard (not app-defined) event
titleis title of the notification to show in the popup.
textis the text of the notification to show in the popup
widgetis a widget where the notification reports to
flagsis a bitmask of NotificationFlag
Since
5.9

Definition at line 419 of file knotification.cpp.

bool KNotification::eventFilter ( QObject watched,
QEvent event 
)
overrideprotectedvirtual

reimplemented for internal reasons

Reimplemented from QObject.

Definition at line 484 of file knotification.cpp.

QString KNotification::eventId ( ) const
Returns
the name of the event

Definition at line 95 of file knotification.cpp.

KNotification::NotificationFlags KNotification::flags ( ) const
Returns
the notification flags.

Definition at line 238 of file knotification.cpp.

QVariantMap KNotification::hints ( ) const
slot
Since
5.57 Returns the custom hints set by setHint()

Definition at line 553 of file knotification.cpp.

QString KNotification::iconName ( ) const
Returns
the icon shown in the popup
See also
setIconName
Since
5.4

Definition at line 163 of file knotification.cpp.

int KNotification::id ( )

the id given by the notification manager

Definition at line 454 of file knotification.cpp.

void KNotification::ignored ( )
signal

The notification has been ignored.

QPixmap KNotification::pixmap ( ) const
Returns
the pixmap shown in the popup
See also
setPixmap

Definition at line 168 of file knotification.cpp.

void KNotification::raiseWidget ( )
slot

Raise the widget.

This will change the desktop, activate the window, and the tab if needed.

Deprecated:
since 5.67, use QWindow raise + requestActivate instead.

Definition at line 327 of file knotification.cpp.

void KNotification::ref ( )
slot

The notification will automatically be closed if all presentations are finished.

if you want to show your own presentation in your application, you should use this function, so it will not be automatically closed when there is nothing to show.

Don't forgot to deref, or the notification may be never closed if there is no timeout.

See also
deref

Definition at line 425 of file knotification.cpp.

void KNotification::sendEvent ( )
slot

Send the notification to the server.

This will cause all the configured plugins to execute their actions on this notification (eg. a sound will play, a popup will show, a command will be executed etc).

Definition at line 444 of file knotification.cpp.

void KNotification::setActions ( const QStringList actions)

Set the list of actions shown in the popup.

The strings passed in that QStringList will be used as labels for those actions, so ideally they should be wrapped in i18n() or tr() calls. In Plasma workspace, these will be shown as buttons inside the notification popup.

The visual representation of actions however depends on the notification server

Parameters
actionsList of strings used as action labels

Definition at line 187 of file knotification.cpp.

void KNotification::setComponentName ( const QString componentName)

The componentData is used to determine the location of the config file.

If no componentName is set, the app name is used by default

Parameters
componentNamethe new component name

Definition at line 256 of file knotification.cpp.

void KNotification::setContexts ( const ContextList contexts)

set the list of contexts, see KNotification::Context

The list of contexts must be set before calling sendEvent;

Definition at line 223 of file knotification.cpp.

void KNotification::setDefaultAction ( const QString defaultAction)

Set a default action that will be triggered when the notification is activated (typically, by clicking on the notification popup).

The default action should raise a window belonging to the application that sent it.

The string will be used as a label for the action, so ideally it should be wrapped in i18n() or tr() calls.

The visual representation of actions depends on the notification server. In Plasma and Gnome desktops, the actions are performed by clicking on the notification popup, and the label is not presented to the user.

Parameters
actionLabel of the default action. The label might or might not be displayed to the user by the notification server, depending on the implementation. Passing an empty string disables the default action.
Since
5.31

Definition at line 200 of file knotification.cpp.

void KNotification::setFlags ( const NotificationFlags flags)

Set the notification flags.

These must be set before calling sendEvent()

Definition at line 243 of file knotification.cpp.

void KNotification::setHint ( const QString hint,
const QVariant value 
)
slot
Since
5.57 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.
Parameters
hintthe hint's key
valuethe hint's value

Definition at line 540 of file knotification.cpp.

void KNotification::setIconName ( const QString icon)

Set the icon that will be shown in the popup.

Parameters
iconthe icon
Since
5.4

Definition at line 150 of file knotification.cpp.

void KNotification::setPixmap ( const QPixmap pix)

Set the pixmap that will be shown in the popup.

If you want to use an icon from the icon theme use setIconName instead.

Parameters
pixthe pixmap

Definition at line 173 of file knotification.cpp.

void KNotification::setText ( const QString text)

Set the notification text that will appear in the popup.

In Plasma workspace, the text is shown in a QML label which uses Text.StyledText, ie. it supports a small subset of HTML entities (mostly just formatting tags)

If the notifications server does not advertise "body-markup" capability, all HTML tags are stripped before sending it to the server

Parameters
textThe text to display in the notification popup

Definition at line 137 of file knotification.cpp.

void KNotification::setTitle ( const QString title)

Set the title of the notification popup.

If no title is set, the application name will be used.

Parameters
titleThe title of the notification
Since
4.3

Definition at line 124 of file knotification.cpp.

void KNotification::setUrgency ( Urgency  urgency)

Sets the urgency of the notification.

This defines the importance of the notification. For example, a track change in a media player would be a low urgency. "You have new mail" would be normal urgency. "Your battery level is low" would be a critical urgency.

Use critical notifications with care as they might be shown even when giving a presentation or when notifications are turned off.

Parameters
urgencyThe urgency.
Since
5.58

Definition at line 276 of file knotification.cpp.

void KNotification::setUrls ( const QList< QUrl > &  urls)

Sets URLs associated with this notification.

For example, a screenshot application might want to provide the URL to the file that was just taken so the notification service can show a preview.

Note
This feature might not be supported by the user's notification service
Parameters
urlsA list of URLs
Since
5.29

Definition at line 266 of file knotification.cpp.

void KNotification::setWidget ( QWidget widget)

Set the widget associated to the notification.

The notification is reparented to the new widget.

See also
widget()
Parameters
widgetthe new widget

Definition at line 115 of file knotification.cpp.

QString KNotification::text ( ) const
Returns
the notification text
See also
setText

Definition at line 105 of file knotification.cpp.

QString KNotification::title ( ) const
Returns
the notification title
See also
setTitle
Since
4.3

Definition at line 100 of file knotification.cpp.

void KNotification::update ( )
slot

update the texts, the icon, and the actions of one existing notification

Definition at line 477 of file knotification.cpp.

KNotification::Urgency KNotification::urgency ( ) const

The urgency of the notification.

Since
5.58

Definition at line 271 of file knotification.cpp.

QList< QUrl > KNotification::urls ( ) const

URLs associated with this notification.

Since
5.29

Definition at line 261 of file knotification.cpp.

QWidget * KNotification::widget ( ) const

the widget associated to the notification

If the widget is destroyed, the notification will be automatically canceled. If the widget is activated, the notification will be automatically closed if the NotificationFlags specify that

When the notification is activated, the widget might be raised. Depending on the configuration, the taskbar entry of the window containing the widget may blink.

Definition at line 110 of file knotification.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Wed Aug 5 2020 22:42:42 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.