Development/Tutorials/PortToKStatusNotifierItem: Difference between revisions
(Mark for archiving) |
|||
| (3 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Archived}} | |||
Here is a list of changes to make to your application so that it can take advantage of the new KStatusNotifierItem (KSNI) class, available since KDE 4.4. | Here is a list of changes to make to your application so that it can take advantage of the new KStatusNotifierItem (KSNI) class, available since KDE 4.4. | ||
KSNI API can be found here: | |||
http://api.kde.org/4.10-api/kdelibs-apidocs/kdeui/html/classKStatusNotifierItem.html | |||
== Initialization == | == Initialization == | ||
* KSNI constructor takes a QObject, not a QWidget | * KSNI constructor takes a QObject, not a QWidget | ||
* Be sure to set the category of your application with setCategory() | * Be sure to set the category of your application with setCategory() | ||
* Tell KSNI what your main window is with setAssociatedWidget() | |||
== Signals == | == Signals == | ||
* activated() becomes activateRequested( | Note: the mapping presented here is the one implemented by the Plasma Systemtray applet. Other implementations may do different choices. | ||
* | |||
* activated(Trigger) becomes activateRequested() | |||
* activated(MiddleClick) becomes secondaryActivateRequested() | |||
* mouse wheel on the item triggers scrollRequested() | |||
== Icons == | == Icons == | ||
| Line 16: | Line 25: | ||
== Tooltip == | == Tooltip == | ||
A KSNI tooltip is made of an icon, a title and a subtitle (which may contain some limited markup). | A KSNI tooltip is made of an icon, a title and a subtitle (which may contain some limited markup). | ||
This means you have to replace your call to setToolTip(QString) with calls to: | This means you have to replace your call to setToolTip(QString) with calls to: | ||
* setToolTipIconByName(QString) or setToolTipIconByPixmap() | * setToolTipIconByName(QString) (prefered) or setToolTipIconByPixmap(QPixmap) | ||
* setToolTipTitle(QString) | * setToolTipTitle(QString) | ||
* setToolTipSubTitle(QString) | * setToolTipSubTitle(QString) | ||
show() | == Status == | ||
An item has a status, which can be set with setStatus(). The host implementation can use this status to adjust the way it presents the item. For example, the Plasma Systemtray applet will automatically hide items with the Passive status by default, making it only visible if you click on the applet expand arrow. | |||
When porting from KSystemTrayIcon, you can replace calls to show() or hide() with setStatus(KStatusNotifierItem::Active) and setStatus(KStatusNotifierItem::Passive) respectively. You can also choose to delete the KSNI instance to hide it, and recreate it when you want to show it. | |||
== Misc == | == Misc == | ||
There is no equivalent for the convenience static loadIcon(QString name) function. You have to replace it with KIconLoader::global()->loadIcon(name, KIconLoader::Panel) | |||
The KStatusNotifierItem handles the "Quit" action in the popup menu itself, displaying a confirmation dialogue and calling qApp->quit() if the user confirms. It is not necessary for the application to handle this action itself. | |||
Latest revision as of 14:44, 31 May 2019
Here is a list of changes to make to your application so that it can take advantage of the new KStatusNotifierItem (KSNI) class, available since KDE 4.4.
KSNI API can be found here:
http://api.kde.org/4.10-api/kdelibs-apidocs/kdeui/html/classKStatusNotifierItem.html
Initialization
- KSNI constructor takes a QObject, not a QWidget
- Be sure to set the category of your application with setCategory()
- Tell KSNI what your main window is with setAssociatedWidget()
Signals
Note: the mapping presented here is the one implemented by the Plasma Systemtray applet. Other implementations may do different choices.
- activated(Trigger) becomes activateRequested()
- activated(MiddleClick) becomes secondaryActivateRequested()
- mouse wheel on the item triggers scrollRequested()
Icons
Icons can be passed as a QString or as a QPixmap. Note that both must go through D-Bus, so for performance reasons, pass icons by name whenever possible.
- setIcon() becomes either setIconByName(QString) or setIconByPixmap(QPixmap)
Tooltip
A KSNI tooltip is made of an icon, a title and a subtitle (which may contain some limited markup). This means you have to replace your call to setToolTip(QString) with calls to:
- setToolTipIconByName(QString) (prefered) or setToolTipIconByPixmap(QPixmap)
- setToolTipTitle(QString)
- setToolTipSubTitle(QString)
Status
An item has a status, which can be set with setStatus(). The host implementation can use this status to adjust the way it presents the item. For example, the Plasma Systemtray applet will automatically hide items with the Passive status by default, making it only visible if you click on the applet expand arrow.
When porting from KSystemTrayIcon, you can replace calls to show() or hide() with setStatus(KStatusNotifierItem::Active) and setStatus(KStatusNotifierItem::Passive) respectively. You can also choose to delete the KSNI instance to hide it, and recreate it when you want to show it.
Misc
There is no equivalent for the convenience static loadIcon(QString name) function. You have to replace it with KIconLoader::global()->loadIcon(name, KIconLoader::Panel)
The KStatusNotifierItem handles the "Quit" action in the popup menu itself, displaying a confirmation dialogue and calling qApp->quit() if the user confirms. It is not necessary for the application to handle this action itself.