quickshell/quickshell-web
3
1
Fork 0
Code Issues Projects Activity

proofreading and tweaks

Browse source
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
Download patch file Download diff file Expand all files Collapse all files

73
src/guide/faq.mdx
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.