KStatusNotifierItem

Search for usage in LXR

#include <KStatusNotifierItem>

Inheritance diagram for KStatusNotifierItem:

Public Types

enum  ItemCategory {
  ApplicationStatus = 1, Communications = 2, SystemServices = 3, Hardware = 4,
  Reserved = 129
}
 
enum  ItemStatus { Passive = 1, Active = 2, NeedsAttention = 3 }
 

Properties

QString attentionIconName
 
ItemCategory category
 
QString iconName
 
QString overlayIconName
 
ItemStatus status
 
QString title
 
QString toolTipIconName
 
QString toolTipSubTitle
 
QString toolTipTitle
 
- Properties inherited from QObject
 objectName
 

Signals

void activateRequested (bool active, const QPoint &pos)
 
void scrollRequested (int delta, Qt::Orientation orientation)
 
void secondaryActivateRequested (const QPoint &pos)
 

Public Slots

virtual void activate (const QPoint &pos=QPoint())
 
void hideAssociatedWidget ()
 

Public Member Functions

 KStatusNotifierItem (const QString &id, QObject *parent=nullptr)
 
 KStatusNotifierItem (QObject *parent=nullptr)
 
QActionaction (const QString &name) const
 
QList< QAction * > actionCollection () const
 
void addAction (const QString &name, QAction *action)
 
QWidgetassociatedWidget () const
 
QString attentionIconName () const
 
QIcon attentionIconPixmap () const
 
QString attentionMovieName () const
 
ItemCategory category () const
 
QMenucontextMenu () const
 
QString iconName () const
 
QIcon iconPixmap () const
 
QString id () const
 
QString overlayIconName () const
 
QIcon overlayIconPixmap () const
 
QString providedToken () const
 
void removeAction (const QString &name)
 
void setAssociatedWidget (QWidget *parent)
 
void setAttentionIconByName (const QString &name)
 
void setAttentionIconByPixmap (const QIcon &icon)
 
void setAttentionMovieByName (const QString &name)
 
void setCategory (const 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 ItemStatus status)
 
void setTitle (const QString &title)
 
void setToolTip (const QIcon &icon, const QString &title, const QString &subTitle)
 
void setToolTip (const QString &iconName, 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
 
ItemStatus status () const
 
QString title () const
 
QString toolTipIconName () const
 
QIcon toolTipIconPixmap () const
 
QString toolTipSubTitle () const
 
QString toolTipTitle () 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 QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, 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 (const QObject *object)
 
qobject_cast (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
 

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)
 

Additional Inherited Members

- 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 *context, Functor functor, 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)
 
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, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 

Detailed Description

KDE Status notifier Item protocol implementation

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.
Author
Marco Martin notma[email protected][email protected][email protected]mail.[email protected]com
Since
4.4

Definition at line 60 of file kstatusnotifieritem.h.

Member Enumeration Documentation

◆ ItemCategory

Different kinds of applications announce their type to the systemtray, so can be drawn in a different way or in a different place.

Enumerator
ApplicationStatus 

An icon for a normal application, can be seen as its taskbar entry. This is the default value.

Communications 

This is a communication oriented application; this icon will be used for things such as the notification of a new message.

SystemServices 

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.

Hardware 

This application shows hardware status or a means to control it.

Definition at line 98 of file kstatusnotifieritem.h.

◆ ItemStatus

All the possible status this icon can have, depending on the importance of the events that happens in the parent application.

Enumerator
Passive 

Nothing is happening in the application, so showing this icon is not required. This is the default value.

Active 

The application is doing something, or it is important that the icon is always reachable from the user.

NeedsAttention 

The application requests the attention of the user, for instance battery running out or a new IM message was received.

Definition at line 82 of file kstatusnotifieritem.h.

Constructor & Destructor Documentation

◆ KStatusNotifierItem() [1/2]

KStatusNotifierItem::KStatusNotifierItem ( QObject parent = nullptr)
explicit

Construct a new status notifier item.

Parameters
parentthe 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
associatedWidget

Definition at line 46 of file kstatusnotifieritem.cpp.

◆ KStatusNotifierItem() [2/2]

KStatusNotifierItem::KStatusNotifierItem ( const QString id,
QObject parent = nullptr 
)
explicit

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.

Parameters
idthe unique id for this icon
parentthe 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
associatedWidget

Definition at line 53 of file kstatusnotifieritem.cpp.

Member Function Documentation

◆ action()

QAction * KStatusNotifierItem::action ( const QString name) const

Retrieves an action from the action collection by the action name.

Parameters
namethe name of the action to retrieve
Since
5.12

Definition at line 553 of file kstatusnotifieritem.cpp.

◆ actionCollection()

QList< QAction * > KStatusNotifierItem::actionCollection ( ) const

All the actions present in the menu.

Definition at line 538 of file kstatusnotifieritem.cpp.

◆ activate

void KStatusNotifierItem::activate ( const QPoint pos = QPoint())
virtualslot

Shows the main widget and try to position it on top of the other windows, if the widget is already visible, hide it.

Parameters
posif it's a valid position it represents the mouse coordinates when the event was triggered

Definition at line 622 of file kstatusnotifieritem.cpp.

◆ activateRequested

void KStatusNotifierItem::activateRequested ( bool  active,
const QPoint pos 
)
signal

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.

Parameters
activeif it's true the application asked for the activation of the main window, if it's false it asked for hiding
posthe position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.

◆ addAction()

void KStatusNotifierItem::addAction ( const QString name,
QAction action 
)

Adds an action to the actionCollection()

Parameters
namethe name of the action
actionthe action we want to add

Definition at line 543 of file kstatusnotifieritem.cpp.

◆ associatedWidget()

QWidget * KStatusNotifierItem::associatedWidget ( ) const

Access the main widget associated with this StatusNotifierItem.

Definition at line 533 of file kstatusnotifieritem.cpp.

◆ attentionIconName()

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

◆ attentionIconPixmap()

QIcon KStatusNotifierItem::attentionIconPixmap ( ) const
Returns
a pixmap of the requesting attention icon

Definition at line 260 of file kstatusnotifieritem.cpp.

◆ attentionMovieName()

QString KStatusNotifierItem::attentionMovieName ( ) const
Returns
the name of the movie to be displayed when the application is requesting the user attention

Definition at line 286 of file kstatusnotifieritem.cpp.

◆ category()

ItemCategory KStatusNotifierItem::category ( ) const
Returns
the application category

◆ contextMenu()

QMenu * KStatusNotifierItem::contextMenu ( ) const

Access the context menu associated to this status notifier item.

Definition at line 476 of file kstatusnotifieritem.cpp.

◆ hideAssociatedWidget

void KStatusNotifierItem::hideAssociatedWidget ( )
slot

Hides the main widget, 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 widget via activate(const QPoint &) is not wanted, but instead the hidden state should be reached in any case.

Since
5.91

Definition at line 656 of file kstatusnotifieritem.cpp.

◆ iconName()

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

◆ iconPixmap()

QIcon KStatusNotifierItem::iconPixmap ( ) const
Returns
a pixmap of the icon

Definition at line 162 of file kstatusnotifieritem.cpp.

◆ id()

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.

Definition at line 75 of file kstatusnotifieritem.cpp.

◆ overlayIconName()

QString KStatusNotifierItem::overlayIconName ( ) const
Returns
the name of the icon to be used as overlay fr the main one

◆ overlayIconPixmap()

QIcon KStatusNotifierItem::overlayIconPixmap ( ) const
Returns
a pixmap of the icon

Definition at line 219 of file kstatusnotifieritem.cpp.

◆ providedToken()

QString KStatusNotifierItem::providedToken ( ) const
Returns
the last provided token to be used with Wayland's xdg_activation_v1

Definition at line 664 of file kstatusnotifieritem.cpp.

◆ removeAction()

void KStatusNotifierItem::removeAction ( const QString name)

Removes an action from the collection.

Parameters
namethe name of the action

Definition at line 548 of file kstatusnotifieritem.cpp.

◆ scrollRequested

void KStatusNotifierItem::scrollRequested ( int  delta,
Qt::Orientation  orientation 
)
signal

Inform the host application that the mouse wheel (or another mean of scrolling that the visualization provides) has been used.

Parameters
deltathe amount of scrolling, can be either positive or negative
orientationdirection of the scrolling, can be either horizontal or vertical

◆ secondaryActivateRequested

void KStatusNotifierItem::secondaryActivateRequested ( const QPoint pos)
signal

Alternate activate action, for instance right mouse click, but this is not guaranteed since it's dependent from the visualization.

Parameters
posthe position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.

◆ setAssociatedWidget()

void KStatusNotifierItem::setAssociatedWidget ( QWidget parent)

Sets the main widget associated with this StatusNotifierItem.

If you pass contextMenu() as a parent then the menu will be displayed when the user activate the icon. In this case the activate() method will not be called and the activateRequested() signal will not be emitted

Parameters
parentthe new main widget: must be a top level window, if it's not parent->window() will be used instead.

Definition at line 481 of file kstatusnotifieritem.cpp.

◆ setAttentionIconByName()

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)

Parameters
nameQIcon::fromTheme compatible name of icon to use

Definition at line 226 of file kstatusnotifieritem.cpp.

◆ setAttentionIconByPixmap()

void KStatusNotifierItem::setAttentionIconByPixmap ( const QIcon icon)

Sets the pixmap of the requesting attention icon.

Use setAttentionIcon(const QString) instead when possible.

Parameters
iconQIcon to use for requesting attention.

Definition at line 245 of file kstatusnotifieritem.cpp.

◆ setAttentionMovieByName()

void KStatusNotifierItem::setAttentionMovieByName ( const QString name)

Sets a movie as the requesting attention icon.

This overrides anything set in setAttentionIcon()

Definition at line 265 of file kstatusnotifieritem.cpp.

◆ setCategory()

void KStatusNotifierItem::setCategory ( const ItemCategory  category)

Sets the category for this icon, usually it's needed to call this function only once.

Parameters
categorythe new category for this icon

Definition at line 81 of file kstatusnotifieritem.cpp.

◆ setContextMenu()

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.

Definition at line 437 of file kstatusnotifieritem.cpp.

◆ setIconByName()

void KStatusNotifierItem::setIconByName ( const QString name)

Sets a new main icon for the system tray.

Parameters
nameit must be a QIcon::fromTheme compatible name, this is the preferred way to set an icon

Definition at line 120 of file kstatusnotifieritem.cpp.

◆ setIconByPixmap()

void KStatusNotifierItem::setIconByPixmap ( const QIcon icon)

Sets a new main icon for the system tray.

Parameters
pixmapour icon, use setIcon(const QString) when possible

Definition at line 143 of file kstatusnotifieritem.cpp.

◆ setOverlayIconByName()

void KStatusNotifierItem::setOverlayIconByName ( const QString name)

Sets an icon to be used as overlay for the main one.

Parameters
iconname, if name is and empty QString() (and overlayIconPixmap() is empty too) the icon will be removed

Definition at line 167 of file kstatusnotifieritem.cpp.

◆ setOverlayIconByPixmap()

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.

Parameters
pixmapour overlay icon, use setOverlayIcon(const QString) when possible.

Definition at line 194 of file kstatusnotifieritem.cpp.

◆ setStandardActionsEnabled()

void KStatusNotifierItem::setStandardActionsEnabled ( bool  enabled)

Sets whether to show the standard items in the menu, such as Quit.

Definition at line 558 of file kstatusnotifieritem.cpp.

◆ setStatus()

void KStatusNotifierItem::setStatus ( const ItemStatus  status)

Sets a new status for this icon.

Definition at line 101 of file kstatusnotifieritem.cpp.

◆ setTitle()

void KStatusNotifierItem::setTitle ( const QString title)

Sets a title for this icon.

Definition at line 96 of file kstatusnotifieritem.cpp.

◆ setToolTip() [1/2]

void KStatusNotifierItem::setToolTip ( const QIcon icon,
const QString title,
const QString subTitle 
)

Sets a new toolTip or this status notifier item.

This is an overloaded member provided for convenience

Definition at line 340 of file kstatusnotifieritem.cpp.

◆ setToolTip() [2/2]

void KStatusNotifierItem::setToolTip ( const QString iconName,
const QString title,
const QString subTitle 
)

Sets a new toolTip or this icon, a toolTip is composed of an icon, a title and a text, all fields are optional.

Parameters
iconNamea QIcon::fromTheme compatible name for the tootip icon
titletootip title
subTitlesubtitle for the toolTip

Definition at line 322 of file kstatusnotifieritem.cpp.

◆ setToolTipIconByName()

void KStatusNotifierItem::setToolTipIconByName ( const QString name)

Set a new icon for the toolTip.

Parameters
namethe name for the icon

Definition at line 361 of file kstatusnotifieritem.cpp.

◆ setToolTipIconByPixmap()

void KStatusNotifierItem::setToolTipIconByPixmap ( const QIcon icon)

Set a new icon for the toolTip.

Use setToolTipIconByName(QString) if possible.

Parameters
pixmaprepresenting the icon

Definition at line 379 of file kstatusnotifieritem.cpp.

◆ setToolTipSubTitle()

void KStatusNotifierItem::setToolTipSubTitle ( const QString subTitle)

Sets a new subtitle for the toolTip.

Definition at line 418 of file kstatusnotifieritem.cpp.

◆ setToolTipTitle()

void KStatusNotifierItem::setToolTipTitle ( const QString title)

Sets a new title for the toolTip.

Definition at line 399 of file kstatusnotifieritem.cpp.

◆ showMessage()

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

Parameters
titlemessage title
messagethe actual text shown to the user
iconicon to be shown to the user
timeouthow much time will elaps before hiding the message

Definition at line 586 of file kstatusnotifieritem.cpp.

◆ standardActionsEnabled()

bool KStatusNotifierItem::standardActionsEnabled ( ) const
Returns
if the standard items in the menu, such as Quit

Definition at line 581 of file kstatusnotifieritem.cpp.

◆ status()

ItemStatus KStatusNotifierItem::status ( ) const
Returns
the current application status

◆ title()

QString KStatusNotifierItem::title ( ) const
Returns
the title of this icon

◆ toolTipIconName()

QString KStatusNotifierItem::toolTipIconName ( ) const
Returns
the name of the toolTip icon if toolTipImage() is not empty this will always return an empty string

◆ toolTipIconPixmap()

QIcon KStatusNotifierItem::toolTipIconPixmap ( ) const
Returns
a serialization of the toolTip icon data

Definition at line 394 of file kstatusnotifieritem.cpp.

◆ toolTipSubTitle()

QString KStatusNotifierItem::toolTipSubTitle ( ) const
Returns
the subtitle of the main icon toolTip

◆ toolTipTitle()

QString KStatusNotifierItem::toolTipTitle ( ) const
Returns
the title of the main icon toolTip

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:49:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.