kosslan/quickshell
1
0
Fork 0
forked from quickshell/quickshell
Code Pull requests Activity

docs: add API documentation for SystemTray and DBusMenu

Browse source
This commit is contained in:
outfoxxed 2024-04-30 01:27:06 -07:00
parent 61061644a5
commit 658f3cf411
Signed by: outfoxxed
GPG key ID: 4C88A185FB89301E
5 changed files with 88 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/services/status_notifier/module.md Normal file
View file

@ -0,0 +1,4 @@
name = "Quickshell.Service.SystemTray"
description = "Types for implementing a system tray"
headers = [ "qml.hpp" ]
-----

40
src/services/status_notifier/qml.hpp
View file

@ -13,11 +13,11 @@ Q_NAMESPACE;
QML_ELEMENT;
enum Enum {
// A passive item does not convey important information and can be considered idle. You may want to hide these.
/// A passive item does not convey important information and can be considered idle. You may want to hide these.
Passive = 0,
// An active item may have information more important than a passive one and you probably do not want to hide it.
/// An active item may have information more important than a passive one and you probably do not want to hide it.
Active = 1,
// An item that needs attention conveys very important information such as low battery.
/// An item that needs attention conveys very important information such as low battery.
NeedsAttention = 2,
};
Q_ENUM_NS(Enum);
@ -29,12 +29,12 @@ Q_NAMESPACE;
QML_ELEMENT;
enum Enum {
// The fallback category for general applications or anything that does
// not fit into a different category.
/// The fallback category for general applications or anything that does
/// not fit into a different category.
ApplicationStatus = 0,
// System services such as IMEs or disk indexing.
/// System services such as IMEs or disk indexing.
SystemServices = 1,
// Hardware controls like battery indicators or volume control.
/// Hardware controls like battery indicators or volume control.
Hardware = 2,
};
Q_ENUM_NS(Enum);
@ -47,19 +47,22 @@ Q_ENUM_NS(Enum);
///
/// [kde/freedesktop spec]: https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/StatusNotifierItem/
class SystemTrayItem: public QObject {
using DBusMenuItem = qs::dbus::dbusmenu::DBusMenuItem;
Q_OBJECT;
// A name unique to the application, such as its name.
/// A name unique to the application, such as its name.
Q_PROPERTY(QString id READ id NOTIFY idChanged);
// A name that describes the application
/// Text that describes the application.
Q_PROPERTY(QString title READ title NOTIFY titleChanged);
Q_PROPERTY(SystemTrayStatus::Enum status READ status NOTIFY statusChanged);
Q_PROPERTY(SystemTrayCategory::Enum category READ category NOTIFY categoryChanged);
// Icon source string, usable as an Image source.
/// Icon source string, usable as an Image source.
Q_PROPERTY(QString icon READ icon NOTIFY iconChanged);
Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged);
Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged);
Q_PROPERTY(qs::dbus::dbusmenu::DBusMenuItem* menu READ menu NOTIFY menuChanged);
// If this tray item only offers a menu and no activation action.
// The context menu provided by the application, generally displayed via a right click.
Q_PROPERTY(DBusMenuItem* menu READ menu NOTIFY menuChanged);
/// If this tray item only offers a menu and activation will do nothing.
Q_PROPERTY(bool onlyMenu READ onlyMenu NOTIFY onlyMenuChanged);
QML_ELEMENT;
QML_UNCREATABLE("SystemTrayItems can only be acquired from SystemTray");
@ -67,13 +70,13 @@ class SystemTrayItem: public QObject {
public:
explicit SystemTrayItem(qs::service::sni::StatusNotifierItem* item, QObject* parent = nullptr);
// Primary activation action, generally triggered via a left click.
/// Primary activation action, generally triggered via a left click.
Q_INVOKABLE void activate();
// Secondary activation action, generally triggered via a middle click.
/// Secondary activation action, generally triggered via a middle click.
Q_INVOKABLE void secondaryActivate();
// Scroll action, such as changing volume on a mixer.
/// Scroll action, such as changing volume on a mixer.
Q_INVOKABLE void scroll(qint32 delta, bool horizontal);
[[nodiscard]] QString id() const;
@ -83,7 +86,7 @@ public:
[[nodiscard]] QString icon() const;
[[nodiscard]] QString tooltipTitle() const;
[[nodiscard]] QString tooltipDescription() const;
[[nodiscard]] qs::dbus::dbusmenu::DBusMenuItem* menu() const;
[[nodiscard]] DBusMenuItem* menu() const;
[[nodiscard]] bool onlyMenu() const;
signals:
@ -107,8 +110,13 @@ private:
friend class SystemTray;
};
///! System tray
/// Referencing the SystemTray singleton will make quickshell start tracking
/// system tray contents, which are updated as the tray changes, and can be
/// accessed via the `items` property.
class SystemTray: public QObject {
Q_OBJECT;
/// List of all system tray icons.
Q_PROPERTY(QQmlListProperty<SystemTrayItem> items READ items NOTIFY itemsChanged);
QML_ELEMENT;
QML_SINGLETON;