diff --git a/src/guide/faq.mdx b/src/guide/faq.mdx index 015737f..6962623 100644 --- a/src/guide/faq.mdx +++ b/src/guide/faq.mdx @@ -8,30 +8,24 @@ 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 +## Misc + +### What will breaking changes look like +Quickshell will have breaking changes in future releases. These changes can +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. + +Migration guides will be provided between each release version. + +### Should I use a process per widget +No. Using a process per widget will use significantly more memory than using a +single process. + ## How do I -### 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. - -- Use @@QtQuick.Loader when the component being loaded inherits from @@QtQuick.Item. -- Use @@Quickshell.LazyLoader in other cases. - -### Show widgets conditionally -The @@QtQuick.Item.visible property can be used to change the visibility of an -Item conditionally, as well as Loaders. - -Note that you can change out a loader's component conditionally: -```qml -@@QtQuick.Loader { - readonly property Component thing1: ... - readonly property Component thing2: ... - - sourceComponent: condition ? thing1 : thing2 -} -``` - ### Make a rounded window Rounded windows are simply transparent square ones with a rounded rectangle inside of them. @@ -50,6 +44,75 @@ 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. + +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. + +### Run a program or script +Use @@Quickshell.Io.Process. + +If you want the entire output of the process as a single string, use +@@Quickshell.Io.StdioCollector to collect the Process's stdio. + +If the process is intended to run for a long time and stream in data, +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. + +Note that you can change out a loader's component conditionally: +```qml +@@QtQuick.Loader { + readonly property Component thing1: ... + readonly property Component thing2: ... + + sourceComponent: condition ? thing1 : thing2 +} +``` + +### 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. + +```qml +@@Quickshell.Widgets.ClippingWrapperRectangle { + radius: 10 + + @@Quickshell.Widgets.IconImage { // or a normal @@QtQuick.Image + source: ... + implicitSize: ... + } +} +``` + +[MarginWrapper]: /docs/guide/size-position#marginwrapper-components + +### 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. + +To get a file path relative to the current QML file, you can use @@QtQml.Qt.resolvedUrl(). + +To get a file path relative to your shell's reserved cache, data, or state directories, +you can use @@Quickshell.Quickshell.cachePath(), @@Quickshell.Quickshell.dataPath() or +@@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. + +When using a MultiEffect, 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: - One draws a purple/black square if the icon is missing. @@ -58,6 +121,26 @@ The @@Quickshell.Quickshell.iconPath() function has three variants: Either of the last two variants can be used to avoid the purple/black square. +### Work with an unsupported WM +Quickshell currently only bundles interfaces for working with Hyprland and i3, +however you can implement your own using @@Quickshell.Io.Socket or @@Quickshell.Io.Process, +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 +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. + +- Use @@QtQuick.Loader when the component being loaded inherits from @@QtQuick.Item. +- Use @@Quickshell.LazyLoader in other cases. + ## Something is broken ### There is a hole in my window