forked from quickshell/quickshell
docs: add API documentation for SystemTray and DBusMenu
This commit is contained in:
parent
61061644a5
commit
658f3cf411
2
docs
2
docs
|
@ -1 +1 @@
|
|||
Subproject commit 7c6cdbcd7b172a354669c0d2cb64bd1fbe1ca75f
|
||||
Subproject commit 6baa630e501c464352e9f876489de9eb966fa265
|
|
@ -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<DBusMenuItem> 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);
|
||||
|
|
4
src/dbus/dbusmenu/module.md
Normal file
4
src/dbus/dbusmenu/module.md
Normal file
|
@ -0,0 +1,4 @@
|
|||
name = "Quickshell.DBusMenu"
|
||||
description = "Types related to DBusMenu (used in system tray)"
|
||||
headers = [ "dbusmenu.hpp" ]
|
||||
-----
|
4
src/services/status_notifier/module.md
Normal file
4
src/services/status_notifier/module.md
Normal file
|
@ -0,0 +1,4 @@
|
|||
name = "Quickshell.Service.SystemTray"
|
||||
description = "Types for implementing a system tray"
|
||||
headers = [ "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<SystemTrayItem> items READ items NOTIFY itemsChanged);
|
||||
QML_ELEMENT;
|
||||
QML_SINGLETON;
|
||||
|
|
Loading…
Reference in a new issue