summaryrefslogtreecommitdiff
path: root/Quickshell.md
blob: 607441f17f0af6212a75d620f46c0e329ec440b6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
https://quickshell.org

XDG standard config paths. Looks for `shell.qml` in all sub-directories unless root dir has one. Target specific config using `quickshell -c configname`.

# Windows
Requires `import Quickshell`.
Types:
- PanelWindow: for bars, widgets and overlays
- FloatingWindow: standard desktop windows

[Type reference](https://quickshell.org/docs/types/Quickshell/PanelWindow)

# Text
[Text](https://doc.qt.io/qt-6/qml-qtquick-text.html) requires `import QtQuick.
Set `id: somename` to reference by `somename`, ie `somename.text = "blaat"`

Strings can be concat using `+`
# Processes
Requires `import Quickshell.Io` (NOTE the capital I in Io)

[Process](https://quickshell.org/docs/types/quickshell.io/process) object runs commands.
[StdioCollector](https://quickshell.org/docs/types/Quickshell.Io/StdioCollector) reads process' output.

Use a [Timer](https://doc.qt.io/qt-6/qml-qtqml-timer.html) to run Process on an interval.

# Component
A reusable tree of objects.
[Variants](https://quickshell.org/docs/types/Quickshell/Variants) creates instances of a component based on user supplied data. For example this used to create instances of a window based on the monitor list.

To prevent many of the same processes when we reuse a component many times use `Scope` to move them outside of the reused component.
We can use a [Property Definition](https://quickshell.org/docs/configuration/qml-overview/#property-definitions) on the parent scope to communicate between components in different scopes but in the same parent scope. Properties are reactive.

# Objects
Properties

`[required] [readonly] [default] property <type> <name>[: binding]`

`id` is a special property that can be used to reference an object throughout
the entire current file. Has to be lowercase.


Functions

```
function <name>(<paramname>[: <type>][, ...])[: returntype] {
  // multiline expression (note that `return` is required)
}
```

Can be invoked in expressions, reactivity is carried through -- so
if the argument value changes all expressions are re-evaluated.

Lambas `() => ...` 


# Multiple files
shell.qml is the root. If a filename starts with a capital letter it can be referenced. E.g Bar.qml
```
Scope {
	Bar {}
}
```

Other folders can be imported using `import` statements.

# Singleton
Has only one instance that is accessible from every scope. For example the date process in the bar.

Set `pragma Singleton` at the top of the file ( before imports ). and Use `Singleton` type.


[Clock formatting](https://doc.qt.io/qt-6/qml-qtqml-qt.html#formatDateTime-method)


# Signals
Event emitter.
Same rules as properties and function.

`signal <name>(<paramname>: <type>[, ...])`

Objects have implict `on<Signal>` (note capital S) for each signal defined.

Connections object can be used to access difficult to reach signal handlers,
such as those from Singletons.

`Connections { target: id; function onClicked() # example target: button }`
Does that somehow override the onClicked function of the target??


All properties have `propertynameChanged` handler, powering the reactivity.


# Attached objects
Every object has `Component` attached, used to run stuff when an Object finishes
initializes using `Component.onCompleted`.