diff --git a/src/guide/v0_3_0/advanced.md b/src/guide/v0_3_0/advanced.md new file mode 100644 index 0000000..7c6bc64 --- /dev/null +++ b/src/guide/v0_3_0/advanced.md @@ -0,0 +1,150 @@ +--- +title: "Advanced Options" +index: 10 +--- +## Pragmas +Quickshell pragmas are comments that influence execution in the form `//@ `. + +#### Internal +```qml +//@ pragma Internal +``` + +The Internal pragma can be added to the top of a QML file to prevent it from being exposed outside +of its module. + +#### If/Endif +```qml +//@ if +//@ endif +``` + +Quickshell supports C-preprocessor like if/endif blocks whose content disappears if the condition +is false. The condition is evaluated as a javascript expression. + +The preprocessing environment makes the following functions available for condition usage: +- `hasVersion(major, minor, features): bool` - Checks for a given Quickshell version and unreleased features. + Works identically to @@Quickshell.Quickshell.hasVersion(). +- `hasQtVersion(major, minor): bool` - Checks for a given Qt version, useful for using newly released Qt features. +- `env(name): string` - Returns the value of a given environment variable. +- `isEnvSet(name): bool` - Returns if a given environment variable is set. + +### Instance Pragmas +Instance pragmas affect properties of the whole Quickshell instance. They can only be placed at the +top of the root `shell.qml` file. + +#### Environment +```qml +//@ pragma Env VAR = VAL +//@ pragma DefaultEnv VAR = VAL +``` + +Qt and Quickshell environment variables can be specified with the `Env` and `DefaultEnv` pragmas. +These are useful for changing things like Qt scaling, theming, etc. + +These environment variables only affect Quickshell itself, and not any processes spawned by it. + +#### UseQApplication +```qml +//@ pragma UseQApplication +``` + +Quickshell launches with a `QGuiApplication` by default. This pragma switches this for +a `QApplication`, which supports using QtWidgets controls. These are needed for things like +the `qqc2-desktop-style` style from KDE. + +#### NativeTextRendering +```qml +//@ pragma UseQApplication +``` + +The NativeTextRendering uses the system text rendering backend over Qt's internal scene backend +which has performance and quality tradeoffs. This is equivalent to setting `Text.renderType` to +`Text.NativeRendering` for all text objects by default. + +#### IgnoreSystemSettings +```qml +//@ pragma UseQApplication +``` + +This can be set to entirely ignore system settings usually relating to application style. +Ususally should not be set. + +#### RespectSystemStyle +```qml +//@ pragma RespectSystemStyle +``` + +By default Quickshell sets the QtQuick Controls style to Fusion to avoid inconsistencies +between systems where a config might be used. Adding this pragma prevents that. + +Instead of following the system, a specific QtQuick Controls style might be desired, which +can be set with an env prama. +```qml +//@ pragma Env QT_QUICK_CONTROLS_STYLE = MyStyle +``` + +#### DropExpensiveFonts +```qml +//@ pragma DropExpensiveFonts +``` + +Font loading in Qt can be quite expensive, use significant memory, and cause stutters. +Compressed fonts amplify this issue and can sometimes be selected by default. This pragma +excludes all `woff` and `woff2` font files. It may become a default in the future. + +This setting can also be set with the `QS_DROP_EXPENSIVE_FONTS=1` environment variable. + +#### IconTheme +```qml +//@ pragma IconTheme +``` + +Sets the Qt icon theme to the given theme. See +[the qt documentation](https://doc.qt.io/qt-6/qicon.html#setThemeName) +for details. + +This setting can also be set with the `QS_ICON_THEME=` environment variable. + +#### AppId +```qml +//@ pragma AppId +``` + +Allows overriding the appid used for Quickshell. Useful if you'd like to have +a custom icon on floating windows. + +This setting can also be set with the `QS_APP_ID=` environment variable. + +#### ShellId +```qml +//@ pragma ShellId +``` + +Quickshell assigns a path-based "Shell Id" for every configuration which is used +to set the default locations for data directories and generally consider two +instances to be running the same config. + +You may want to override this if your config appears at multiple paths for whatever reason. + +#### DataDir, StateDir, CacheDir +```qml +//@ pragma DataDir +//@ pragma StateDir +//@ pragma CacheDir +``` + +Quickshell defines default data, state, and cache directories based off the shell id and exposed +by @@Quickshell.Quickshell.dataDir, @@Quickshell.Quickshell.stateDir and @@Quickshell.Quickshell.cacheDir. + +The dir definition can include `$BASE/` which is replaced by the XDG base directory (data, state, cache). + +## Environment + +In addition to the environment variables listed above, the following are available: +- `QS_DISABLE_FILE_WATCHER` - Disables hot reloading +- `QS_CONFIG_PATH` - Equivalent to `--path`. +- `QS_NO_XINERAMA_STRUTS` - Hack around X11 bar positioning. May either fix or further break it depending on window manager bugs. +- `QS_CRASHREPORT_URL` - Url for the crash reporter to direct users to instead of the Quickshell issue tracker. +- `QS_DISABLE_CRASH_HANDLER` - Disables the crash handler and relaunch system entirely. +- `QS_NO_RELOAD_POPUP` - Disables the reload notification popup. (This can also be done by hooking it inside the config.) diff --git a/src/guide/v0_3_0/distribution.md b/src/guide/v0_3_0/distribution.md new file mode 100644 index 0000000..cdd11bf --- /dev/null +++ b/src/guide/v0_3_0/distribution.md @@ -0,0 +1,35 @@ +--- +title: "Distributing Configurations" +index: 9 +--- +If you plan to distribute your configuration to a lot of users, you should keep +a couple things in mind: + +### API Breaks +As Quickshell is still in a somewhat early stage of development, Quickshell will +have API breaks for future versions. We will attempt to have a deprecation window +whenever possible. + +@@Quickshell.Quickshell.hasVersion() and the Quickshell preprocessor can be used to +version gate blocks of code if you need to work with multiple Quickshell versions. +See [Advanced Options](@docs/guide/advanced) for detauls. + +### Configuration Paths +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 it in +`$XDG_CONFIG_HOME/quickshell/` (usually `~/.config/quickshell/`). + +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 `. + +#### As a package +Some configurations are distributed as distro packages. These packages should use a +path in `$XDG_CONFIG_DIRS`, usually `/etc/xdg` for their files. + +As with dotfiles, named configurations should be used (`$CONFIG_DIR/quickshell/`).