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

service/pipewire: improve documentation

Browse source
This commit is contained in:
outfoxxed 2024-09-24 01:59:38 -07:00
parent fdc78ae16f
commit fbaec141c0
Signed by untrusted user: outfoxxed
GPG key ID: 4C88A185FB89301E
1 changed files with 40 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

48
src/services/pipewire/qml.hpp
View file

@ -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<PwNodeIface>* 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<PwLinkIface>* 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<PwLinkGroupIface>* 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 <id>`.
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 <id>`.
@ -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<QObject*> objects READ objects WRITE setObjects NOTIFY objectsChanged);
QML_ELEMENT;