Member Function Documentation

[explicit, since 4.4] KNotification::KNotification(const QString &eventId, KNotification::NotificationFlags flags = CloseOnTimeout, QObject *parent = nullptr)

Create a new notification.

You have to use sendEvent to show the notification.

The pointer is automatically deleted when the event is closed.

eventId is the name of the event

flags is a bitmask of NotificationFlag

parent parent object

This function was introduced in 4.4.

[signal, since 5.88] void KNotification::actionsChanged()

Emitted when actions changed.

This function was introduced in 5.88.

[since 6.0] KNotificationAction *KNotification::addAction(const QString &label)

Add an action to the notification.

The visual representation of actions depends on the notification server.

label the user-visible label of the action

This function was introduced in 6.0.

See also KNotificationAction.

[since 6.0] KNotificationAction *KNotification::addDefaultAction(const QString &label)

Add a default action that will be triggered when the notification is activated (typically, by clicking on the notification popup). The default action typically raises 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.

Calling this overrides the current default action

This function was introduced in 6.0.

[signal, since 5.88] void KNotification::autoDeleteChanged()

Emitted when autoDelete changed.

This function was introduced in 5.88.

[static] void KNotification::beep(const QString &reason = QString())

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

reason a short text explaining what has happened (may be empty)

[since 6.0] void KNotification::clearActions()

Removes all actions previously added by addAction() from the notification.

This function was introduced in 6.0.

See also addAction.

[slot] void KNotification::close()

Close the notification without activating it.

This will delete the notification.

[signal] void KNotification::closed()

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.

[since 5.88] QString KNotification::componentName() const

Returns the component name used to determine the location of the configuration file.

This function was introduced in 5.88.

See also setComponentName().

[signal, since 5.88] void KNotification::componentNameChanged()

Emitted when componentName changed.

This function was introduced in 5.88.

[since 6.0] KNotificationAction *KNotification::defaultAction() const

Returns the default action, or nullptr if none is set

This function was introduced in 6.0.

[signal, since 5.88] void KNotification::defaultActionChanged()

Emitted when defaultAction changed.

This function was introduced in 5.88.

[static, since 4.4] KNotification *KNotification::event(const QString &eventId, const QString &title, const QString &text, const QPixmap &pixmap = QPixmap(), const KNotification::NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString())

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.

eventId is the name of the event

title is title of the notification to show in the popup.

text is the text of the notification to show in the popup.

pixmap is a picture which may be shown in the popup.

flags is a bitmask of NotificationFlag

componentName used to determine the location of the config file. by default, appname is used

This function was introduced in 4.4.

[static] KNotification *KNotification::event(KNotification::StandardEvent eventId, const QString &text = QString(), const QPixmap &pixmap = QPixmap(), const KNotification::NotificationFlags &flags = CloseOnTimeout)

Emit a standard event

This is an overloaded function.

This will emit a standard event

eventId is the name of the event

text is the text of the notification to show in the popup

pixmap is a picture which may be shown in the popup

flags is a bitmask of NotificationFlag

[static, since 5.9] KNotification *KNotification::event(KNotification::StandardEvent eventId, const QString &title, const QString &text, const KNotification::NotificationFlags &flags = CloseOnTimeout)

Emit a standard event

This is an overloaded function.

This will emit a standard event with its standard icon

eventId the type of the standard (not app-defined) event

title is title of the notification to show in the popup.

text is the text of the notification to show in the popup

flags is a bitmask of NotificationFlag

This function was introduced in 5.9.

[static, since 4.4] KNotification *KNotification::event(KNotification::StandardEvent eventId, const QString &title, const QString &text, const QPixmap &pixmap, const KNotification::NotificationFlags &flags = CloseOnTimeout)

Emit a standard event

This is an overloaded function.

This will emit a standard event

eventId is the name of the event

title is title of the notification to show in the popup.

text is the text of the notification to show in the popup

pixmap is a picture which may be shown in the popup

flags is a bitmask of NotificationFlag

This function was introduced in 4.4.

[static, since 5.9] KNotification *KNotification::event(KNotification::StandardEvent eventId, const QString &title, const QString &text, const QString &iconName, const KNotification::NotificationFlags &flags = CloseOnTimeout)

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

This is an overloaded function.

This will emit a standard event with a custom icon

eventId the type of the standard (not app-defined) event

title is title of the notification to show in the popup.

text is the text of the notification to show in the popup

iconName a Freedesktop compatible icon name to be shown in the popup

flags is a bitmask of NotificationFlag

This function was introduced in 5.9.

[static] KNotification *KNotification::event(const QString &eventId, const QString &text = QString(), const QPixmap &pixmap = QPixmap(), const KNotification::NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString())

Emit a standard event

This is an overloaded function.

This will emit a standard event

eventId is the name of the event

text is the text of the notification to show in the popup.

pixmap is a picture which may be shown in the popup.

flags is a bitmask of NotificationFlag

componentName used to determine the location of the config file. by default, plasma_workspace is used

[static, since 5.4] KNotification *KNotification::event(const QString &eventId, const QString &title, const QString &text, const QString &iconName, const KNotification::NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString())

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

This is an overloaded function.

This will emit a standard event

eventId is the name of the event

title is title of the notification to show in the popup.

text is the text of the notification to show in the popup

iconName a Freedesktop compatible icon name to be shown in the popup

flags is a bitmask of NotificationFlag

componentName used to determine the location of the config file. by default, plasma_workspace is used

This function was introduced in 5.4.

QString KNotification::eventId() const

Returns the name of the event

See also setEventId().

[signal, since 5.88] void KNotification::eventIdChanged()

Emitted when eventId changed.

This function was introduced in 5.88.

KNotification::NotificationFlags KNotification::flags() const

Returns the notification flags.

See also setFlags().

[signal, since 5.88] void KNotification::flagsChanged()

Emitted when flags changed.

This function was introduced in 5.88.

[slot, since 5.57] QVariantMap KNotification::hints() const

Returns the custom hints set by setHint()

This function was introduced in 5.57.

See also setHints().

[signal, since 5.101] void KNotification::hintsChanged()

Emitted when hints changes.

This function was introduced in 5.101.

[since 5.4] QString KNotification::iconName() const

Returns the icon shown in the popup

This function was introduced in 5.4.

See also setIconName.

[signal, since 5.88] void KNotification::iconNameChanged()

Emitted when iconName changed.

This function was introduced in 5.88.

[signal] void KNotification::ignored()

The notification has been ignored

[since 5.88] bool KNotification::isAutoDelete() const

Returns whether this notification object will be automatically deleted after closing.

This function was introduced in 5.88.

QPixmap KNotification::pixmap() const

Returns the pixmap shown in the popup

See also setPixmap.

[since 5.81] KNotificationReplyAction *KNotification::replyAction() const

Returns the inline reply action.

This function was introduced in 5.81.

See also setReplyAction().

[slot] void KNotification::sendEvent()

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).

[since 5.88] void KNotification::setAutoDelete(bool autoDelete)

Sets whether this notification object will be automatically deleted after closing. This is on by default for C++, and off by default for QML.

This function was introduced in 5.88.

See also isAutoDelete().

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

componentName the new component name

See also componentName().

[since 5.88] void KNotification::setEventId(const QString &eventId)

Set the event id, if not already passed to the constructor.

This function was introduced in 5.88.

See also eventId().

void KNotification::setFlags(const KNotification::NotificationFlags &flags)

Set the notification flags.

These must be set before calling sendEvent()

See also flags().

[slot, since 5.57] void KNotification::setHint(const QString &hint, const QVariant &value)

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.

hint the hint's key

value the hint's value

This function was introduced in 5.57.

[slot, since 5.101] void KNotification::setHints(const QVariantMap &hints)

Set custom hints on the notification.

This function was introduced in 5.101.

See also hints() and setHint.

[since 5.4] void KNotification::setIconName(const QString &icon)

Set the icon that will be shown in the popup.

icon the icon

This function was introduced in 5.4.

See also iconName().

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.

pix the pixmap

See also pixmap().

[since 5.81] void KNotification::setReplyAction(std::unique_ptr<KNotificationReplyAction> replyAction)

Add an inline reply action to the notification.

On supported platforms this lets the user type a reply to a notification, such as replying to a chat message, from the notification popup, for example:

KNotification *notification = new KNotification(QStringLiteral("notification"));
...
auto replyAction = std::make_unique<KNotificationReplyAction>(i18nc("@action:button", "Reply"));
replyAction->setPlaceholderText(i18nc("@info:placeholder", "Reply to Dave..."));
QObject::connect(replyAction.get(), &KNotificationReplyAction::replied, [](const QString &text) {
    qDebug() << "you replied with" << text;
});
notification->setReplyAction(std::move(replyAction));

replyAction the reply action to set

This function was introduced in 5.81.

See also replyAction().

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

text The text to display in the notification popup

See also text().

[since 4.3] void KNotification::setTitle(const QString &title)

Set the title of the notification popup. If no title is set, the application name will be used.

title The title of the notification

This function was introduced in 4.3.

See also title().

[since 5.58] void KNotification::setUrgency(KNotification::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.

urgency The urgency.

This function was introduced in 5.58.

See also urgency().

[since 5.29] 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.

urls A list of URLs

This function was introduced in 5.29.

See also urls().

[since 6.0] void KNotification::setWindow(QWindow *window)

Sets the window associated with this notification. This is relevant when using the CloseWhenWindowActivated flag.

This function was introduced in 6.0.

See also window().

QString KNotification::text() const

Returns the notification text

See also setText.

[signal, since 5.88] void KNotification::textChanged()

Emitted when text changed.

This function was introduced in 5.88.

[since 4.3] QString KNotification::title() const

Returns the notification title

This function was introduced in 4.3.

See also setTitle.

[signal, since 5.88] void KNotification::titleChanged()

Emitted when title changed.

This function was introduced in 5.88.

[since 5.58] KNotification::Urgency KNotification::urgency() const

The urgency of the notification.

This function was introduced in 5.58.

See also setUrgency().

[signal, since 5.88] void KNotification::urgencyChanged()

Emitted when urgency changed.

This function was introduced in 5.88.

[since 5.29] QList<QUrl> KNotification::urls() const

URLs associated with this notification

This function was introduced in 5.29.

See also setUrls().

[signal, since 5.88] void KNotification::urlsChanged()

Emitted when urls changed.

This function was introduced in 5.88.

[since 6.0] QWindow *KNotification::window() const

The window associated with this notification. nullptr by default. Returns the window set by setWindow()

This function was introduced in 6.0.

See also setWindow().

[since 5.90] QString KNotification::xdgActivationToken() const

Returns the activation token to use to activate a window.

This function was introduced in 5.90.

[signal, since 5.90] void KNotification::xdgActivationTokenChanged()

Emitted when xdgActivationToken changes.

This function was introduced in 5.90.