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

docs: use new member reference shorthand

Browse source
This commit is contained in:
outfoxxed 2024-07-21 17:41:49 -07:00
parent dfcf533424
commit a9e4720fae
Signed by: outfoxxed
GPG key ID: 4C88A185FB89301E
35 changed files with 182 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/services/greetd/connection.hpp
View file

@ -7,6 +7,8 @@
#include <qqmlintegration.h>
#include <qtmetamacros.h>
///! State of the Greetd connection.
/// See @@Greetd.state.
class GreetdState: public QObject {
Q_OBJECT;
QML_ELEMENT;

14
src/services/greetd/qml.hpp
View file

@ -33,29 +33,29 @@ public:
Q_INVOKABLE static void cancelSession();
/// Respond to an authentication message.
///
/// May only be called in response to an `authMessage` with responseRequired set to true.
/// May only be called in response to an @@authMessage(s) with `responseRequired` set to true.
Q_INVOKABLE static void respond(QString response);
// docgen currently can't handle default params
// clang-format off
/// Launch the session, exiting quickshell.
/// `readyToLaunch` must be true to call this function.
/// @@state must be `GreetdState.ReadyToLaunch` to call this function.
Q_INVOKABLE static void launch(const QList<QString>& command);
/// Launch the session, exiting quickshell.
/// `readyToLaunch` must be true to call this function.
/// @@state must be `GreetdState.ReadyToLaunch` to call this function.
Q_INVOKABLE static void launch(const QList<QString>& command, const QList<QString>& environment);
/// Launch the session, exiting quickshell if `quit` is true.
/// `readyToLaunch` must be true to call this function.
/// Launch the session, exiting quickshell if @@quit is true.
/// @@state must be `GreetdState.ReadyToLaunch` to call this function.
///
/// The `launched` signal can be used to perform an action after greetd has acknowledged
/// The @@launched signal can be used to perform an action after greetd has acknowledged
/// the desired session.
///
/// > [!WARNING] Note that greetd expects the greeter to terminate as soon as possible
/// > after setting a target session, and waiting too long may lead to unexpected behavior
/// > such as the greeter restarting.
/// >
/// > Performing animations and such should be done *before* calling `launch`.
/// > Performing animations and such should be done *before* calling @@launch.
Q_INVOKABLE static void launch(const QList<QString>& command, const QList<QString>& environment, bool quit);
// clang-format on

73
src/services/mpris/player.hpp
View file

@ -13,6 +13,8 @@
namespace qs::service::mpris {
///! Playback state of an MprisPlayer
/// See @@MprisPlayer.playbackState.
class MprisPlaybackState: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -29,6 +31,8 @@ public:
Q_INVOKABLE static QString toString(MprisPlaybackState::Enum status);
};
///! Loop state of an MprisPlayer
/// See @@MprisPlayer.loopState.
class MprisLoopState: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -72,17 +76,17 @@ class MprisPlayer: public QObject {
/// The name of the desktop entry for the media player, or an empty string if not provided.
Q_PROPERTY(QString desktopEntry READ desktopEntry NOTIFY desktopEntryChanged);
/// The current position in the playing track, as seconds, with millisecond precision,
/// or `0` if `positionSupported` is false.
/// or `0` if @@positionSupported is false.
///
/// May only be written to if `canSeek` and `positionSupported` are true.
/// May only be written to if @@canSeek and @@positionSupported are true.
///
/// > [!WARNING] To avoid excessive property updates wasting CPU while `position` is not
/// > actively monitored, `position` usually will not update reactively, unless a nonlinear
/// > change in position occurs, however reading it will always return the current position.
/// >
/// > If you want to actively monitor the position, the simplest way it to emit the `positionChanged`
/// > signal manually for the duration you are monitoring it, Using a [FrameAnimation] if you need
/// > the value to update smoothly, such as on a slider, or a [Timer] if not, as shown below.
/// > If you want to actively monitor the position, the simplest way it to emit the @@positionChanged(s)
/// > signal manually for the duration you are monitoring it, Using a @@QtQuick.FrameAnimation if you need
/// > the value to update smoothly, such as on a slider, or a @@QtQuick.Timer if not, as shown below.
/// >
/// > ```qml {filename="Using a FrameAnimation"}
/// > FrameAnimation {
@ -104,18 +108,15 @@ class MprisPlayer: public QObject {
/// > onTriggered: player.positionChanged()
/// > }
/// > ```
///
/// [FrameAnimation]: https://doc.qt.io/qt-6/qml-qtquick-frameanimation.html
/// [Timer]: https://doc.qt.io/qt-6/qml-qtqml-timer.html
Q_PROPERTY(qreal position READ position WRITE setPosition NOTIFY positionChanged);
Q_PROPERTY(bool positionSupported READ positionSupported NOTIFY positionSupportedChanged);
/// The length of the playing track, as seconds, with millisecond precision,
/// or the value of `position` if `lengthSupported` is false.
/// or the value of @@position if @@lengthSupported is false.
Q_PROPERTY(qreal length READ length NOTIFY lengthChanged);
Q_PROPERTY(bool lengthSupported READ lengthSupported NOTIFY lengthSupportedChanged);
/// The volume of the playing track from 0.0 to 1.0, or 1.0 if `volumeSupported` is false.
/// The volume of the playing track from 0.0 to 1.0, or 1.0 if @@volumeSupported is false.
///
/// May only be written to if `canControl` and `volumeSupported` are true.
/// May only be written to if @@canControl and @@volumeSupported are true.
Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged);
Q_PROPERTY(bool volumeSupported READ volumeSupported NOTIFY volumeSupportedChanged);
/// Metadata of the current track.
@ -123,7 +124,7 @@ class MprisPlayer: public QObject {
/// A map of common properties is available [here](https://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata).
/// Do not count on any of them actually being present.
///
/// Note that the `trackTitle`, `trackAlbum`, `trackAlbumArtist`, `trackArtists` and `trackArtUrl`
/// Note that the @@trackTitle, @@trackAlbum, @@trackAlbumArtist, @@trackArtists and @@trackArtUrl
/// properties have extra logic to guard against bad players sending weird metadata, and should
/// be used over grabbing the properties directly from the metadata.
Q_PROPERTY(QVariantMap metadata READ metadata NOTIFY metadataChanged);
@ -139,37 +140,37 @@ class MprisPlayer: public QObject {
Q_PROPERTY(QString trackArtUrl READ trackArtUrl NOTIFY trackArtUrlChanged);
/// The playback state of the media player.
///
/// - If `canPlay` is false, you cannot assign the `Playing` state.
/// - If `canPause` is false, you cannot assign the `Paused` state.
/// - If `canControl` is false, you cannot assign the `Stopped` state.
/// - If @@canPlay is false, you cannot assign the `Playing` state.
/// - If @@canPause is false, you cannot assign the `Paused` state.
/// - If @@canControl is false, you cannot assign the `Stopped` state.
/// (or any of the others, though their repsective properties will also be false)
Q_PROPERTY(MprisPlaybackState::Enum playbackState READ playbackState WRITE setPlaybackState NOTIFY playbackStateChanged);
/// The loop state of the media player, or `None` if `loopSupported` is false.
/// The loop state of the media player, or `None` if @@loopSupported is false.
///
/// May only be written to if `canControl` and `loopSupported` are true.
/// May only be written to if @@canControl and @@loopSupported are true.
Q_PROPERTY(MprisLoopState::Enum loopState READ loopState WRITE setLoopState NOTIFY loopStateChanged);
Q_PROPERTY(bool loopSupported READ loopSupported NOTIFY loopSupportedChanged);
/// The speed the song is playing at, as a multiplier.
///
/// Only values between `minRate` and `maxRate` (inclusive) may be written to the property.
/// Only values between @@minRate and @@maxRate (inclusive) may be written to the property.
/// Additionally, It is recommended that you only write common values such as `0.25`, `0.5`, `1.0`, `2.0`
/// to the property, as media players are free to ignore the value, and are more likely to
/// accept common ones.
Q_PROPERTY(qreal rate READ rate WRITE setRate NOTIFY rateChanged);
Q_PROPERTY(qreal minRate READ minRate NOTIFY minRateChanged);
Q_PROPERTY(qreal maxRate READ maxRate NOTIFY maxRateChanged);
/// If the play queue is currently being shuffled, or false if `shuffleSupported` is false.
/// If the play queue is currently being shuffled, or false if @@shuffleSupported is false.
///
/// May only be written if `canControl` and `shuffleSupported` are true.
/// May only be written if @@canControl and @@shuffleSupported are true.
Q_PROPERTY(bool shuffle READ shuffle WRITE setShuffle NOTIFY shuffleChanged);
Q_PROPERTY(bool shuffleSupported READ shuffleSupported NOTIFY shuffleSupportedChanged);
/// If the player is currently shown in fullscreen.
///
/// May only be written to if `canSetFullscreen` is true.
/// May only be written to if @@canSetFullscreen is true.
Q_PROPERTY(bool fullscreen READ fullscreen WRITE setFullscreen NOTIFY fullscreenChanged);
/// Uri schemes supported by `openUri`.
/// Uri schemes supported by @@openUri().
Q_PROPERTY(QList<QString> supportedUriSchemes READ supportedUriSchemes NOTIFY supportedUriSchemesChanged);
/// Mime types supported by `openUri`.
/// Mime types supported by @@openUri().
Q_PROPERTY(QList<QString> supportedMimeTypes READ supportedMimeTypes NOTIFY supportedMimeTypesChanged);
// clang-format on
QML_ELEMENT;
@ -180,42 +181,42 @@ public:
/// Bring the media player to the front of the window stack.
///
/// May only be called if `canRaise` is true.
/// May only be called if @@canRaise is true.
Q_INVOKABLE void raise();
/// Quit the media player.
///
/// May only be called if `canQuit` is true.
/// May only be called if @@canQuit is true.
Q_INVOKABLE void quit();
/// Open the given URI in the media player.
///
/// Many players will silently ignore this, especially if the uri
/// does not match `supportedUriSchemes` and `supportedMimeTypes`.
/// does not match @@supportedUriSchemes and @@supportedMimeTypes.
Q_INVOKABLE void openUri(const QString& uri);
/// Play the next song.
///
/// May only be called if `canGoNext` is true.
/// May only be called if @@canGoNext is true.
Q_INVOKABLE void next();
/// Play the previous song, or go back to the beginning of the current one.
///
/// May only be called if `canGoPrevious` is true.
/// May only be called if @@canGoPrevious is true.
Q_INVOKABLE void previous();
/// Change `position` by an offset.
///
/// Even if `positionSupported` is false and you cannot set `position`,
/// Even if @@positionSupported is false and you cannot set `position`,
/// this function may work.
///
/// May only be called if `canSeek` is true.
/// May only be called if @@canSeek is true.
Q_INVOKABLE void seek(qreal offset);
/// Equivalent to setting `playbackState` to `Playing`.
/// Equivalent to setting @@playbackState to `Playing`.
Q_INVOKABLE void play();
/// Equivalent to setting `playbackState` to `Paused`.
/// Equivalent to setting @@playbackState to `Paused`.
Q_INVOKABLE void pause();
/// Equivalent to setting `playbackState` to `Stopped`.
/// Equivalent to setting @@playbackState to `Stopped`.
Q_INVOKABLE void stop();
/// Equivalent to calling `play()` if not playing or `pause()` if playing.
/// Equivalent to calling @@play() if not playing or @@pause() if playing.
///
/// May only be called if `canTogglePlaying` is true, which is equivalent to
/// `canPlay` or `canPause` depending on the current playback state.
/// May only be called if @@canTogglePlaying is true, which is equivalent to
/// @@canPlay or @@canPause() depending on the current playback state.
Q_INVOKABLE void togglePlaying();
[[nodiscard]] bool isValid() const;

13
src/services/notifications/notification.hpp
View file

@ -14,6 +14,8 @@ namespace qs::service::notifications {
class NotificationImage;
///! The urgency level of a Notification.
/// See @@Notification.urgency.
class NotificationUrgency: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -30,6 +32,8 @@ public:
Q_INVOKABLE static QString toString(NotificationUrgency::Enum value);
};
///! The reason a Notification was closed.
/// See @@Notification.closed(s).
class NotificationCloseReason: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -53,7 +57,8 @@ class NotificationAction;
///! A notification emitted by a NotificationServer.
/// A notification emitted by a NotificationServer.
/// > [!INFO] This type is @@Quickshell.Retainable$. It
///
/// > [!INFO] This type is @@Quickshell.Retainable. It
/// > can be retained after destruction if necessary.
class Notification
: public QObject
@ -63,13 +68,13 @@ class Notification
Q_PROPERTY(quint32 id READ id CONSTANT);
/// If the notification is tracked by the notification server.
///
/// Setting this property to false is equivalent to calling `dismiss()`.
/// Setting this property to false is equivalent to calling @@dismiss().
Q_PROPERTY(bool tracked READ isTracked WRITE setTracked NOTIFY trackedChanged);
/// If this notification was carried over from the last generation
/// when quickshell reloaded.
///
/// Notifications from the last generation will only be emitted
/// if @@NotificationServer.keepOnReloadis true.
/// if @@NotificationServer.keepOnReload is true.
Q_PROPERTY(bool lastGeneration READ isLastGeneration CONSTANT);
/// Time in seconds the notification should be valid for
Q_PROPERTY(qreal expireTimeout READ expireTimeout NOTIFY expireTimeoutChanged);
@ -190,6 +195,8 @@ private:
QVariantMap mHints;
};
///! An action associated with a Notification.
/// See @@Notification.actions.
class NotificationAction: public QObject {
Q_OBJECT;
/// The identifier of the action.

6
src/services/pam/conversation.hpp
View file

@ -13,7 +13,8 @@
Q_DECLARE_LOGGING_CATEGORY(logPam);
/// The result of an authentication.
///! The result of an authentication.
/// See @@PamContext.completed(s).
class PamResult: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -35,7 +36,8 @@ public:
Q_INVOKABLE static QString toString(PamResult::Enum value);
};
/// An error that occurred during an authentication.
///! An error that occurred during an authentication.
/// See @@PamContext.error(s).
class PamError: public QObject {
Q_OBJECT;
QML_ELEMENT;

18
src/services/pam/qml.hpp
View file

@ -20,23 +20,23 @@ class PamContext
// clang-format off
/// If the pam context is actively performing an authentication.
///
/// Setting this value behaves exactly the same as calling `start()` and `abort()`.
/// Setting this value behaves exactly the same as calling @@start() and @@abort().
Q_PROPERTY(bool active READ isActive WRITE setActive NOTIFY activeChanged);
/// The pam configuration to use. Defaults to "login".
///
/// The configuration should name a file inside `configDirectory`.
/// The configuration should name a file inside @@configDirectory.
///
/// This property may not be set while `active` is true.
/// This property may not be set while @@active is true.
Q_PROPERTY(QString config READ config WRITE setConfig NOTIFY configChanged);
/// The pam configuration directory to use. Defaults to "/etc/pam.d".
///
/// The configuration directory is resolved relative to the current file if not an absolute path.
///
/// This property may not be set while `active` is true.
/// This property may not be set while @@active is true.
Q_PROPERTY(QString configDirectory READ configDirectory WRITE setConfigDirectory NOTIFY configDirectoryChanged);
/// The user to authenticate as. If unset the current user will be used.
///
/// This property may not be set while `active` is true.
/// This property may not be set while @@active is true.
Q_PROPERTY(QString user READ user WRITE setUser NOTIFY userChanged);
/// The last message sent by pam.
Q_PROPERTY(QString message READ message NOTIFY messageChanged);
@ -44,9 +44,9 @@ class PamContext
Q_PROPERTY(bool messageIsError READ messageIsError NOTIFY messageIsErrorChanged);
/// If pam currently wants a response.
///
/// Responses can be returned with the `respond()` function.
/// Responses can be returned with the @@respond() function.
Q_PROPERTY(bool responseRequired READ isResponseRequired NOTIFY responseRequiredChanged);
/// If the user's response should be visible. Only valid when `responseRequired` is true.
/// If the user's response should be visible. Only valid when @@responseRequired is true.
Q_PROPERTY(bool responseVisible READ isResponseVisible NOTIFY responseVisibleChanged);
// clang-format on
QML_ELEMENT;
@ -68,7 +68,7 @@ public:
/// Respond to pam.
///
/// May not be called unless `responseRequired` is true.
/// May not be called unless @@responseRequired is true.
Q_INVOKABLE void respond(const QString& response);
[[nodiscard]] bool isActive() const;
@ -93,7 +93,7 @@ signals:
void completed(PamResult::Enum result);
/// Emitted if pam fails to perform authentication normally.
///
/// A `completed(false)` will be emitted after this event.
/// A `completed(PamResult.Error)` will be emitted after this event.
void error(PamError::Enum error);
/// Emitted whenever pam sends a new message, after the change signals for

2
src/services/pipewire/link.hpp
View file

@ -13,6 +13,8 @@
namespace qs::service::pipewire {
///! State of a pipewire link.
/// See @@PwLink.state.
class PwLinkState: public QObject {
Q_OBJECT;
QML_ELEMENT;

2
src/services/pipewire/node.hpp
View file

@ -18,6 +18,8 @@
namespace qs::service::pipewire {
///! Audio channel of a pipewire node.
/// See @@PwNodeAudio.channels.
class PwAudioChannel: public QObject {
Q_OBJECT;
QML_ELEMENT;

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

@ -136,6 +136,9 @@ private:
};
///! Audio specific properties of pipewire nodes.
/// Extra properties of a @@PwNode if the node is an audio node.
///
/// See @@PwNode.audio.
class PwNodeAudioIface: public QObject {
Q_OBJECT;
/// If the node is currently muted. Setting this property changes the mute state.
@ -152,8 +155,8 @@ class PwNodeAudioIface: public QObject {
/// > [!WARNING] This property is invalid unless the node is [bound](../pwobjecttracker).
Q_PROPERTY(QVector<PwAudioChannel::Enum> channels READ channels NOTIFY channelsChanged);
/// The volumes of each audio channel individually. Each entry corrosponds to
/// the channel at the same index in `channels`. `volumes` and `channels` will always be
/// the same length.
/// the volume of the channel at the same index in @@channels. @@volumes and @@channels
/// will always be the same length.
///
/// > [!WARNING] This property is invalid unless the node is [bound](../pwobjecttracker).
Q_PROPERTY(QVector<float> volumes READ volumes WRITE setVolumes NOTIFY volumesChanged);
@ -195,11 +198,11 @@ class PwNodeIface: public PwObjectIface {
Q_PROPERTY(QString name READ name CONSTANT);
/// The node's description, corrosponding to the object's `node.description` property.
///
/// May be empty. Generally more human readable than `name`.
/// May be empty. Generally more human readable than @@name.
Q_PROPERTY(QString description READ description CONSTANT);
/// The node's nickname, corrosponding to the object's `node.nickname` property.
///
/// May be empty. Generally but not always more human readable than `description`.
/// May be empty. Generally but not always more human readable than @@description.
Q_PROPERTY(QString nickname READ nickname CONSTANT);
/// If `true`, then the node accepts audio input from other nodes,
/// if `false` the node outputs audio to other nodes.
@ -249,7 +252,7 @@ private:
///! A connection between pipewire nodes.
/// Note that there is one link per *channel* of a connection between nodes.
/// You usually want @@PwLinkGroup$.
/// You usually want @@PwLinkGroup.
class PwLinkIface: public PwObjectIface {
Q_OBJECT;
/// The pipewire object id of the link.

12
src/services/status_notifier/qml.hpp
View file

@ -8,6 +8,8 @@
#include "../../core/model.hpp"
#include "item.hpp"
///! Statis of a SystemTrayItem.
/// See @@SystemTrayItem.status.
namespace SystemTrayStatus { // NOLINT
Q_NAMESPACE;
QML_ELEMENT;
@ -24,6 +26,8 @@ Q_ENUM_NS(Enum);
} // namespace SystemTrayStatus
///! Category of a SystemTrayItem.
/// See @@SystemTrayItem.category.
namespace SystemTrayCategory { // NOLINT
Q_NAMESPACE;
QML_ELEMENT;
@ -60,8 +64,8 @@ class SystemTrayItem: public QObject {
Q_PROPERTY(QString icon READ icon NOTIFY iconChanged);
Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged);
Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged);
/// If this tray item has an associated menu accessible via `display`
/// or a @@SystemTrayMenuWatcher$.
/// If this tray item has an associated menu accessible via @@display()
/// or a @@SystemTrayMenuWatcher.
Q_PROPERTY(bool hasMenu READ hasMenu NOTIFY hasMenuChanged);
/// If this tray item only offers a menu and activation will do nothing.
Q_PROPERTY(bool onlyMenu READ onlyMenu NOTIFY onlyMenuChanged);
@ -110,7 +114,7 @@ signals:
///! 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.
/// accessed via the @@items property.
class SystemTray: public QObject {
Q_OBJECT;
/// List of all system tray icons.
@ -141,7 +145,7 @@ class SystemTrayMenuWatcher: public QObject {
Q_OBJECT;
/// The tray item to watch.
Q_PROPERTY(SystemTrayItem* trayItem READ trayItem WRITE setTrayItem NOTIFY trayItemChanged);
/// The menu associated with the tray item. Will be null if `trayItem` is null
/// The menu associated with the tray item. Will be null if @@trayItem is null
/// or has no associated menu.
Q_PROPERTY(DBusMenuItem* menu READ menu NOTIFY menuChanged);
QML_ELEMENT;

2
src/services/upower/core.hpp
View file

@ -55,7 +55,7 @@ class UPowerQml: public QObject {
QML_SINGLETON;
/// UPower's DisplayDevice for your system. Can be `null`.
///
/// This is an aggregate device and not a physical one, meaning you will not find it in `devices`.
/// This is an aggregate device and not a physical one, meaning you will not find it in @@devices.
/// It is typically the device that is used for displaying information in desktop environments.
Q_PROPERTY(UPowerDevice* displayDevice READ displayDevice NOTIFY displayDeviceChanged);
/// All connected UPower devices.

8
src/services/upower/device.hpp
View file

@ -12,6 +12,8 @@
namespace qs::service::upower {
///! Power state of a UPower device.
/// See @@UPowerDevice.state.
class UPowerDeviceState: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -34,6 +36,8 @@ public:
Q_INVOKABLE static QString toString(UPowerDeviceState::Enum status);
};
///! Type of a UPower device.
/// See @@UPowerDevice.type.
class UPowerDeviceType: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -100,7 +104,7 @@ class UPowerDevice: public QObject {
Q_PROPERTY(qreal timeToFull READ timeToFull NOTIFY timeToFullChanged);
/// Current charge level as a percentage.
///
/// This would be equivalent to `energy / energyCapacity`.
/// This would be equivalent to @@energy / @@energyCapacity.
Q_PROPERTY(qreal percentage READ percentage NOTIFY percentageChanged);
/// If the power source is present in the bay or slot, useful for hot-removable batteries.
///
@ -115,7 +119,7 @@ class UPowerDevice: public QObject {
Q_PROPERTY(QString iconName READ iconName NOTIFY iconNameChanged);
/// If the device is a laptop battery or not. Use this to check if your device is a valid battery.
///
/// This will be equivalent to `type == Battery && powerSupply == true`.
/// This will be equivalent to @@type == Battery && @@powerSupply == true.
Q_PROPERTY(bool isLaptopBattery READ isLaptopBattery NOTIFY isLaptopBatteryChanged);
/// Native path of the device specific to your OS.
Q_PROPERTY(QString nativePath READ nativePath NOTIFY nativePathChanged);