docs: add API documentation for SystemTray and DBusMenu

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

2
docs

@ -1 +1 @@
Subproject commit 7c6cdbcd7b172a354669c0d2cb64bd1fbe1ca75f Subproject commit 6baa630e501c464352e9f876489de9eb966fa265

View file

@ -24,8 +24,11 @@ Q_NAMESPACE;
QML_ELEMENT; QML_ELEMENT;
enum Enum { enum Enum {
/// This menu item does not have a checkbox or a radiobutton associated with it.
None = 0, None = 0,
/// This menu item should draw a checkbox.
CheckBox = 1, CheckBox = 1,
/// This menu item should draw a radiobutton.
RadioButton = 2, RadioButton = 2,
}; };
Q_ENUM_NS(Enum); Q_ENUM_NS(Enum);
@ -41,19 +44,64 @@ QDebug operator<<(QDebug debug, const ToggleButtonType::Enum& toggleType);
class DBusMenu; class DBusMenu;
class DBusMenuPngImage; 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 { class DBusMenuItem: public QObject {
Q_OBJECT; Q_OBJECT;
// clang-format off // clang-format off
/// Handle to the root of this menu.
Q_PROPERTY(DBusMenu* menuHandle READ menuHandle CONSTANT); Q_PROPERTY(DBusMenu* menuHandle READ menuHandle CONSTANT);
/// Text of the menu item, including hotkey markup.
Q_PROPERTY(QString label READ label NOTIFY labelChanged); Q_PROPERTY(QString label READ label NOTIFY labelChanged);
/// Text of the menu item without hotkey markup.
Q_PROPERTY(QString cleanLabel READ cleanLabel NOTIFY labelChanged); 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); 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); 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); 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); 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); 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); 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); 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<DBusMenuItem> children READ children NOTIFY childrenChanged); Q_PROPERTY(QQmlListProperty<DBusMenuItem> children READ children NOTIFY childrenChanged);
// clang-format on // clang-format on
QML_NAMED_ELEMENT(DBusMenu); QML_NAMED_ELEMENT(DBusMenu);
@ -62,7 +110,12 @@ class DBusMenuItem: public QObject {
public: public:
explicit DBusMenuItem(qint32 id, DBusMenu* menu, DBusMenuItem* parentMenu); explicit DBusMenuItem(qint32 id, DBusMenu* menu, DBusMenuItem* parentMenu);
/// Send a `clicked` event to the remote application for this menu item.
Q_INVOKABLE void click(); 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; Q_INVOKABLE void hover() const;
[[nodiscard]] DBusMenu* menuHandle() const; [[nodiscard]] DBusMenu* menuHandle() const;
@ -122,6 +175,8 @@ private:
QDebug operator<<(QDebug debug, DBusMenuItem* item); 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 { class DBusMenu: public QObject {
Q_OBJECT; Q_OBJECT;
Q_PROPERTY(DBusMenuItem* menu READ menu CONSTANT); Q_PROPERTY(DBusMenuItem* menu READ menu CONSTANT);

View file

@ -0,0 +1,4 @@
name = "Quickshell.DBusMenu"
description = "Types related to DBusMenu (used in system tray)"
headers = [ "dbusmenu.hpp" ]
-----

View file

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

View file

@ -13,11 +13,11 @@ Q_NAMESPACE;
QML_ELEMENT; QML_ELEMENT;
enum Enum { 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, 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, 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, NeedsAttention = 2,
}; };
Q_ENUM_NS(Enum); Q_ENUM_NS(Enum);
@ -29,12 +29,12 @@ Q_NAMESPACE;
QML_ELEMENT; QML_ELEMENT;
enum Enum { enum Enum {
// The fallback category for general applications or anything that does /// The fallback category for general applications or anything that does
// not fit into a different category. /// not fit into a different category.
ApplicationStatus = 0, ApplicationStatus = 0,
// System services such as IMEs or disk indexing. /// System services such as IMEs or disk indexing.
SystemServices = 1, SystemServices = 1,
// Hardware controls like battery indicators or volume control. /// Hardware controls like battery indicators or volume control.
Hardware = 2, Hardware = 2,
}; };
Q_ENUM_NS(Enum); Q_ENUM_NS(Enum);
@ -47,19 +47,22 @@ Q_ENUM_NS(Enum);
/// ///
/// [kde/freedesktop spec]: https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/StatusNotifierItem/ /// [kde/freedesktop spec]: https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/StatusNotifierItem/
class SystemTrayItem: public QObject { class SystemTrayItem: public QObject {
using DBusMenuItem = qs::dbus::dbusmenu::DBusMenuItem;
Q_OBJECT; 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); 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(QString title READ title NOTIFY titleChanged);
Q_PROPERTY(SystemTrayStatus::Enum status READ status NOTIFY statusChanged); Q_PROPERTY(SystemTrayStatus::Enum status READ status NOTIFY statusChanged);
Q_PROPERTY(SystemTrayCategory::Enum category READ category NOTIFY categoryChanged); 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 icon READ icon NOTIFY iconChanged);
Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged); Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged);
Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged); Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged);
Q_PROPERTY(qs::dbus::dbusmenu::DBusMenuItem* menu READ menu NOTIFY menuChanged); // The context menu provided by the application, generally displayed via a right click.
// If this tray item only offers a menu and no activation action. 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); Q_PROPERTY(bool onlyMenu READ onlyMenu NOTIFY onlyMenuChanged);
QML_ELEMENT; QML_ELEMENT;
QML_UNCREATABLE("SystemTrayItems can only be acquired from SystemTray"); QML_UNCREATABLE("SystemTrayItems can only be acquired from SystemTray");
@ -67,13 +70,13 @@ class SystemTrayItem: public QObject {
public: public:
explicit SystemTrayItem(qs::service::sni::StatusNotifierItem* item, QObject* parent = nullptr); 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(); 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(); 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); Q_INVOKABLE void scroll(qint32 delta, bool horizontal);
[[nodiscard]] QString id() const; [[nodiscard]] QString id() const;
@ -83,7 +86,7 @@ public:
[[nodiscard]] QString icon() const; [[nodiscard]] QString icon() const;
[[nodiscard]] QString tooltipTitle() const; [[nodiscard]] QString tooltipTitle() const;
[[nodiscard]] QString tooltipDescription() const; [[nodiscard]] QString tooltipDescription() const;
[[nodiscard]] qs::dbus::dbusmenu::DBusMenuItem* menu() const; [[nodiscard]] DBusMenuItem* menu() const;
[[nodiscard]] bool onlyMenu() const; [[nodiscard]] bool onlyMenu() const;
signals: signals:
@ -107,8 +110,13 @@ private:
friend class SystemTray; 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 { class SystemTray: public QObject {
Q_OBJECT; Q_OBJECT;
/// List of all system tray icons.
Q_PROPERTY(QQmlListProperty<SystemTrayItem> items READ items NOTIFY itemsChanged); Q_PROPERTY(QQmlListProperty<SystemTrayItem> items READ items NOTIFY itemsChanged);
QML_ELEMENT; QML_ELEMENT;
QML_SINGLETON; QML_SINGLETON;