From fbaec141c01e8b3376850bd98aabeadf9fad0fcf Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Tue, 24 Sep 2024 01:59:38 -0700 Subject: [PATCH] service/pipewire: improve documentation --- src/services/pipewire/qml.hpp | 48 +++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/src/services/pipewire/qml.hpp b/src/services/pipewire/qml.hpp index 80049ddc..2366a373 100644 --- a/src/services/pipewire/qml.hpp +++ b/src/services/pipewire/qml.hpp @@ -52,11 +52,31 @@ private: class Pipewire: public QObject { Q_OBJECT; // clang-format off - /// All pipewire nodes. + /// All nodes present in pipewire. + /// + /// This list contains every node on the system. + /// To find a useful subset, filtering with the following properties may be helpful: + /// - @@PwNode.isStream - if the node is an application or hardware device. + /// - @@PwNode.isSink - if the node is a sink or source. + /// - @@PwNode.audio - if non null the node is an audio node. Q_PROPERTY(ObjectModel* nodes READ nodes CONSTANT); - /// All pipewire links. + /// All links present in pipewire. + /// + /// Links connect pipewire nodes to each other, and can be used to determine + /// their relationship. + /// + /// If you already have a node you want to check for connections to, + /// use @@PwNodeLinkTracker instead of filtering this list. + /// + /// > [!INFO] Multiple links may exist between the same nodes. See @@linkGroups + /// > for a deduplicated list containing only one entry per link between nodes. Q_PROPERTY(ObjectModel* links READ links CONSTANT); - /// All pipewire link groups. + /// All link groups present in pipewire. + /// + /// The same as @@links but deduplicated. + /// + /// If you already have a node you want to check for connections to, + /// use @@PwNodeLinkTracker instead of filtering this list. Q_PROPERTY(ObjectModel* linkGroups READ linkGroups CONSTANT); /// The default audio sink (output) or `null`. /// @@ -231,7 +251,7 @@ class PwNodeIface: public PwObjectIface { Q_OBJECT; /// The pipewire object id of the node. /// - /// Mainly useful for debugging. you can inspect the node directly + /// Mainly useful for debugging. You can inspect the node directly /// with `pw-cli i `. Q_PROPERTY(quint32 id READ id CONSTANT); /// The node's name, corrosponding to the object's `node.name` property. @@ -247,7 +267,8 @@ class PwNodeIface: public PwObjectIface { /// If `true`, then the node accepts audio input from other nodes, /// if `false` the node outputs audio to other nodes. Q_PROPERTY(bool isSink READ isSink CONSTANT); - /// If `true` then the node is likely to be a program, if false it is liekly to be hardware. + /// If `true` then the node is likely to be a program, if `false` it is likely to be + /// a hardware device. Q_PROPERTY(bool isStream READ isStream CONSTANT); /// The property set present on the node, as an object containing key-value pairs. /// You can inspect this directly with `pw-cli i `. @@ -263,6 +284,9 @@ class PwNodeIface: public PwObjectIface { /// > [!WARNING] This property is invalid unless the node is [bound](../pwobjecttracker). Q_PROPERTY(QVariantMap properties READ properties NOTIFY propertiesChanged); /// Extra information present only if the node sends or receives audio. + /// + /// The presence or absence of this property can be used to determine if a node + /// manages audio, regardless of if it is bound. If non null, the node is an audio node. Q_PROPERTY(PwNodeAudioIface* audio READ audio CONSTANT); QML_NAMED_ELEMENT(PwNode); QML_UNCREATABLE("PwNodes cannot be created directly"); @@ -370,11 +394,19 @@ private: }; ///! Binds pipewire objects. -/// If the object list of at least one PwObjectTracker contains a given pipewire object, -/// it will become *bound* and you will be able to interact with bound-only properties. +/// PwObjectTracker binds every node given in its @@objects list. +/// +/// #### Object Binding +/// By default, pipewire objects are unbound. Unbound objects only have a subset of +/// information available for use or modification. **Binding an object makes all of its +/// properties available for use or modification if applicable.** +/// +/// Properties that require their object be bound to use are clearly marked. You do not +/// need to bind the object unless mentioned in the description of the property you +/// want to use. class PwObjectTracker: public QObject { Q_OBJECT; - /// The list of objects to bind. + /// The list of objects to bind. May contain nulls. Q_PROPERTY(QList objects READ objects WRITE setObjects NOTIFY objectsChanged); QML_ELEMENT;