proofreading and tweaks

This commit is contained in:
starchglazer 2025-06-18 21:17:00 +08:00 committed by outfoxxed
parent 58eba03e3f
commit 403dc6d424
Signed by: outfoxxed
GPG key ID: 4C88A185FB89301E
7 changed files with 206 additions and 194 deletions

View file

@ -6,12 +6,15 @@ If you plan to distribute your configuration to a lot of users, you should keep
a couple things in mind:
### API Breaks
Quickshell will have API breaks in future versions.
You should have a way to track specific revisions with your distribution
to avoid breakage if a user updates quickshell before you can update your configuration.
As Quickshell is still in a somewhat early stage of development, Quickshell will
have API breaks for future versions.
With Nix this should be as simple as tracking a specific revision.
For Arch, and other distributions without a mechanism to do this, you may
You should have a way to track specific revisions to avoid breakage if a user
updates Quickshell before you can update your configuration.
With Nix, this should be as simple as tracking a specific revision.
For Arch, or any other distributions without a mechanism to do this, you may
want to include a package that builds a specific Quickshell revision with
your configuration.
@ -20,13 +23,14 @@ Quickshell can load configurations from a number of different paths.
The ideal path depends on how you distribute your config.
#### As dotfiles
If you distribute your config as a set of dotfiles, you should place
the config in `$XDG_CONFIG_HOME/quickshell/<name>` (usually `~/.config/quickshell/<name>`).
Named configurations can be used in the quickshell command by specifying `--config` or `-c`
(`qs -c <name>`).
If you distribute your config as a set of dotfiles, you should place it in
`$XDG_CONFIG_HOME/quickshell/<name>` (usually `~/.config/quickshell/<name>`).
You should not use the bare `$XDG_CONFIG_HOME/quickshell` directory as that will
make it harder for users to have any other configuration.
You should name your config and refrain from using the bare `$XDG_CONFIG_HOME/quickshell`
directory, as that will make it harder for users to have any other configuration.
Any directory in the `$XDG_CONFIG_HOME/quickshell` can be used using the Quickshell command
by specifying `--config` or `-c`, like so: `qs -c <name>`.
#### As a package
Some configurations are distributed as distro packages. These packages should use a

View file

@ -3,10 +3,13 @@ title: "FAQ"
description: "Frequently Asked Questions"
index: 1000
---
This page is being actively expanded as common questions come up again.
Make sure to also read the [Item Size and Position](/docs/guide/size-position) and
[QML Language](/docs/guide/qml-language) pages for questions related to
> [!NOTE]
> This page is being actively expanded upon as more common questions come up.
>
> Make sure to also read the [Item Size and Position](/docs/guide/size-position) and
> [QML Language](/docs/guide/qml-language) pages for questions related to
> item sizing/positioning and QML in general.
## Misc
@ -16,7 +19,7 @@ span the APIs exposed by Quickshell, as well as best practice across all
APIs, but will not change the language syntax or anything exposed by Qt.
Most changes will be relatively trivial, though you may have to make the same
trivial change a great number of times if you have a large configuration.
trivial change a considerable amount of times if you have a large configuration.
Migration guides will be provided between each release version.
@ -27,7 +30,7 @@ single process.
## How do I
### Make a rounded window
Rounded windows are simply transparent square ones with a rounded rectangle
Rounded windows are simply transparent, square windows, with a rounded rectangle
inside of them.
```qml
@ -46,11 +49,11 @@ inside of them.
### Make a list of widgets
If you have a short list of items to display, such as a list of active music
players or system tray items, you want a @@QtQuick.Repeater, usually combined
with a @@QtQuick.Layouts.RowLayout or @@QtQuick.Layouts.ColumnLayout.
players or system tray items, you want a @@QtQuick.Repeater, which is
usually combined with a @@QtQuick.Layouts.RowLayout or @@QtQuick.Layouts.ColumnLayout.
If you have a longer list, such as a list of entries in an application launcher,
or a list that needs to scroll, you may want a @@QtQuick.ListView instead.
If you have a longer list, such as a list of entries in an application launcher
or a list that needs to be scrolled, you want a @@QtQuick.ListView instead.
### Run a program or script
Use @@Quickshell.Io.Process.
@ -63,10 +66,15 @@ e.g. a command that listens to window manager IPC commands, use
@@Quickshell.Io.SplitParser to return each datum as it arrives.
### Show widgets conditionally
The @@QtQuick.Item.visible property can be used to change the visibility of an
Item conditionally, as well as Loaders.
Conditionally showing widgets can be done in two ways, simply using the @@QtQuick.Item.visible property,
or by using a @@QtQuick.Loader.
Depending on your use case, both the @@QtQuick.Loader and the @@QtQuick.Item.visible property
may make sense at equal complexity. If you want to unload a widget tree to save memory or
speed up load times, then you should use Loaders.
Note that you can also change out a Loader's component conditionally:
Note that you can change out a loader's component conditionally:
```qml
@@QtQuick.Loader {
readonly property Component thing1: ...
@ -77,9 +85,9 @@ Note that you can change out a loader's component conditionally:
```
### Round an image
The easiest way to round an image is with @@Quickshell.Widgets.ClippingWrapperRectangle.
ClippingWrapperRectangle is a [MarginWrapper] component, which will attempt to match
the size of its contained item.
The easiest way to round an image is with @@Quickshell.Widgets.ClippingWrapperRectangle,
which is a [MarginWrapper] component. This component will attempt to match the size of
its contained item.
```qml
@@Quickshell.Widgets.ClippingWrapperRectangle {
@ -97,7 +105,7 @@ the size of its contained item.
### Reference images and resources
By default, paths passed to components such as @@QtQuick.Image or
@@Quickshell.Io.FileView as strings are relative to Quickshell's working
directory. Usually this is not the desired behavior.
directory. Usually, this is not the desired behavior.
To get a file path relative to the current QML file, you can use @@QtQml.Qt.resolvedUrl().
@ -106,12 +114,12 @@ you can use @@Quickshell.Quickshell.cachePath(), @@Quickshell.Quickshell.dataPat
@@Quickshell.Quickshell.statePath(),
### Add a drop-shadow
If you want a *rectangular*, *round rectangular*, or *circular* drop shadow,
use @@QtQuick.Effects.RectangularShadow.
For any other shape, you will have to use a @@QtQuick.Effects.MultiEffect.
Use @@QtQuick.Effects.RectangularShadow if you want a *rectangular*, *round rectangular*,
or *circular* drop shadow.
When using a MultiEffect, set @@QtQuick.Effects.MultiEffect.shadowEnabled,
as well as its other shadow and blur related properties.
For any other shape, you will have to use a @@QtQuick.Effects.MultiEffect and set
@@QtQuick.Effects.MultiEffect.shadowEnabled, as well as its other shadow and blur
related properties.
### Get rid of the purple/black icons
The @@Quickshell.Quickshell.iconPath() function has three variants:
@ -127,19 +135,20 @@ however you can implement your own using @@Quickshell.Io.Socket or @@Quickshell.
which can be used to parse and send IPC messages.
### Open/close windows with commands
Quickshell doesn't come with a command to open or close a window, however you can
make your own using @@Quickshell.Io.IpcHandler, which allows you to call functions
Quickshell doesn't come with a command to open or close a window; however, you can
make your own using @@Quickshell.Io.IpcHandler, allowing you to call functions
inside of Quickshell with a command. Said functions can change the
@@Quickshell.QsWindow.visible property of a window, or load/unload it using a
@@Quickshell.LazyLoader.
### Reduce memory usage
The main thing you can do to reduce the memory usage of a given configuration
is to use loaders. Loaders can be used to create objects only when needed,
and destroy them when not needed.
is to use Loaders.
- Use @@QtQuick.Loader when the component being loaded inherits from @@QtQuick.Item.
- Use @@Quickshell.LazyLoader in other cases.
Loaders can be used to create objects only when needed, and destroy them when not needed.
@@QtQuick.Loader should be used if the component being loaded inherits from @@QtQuick.Item,
otherwise, a @@Quickshell.LazyLoader should be used.
## Something is broken
@ -153,9 +162,11 @@ if the only border property you wanted to set was radius.
### My window should not be opaque
If a window is created with an opaque background color, Quickshell will use
a window surface format that is opaque, which reduces the amount of processing
the gpu must do to draw it. If you change the background color of your window
between opaque and transparent colors, this may affect you.
a window surface format that is opaque. This is done to reduce the amount of
processing the gpu must do to draw it.
To tell Quickshell to always create a window capable of showing transparency,
If you change the background color of your window between opaque and transparent colors,
then this may affect you.
To tell Quickshell that you want to create a window capable of showing transparency,
use @@Quickshell.QsWindow.surfaceFormat to set `opaque` to false.

View file

@ -6,12 +6,12 @@ index: -1
See the [Installation and Setup](/docs/guide/install-setup) page to get started.
To write a Quickshell config, start by following the
[Guided Introduction](/docs/guide/introduction) and skimming the
[Guided Introduction](/docs/guide/introduction), and skimming the
[QML Language Overview](/docs/guide/qml-language).
Before continuing on your own, read the [Item Size and Position](/docs/guide/size-position)
page to learn how to lay out elements in QML. This is significantly different
from many other layout systems such as CSS.
After that, read the [Item Size and Position](/docs/guide/size-position) page before
continuing on your own to learn how to lay out elements in QML. Laying out elements
in QML is significantly different from many other layout systems such as CSS.
To learn what features Quickshell offers and how to use them, use the
left sidebar and click through the `Quickshell Types` pages. The sidebar

View file

@ -8,7 +8,8 @@ index: 0
## Installation
All packages currently track quickshell's master branch. This may change in the future.
Since Quickshell 0.1, you can now choose whether to install by tracking the master branch,
or install by latest release.
Note that you may want to install some additional packages (names vary by distro):
- `qtsvg`: support for SVG image loading (bundled with most packages)
@ -17,12 +18,13 @@ Note that you may want to install some additional packages (names vary by distro
- `qt5compat`: extra visual effects, notably gaussian blur. @@QtQuick.Effects.MultiEffect is usually preferable
### Nix
Quickshell releases are packaged in nixpkgs as `quickshell`.
The Quickshell repo has an embedded flake. You can use either of the two:
The Quickshell repo also has an embedded flake.
You can use either `git+https://git.outfoxxed.me/outfoxxed/quickshell`
or `github:quickshell-mirror/quickshell`. Use `?ref=` to specify a tag
if you want a tagged release.
- `git+https://git.outfoxxed.me/outfoxxed/quickshell`
- `github:quickshell-mirror/quickshell`
> [!NOTE]
> You can use `?ref=` to specify a tag if you want a tagged release.
```nix
{
@ -41,20 +43,19 @@ if you want a tagged release.
}
```
The package is available as `quickshell.packages.<system>.default`, which you can add to
`environment.systemPackages` or `home.packages` if you use home-manager.
The package is available as `quickshell.packages.<system>.default`, which can be added to
your `environment.systemPackages` or `home.packages` if you use home-manager.
### Arch
Quickshell is available from the aur under
the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release,
or the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package
which tracks the master branch.
Quickshell is available from the aur under:
- the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release
- the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package that tracks the master branch
> [!WARNING]
> When using an AUR package, quickshell may break any time Qt is updated.
> When using an AUR package, Quickshell may break whenever Qt is updated.
> The AUR gives us no way to actually fix this, but Quickshell will attempt to
> warn you if it detects a breakage when updating. If warned of a breakage,
> please reinstall the package
> please reinstall the package.
Install using the command below:
```sh
@ -65,9 +66,9 @@ yay -S quickshell-git
(or your AUR helper of choice)
### Fedora
Quickshell is available from the [errornointernet/quickshell] COPR, as either
`quickshell` which tracks the latest release or `quickshell-git` which tracks
the master branch.
Quickshell is available from the [errornointernet/quickshell] COPR, as either:
- `quickshell` that tracks the latest release
- `quickshell-git` that tracks the master branch
[errornointernet/quickshell]: https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell
@ -90,7 +91,8 @@ Quickshell's source repository works as a channel. Add the following to your cha
(branch "master"))
```
Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git` to your system or home definition.
Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git`
to your system or home definition.
You can also clone the repository and use `guix shell -f quickshell.scm` to try out the package.
@ -172,13 +174,13 @@ We are aware of the following issues:
- Qmlls does not work well when a file is not correctly structured.
This means that completions and lints won't work unless braces are closed
correctly and such.
- Qmlls cannot handle quickshell's singletons. This means you won't see
completions, and usages of singleton members may show a warning.
We're still investigating this problem and how to fix it.
- Qmlls cannot handle Quickshell's Singleton, which means you won't see completions,
and usages of Singleton members may show a warning. We're still investigating
this problem and how to fix it.
- The LSP cannot provide any documentation for Quickshell types.
Keeping in mind the above caveats, qmlls should be able to guide you towards
more correct code should you chose to use it.
Keeping in mind the above caveats, qmlls should be able to guide you towards a
more correct code should you choose to use it.
> [!NOTE]
> Nix users should note that qmlls will not be able to pick up qml modules

View file

@ -7,25 +7,28 @@ introduce you to all the basic concepts involved. You can use the
[QML Language Reference](/docs/guide/qml-language) to learn about the syntax
of the QML language.
Note that all the <a>Green Links</a> in code blocks will take you to the documentation
for their respective types.
> [!NOTE]
> All the <a>Green Links</a> in code blocks will take you to the documentation,
> listing their respective types.
## Config Files
Quickshell searches the `quickshell` subfolder of every XDG standard config path
for configs. Usually this is `~/.config/quickshell`.
for configs. Usually, this is `~/.config/quickshell`.
Each named subfolder containing a `shell.qml` file is considered to be a config.
If the base `quickshell` folder contains a shell.qml file, subfolders will not be
considered.
If the base `quickshell` folder contains a `shell.qml` file, subfolders will
not be considered.
A specific config can be picked using the `--config` or `-c` argument to Quickshell.
A specific configuration can be picked using the `--config` or `-c` argument to Quickshell.
Configs at other paths, including raw qml files can be run with `--path` or `-p`.
Configs located at other paths outside XDG standard, including raw qml files,
can be run with `--path` or `-p`.
## Creating Windows
Quickshell has two main window types available, @@Quickshell.PanelWindow for bars
and widgets, and @@Quickshell.FloatingWindow for standard desktop windows.
Quickshell has two main window types available:
- @@Quickshell.PanelWindow for bars, widgets, and overlays
- @@Quickshell.FloatingWindow for standard desktop windows
We'll start with an example:
@ -52,14 +55,15 @@ import QtQuick // for Text
```
The above example creates a bar/panel on your currently focused monitor with
a centered piece of [text](https://doc.qt.io/qt-6/qml-qtquick-text.html). It will also reserve space for itself on your monitor.
a centered piece of [text](https://doc.qt.io/qt-6/qml-qtquick-text.html).
It will also reserve space for itself on your monitor.
More information about available properties is available in the [type reference](/docs/types/Quickshell/PanelWindow).
## Running a process
Now that we have a piece of text, what if it did something useful?
To start with lets make a clock. To get the time we'll use the `date` command.
To start with, let's make a clock. To get the time, we'll use the `date` command.
> [!note/Note]
> Quickshell can do more than just run processes. Read until the end for more information.
@ -173,13 +177,12 @@ import QtQuick
## Reusable components
If you have multiple monitors you might have noticed that your bar
If you have multiple monitors, you might have noticed that your bar
is only on one of them. If not, you'll still want to **follow this section
to make sure your bar doesn't disappear if your monitor disconnects**.
We can use a @@Quickshell.Variants object to create instances of _non widget items_.
(See @@QtQuick.Repeater for doing
something similar with visual items.)
We can use a @@Quickshell.Variants object to create instances of _non-widget items_.
(See @@QtQuick.Repeater for doing something similar with visual items.)
The @@Quickshell.Variants type creates instances of a @@QtQml.Component based on
a data model you supply. (A component is a re-usable tree of objects.)
@ -248,12 +251,11 @@ import QtQuick
</span>
With this example, bars will be created and destroyed as you plug and unplug them,
due to the reactive nature of the
@@Quickshell.Quickshell.screens property.
due to the reactive nature of the @@Quickshell.Quickshell.screens property.
(See: [Reactive Bindings](/docs/configuration/qml-overview/#reactive-bindings).)
Now there's an important problem you might have noticed: when the window
is created multiple times we also make a new Process and Timer, which makes the
is created multiple times, we also make a new Process and Timer, which makes the
bar less efficient than it could be. We can fix this by moving the
Process and Timer outside of the window using @@Quickshell.Scope.
@ -309,11 +311,10 @@ import QtQuick
}
```
However there is a problem with naively moving the Process and Timer
out of the component.
However, there is a problem with naively moving the Process and Timer out of the component.
_What about the `clock` that the process references?_
If you run the above example you'll see something like this in the console every second:
If you run the above example, you'll see something like this in the console every second:
```
WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
@ -394,8 +395,8 @@ import QtQuick
}
```
Now we've fixed the problem so there's nothing actually wrong with the
above code, but we can make it more concise:
Now we've fixed the problem, so there's nothing actually wrong with the
above code; however, we can make it more concise:
1. `Component`s can be defined implicitly, meaning we can remove the
component wrapping the window and place the window directly into the
@ -532,11 +533,11 @@ We can bring in other folders as well using
[import statements](/docs/configuration/qml-overview/#explicit-imports).
Now what about breaking out the clock? This is a bit more complex because
the clock component in the bar, as well as the process and timer that
make up the actual clock, need to be dealt with.
the clock component in the bar need to be dealt with, as well as the necessary
processes that make up the actual clock.
To start with, we can move the clock widget to a new file. For now it's just a
single @@QtQuick.Text object but the same concepts apply regardless of complexity.
To start with, we can move the clock widget to a new file. For now, it's just a
single @@QtQuick.Text object, but the same concepts apply regardless of complexity.
```qml
// ClockWidget.qml
@ -683,7 +684,7 @@ any scope.
```qml
// Time.qml
// with this line our type becomes a singleton
// with this line our type becomes a Singleton
pragma Singleton
import Quickshell

View file

@ -5,7 +5,7 @@ index: 10
import Collapsible from "@components/Collapsible.astro";
Quickshell is configured using the Qt Modeling Language, or QML.
This page explains what you need to know about QML to start using quickshell.
This page explains what you need to know about QML to start using Quickshell.
<span class="small">
See also: [Qt Documentation: QML
@ -129,8 +129,9 @@ import "<filename>" as <Namespace>
- `Namespace` is the namespace functions and variables from the javascript
file will be made available under.
Note: All _Module_ and _Namespace_ names must start with an uppercase letter.
Attempting to use a lowercase namespace is an error.
> [!NOTE]
> All _Module_ and _Namespace_ names must start with an uppercase letter.
> Attempting to use a lowercase namespace will result in an error.
##### Examples
@ -142,21 +143,8 @@ import QtQuick.Layouts 6.0 as L
import "jsfile.js" as JsFile
```
<Collapsible title="When no module version">
By default, when no module version is requested, the QML engine will pick
the latest available version of the module. Requesting a specific version
can help ensure you get a specific version of the module's types, and as a
result your code doesn't break across Qt or quickshell updates.
While Qt's types usually don't majorly change across versions, quickshell's
are much more likely to break. To put off dealing with the breakage we suggest
specifying a version at least when importing quickshell modules.
</Collapsible>
<span class="small">
[Qt Documentation: Import
See also: [Qt Documentation: Import
syntax](https://doc.qt.io/qt-6/qtqml-syntax-imports.html)
</span>
@ -171,7 +159,7 @@ root
|-shell.qml
```
In this example, `MyButton` will automatically be imported as a type usable from shell.qml
In this example, `MyButton` will automatically be imported as a type usable from `shell.qml`
or any other neighboring files.
### Objects
@ -195,13 +183,14 @@ by looking it up in the [Type Reference](/docs/types/).
#### Properties
Every object may have any number of property assignments (only one per specific property).
Each assignment binds the named property to the given expression.
Every object may have any number of property assignment, with only one assignment per specific property.
Each assignment binds the named property to the given value/expression.
##### Property bindings
Expressions are snippets of javascript code assigned to a property. The last (or only) line
can be the return value, or an explicit return statement (multiline expressions only) can be used.
Expressions are snippets of javascript code assigned to a property.
The last line can serve as the return value.
Alternatively, an explicit return statement can also be used for multi-line expressions.
```qml
@@QtQuick.Item {
@ -226,16 +215,14 @@ can be the return value, or an explicit return statement (multiline expressions
}
```
Semicolons are optional and allowed on any line of a single or multiline expression,
Semicolons, while optional, can be included on any line of a single or multi-line expression,
including the last line.
All property bindings are [_reactive_](#reactive-bindings), which means when any property the expression depends
on is updated, the expression is re-evaluated and the property is updated.
All property bindings are [_reactive_](#reactive-bindings). This means that whenever any
property the expression depends on is updated, the expression is re-evaluated and the property
is updated accordingly.
<span class="small">See: [Reactive bindings](#reactive-bindings)</span>
Note that it is an error to try to assign to a property that does not exist.
(See: [property definitions](#property-definitions))
<span class="small">See also [Reactive bindings](#reactive-bindings) for more information</span>
##### Property definitions
@ -269,6 +256,8 @@ Properties can be defined inside of objects with the following syntax:
Defining a property with the same name as one provided by the current object will override
the property of the type it is derived from in the current context.
Trying to assign to a property that does not exist is an error.
##### The default property
Types can have a _default property_ which must accept either an object or a list of objects.
@ -307,7 +296,8 @@ would put a single object in:
##### The `id` property
Every object has a special property called `id` that can be assigned to give
the object a name it can be referred to throughout the current file. The id must be lowercase.
the object a name that it can be referred to throughout the current file.
The id must be lowercase.
```qml
@@QtQuick.Layouts.ColumnLayout {
@ -323,7 +313,7 @@ the object a name it can be referred to throughout the current file. The id must
}
```
<Collapsible title="The `id` property compared to normal properties">
<Collapsible title="How is the `id` property different from normal properties?">
The `id` property isn't really a property, and doesn't do anything other than
expose the object to the current file. It is only called a property because it
@ -385,14 +375,14 @@ all other objects, you should refer to them by id when accessing properties.
```
<span class="small">
[Qt Documentation: Scope and Naming
See also: [Qt Documentation: Scope and Naming
Resolution](https://doc.qt.io/qt-6/qtqml-documents-scope.html)
</span>
#### Functions
Functions in QML can be declared everywhere [properties](#properties) can, and follow
the same [scoping rules](#property-access-scopes).
Functions in QML can be declared everywhere [properties](#properties),
and follow the same [scoping rules](#property-access-scopes).
Function definition syntax:
@ -426,7 +416,7 @@ every expression depending on the function is also re-evaluated.
```
In this example, every time the button is clicked, the label's count increases
by one, as `clicks` is changed, which triggers a re-evaluation of `text` through
by one as the value of `clicks` is changed, triggering a re-evaluation of `text` through
`makeClicksLabel`.
##### Lambdas
@ -497,7 +487,7 @@ They can be declared everywhere [properties](#properties) and [functions](#funct
can, and follow the same [scoping rules](#property-access-scopes).
<span class="small">
[Qt Documentation: Signal and Handler Event
See also: [Qt Documentation: Signal and Handler Event
System](https://doc.qt.io/qt-6/qtqml-syntax-signals.html)
</span>
@ -541,24 +531,24 @@ or signal when the signal is emitted.
<span class="small">
`Component.onCompleted` will be addressed later in [Attached
Properties](#attached-properties) but for now just know that it runs
Properties](#attached-properties), but for now, just know that it runs
immediately once the object is fully initialized.
</span>
When the button is clicked, the button emits the @@QtQuick.Controls.Button.clicked(s)
signal which we connected to `updateText`. The signal then invokes `updateText`
signal, which we connected to `updateText`. The signal then invokes `updateText`,
which updates the counter and the text on the label.
##### Signal handlers
Signal handlers are a more concise way to make a connections, and prior examples have used them.
Signal handlers are a more concise way to make connections, and prior examples have used them.
When creating an object, for every signal present on its type there is a corresponding `on<Signal>`
property implicitly defined which can be set to a function. (Note that the first letter of the
signal's name it capitalized.)
When creating an object, there is a corresponding `on<Signal>` property implicitly defined for every
signal present on its type, which can be set to a function. Do note that the first letter of the
signal's name is capitalized.
Below is the same example as in [Making Connections](#making-connections),
this time using the implicit signal handler property to handle @@QtQuick.Controls.Button.clicked(s).
Below is the same example from [Making Connections](#making-connections), but this time,
using the implicit signal handler property to handle @@QtQuick.Controls.Button.clicked(s).
```qml
@@QtQuick.Layouts.ColumnLayout {
@ -583,10 +573,10 @@ this time using the implicit signal handler property to handle @@QtQuick.Control
##### Indirect signal handlers
When it is not possible or not convenient to directly define a signal handler, before resorting
to `.connect`ing the properties, a @@QtQml.Connections object can be used to access them.
Signal handlers should be preferred, but there are times where it is not possible or inconvenient to define one.
In those cases, before resorting to `.connect`ing the properties, a @@QtQml.Connections object can be used to access them.
This is especially useful to connect to signals of singletons.
This is especially useful to connect to signals of a Singleton.
```qml
@@QtQuick.Item {
@ -610,8 +600,8 @@ This is especially useful to connect to signals of singletons.
Every property has an associated signal, which powers QML's [reactive bindings](#reactive-bindings).
The signal is named `<propertyname>Changed` and works exactly the same as any other signal.
Whenever the property is re-evaluated, its change signal is emitted. This is used internally
to update dependent properties, but can be directly used, usually with a signal handler.
When it is not possible or inconvenient to directly define a signal handler, before resorting
to `.connect`ing the properties, a @@QtQml.Connections object can be used to access them.
```qml
@@QtQuick.Layouts.ColumnLayout {
@ -634,10 +624,10 @@ to update dependent properties, but can be directly used, usually with a signal
}
```
In this example we listen for changes to the @@QtQuick.Controls.CheckBox.checkState property of the CheckBox
In this example, we listen for changes to the @@QtQuick.Controls.CheckBox.checkState property of the CheckBox
using its change signal, `checkStateChanged` with the signal handler `onCheckStateChanged`.
Since text is also a property we can do the same thing more concisely:
Since text is also a property, we can do the same thing more concisely:
```qml
@@QtQuick.Layouts.ColumnLayout {
@ -690,6 +680,8 @@ properties, functions and signals.
A good example is the @@QtQml.Component type,
which is attached to every object and often used to run code when an object initializes.
In this example, the text property is set inside the `Component.onCompleted` attached signal handler.
```qml
@@QtQuick.Text {
Component.onCompleted: {
@ -698,12 +690,10 @@ which is attached to every object and often used to run code when an object init
}
```
In this example, the text property is set inside the `Component.onCompleted` attached signal handler.
#### Creating types
Every QML file with an uppercase name is implicitly a type, and can be used from
neighboring files or imported (See [Imports](#imports).)
neighboring files or imported. (See [Imports](#imports).)
A type definition is just a normal object. All properties defined for the root object
are visible to the consumer of the type. Objects identified by [id properties](#the-id-property)
@ -776,11 +766,10 @@ Example of an inline component:
##### Singletons
QML Types can be easily made into a singleton, meaning there is only one instance
of the type.
QML Types can be easily made into a Singleton, meaning there is only one instance of the type.
To make a type a singleton, put `pragma Singleton` at the top of the file.
To ensure it behaves correctly with quickshell you should also make
To make a type of a Singleton, put `pragma Singleton` at the top of the file.
To ensure it behaves correctly with Quickshell, you should also make the
@@Quickshell.Singleton the root item of your type.
```qml
@ -792,7 +781,7 @@ import ...
}
```
once a type is a singleton, its members can be accessed by name from neighboring
Once a type is a Singleton, its members can be accessed by name from neighboring
files.
## Concepts
@ -815,7 +804,7 @@ Bindings can be created in two different ways:
##### Automatic bindings
A reactive binding occurs automatically when you use one or more properties in the definition
of another property. .
of another property.
```qml
@@QtQuick.Item {
@ -851,7 +840,7 @@ as assignments to properties do not create binding.
##### Manual bindings
Sometimes (not often) you need to create a binding inside of a function, signal, or expression.
Occasionally, a binding might need to be created inside of a function, signal, or expression.
If you need to change or attach a binding at runtime, the `Qt.binding` function can be used to
create one.
@ -906,11 +895,10 @@ it will not be updated further by the binding.
### Lazy loading
Often not all of your interface needs to load immediately. By default the QML
engine initializes every object in the scene before showing anything onscreen.
For parts of the interface you don't need to be immediately visible, load them
asynchronously using a @@Quickshell.LazyLoader.
See its documentation for more information.
Often, not all of your interface needs to load immediately. By default, the QML engine
initializes every object in the scene before showing anything onscreen. For parts of
the interface you don't need to be immediately visible, load them asynchronously using
a @@Quickshell.LazyLoader. See its documentation for more information.
#### Components

View file

@ -3,40 +3,43 @@ title: "Item Size and Position"
index: 2
---
> [!TIP]
> Read the entire page, understanding this is critical to building a well designed shell.
> Read the entire page, as understanding this is critical to building a well designed shell.
@@QtQuick.Item has two sets of size properties, actual size (@@QtQuick.Item.width and @@QtQuick.Item.height)
and implicit / desired (@@QtQuick.Item.implicitWidth and @@QtQuick.Item.implicitHeight).
An @@QtQuick.Item (and its subclasses) has two sets of size properties:
- actual size (@@QtQuick.Item.width and @@QtQuick.Item.height)
- implicit/desired size (@@QtQuick.Item.implicitWidth and @@QtQuick.Item.implicitHeight)
Container items, such as layouts and wrappers, use the implicit size of their children to determine
their own implicit size, and their actual size to detetermine the actual size of their children.
If managed by a container, an Item should not set its own size, and should instead allow
the container to determine it based on its implicit size.
Container items, such as layouts and wrappers, use the implicit size of their children
to determine their own implicit size. They use their actual size to determine the sizes
of their children.
Put simply, implicit size should flow from children to parents, while actual size should flow from
parent to children.
If an Item is managed by a container, it should not set its own size. Instead, it should
allow the container to determine its size based on its implicit size.
In addition to size, Items also have position properties (@@QtQuick.Item.x and @@QtQuick.Item.y).
Similarly to actual size, (actual) position should not be set directly if your item is managed
by a container, though there is no such thing as implicit position.
In other words, implicit size should flow from children to parent, while actual size
should flow from parent to children.
In addition to size, Items also have positional properties (@@QtQuick.Item.x and @@QtQuick.Item.y).
Similar to actual size, the actual position should not be set directly if the item is managed by
a container, though there is no such thing as implicit position.
> [!WARNING]
> Many QtQuick Items have *zero size* by default (both implicit and actual).
>
> An invisible zero sized item (usually a custom container without implicit size set)
> An invisible, zero-sized item, which is usually a custom container without implicit size set,
> is a common bug and often manifests as an item being laid out as if it took no space.
>
> Quickshell will attempt to detect zero sized items when a window is initially made visible
> and log a warning, but it cannot detect all cases. Please be aware these exist.
> Quickshell will attempt to detect zero-sized items when a window is initially made visible
> and log a warning, but it cannot detect all cases. Please be aware that these exist.
## Container Items
Below is an example container which adds a margin to a rectangle, and interacts properly
Below is an example container that adds a margin to its child rectangle and interacts properly
with other container types.
```qml
@@QtQuick.Item {
property real margin: 5
// Set the implicit size of the containing item to the size of
// the contained item, plus the margin on each side.
implicitWidth: child.implicitWidth + margin * 2
@ -53,7 +56,7 @@ with other container types.
y: parent.margin
width: parent.width - parent.margin * 2
height: parent.height - parent.margin * 2
// The child's implicit / desired size, which will be respected
// by the container item as long as it is not constrained
// or stretched.
@ -85,7 +88,10 @@ to control the child item's actual size and position.
@@QtQuick.Binding { wrapper.child.height: wrapper.height - wrapper.margin * 2 }
}
```
Note: @@Quickshell.Widgets.WrapperItem is a builtin component that adds margins similarly to this.
> [!TIP]
> Quickshell has a builtin component @@Quickshell.Widgets.WrapperItem
> that adds margins similar to the behavior above.
### Reducing boilerplate with Anchors
We can reduce the amount of boilerplate we have to write using
@ -99,7 +105,7 @@ position and size directly. A similar change can be made to the `Binding` exampl
```qml
@@QtQuick.Item {
property real margin: 5
implicitWidth: child.implicitWidth + margin * 2
implicitHeight: child.implicitHeight + margin * 2
@ -110,7 +116,7 @@ position and size directly. A similar change can be made to the `Binding` exampl
anchors.fill: parent
// Add a margin to all anchored sides.
anchors.margins: parent.margin
implicitWidth: 50
implicitHeight: 50
}
@ -125,7 +131,7 @@ to determine the size of a child item, such as in the example below:
@@QtQuick.Item {
implicitWidth: childrenRect.width
implicitHeight: childrenRect.height
@@QtQuick.Rectangle {
anchors.fill: parent
@ -139,11 +145,11 @@ While the snippet above might look like it should work, it is actually hiding a
As stated at the top of the page, an item's implicit size should be used to determine
its parent's implicit size, and the parent's actual size should be used to determine
the child's actual size. **`childrenRect` breaks this pattern.**
the child's actual size. The **`childrenRect` breaks this pattern.**
`childrenRect` encompasses the geometry of all child items, meaning their *actual* geometry,
not their *implicit* geometry. This results in the container item's size having an indirect
dependency on itself, in what is known as a *binding loop*.
The `childrenRect` property represents the *actual* geometry of all child items, not their
*implicit* geometry. This results in the container item's size having an indirect dependency
on itself, which is known as a *binding loop*.
If we were to try to figure out what implicitWidth is by hand, it would look something like this:
@ -153,7 +159,7 @@ If we were to try to figure out what implicitWidth is by hand, it would look som
which isn't a valid definition.
### MarginWrapper components
To solve the boilerplate problem that often leads users to `childrenRect`, Quickshell comes with
To solve the boilerplate problem, which often leads users to use `childrenRect`, Quickshell comes with
@@Quickshell.Widgets.MarginWrapperManager and a set of components based on it.
@@Quickshell.Widgets.MarginWrapperManager automatically handles the size and position relationship
@ -164,7 +170,7 @@ Rewriting the examples from the top of the page:
```qml
@@QtQuick.Item {
@@Quickshell.Widgets.MarginWrapperManager { margin: 5 }
// Automatically detected by MarginWrapperManager as the
// primary child of the container and sized accordingly.
@@QtQuick.Rectangle {
@ -180,7 +186,7 @@ Or as a reusable component:
// A bidirectional binding to manager.margin,
// where the default value is set.
property alias margin: manager.margin
// MarginWrapperManager tries to automatically detect
// the primary child of the container, but exposing the
// child property allows us to both access the child
@ -207,8 +213,8 @@ to the example above:
QtQuick comes with a set of layout types in the
[QtQuick.Layouts](https://doc.qt.io/qt-6/qtquicklayouts-overview.html) module.
Layouts, such as the Row, Column and Grid layout, are extremely useful for positioning
items adjacent to eachother. See the linked qt documentation for more details.
Layouts, such as the Row, Column, and Grid layout, are extremely useful for positioning
items adjacent to each other. See the linked Qt documentation for more details.
> [!NOTE]
> - Layouts have a default spacing of 5 pixels between items, not zero.