From 658f3cf411edf0038224ae89802f138bbab85c0a Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Tue, 30 Apr 2024 01:27:06 -0700 Subject: [PATCH] docs: add API documentation for SystemTray and DBusMenu --- docs | 2 +- src/dbus/dbusmenu/dbusmenu.hpp | 55 ++++++++++++++++++++++++++ src/dbus/dbusmenu/module.md | 4 ++ src/services/status_notifier/module.md | 4 ++ src/services/status_notifier/qml.hpp | 40 +++++++++++-------- 5 files changed, 88 insertions(+), 17 deletions(-) create mode 100644 src/dbus/dbusmenu/module.md create mode 100644 src/services/status_notifier/module.md diff --git a/docs b/docs index 7c6cdbcd..6baa630e 160000 --- a/docs +++ b/docs @@ -1 +1 @@ -Subproject commit 7c6cdbcd7b172a354669c0d2cb64bd1fbe1ca75f +Subproject commit 6baa630e501c464352e9f876489de9eb966fa265 diff --git a/src/dbus/dbusmenu/dbusmenu.hpp b/src/dbus/dbusmenu/dbusmenu.hpp index dcf4d688..1fa5e58f 100644 --- a/src/dbus/dbusmenu/dbusmenu.hpp +++ b/src/dbus/dbusmenu/dbusmenu.hpp @@ -24,8 +24,11 @@ Q_NAMESPACE; QML_ELEMENT; enum Enum { + /// This menu item does not have a checkbox or a radiobutton associated with it. None = 0, + /// This menu item should draw a checkbox. CheckBox = 1, + /// This menu item should draw a radiobutton. RadioButton = 2, }; Q_ENUM_NS(Enum); @@ -41,19 +44,64 @@ QDebug operator<<(QDebug debug, const ToggleButtonType::Enum& toggleType); class DBusMenu; class DBusMenuPngImage; +///! Menu item shared by an external program. +/// Menu item shared by an external program via the +/// [DBusMenu specification](https://github.com/AyatanaIndicators/libdbusmenu/blob/master/libdbusmenu-glib/dbus-menu.xml). class DBusMenuItem: public QObject { Q_OBJECT; // clang-format off + /// Handle to the root of this menu. Q_PROPERTY(DBusMenu* menuHandle READ menuHandle CONSTANT); + /// Text of the menu item, including hotkey markup. Q_PROPERTY(QString label READ label NOTIFY labelChanged); + /// Text of the menu item without hotkey markup. Q_PROPERTY(QString cleanLabel READ cleanLabel NOTIFY labelChanged); + /// If the menu item should be shown as enabled. + /// + /// > [!INFO] Disabled menu items are often used as headers in addition + /// > to actual disabled entries. Q_PROPERTY(bool enabled READ enabled NOTIFY enabledChanged); + /// Url of the menu item's icon or `""` if it doesn't have one. + /// + /// This can be passed to [Image.source](https://doc.qt.io/qt-6/qml-qtquick-image.html#source-prop) + /// as shown below. + /// + /// ```qml + /// Image { + /// source: menuItem.icon + /// // To get the best image quality, set the image source size to the same size + /// // as the rendered image. + /// sourceSize.width: width + /// sourceSize.height: height + /// } + /// ``` Q_PROPERTY(QString icon READ icon NOTIFY iconChanged); + /// If this menu item has an associated checkbox or radiobutton. + /// + /// > [!INFO] It is the responsibility of the remote application to update the state of + /// > checkboxes and radiobuttons via [checkState](#prop.checkState). Q_PROPERTY(ToggleButtonType::Enum toggleType READ toggleType NOTIFY toggleTypeChanged); + /// The check state of the checkbox or radiobutton if applicable, as a + /// [Qt.CheckState](https://doc.qt.io/qt-6/qt.html#CheckState-enum). Q_PROPERTY(Qt::CheckState checkState READ checkState NOTIFY checkStateChanged); + /// If this menu item should be rendered as a separator between other items. + /// + /// No other properties have a meaningful value when `isSeparator` is true. Q_PROPERTY(bool isSeparator READ isSeparator NOTIFY separatorChanged); + /// If this menu item reveals a submenu containing more items. + /// + /// Any submenu items must be requested by setting [showChildren](#prop.showChildren). Q_PROPERTY(bool hasChildren READ hasChildren NOTIFY hasChildrenChanged); + /// If submenu entries of this item should be shown. + /// + /// When true, children of this menu item will be exposed via [children](#prop.children). + /// Setting this property will additionally send the `opened` and `closed` events to the + /// process that provided the menu. Q_PROPERTY(bool showChildren READ isShowingChildren WRITE setShowChildren NOTIFY showingChildrenChanged); + /// Children of this menu item. Only populated when [showChildren](#prop.showChildren) is true. + /// + /// > [!INFO] Use [hasChildren](#prop.hasChildren) to check if this item should reveal a submenu + /// > instead of checking if `children` is empty. Q_PROPERTY(QQmlListProperty children READ children NOTIFY childrenChanged); // clang-format on QML_NAMED_ELEMENT(DBusMenu); @@ -62,7 +110,12 @@ class DBusMenuItem: public QObject { public: explicit DBusMenuItem(qint32 id, DBusMenu* menu, DBusMenuItem* parentMenu); + /// Send a `clicked` event to the remote application for this menu item. Q_INVOKABLE void click(); + + /// Send a `hovered` event to the remote application for this menu item. + /// + /// Note: we are not aware of any programs that use this in any meaningful way. Q_INVOKABLE void hover() const; [[nodiscard]] DBusMenu* menuHandle() const; @@ -122,6 +175,8 @@ private: QDebug operator<<(QDebug debug, DBusMenuItem* item); +///! Handle to a DBusMenu tree. +/// Handle to a menu tree provided by a remote process. class DBusMenu: public QObject { Q_OBJECT; Q_PROPERTY(DBusMenuItem* menu READ menu CONSTANT); diff --git a/src/dbus/dbusmenu/module.md b/src/dbus/dbusmenu/module.md new file mode 100644 index 00000000..810393e4 --- /dev/null +++ b/src/dbus/dbusmenu/module.md @@ -0,0 +1,4 @@ +name = "Quickshell.DBusMenu" +description = "Types related to DBusMenu (used in system tray)" +headers = [ "dbusmenu.hpp" ] +----- diff --git a/src/services/status_notifier/module.md b/src/services/status_notifier/module.md new file mode 100644 index 00000000..ff1e6208 --- /dev/null +++ b/src/services/status_notifier/module.md @@ -0,0 +1,4 @@ +name = "Quickshell.Service.SystemTray" +description = "Types for implementing a system tray" +headers = [ "qml.hpp" ] +----- diff --git a/src/services/status_notifier/qml.hpp b/src/services/status_notifier/qml.hpp index 26b252a0..39463871 100644 --- a/src/services/status_notifier/qml.hpp +++ b/src/services/status_notifier/qml.hpp @@ -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 items READ items NOTIFY itemsChanged); QML_ELEMENT; QML_SINGLETON;