quickshell

2 files changed, 58 insertions, 13 deletions

diff --git a/Item Size Position.md b/Item Size Position.md
new file mode 100644
index 0000000..2479688
--- /dev/null
+++ b/Item Size Position.md
@@ -0,0 +1,40 @@
+[[Quickshell]]
+
+---
+
+# Item Size Position
+
+`Item` type is the base type for "visual items". It has two properties:
+- actual size ( width, height )
+- implicit/desired size ( implicitWidth, implicitHeight )
+
+Implicit size is used by containers to determine their own.
+
+## Container items
+
+Container (ie. `Item`):
+```qml
+implicitWidth: child.implicitWidth + margin * 2
+implicitHeight: child.implicitHeight + margin * 2
+```
+
+^ `WrapperItem` does this margin for us.
+
+Child (ie. `Rectangle`):
+```qml
+x: parent.margin
+y: parent.margin
+width: parent.width - parent.margin * 2
+height: parent.height - parent.margin * 2
+implicitWidth: 50
+implicitHeight: 50
+```
+[Binding](https://doc.qt.io/qt-6/qml-qtqml-binding.html) can be used to map any property
+[Anchors](https://doc.qt.io/qt-6/qtquick-positioning-anchors.html) are a shorthand way to achieve many common position and size bindings.
+
+Using a containers' Item.childrenRect to determine size of children is a mistake.
+Item.childrenRect represents the actual geometry of all child items, not the mplicit one.
+
+Use [MarginWrapperManager](https://quickshell.org/docs/types/Quickshell.Widgets/MarginWrapperManager) to handle size and position of container and a single child item.
+
+## Layouts
diff --git a/Quickshell.md b/Quickshell.md
index 607441f..c801fee 100644
--- a/Quickshell.md
+++ b/Quickshell.md
@@ -1,8 +1,14 @@
+[[Item Size Position]]
+
+---
+
+# Quickshell
+
 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
+## Windows
 Requires `import Quickshell`.
 Types:
 - PanelWindow: for bars, widgets and overlays
@@ -10,12 +16,12 @@ Types:
 
 [Type reference](https://quickshell.org/docs/types/Quickshell/PanelWindow)
 
-# Text
+## 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
+## Processes
 Requires `import Quickshell.Io` (NOTE the capital I in Io)
 
 [Process](https://quickshell.org/docs/types/quickshell.io/process) object runs commands.
@@ -23,25 +29,24 @@ Requires `import Quickshell.Io` (NOTE the capital I in Io)
 
 Use a [Timer](https://doc.qt.io/qt-6/qml-qtqml-timer.html) to run Process on an interval.
 
-# Component
+## 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
+## 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.
+`id` is a special property that can be used to reference an object throughout the entire current file. Has to be lowercase.
 
 
 Functions
 
-```
+```qml
 function <name>(<paramname>[: <type>][, ...])[: returntype] {
   // multiline expression (note that `return` is required)
 }
@@ -53,9 +58,9 @@ if the argument value changes all expressions are re-evaluated.
 Lambas `() => ...` 
 
 
-# Multiple files
+## Multiple files
 shell.qml is the root. If a filename starts with a capital letter it can be referenced. E.g Bar.qml
-```
+```qml
 Scope {
 	Bar {}
 }
@@ -63,7 +68,7 @@ Scope {
 
 Other folders can be imported using `import` statements.
 
-# Singleton
+## 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.
@@ -72,7 +77,7 @@ Set `pragma Singleton` at the top of the file ( before imports ). and Use `Singl
 [Clock formatting](https://doc.qt.io/qt-6/qml-qtqml-qt.html#formatDateTime-method)
 
 
-# Signals
+## Signals
 Event emitter.
 Same rules as properties and function.
 
@@ -90,7 +95,7 @@ Does that somehow override the onClicked function of the target??
 All properties have `propertynameChanged` handler, powering the reactivity.
 
 
-# Attached objects
+## Attached objects
 Every object has `Component` attached, used to run stuff when an Object finishes
 initializes using `Component.onCompleted`.