poz/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 untrusted user: 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

8
src/core/desktopentry.hpp
View file

@ -27,7 +27,7 @@ class DesktopEntry: public QObject {
Q_PROPERTY(QString comment MEMBER mComment CONSTANT);
/// Name of the icon associated with this application. May be empty.
Q_PROPERTY(QString icon MEMBER mIcon CONSTANT);
/// The raw `Exec` string from the desktop entry. You probably want `execute()`.
/// The raw `Exec` string from the desktop entry. You probably want @@execute().
Q_PROPERTY(QString execString MEMBER mExecString CONSTANT);
/// The working directory to execute from.
Q_PROPERTY(QString workingDirectory MEMBER mWorkingDirectory CONSTANT);
@ -44,7 +44,7 @@ public:
void parseEntry(const QString& text);
/// Run the application. Currently ignores `runInTerminal` and field codes.
/// Run the application. Currently ignores @@runInTerminal and field codes.
Q_INVOKABLE void execute() const;
[[nodiscard]] bool isValid() const;
@ -81,7 +81,7 @@ class DesktopAction: public QObject {
Q_PROPERTY(QString id MEMBER mId CONSTANT);
Q_PROPERTY(QString name MEMBER mName CONSTANT);
Q_PROPERTY(QString icon MEMBER mIcon CONSTANT);
/// The raw `Exec` string from the desktop entry. You probably want `execute()`.
/// The raw `Exec` string from the desktop entry. You probably want @@execute().
Q_PROPERTY(QString execString MEMBER mExecString CONSTANT);
QML_ELEMENT;
QML_UNCREATABLE("DesktopAction instances must be retrieved from a DesktopEntry");
@ -92,7 +92,7 @@ public:
, entry(entry)
, mId(std::move(id)) {}
/// Run the application. Currently ignores `runInTerminal` and field codes.
/// Run the application. Currently ignores @@DesktopEntry.runInTerminal and field codes.
Q_INVOKABLE void execute() const;
private:

2
src/core/floatingwindow.hpp
View file

@ -17,7 +17,7 @@ public:
void setHeight(qint32 height) override;
};
///! Standard floating window.
///! Standard toplevel operating system window that looks like any other application.
class FloatingWindowInterface: public WindowInterface {
Q_OBJECT;
QML_NAMED_ELEMENT(FloatingWindow);

18
src/core/lazyloader.hpp
View file

@ -87,8 +87,8 @@
/// > meaning if you create all windows inside of lazy loaders, none of them will ever load.
class LazyLoader: public Reloadable {
Q_OBJECT;
/// The fully loaded item if the loader is `loading` or `active`, or `null`
/// if neither `loading` or `active`.
/// The fully loaded item if the loader is @@loading or @@active, or `null`
/// if neither @@loading nor @@active.
///
/// Note that the item is owned by the LazyLoader, and destroying the LazyLoader
/// will destroy the item.
@ -96,7 +96,7 @@ class LazyLoader: public Reloadable {
/// > [!WARNING] If you access the `item` of a loader that is currently loading,
/// > it will block as if you had set `active` to true immediately beforehand.
/// >
/// > You can instead set `loading` and listen to the `activeChanged` signal to
/// > You can instead set @@loading and listen to @@activeChanged(s) signal to
/// > ensure loading happens asynchronously.
Q_PROPERTY(QObject* item READ item NOTIFY itemChanged);
/// If the loader is actively loading.
@ -105,7 +105,7 @@ class LazyLoader: public Reloadable {
/// loading it asynchronously. If the component is already loaded, setting
/// this property has no effect.
///
/// See also: [activeAsync](#prop.activeAsync).
/// See also: @@activeAsync.
Q_PROPERTY(bool loading READ isLoading WRITE setLoading NOTIFY loadingChanged);
/// If the component is fully loaded.
///
@ -113,17 +113,17 @@ class LazyLoader: public Reloadable {
/// blocking the UI, and setting it to `false` will destroy the component, requiring
/// it to be loaded again.
///
/// See also: [activeAsync](#prop.activeAsync).
/// See also: @@activeAsync.
Q_PROPERTY(bool active READ isActive WRITE setActive NOTIFY activeChanged);
/// If the component is fully loaded.
///
/// Setting this property to true will asynchronously load the component similarly to
/// [loading](#prop.loading). Reading it or setting it to false will behanve
/// the same as [active](#prop.active).
/// @@loading. Reading it or setting it to false will behanve
/// the same as @@active.
Q_PROPERTY(bool activeAsync READ isActive WRITE setActiveAsync NOTIFY activeChanged);
/// The component to load. Mutually exclusive to `source`.
/// The component to load. Mutually exclusive to @@source.
Q_PROPERTY(QQmlComponent* component READ component WRITE setComponent NOTIFY componentChanged);
/// The URI to load the component from. Mutually exclusive to `component`.
/// The URI to load the component from. Mutually exclusive to @@component.
Q_PROPERTY(QString source READ source WRITE setSource NOTIFY sourceChanged);
Q_CLASSINFO("DefaultProperty", "component");
QML_ELEMENT;

2
src/core/model.hpp
View file

@ -27,7 +27,7 @@
/// property var foo: model[3]
/// ```
///
/// You can work around this limitation using the `values` property of the model to view it as a list.
/// You can work around this limitation using the @@values property of the model to view it as a list.
/// ```qml
/// // will update reactively
/// property var foo: model.values[3]

4
src/core/objectrepeater.hpp
View file

@ -11,7 +11,7 @@
#include "model.hpp"
///! A Repeater / for loop / map for non Item derived objects.
/// > [!ERROR] Removed in favor of QtQml.Models.Instantiator
/// > [!ERROR] Removed in favor of @@QtQml.Models.Instantiator
///
/// The ObjectRepeater creates instances of the provided delegate for every entry in the
/// given model, similarly to a @@QtQuick.Repeater but for non visual types.
@ -19,7 +19,7 @@ class ObjectRepeater: public ObjectModel<QObject> {
Q_OBJECT;
/// The model providing data to the ObjectRepeater.
///
/// Currently accepted model types are QML `list<T>` lists, javascript arrays,
/// Currently accepted model types are `list<T>` lists, javascript arrays,
/// and [QAbstractListModel] derived models, though only one column will be repeated
/// from the latter.
///

10
src/core/panelinterface.hpp
View file

@ -57,6 +57,8 @@ public:
qint32 mBottom = 0;
};
///! Panel exclusion mode
/// See @@PanelWindow.exclusionMode.
namespace ExclusionMode { // NOLINT
Q_NAMESPACE;
QML_ELEMENT;
@ -111,15 +113,19 @@ class PanelWindowInterface: public WindowInterface {
/// > [!INFO] Only applies to edges with anchors
Q_PROPERTY(Margins margins READ margins WRITE setMargins NOTIFY marginsChanged);
/// The amount of space reserved for the shell layer relative to its anchors.
/// Setting this property sets `exclusionMode` to `Normal`.
/// Setting this property sets @@exclusionMode to `ExclusionMode.Normal`.
///
/// > [!INFO] Either 1 or 3 anchors are required for the zone to take effect.
Q_PROPERTY(qint32 exclusiveZone READ exclusiveZone WRITE setExclusiveZone NOTIFY exclusiveZoneChanged);
/// Defaults to `ExclusionMode.Auto`.
Q_PROPERTY(ExclusionMode::Enum exclusionMode READ exclusionMode WRITE setExclusionMode NOTIFY exclusionModeChanged);
/// If the panel should render above standard windows. Defaults to true.
///
/// Note: On Wayland this property corrosponds to @@Quickshell.Wayland.WlrLayershell.layer.
Q_PROPERTY(bool aboveWindows READ aboveWindows WRITE setAboveWindows NOTIFY aboveWindowsChanged);
/// Defaults to false.
/// If the panel should accept keyboard focus. Defaults to false.
///
/// Note: On Wayland this property corrosponds to @@Quickshell.Wayland.WlrLayershell.keyboardFocus.
Q_PROPERTY(bool focusable READ focusable WRITE setFocusable NOTIFY focusableChanged);
// clang-format on
QSDOC_NAMED_ELEMENT(PanelWindow);

10
src/core/qmlglobal.hpp
View file

@ -112,22 +112,18 @@ public:
QQmlListProperty<QuickshellScreenInfo> screens();
/// Reload the shell from the [ShellRoot].
/// Reload the shell.
///
/// `hard` - perform a hard reload. If this is false, Quickshell will attempt to reuse windows
/// that already exist. If true windows will be recreated.
///
/// See [Reloadable] for more information on what can be reloaded and how.
///
/// [Reloadable]: ../reloadable
/// See @@Reloadable for more information on what can be reloaded and how.
Q_INVOKABLE void reload(bool hard);
/// Returns the string value of an environment variable or null if it is not set.
Q_INVOKABLE QVariant env(const QString& variable);
/// Returns a source string usable in an [Image] for a given system icon.
///
/// [Image]: https://doc.qt.io/qt-6/qml-qtquick-image.html
/// Returns a string usable for a @@QtQuick.Image.source for a given system icon.
Q_INVOKABLE static QString iconPath(const QString& icon);
[[nodiscard]] QString workingDirectory() const;

4
src/core/qsmenu.hpp
View file

@ -12,6 +12,8 @@
namespace qs::menu {
///! Button type associated with a QsMenuEntry.
/// See @@QsMenuEntry.buttonType.
class QsMenuButtonType: public QObject {
Q_OBJECT;
QML_ELEMENT;
@ -35,7 +37,7 @@ class QsMenuEntry: public QObject {
Q_OBJECT;
/// If this menu item should be rendered as a separator between other items.
///
/// No other properties have a meaningful value when `isSeparator` is true.
/// No other properties have a meaningful value when @@isSeparator is true.
Q_PROPERTY(bool isSeparator READ isSeparator NOTIFY isSeparatorChanged);
Q_PROPERTY(bool enabled READ enabled NOTIFY enabledChanged);
/// Text of the menu item.

15
src/core/region.hpp
View file

@ -9,7 +9,8 @@
#include <qtmetamacros.h>
#include <qtypes.h>
/// Shape of a Region.
///! Shape of a Region.
/// See @@Region.shape.
namespace RegionShape { // NOLINT
Q_NAMESPACE;
QML_ELEMENT;
@ -23,6 +24,7 @@ Q_ENUM_NS(Enum);
} // namespace RegionShape
///! Intersection strategy for Regions.
/// See @@Region.intersection.
namespace Intersection { // NOLINT
Q_NAMESPACE;
QML_ELEMENT;
@ -44,6 +46,7 @@ Q_ENUM_NS(Enum);
} // namespace Intersection
///! A composable region used as a mask.
/// See @@QsWindow.mask.
class PendingRegion: public QObject {
Q_OBJECT;
/// Defaults to `Rect`.
@ -52,16 +55,16 @@ class PendingRegion: public QObject {
Q_PROPERTY(Intersection::Enum intersection MEMBER mIntersection NOTIFY intersectionChanged);
/// The item that determines the geometry of the region.
/// `item` overrides `x`, `y`, `width` and `height`.
/// `item` overrides @@x, @@y, @@width and @@height.
Q_PROPERTY(QQuickItem* item MEMBER mItem WRITE setItem NOTIFY itemChanged);
/// Defaults to 0. Does nothing if `item` is set.
/// Defaults to 0. Does nothing if @@item is set.
Q_PROPERTY(qint32 x MEMBER mX NOTIFY xChanged);
/// Defaults to 0. Does nothing if `item` is set.
/// Defaults to 0. Does nothing if @@item is set.
Q_PROPERTY(qint32 y MEMBER mY NOTIFY yChanged);
/// Defaults to 0. Does nothing if `item` is set.
/// Defaults to 0. Does nothing if @@item is set.
Q_PROPERTY(qint32 width MEMBER mWidth NOTIFY widthChanged);
/// Defaults to 0. Does nothing if `item` is set.
/// Defaults to 0. Does nothing if @@item is set.
Q_PROPERTY(qint32 height MEMBER mHeight NOTIFY heightChanged);
/// Regions to apply on top of this region.

7
src/core/reload.hpp
View file

@ -25,7 +25,7 @@ class Reloadable
/// this object in the current revision, and facilitate smoother reloading.
///
/// Note that identifiers are scoped, and will try to do the right thing in context.
/// For example if you have a `Variants` wrapping an object with an identified element inside,
/// For example if you have a @@Variants wrapping an object with an identified element inside,
/// a scope is created at the variant level.
///
/// ```qml
@ -83,10 +83,9 @@ private:
};
///! Scope that propagates reloads to child items in order.
/// Convenience type equivalent to setting `reloadableId` on properties in a
/// QtObject instance.
/// Convenience type equivalent to setting @@Reloadable.reloadableId for all children.
///
/// Note that this does not work for visible `Item`s (all widgets).
/// Note that this does not work for visible @@QtQuick.Item$s (all widgets).
///
/// ```qml
/// ShellRoot {

14
src/core/retainable.hpp
View file

@ -12,11 +12,11 @@ class Retainable;
/// kept around (retained) after they would normally be destroyed, which
/// is especially useful for things like exit transitions.
///
/// An object that is retainable will have `Retainable` as an attached property.
/// An object that is retainable will have @@Retainable as an attached property.
/// All retainable objects will say that they are retainable on their respective
/// typeinfo pages.
///
/// > [!INFO] Working directly with Retainable is often overly complicated and
/// > [!INFO] Working directly with @@Retainable is often overly complicated and
/// > error prone. For this reason @@RetainableLock should
/// > usually be used instead.
class RetainableHook: public QObject {
@ -46,11 +46,11 @@ public:
/// > Using @@RetainableLock is recommended as it will help
/// > avoid this scenario and make misuse more obvious.
Q_INVOKABLE void lock();
/// Remove a lock on the object. See `lock()` for more information.
/// Remove a lock on the object. See @@lock() for more information.
Q_INVOKABLE void unlock();
/// Forcibly remove all locks, destroying the object.
///
/// `unlock()` should usually be preferred.
/// @@unlock() should usually be preferred.
Q_INVOKABLE void forceUnlock();
[[nodiscard]] bool isRetained() const;
@ -121,7 +121,7 @@ private:
/// ```
class RetainableLock: public QObject {
Q_OBJECT;
/// The object to lock. Must be [Retainable](../retainable).
/// The object to lock. Must be @@Retainable.
Q_PROPERTY(QObject* object READ object WRITE setObject NOTIFY objectChanged);
/// If the object should be locked.
Q_PROPERTY(bool locked READ locked WRITE setLocked NOTIFY lockedChanged);
@ -143,9 +143,9 @@ public:
[[nodiscard]] bool isRetained() const;
signals:
/// Rebroadcast of the object's `dropped()` signal.
/// Rebroadcast of the object's @@Retainable.dropped(s).
void dropped();
/// Rebroadcast of the object's `aboutToDestroy()` signal.
/// Rebroadcast of the object's @@Retainable.aboutToDestroy(s).
void aboutToDestroy();
void retainedChanged();

2
src/core/transformwatcher.hpp
View file

@ -13,7 +13,7 @@ class TestTransformWatcher;
///! Monitor of all geometry changes between two objects.
/// The TransformWatcher monitors all properties that affect the geometry
/// of two `Item`s relative to eachother.
/// of two @@QtQuick.Item$s relative to eachother.
///
/// > [!INFO] The algorithm responsible for determining the relationship
/// > between `a` and `b` is biased towards `a` being a parent of `b`,

8
src/core/variants.hpp
View file

@ -28,11 +28,11 @@ public:
///! Creates instances of a component based on a given model.
/// Creates and destroys instances of the given component when the given property changes.
///
/// `Variants` is similar to @@QtQuick.Repeater except it is for *non Item* objects, and acts as
/// `Variants` is similar to @@QtQuick.Repeater except it is for *non @@QtQuick.Item$* objects, and acts as
/// a reload scope.
///
/// Each non duplicate value passed to [model](#prop.model) will create a new instance of
/// [delegate](#prop.delegate) with its `modelData` property set to that value.
/// Each non duplicate value passed to @@model will create a new instance of
/// @@delegate with a `modelData` property set to that value.
///
/// See @@Quickshell.screens for an example of using `Variants` to create copies of a window per
/// screen.
@ -44,7 +44,7 @@ class Variants: public Reloadable {
/// The component to create instances of.
///
/// The delegate should define a `modelData` property that will be popuplated with a value
/// from the [model](#prop.model).
/// from the @@model.
Q_PROPERTY(QQmlComponent* delegate MEMBER mDelegate);
/// The list of sets of properties to create instances with.
/// Each set creates an instance of the component, which are updated when the input sets update.