KStatusNotifierItem Class
KDE Status Notifier Item protocol implementation. More...
| Header: | #include <KStatusNotifierItem> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS StatusNotifierItem)target_link_libraries(mytarget PRIVATE KF6::StatusNotifierItem) |
| Since: | 4.4 |
| Inherits: | QObject |
Public Types
| enum | ItemCategory { ApplicationStatus, Communications, SystemServices, Hardware, Reserved } |
| enum | ItemStatus { Passive, Active, NeedsAttention } |
Public Functions
| KStatusNotifierItem(QObject *parent = nullptr) | |
| KStatusNotifierItem(const QString &id, QObject *parent = nullptr) | |
(since 6.5) void | abortQuit() |
(since 6.0) QWindow * | associatedWindow() const |
| QString | attentionIconName() const |
| QIcon | attentionIconPixmap() const |
| QString | attentionMovieName() const |
| KStatusNotifierItem::ItemCategory | category() const |
| QMenu * | contextMenu() const |
| QString | iconName() const |
| QIcon | iconPixmap() const |
| QString | id() const |
| QString | overlayIconName() const |
| QIcon | overlayIconPixmap() const |
| QString | providedToken() const |
(since 6.0) void | setAssociatedWindow(QWindow *window) |
| void | setAttentionIconByName(const QString &name) |
| void | setAttentionIconByPixmap(const QIcon &icon) |
| void | setAttentionMovieByName(const QString &name) |
| void | setCategory(const KStatusNotifierItem::ItemCategory category) |
| void | setContextMenu(QMenu *menu) |
| void | setIconByName(const QString &name) |
| void | setIconByPixmap(const QIcon &icon) |
| void | setOverlayIconByName(const QString &name) |
| void | setOverlayIconByPixmap(const QIcon &icon) |
| void | setStandardActionsEnabled(bool enabled) |
| void | setStatus(const KStatusNotifierItem::ItemStatus status) |
| void | setTitle(const QString &title) |
| void | setToolTip(const QString &iconName, const QString &title, const QString &subTitle) |
| void | setToolTip(const QIcon &icon, const QString &title, const QString &subTitle) |
| void | setToolTipIconByName(const QString &name) |
| void | setToolTipIconByPixmap(const QIcon &icon) |
| void | setToolTipSubTitle(const QString &subTitle) |
| void | setToolTipTitle(const QString &title) |
| void | showMessage(const QString &title, const QString &message, const QString &icon, int timeout = 10000) |
| bool | standardActionsEnabled() const |
| KStatusNotifierItem::ItemStatus | status() const |
| QString | title() const |
| QString | toolTipIconName() const |
| QIcon | toolTipIconPixmap() const |
| QString | toolTipSubTitle() const |
| QString | toolTipTitle() const |
Public Slots
| virtual void | activate(const QPoint &pos = QPoint()) |
(since 6.0) void | hideAssociatedWindow() |
Signals
| void | activateRequested(bool active, const QPoint &pos) |
(since 6.5) void | quitRequested() |
| void | scrollRequested(int delta, Qt::Orientation orientation) |
| void | secondaryActivateRequested(const QPoint &pos) |
Detailed Description
This class implements the Status notifier Item D-Bus specification. It provides an icon similar to the classical systemtray icons, with some key differences:
- the actual representation is done by the systemtray (or the app behaving like it) itself, not by this app. Since 4.5 this also includes the menu, which means you cannot use embed widgets in the menu.
- there is communication between the systemtray and the icon owner, so the system tray can know if the application is in a normal or in a requesting attention state.
- icons are divided in categories, so the systemtray can represent in a different way the icons from normal applications and for instance the ones about hardware status.
Whenever possible you should prefer passing icon by name rather than by pixmap because:
- it is much lighter on D-Bus (no need to pass all image pixels).
- it makes it possible for the systemtray to load an icon of the appropriate size or to replace your icon with a systemtray specific icon which matches with the desktop theme.
- some implementations of the system tray do not support passing icons by pixmap and will show a blank icon instead.
Note: When used inside a Flatpak it is important to request explicit support in the Flatpak manifest with the following line: --talk-name=org.kde.StatusNotifierWatcher
Member Type Documentation
enum KStatusNotifierItem::ItemCategory
Different kinds of applications announce their type to the systemtray, so can be drawn in a different way or in a different place.
| Constant | Value | Description |
|---|---|---|
KStatusNotifierItem::ApplicationStatus | 1 | An icon for a normal application, can be seen as its taskbar entry. This is the default value. |
KStatusNotifierItem::Communications | 2 | This is a communication oriented application; this icon will be used for things such as the notification of a new message. |
KStatusNotifierItem::SystemServices | 3 | This is a system service, it can show itself in the system tray if it requires interaction from the user or wants to inform him about something. |
KStatusNotifierItem::Hardware | 4 | This application shows hardware status or a means to control it. |
KStatusNotifierItem::Reserved | 129 |
enum KStatusNotifierItem::ItemStatus
All the possible status this icon can have, depending on the importance of the events that happens in the parent application.
| Constant | Value | Description |
|---|---|---|
KStatusNotifierItem::Passive | 1 | Nothing is happening in the application, so showing this icon is not required. This is the default value. |
KStatusNotifierItem::Active | 2 | The application is doing something, or it is important that the icon is always reachable from the user. |
KStatusNotifierItem::NeedsAttention | 3 | The application requests the attention of the user, for instance battery running out or a new IM message was received. |
Member Function Documentation
[explicit] KStatusNotifierItem::KStatusNotifierItem(QObject *parent = nullptr)
Construct a new status notifier item.
parent the parent object for this object. If the object passed in as a parent is also a QWidget, it will be used as the main application window represented by this icon and will be shown/hidden when an activation is requested.
See also associatedWindow.
[explicit] KStatusNotifierItem::KStatusNotifierItem(const QString &id, QObject *parent = nullptr)
Construct a new status notifier item with a unique identifier.
If your application has more than one status notifier item and the user should be able to manipulate them separately (e.g. mark them for hiding in a user interface), the id can be used to differentiate between them.
The id should remain consistent even between application restarts. Status notifier items without ids default to the application's name for the id. This id may be used, for instance, by hosts displaying status notifier items to associate configuration information with this item in a way that can persist between sessions or application restarts.
id the unique id for this icon
parent the parent object for this object. If the object passed in as a parent is also a QWidget, it will be used as the main application window represented by this icon and will be shown/hidden when an activation is requested.
See also associatedWindow.
[since 6.5] void KStatusNotifierItem::abortQuit()
Cancelles an ongoing quit operation.
Call this in a slot connected to quitRequested().
This function was introduced in 6.5.
See also quitRequested().
[virtual slot] void KStatusNotifierItem::activate(const QPoint &pos = QPoint())
Shows the main window and try to position it on top of the other windows, if the window is already visible, hide it.
pos if it's a valid position it represents the mouse coordinates when the event was triggered
[signal] void KStatusNotifierItem::activateRequested(bool active, const QPoint &pos)
Inform the host application that an activation has been requested.
For instance left mouse click, but this is not guaranteed since it's dependent from the visualization
active if it's true the application asked for the activation of the main window, if it's false it asked for hiding
pos the position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.
[since 6.0] QWindow *KStatusNotifierItem::associatedWindow() const
Access the main window associated with this StatusNotifierItem.
This function was introduced in 6.0.
See also setAssociatedWindow().
QString KStatusNotifierItem::attentionIconName() const
Returns the name of the icon to be displayed when the application is requesting the user's attention.
If attentionImage() is not empty this will always return an empty string.
Note: Getter function for property attentionIconName.
QIcon KStatusNotifierItem::attentionIconPixmap() const
Returns a pixmap of the requesting attention icon
QString KStatusNotifierItem::attentionMovieName() const
Returns the name of the movie to be displayed when the application is requesting the user attention.
KStatusNotifierItem::ItemCategory KStatusNotifierItem::category() const
Returns the application category.
Note: Getter function for property category.
See also setCategory().
QMenu *KStatusNotifierItem::contextMenu() const
Access the context menu associated to this status notifier item.
See also setContextMenu().
[slot, since 6.0] void KStatusNotifierItem::hideAssociatedWindow()
Hides the main window, if not already hidden.
Stores some information about the window which otherwise would be lost due to unmapping from the window system. Use when toggling the main window via activate(const QPoint &) is not wanted, but instead the hidden state should be reached in any case.
This function was introduced in 6.0.
QString KStatusNotifierItem::iconName() const
Returns the name of the main icon to be displayed.
If image() is not empty this will always return an empty string
Note: Getter function for property iconName.
QIcon KStatusNotifierItem::iconPixmap() const
Returns a pixmap of the icon.
QString KStatusNotifierItem::id() const
Returns the id which was specified in the constructor.
This should be guaranteed to be consistent between application starts and untranslated, as host applications displaying items may use it for storing configuration related to this item.
QString KStatusNotifierItem::overlayIconName() const
Returns the name of the icon to be used as overlay fr the main one.
Note: Getter function for property overlayIconName.
QIcon KStatusNotifierItem::overlayIconPixmap() const
Returns a pixmap of the icon
QString KStatusNotifierItem::providedToken() const
Returns the last provided token to be used with Wayland's xdg_activation_v1.
[signal, since 6.5] void KStatusNotifierItem::quitRequested()
Emitted when the Quit action is triggered.
If abortQuit() is called from the slot the quit is cancelled. This allows to e.g. display a custom confirmation prompt.
This function was introduced in 6.5.
[signal] void KStatusNotifierItem::scrollRequested(int delta, Qt::Orientation orientation)
Inform the host application that the mouse wheel (or another mean of scrolling that the visualization provides) has been used.
delta the amount of scrolling, can be either positive or negative
orientation direction of the scrolling, can be either horizontal or vertical
[signal] void KStatusNotifierItem::secondaryActivateRequested(const QPoint &pos)
Alternate activate action.
For instance right mouse click, but this is not guaranteed since it's dependent from the visualization
pos the position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.
[since 6.0] void KStatusNotifierItem::setAssociatedWindow(QWindow *window)
Sets the main window associated with this StatusNotifierItem.
window The window to be used.
This function was introduced in 6.0.
See also associatedWindow().
void KStatusNotifierItem::setAttentionIconByName(const QString &name)
Sets a new icon that should be used when the application wants to request attention (usually the systemtray will blink between this icon and the main one).
name QIcon::fromTheme compatible name of icon to use
Note: Setter function for property attentionIconName.
void KStatusNotifierItem::setAttentionIconByPixmap(const QIcon &icon)
Sets the pixmap of the requesting attention icon.
Use setAttentionIcon(const QString) instead when possible.
icon QIcon to use for requesting attention.
void KStatusNotifierItem::setAttentionMovieByName(const QString &name)
Sets a movie name as the requesting attention icon.
This overrides anything set in setAttentionIcon()
void KStatusNotifierItem::setCategory(const KStatusNotifierItem::ItemCategory category)
Sets the category for this icon.
Usually it's needed to call this function only once.
category the new category for this icon
Note: Setter function for property category.
See also category().
void KStatusNotifierItem::setContextMenu(QMenu *menu)
Sets a new context menu for this StatusNotifierItem.
the menu will be shown with a contextMenu(int,int) call by the systemtray over D-Bus usually you don't need to call this unless you want to use a custom QMenu subclass as context menu.
The KStatusNotifierItem instance takes ownership of the menu, and will delete it upon its destruction.
See also contextMenu().
void KStatusNotifierItem::setIconByName(const QString &name)
Sets a new main icon for the system tray.
name it must be a QIcon::fromTheme compatible name, this is the preferred way to set an icon
Note: Setter function for property iconName.
void KStatusNotifierItem::setIconByPixmap(const QIcon &icon)
Sets a new main icon for the system tray.
icon our icon, use setIcon(const QString) when possible
void KStatusNotifierItem::setOverlayIconByName(const QString &name)
Sets an icon to be used as overlay for the main one.
name the icon name, if name is and empty QString() (and overlayIconPixmap() is empty too) the icon will be removed
Note: Setter function for property overlayIconName.
void KStatusNotifierItem::setOverlayIconByPixmap(const QIcon &icon)
Sets an icon to be used as overlay for the main one.
setOverlayIconByPixmap(QIcon()) will remove the overlay when overlayIconName() is empty too.
icon our overlay icon, use setOverlayIcon(const QString) when possible.
void KStatusNotifierItem::setStandardActionsEnabled(bool enabled)
enabled Whether to show the standard items in the menu, such as Quit.
See also standardActionsEnabled().
void KStatusNotifierItem::setStatus(const KStatusNotifierItem::ItemStatus status)
Sets a new status for this icon.
Note: Setter function for property status.
See also status().
void KStatusNotifierItem::setTitle(const QString &title)
Sets a title for this icon.
Note: Setter function for property title.
See also title().
void KStatusNotifierItem::setToolTip(const QString &iconName, const QString &title, const QString &subTitle)
Sets a new toolTip for this icon.
A toolTip is composed of an icon, a title and a text, all fields are optional.
iconName a QIcon::fromTheme compatible name for the tootip icon
title tootip title
subTitle subtitle for the toolTip
void KStatusNotifierItem::setToolTip(const QIcon &icon, const QString &title, const QString &subTitle)
Sets a new toolTip or this status notifier item.
This function overloads setTooltip().
icon a QIcon() pixmap for the tooltip icon
title tootip title
subTitle subtitle for the toolTip
void KStatusNotifierItem::setToolTipIconByName(const QString &name)
Sets a new icon for the toolTip.
name the name for the icon
Note: Setter function for property toolTipIconName.
void KStatusNotifierItem::setToolTipIconByPixmap(const QIcon &icon)
Set a new icon for the toolTip.
Use setToolTipIconByName(QString) if possible.
icon representing the icon
void KStatusNotifierItem::setToolTipSubTitle(const QString &subTitle)
Sets a new subTitle for the toolTip.
Note: Setter function for property toolTipSubTitle.
See also toolTipSubTitle().
void KStatusNotifierItem::setToolTipTitle(const QString &title)
Sets a new title for the toolTip.
Note: Setter function for property toolTipTitle.
See also toolTipTitle().
void KStatusNotifierItem::showMessage(const QString &title, const QString &message, const QString &icon, int timeout = 10000)
Shows the user a notification.
If possible use KNotify instead.
title message title
message the actual text shown to the user
icon icon to be shown to the user
timeout how much time will elapse before hiding the message
bool KStatusNotifierItem::standardActionsEnabled() const
Returns if the standard items in the menu, such as Quit.
See also setStandardActionsEnabled().
KStatusNotifierItem::ItemStatus KStatusNotifierItem::status() const
Returns the current application status.
Note: Getter function for property status.
See also setStatus().
QString KStatusNotifierItem::title() const
Returns the title of this icon.
Note: Getter function for property title.
See also setTitle().
QString KStatusNotifierItem::toolTipIconName() const
Returns the name of the toolTip icon.
If toolTipImage() is not empty this will always return an empty string.
Note: Getter function for property toolTipIconName.
QIcon KStatusNotifierItem::toolTipIconPixmap() const
Returns a serialization of the toolTip icon data.
QString KStatusNotifierItem::toolTipSubTitle() const
Returns the subtitle of the main icon toolTip.
Note: Getter function for property toolTipSubTitle.
See also setToolTipSubTitle().
QString KStatusNotifierItem::toolTipTitle() const
Returns the title of the main icon toolTip.
Note: Getter function for property toolTipTitle.
See also setToolTipTitle().