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

Compare commits

base: quickshell:f0e3b46627e0d337f2dd429e11eb490ed0d26c61
Branches Tags
quickshell:main
..
compare: quickshell:d826bce7b39aa74c2360960bbb299ae49330d9e7
Branches Tags
quickshell:main

No commits in common. "f0e3b46627e0d337f2dd429e11eb490ed0d26c61" and "d826bce7b39aa74c2360960bbb299ae49330d9e7" have entirely different histories.
f0e3b46627 ... d826bce7b3

2 changed files with 32 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

41
src/guide/faq.mdx
View file

@ -12,28 +12,6 @@ Make sure to also read the [Item Size and Position](/docs/guide/size-position) a
## How do I ## 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 ### Make a rounded window
Rounded windows are simply transparent square ones with a rounded rectangle Rounded windows are simply transparent square ones with a rounded rectangle
inside of them. inside of them.
@ -51,22 +29,3 @@ inside of them.
} }
} }
``` ```
## Something is broken
### There is a hole in my window
If you set a Rectangle's color to `"transparent"` and touch its `border` property,
you'll hit [QTBUG-137166](https://bugreports.qt.io/browse/QTBUG-137166), which
causes everything under the transparent rectangle to become invisible.
Adding a definition like `border.width: 0` seems to work around it, especially
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.
To tell Quickshell to always create a window capable of showing transparency,
use @@Quickshell.QsWindow.surfaceFormat to set `opaque` to false.

99
src/guide/qml-language.mdx
View file

@ -2,6 +2,7 @@
title: "QML Language" title: "QML Language"
index: 10 index: 10
--- ---
import MD_Title from "@components/MD_Title.tsx"
import Collapsible from "@components/Collapsible.astro"; import Collapsible from "@components/Collapsible.astro";
# {frontmatter.title} # {frontmatter.title}
@ -14,7 +15,7 @@ This page explains what you need to know about QML to start using quickshell.
Tutorial](https://doc.qt.io/qt-6/qml-tutorial.html) Tutorial](https://doc.qt.io/qt-6/qml-tutorial.html)
</span> </span>
## Structure ## <MD_Title titleVar={2}> Structure </MD_Title>
Below is a QML document showing most of the syntax. Below is a QML document showing most of the syntax.
Keep it in mind as you read the detailed descriptions below. Keep it in mind as you read the detailed descriptions below.
@ -86,17 +87,12 @@ import "myjs.js" as MyJs
function dub(x: int): int { function dub(x: int): int {
return x * 2 return x * 2
} }
// Inline component
component MyComponent: Object {
// ...
}
} }
``` ```
### Imports ### <MD_Title titleVar={3}> Imports </MD_Title>
#### Manual imports #### <MD_Title titleVar={4}> Manual imports </MD_Title>
Every QML File begins with a list of imports. Every QML File begins with a list of imports.
Import statements tell the QML engine where Import statements tell the QML engine where
@ -134,7 +130,7 @@ import "<filename>" as <Namespace>
Note: All _Module_ and _Namespace_ names must start with an uppercase letter. Note: All _Module_ and _Namespace_ names must start with an uppercase letter.
Attempting to use a lowercase namespace is an error. Attempting to use a lowercase namespace is an error.
##### Examples ##### <MD_Title titleVar={5}> Examples </MD_Title>
```qml ```qml
import QtQuick import QtQuick
@ -162,7 +158,7 @@ specifying a version at least when importing quickshell modules.
syntax](https://doc.qt.io/qt-6/qtqml-syntax-imports.html) syntax](https://doc.qt.io/qt-6/qtqml-syntax-imports.html)
</span> </span>
#### Implicit imports #### <MD_Title titleVar={4}> Implicit imports </MD_Title>
The QML engine will automatically import any [types](#creating-types) in neighboring files The QML engine will automatically import any [types](#creating-types) in neighboring files
with names that start with an uppercase letter. with names that start with an uppercase letter.
@ -176,7 +172,7 @@ root
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. or any other neighboring files.
### Objects ### <MD_Title titleVar={3}> Objects </MD_Title>
Objects are instances of a type from an imported module. Objects are instances of a type from an imported module.
The name of an object must start with an uppercase letter. The name of an object must start with an uppercase letter.
@ -195,12 +191,12 @@ Every object can contain [properties](#properties), [functions](#functions),
and [signals](#signals). You can find out what properties are available for a type and [signals](#signals). You can find out what properties are available for a type
by looking it up in the [Type Reference](/docs/types/). by looking it up in the [Type Reference](/docs/types/).
#### Properties #### <MD_Title titleVar={4}> Properties </MD_Title>
Every object may have any number of property assignments (only one per specific property). Every object may have any number of property assignments (only one per specific property).
Each assignment binds the named property to the given expression. Each assignment binds the named property to the given expression.
##### Property bindings ##### <MD_Title titleVar={5}> Property bindings </MD_Title>
Expressions are snippets of javascript code assigned to a property. The last (or only) line 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. can be the return value, or an explicit return statement (multiline expressions only) can be used.
@ -239,7 +235,7 @@ on is updated, the expression is re-evaluated and the property is updated.
Note that it is an error to try to assign to a property that does not exist. Note that it is an error to try to assign to a property that does not exist.
(See: [property definitions](#property-definitions)) (See: [property definitions](#property-definitions))
##### Property definitions ##### <MD_Title titleVar={5}> Property definitions </MD_Title>
Properties can be defined inside of objects with the following syntax: Properties can be defined inside of objects with the following syntax:
@ -271,7 +267,7 @@ 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 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. the property of the type it is derived from in the current context.
##### The default property ##### <MD_Title titleVar={5}> The default property </MD_Title>
Types can have a _default property_ which must accept either an object or a list of objects. Types can have a _default property_ which must accept either an object or a list of objects.
@ -306,7 +302,7 @@ would put a single object in:
} }
``` ```
##### The `id` property ##### <MD_Title titleVar={5}> The `id` property </MD_Title>
Every object has a special property called `id` that can be assigned to give 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 it can be referred to throughout the current file. The id must be lowercase.
@ -334,7 +330,7 @@ definition rules. The name `id` is always reserved for the id property.
</Collapsible> </Collapsible>
##### Property access scopes ##### <MD_Title titleVar={5}> Property access scopes </MD_Title>
Properties are "in scope" and usable in two cases. Properties are "in scope" and usable in two cases.
@ -347,9 +343,6 @@ or make sure the property you are accessing is from the current object using `th
The `parent` property is also defined for all objects, but may not always point to what it The `parent` property is also defined for all objects, but may not always point to what it
looks like it should. Use the `id` property if `parent` does not do what you want. looks like it should. Use the `id` property if `parent` does not do what you want.
In general, you should only access properties of the *current* object without an id. For
all other objects, you should refer to them by id when accessing properties.
```qml ```qml
@@QtQuick.Item { @@QtQuick.Item {
property string rootDefinition property string rootDefinition
@ -391,7 +384,7 @@ all other objects, you should refer to them by id when accessing properties.
Resolution](https://doc.qt.io/qt-6/qtqml-documents-scope.html) Resolution](https://doc.qt.io/qt-6/qtqml-documents-scope.html)
</span> </span>
#### Functions #### <MD_Title titleVar={4}> Functions </MD_Title>
Functions in QML can be declared everywhere [properties](#properties) can, and follow Functions in QML can be declared everywhere [properties](#properties) can, and follow
the same [scoping rules](#property-access-scopes). the same [scoping rules](#property-access-scopes).
@ -431,7 +424,7 @@ 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 `clicks` is changed, which triggers a re-evaluation of `text` through
`makeClicksLabel`. `makeClicksLabel`.
##### Lambdas ##### <MD_Title titleVar={5}> Lambdas </MD_Title>
Functions can also be values, and you can assign them to properties or pass them to Functions can also be values, and you can assign them to properties or pass them to
other functions (callbacks). There is a shorter way to write these functions, known other functions (callbacks). There is a shorter way to write these functions, known
@ -492,7 +485,7 @@ An overcomplicated click counter using a lambda callback:
} }
``` ```
#### Signals #### <MD_Title titleVar={4}> Signals </MD_Title>
A signal is basically an event emitter you can connect to and receive updates from. A signal is basically an event emitter you can connect to and receive updates from.
They can be declared everywhere [properties](#properties) and [functions](#functions) They can be declared everywhere [properties](#properties) and [functions](#functions)
@ -503,7 +496,7 @@ can, and follow the same [scoping rules](#property-access-scopes).
System](https://doc.qt.io/qt-6/qtqml-syntax-signals.html) System](https://doc.qt.io/qt-6/qtqml-syntax-signals.html)
</span> </span>
##### Signal definitions ##### <MD_Title titleVar={5}> Signal definitions </MD_Title>
A signal can be explicitly defined with the following syntax: A signal can be explicitly defined with the following syntax:
@ -511,7 +504,7 @@ A signal can be explicitly defined with the following syntax:
signal <name>(<paramname>: <type>[, ...]) signal <name>(<paramname>: <type>[, ...])
``` ```
##### Making connections ##### <MD_Title titleVar={5}> Making connections </MD_Title>
Signals all have a `connect(<function>)` method which invokes the given function Signals all have a `connect(<function>)` method which invokes the given function
or signal when the signal is emitted. or signal when the signal is emitted.
@ -551,7 +544,7 @@ When the button is clicked, the button emits the @@QtQuick.Controls.Button.click
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. which updates the counter and the text on the label.
##### Signal handlers ##### <MD_Title titleVar={5}> Signal handlers </MD_Title>
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 a connections, and prior examples have used them.
@ -583,7 +576,7 @@ this time using the implicit signal handler property to handle @@QtQuick.Control
} }
``` ```
##### Indirect signal handlers ##### <MD_Title titleVar={5}> Indirect signal handlers </MD_Title>
When it is not possible or not convenient to directly define a signal handler, before resorting 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. to `.connect`ing the properties, a @@QtQml.Connections object can be used to access them.
@ -607,7 +600,7 @@ This is especially useful to connect to signals of singletons.
} }
``` ```
##### Property change signals ##### <MD_Title titleVar={5}> Property change signals </MD_Title>
Every property has an associated signal, which powers QML's [reactive bindings](#reactive-bindings). 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. The signal is named `<propertyname>Changed` and works exactly the same as any other signal.
@ -680,7 +673,7 @@ And the function can also be inlined to an expression:
You can also remove the return statement if you wish. You can also remove the return statement if you wish.
##### Attached objects ##### <MD_Title titleVar={5}> Attached objects </MD_Title>
Attached objects are additional objects that can be associated with an object Attached objects are additional objects that can be associated with an object
as decided by internal library code. The documentation for a type will as decided by internal library code. The documentation for a type will
@ -702,7 +695,7 @@ 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. In this example, the text property is set inside the `Component.onCompleted` attached signal handler.
#### Creating types #### <MD_Title titleVar={4}> Creating types </MD_Title>
Every QML file with an uppercase name is implicitly a type, and can be used from 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).)
@ -748,35 +741,7 @@ are not visible outside the file.
} }
``` ```
##### Inline Components ##### <MD_Title titleVar={5}> Singletons </MD_Title>
Inline components work the same as any other type, but are created inside
another QML file. These components only work within the file, and can reference
IDs inside the file.
While inline components can be created anywhere inside a QML file, they are
scoped to the file itself and cannot be nested.
Example of an inline component:
```qml
@@QtQuick.Layouts.ColumnLayout {
id: layout
property real textPointSize: 10
MyText { text: "Thing 1" }
MyText { text: "Thing 2" }
MyText { text: "Thing 3" }
component MyText: @@QtQuick.Text {
// applied to all MyText instances
color: "red"
// references an id outside of the component
font.pointSize: layout.textPointSize
}
}
```
##### Singletons
QML Types can be easily made into a singleton, meaning there is only one instance QML Types can be easily made into a singleton, meaning there is only one instance
of the type. of the type.
@ -797,9 +762,9 @@ 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. files.
## Concepts ## <MD_Title titleVar={2}> Concepts </MD_Title>
### Reactive bindings ### <MD_Title titleVar={3}> Reactive bindings </MD_Title>
<span class="small"> <span class="small">
This section assumes knowledge of: [Properties](#properties), This section assumes knowledge of: [Properties](#properties),
@ -814,7 +779,7 @@ are then re-evaluated and so forth.
Bindings can be created in two different ways: Bindings can be created in two different ways:
##### Automatic bindings ##### <MD_Title titleVar={5}> Automatic bindings </MD_Title>
A reactive binding occurs automatically when you use one or more properties in the definition A reactive binding occurs automatically when you use one or more properties in the definition
of another property. . of another property. .
@ -833,7 +798,7 @@ of another property. .
In this example, the button's @@QtQuick.Controls.Button.text property is re-evaluated In this example, the button's @@QtQuick.Controls.Button.text property is re-evaluated
every time the button is clicked, because the `clicks` property has changed. every time the button is clicked, because the `clicks` property has changed.
###### Avoiding creation ###### <MD_Title titleVar={6}> Avoiding creation </MD_Title>
To avoid creating a binding, do not use any other properties in the definition of a property. To avoid creating a binding, do not use any other properties in the definition of a property.
@ -851,7 +816,7 @@ as assignments to properties do not create binding.
} }
``` ```
##### Manual bindings ##### <MD_Title titleVar={5}> Manual bindings </MD_Title>
Sometimes (not often) you need to create a binding inside of a function, signal, or expression. Sometimes (not often) you need to create a binding 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 If you need to change or attach a binding at runtime, the `Qt.binding` function can be used to
@ -883,7 +848,7 @@ In this example, `boundText`'s `text` property is bound to the button's pressed
when the button is first clicked. When you press or unpress the button the text will when the button is first clicked. When you press or unpress the button the text will
be updated. be updated.
##### Removing bindings ##### <MD_Title titleVar={5}> Removing bindings </MD_Title>
To remove a binding, just assign a new value to the property without using `Qt.binding`. To remove a binding, just assign a new value to the property without using `Qt.binding`.
@ -906,7 +871,7 @@ When the button is first pressed, the text will be updated, but once `onClicked`
the text will be unbound, and even though it contains a reference to the `pressed` property, the text will be unbound, and even though it contains a reference to the `pressed` property,
it will not be updated further by the binding. it will not be updated further by the binding.
### Lazy loading ### <MD_Title titleVar={3}> Lazy loading </MD_Title>
Often not all of your interface needs to load immediately. By default the QML 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. engine initializes every object in the scene before showing anything onscreen.
@ -914,7 +879,7 @@ For parts of the interface you don't need to be immediately visible, load them
asynchronously using a @@Quickshell.LazyLoader. asynchronously using a @@Quickshell.LazyLoader.
See its documentation for more information. See its documentation for more information.
#### Components #### <MD_Title titleVar={4}> Components </MD_Title>
Another delayed loading mechanism is the @@QtQml.Component type. Another delayed loading mechanism is the @@QtQml.Component type.
This type can be used to create multiple instances of objects or lazily load them. It's used by types such This type can be used to create multiple instances of objects or lazily load them. It's used by types such