### Configuring Quickshell Manifest File (manifest.conf)

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

Quickshell configurations can be managed via a manifest file, which defaults to `~/.config/quickshell/manifest.conf`. This file is a list of `name = path` pairs, allowing for flexible organization and launching of different shell setups. Paths can be relative or absolute, and lines starting with `#` are treated as comments.

```properties
# ~/.config/quickshell/manifest.conf
myconf1 = myconf
myconf2 = ./myconf
myconf3 = myconf/shell.nix
myconf4 = ~/.config/quickshell/myconf
```

--------------------------------

### Practical QML Import Statement Examples

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet provides various practical examples of QML import statements, demonstrating how to import modules with and without versions, use namespaces, and import local JavaScript files. These examples illustrate common import patterns for different scenarios in QML development.

```qml
import QtQuick
import QtQuick.Controls 6.0
import Quickshell as QS
import QtQuick.Layouts 6.0 as L
import "jsfile.js" as JsFile
```

--------------------------------

### Build and Serve quickshell Documentation Locally

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/README.md

This command utilizes the 'just' command runner to build and serve the quickshell project documentation on a local server. It requires 'just', 'hugo', and 'rust' to be installed and must be executed from a subdirectory within the main quickshell repository where this documentation is cloned as a submodule.

```shell
$ just serve
```

--------------------------------

### QML Property Access Scopes Example

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Demonstrates property access rules within QML, showing legal and illegal access patterns based on current object, root object, and ID-based references. It illustrates the use of `this` and `id` for property resolution.

```qml
Item {
  property string rootDefinition

  Item {
    id: mid
    property string midDefinition

    Text {
      property string innerDefinition

      // legal - innerDefinition is defined on the current object
      text: innerDefinition

      // legal - innerDefinition is accessed via `this` to refer to the current object
      text: this.innerDefinition

      // legal - width is defined for Text
      text: width

      // legal - rootDefinition is defined on the root object
      text: rootDefinition

      // illegal - midDefinition is not defined on the root or current object
      text: midDefinition

      // legal - midDefinition is accessed via `mid`'s id.
      text: mid.midDefinition

      // legal - midDefinition is accessed via `parent`
      text: parent.midDefinition
    }
  }
}
```

--------------------------------

### QML Function Invocation and Reactivity Example

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Shows a QML example where a function `makeClicksLabel` is invoked in a `Text` element. It demonstrates how changes to a dependent property (`clicks`) trigger re-evaluation of the function and the UI element.

```qml
ColumnLayout {
  property int clicks: 0

  function makeClicksLabel(): string {
    return "the button has been clicked " + clicks + " times!";
  }

  Button {
    text: "click me"
    onClicked: clicks += 1
  }

  Text {
    text: makeClicksLabel()
  }
}
```

--------------------------------

### Creating a Basic Quickshell Panel Window with Text

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This example demonstrates how to create a simple top-anchored panel window using `PanelWindow` within the `ShellRoot`. It includes a `Text` element centered within the panel, displaying 'hello world'. `PanelWindow` is suitable for creating bars and widgets, and it automatically reserves space for itself on your monitor.

```qml
import Quickshell // for ShellRoot and PanelWindow
import QtQuick // for Text

ShellRoot {
  PanelWindow {
    anchors {
      top: true
      left: true
      right: true
    }

    height: 30

    Text {
      // center the bar in its parent component (the window)
      anchors.centerIn: parent

      text: "hello world"
    }
  }
}
```

--------------------------------

### Initial Separation of Shell Bar into Multiple QML Files

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This example demonstrates how to separate the main shell bar component into its own `Bar.qml` file. The `shell.qml` file then imports and uses this `Bar` component. It also shows how to adjust property references (e.g., `time` instead of `root.time`) when components are moved.

```qml
import Quickshell

ShellRoot {
  Bar {}
}
```

```qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  property string time;

  Variants {
    model: Quickshell.screens

    PanelWindow {
      property var modelData
      screen: modelData

      anchors {
        top: true
        left: true
        right: true
      }

      height: 30

      Text {
        anchors.centerIn: parent

        // now just time instead of root.time
        text: time
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      // now just time instead of root.time
      onRead: data => time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Examples of QML Property Definitions

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet provides practical examples of defining properties in Quickshell's QML. It demonstrates a normal integer property, a `readonly` string property, and a `var` type property with an array binding. Defining a property with an existing name overrides the inherited property.

```qml
Item {
  // normal property
  property int foo: 3

  // readonly property
  readonly property string bar: "hi!"

  // bound property
  property var things: [ "foo", "bar" ]
}
```

--------------------------------

### Defining the Quickshell Root File (shell.qml)

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

Every Quickshell instance starts from a shell root file, conventionally named `shell.qml` and typically located at `~/.config/quickshell/shell.qml`. This file contains the `ShellRoot` object, which acts as the primary container for all visual and non-visual elements of your shell configuration. Only one `ShellRoot` object may exist per configuration.

```qml
import Quickshell

ShellRoot {
  // ...
}
```

--------------------------------

### Create Automatic Reactive Bindings in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Shows how QML automatically creates reactive bindings when one property's definition uses another. The example demonstrates a Button's text property updating automatically as a clicks property changes, reflecting real-time reactivity.

```qml
Item {
  property int clicks: 0

  Button {
    text: `clicks: ${clicks}`
    onClicked: clicks += 1
  }
}
```

--------------------------------

### QML Lambda Callback for Click Counter

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

An example demonstrating the use of a lambda as a callback function. It shows an `incrementAndCall` function that takes a callback, which then updates a `Text` element with the click count.

```qml
ColumnLayout {
  property int clicks: 0

  function incrementAndCall(callback) {
    clicks += 1;
    callback(clicks);
  }

  Button {
    text: "click me"
    onClicked: incrementAndCall(clicks => {
        label.text = `the button was clicked ${clicks} time(s)!`;
    })
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }
}
```

--------------------------------

### Comprehensive QML Document Structure Example

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This QML snippet demonstrates the core syntax elements of a QML document, including import statements, root object definition, property declarations and bindings, object assignments, signal declarations and handlers, and function definitions. It serves as a reference for understanding the overall structure and various components of a QML file.

```qml
// QML Import statement
import QtQuick 6.0

// Javascript import statement
import "myjs.js" as MyJs

// Root Object
Item {
  // Id assignment

  id: root
  // Property declaration
  property int myProp: 5;

  // Property binding
  width: 100

  // Property binding
  height: width

  // Multiline property binding
  prop: {
    // ...
    5
  }

  // Object assigned to a property
  objProp: Object {
    // ...
  }

  // Object assigned to the parent's default property
  AnotherObject {
    // ...
  }

  // Signal declaration
  signal foo(bar: int)

  // Signal handler
  onSignal: console.log("received signal!")

  // Property change signal handler
  onWidthChanged: console.log(`width is now ${width}!`)

  // Multiline signal handler
  onOtherSignal: {
    console.log("received other signal!");
    console.log(`5 * 2 is ${dub(5)}`);
    // ...
  }

  // Attached property signal handler
  Component.onCompleted: MyJs.myfunction()

  // Function
  function dub(x: int): int {
    return x * 2
  }
}
```

--------------------------------

### Create Manual Reactive Bindings with Qt.binding

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Demonstrates how to create a reactive binding manually at runtime using the `Qt.binding` function. The example shows a button click dynamically binding a Text element's text property to the button's pressed state, allowing for conditional or dynamic binding creation.

```qml
Item {
  Text {
    id: boundText
    text: "not bound to anything"
  }

  Button {
    text: "bind the above text"
    onClicked: {
      if (boundText.text == "not bound to anything") {
        text = "press me";
        boundText.text = Qt.binding(() => `button is pressed: ${this.pressed}`);
      }
    }
  }
}
```

--------------------------------

### Understand QML Property Definition Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet illustrates the general syntax for defining properties in Quickshell's QML. It includes optional keywords like `required`, `readonly`, and `default`, followed by the property's type, name, and an optional binding. Properties cannot start with an uppercase letter.

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

--------------------------------

### Handle Signal with Implicit Handler in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Shows a more concise way to handle signals in QML by using implicit signal handler properties (e.g., `onClicked`). This example achieves the same functionality as the `connect()` method but with cleaner, more idiomatic QML syntax, directly associating the handler with the object emitting the signal.

```qml
ColumnLayout {
  property int clicks: 0

  function updateText() {
    clicks += 1;
    label.text = `the button has been clicked ${clicks} times!`;
  }

  Button {
    text: "click me"
    onClicked: updateText()
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }
}
```

--------------------------------

### Dynamic Multi-Monitor Bar Creation with QML Variants

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet demonstrates how to use "Quickshell.Variants" with "Quickshell.screens" to automatically create a "PanelWindow" for each connected monitor. Each window's "screen" property is bound to the "modelData" injected by "Variants". The example also includes a basic clock implemented with "Process" and "Timer" directly within each window's delegate, which leads to resource duplication.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

ShellRoot {
  Variants {
    model: Quickshell.screens;

    delegate: Component {
      PanelWindow {
        // the screen from the screens list will be injected into this
        // property
        property var modelData

        // we can then set the window's screen to the injected property
        screen: modelData

        anchors {
          top: true
          left: true
          right: true
        }

        height: 30

        Text {
          id: clock
          anchors.centerIn: parent

          Process {
            id: dateProc
            command: ["date"]
            running: true

            stdout: SplitParser {
              onRead: data => clock.text = data
            }
          }

          Timer {
            interval: 1000
            running: true
            repeat: true
            onTriggered: dateProc.running = true
          }
        }
      }
    }
  }
}
```

--------------------------------

### Use Component.onCompleted Attached Object in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Illustrates the use of attached objects, specifically `Component.onCompleted`, to execute code when an object is fully initialized and ready. This is commonly used for initial setup tasks, such as setting a property's value immediately after creation.

```qml
Text {
  Component.onCompleted: {
    text = "hello!"
  }
}
```

--------------------------------

### Running a Quickshell Process at a regular interval using Timer

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

Building on the previous example, this QML snippet shows how to update the `date` command's output periodically. It uses a `Timer` to re-trigger the `Process` object every second, ensuring the displayed time is continuously updated. The timer is set to run immediately and repeat indefinitely.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

ShellRoot {
  PanelWindow {
    anchors {
      top: true
      left: true
      right: true
    }

    height: 30

    Text {
      id: clock
      anchors.centerIn: parent

      Process {
        // give the process object an id so we can talk
        // about it from the timer
        id: dateProc

        command: ["date"]
        running: true

        stdout: SplitParser {
          onRead: data => clock.text = data
        }
      }

      // use a timer to rerun the process at an interval
      Timer {
        // 1000 milliseconds is 1 second
        interval: 1000

        // start the timer immediately
        running: true

        // run the timer again when it ends
        repeat: true

        // when the timer is triggered, set the running property of the
        // process to true, which reruns it if stopped.
        onTriggered: dateProc.running = true
      }
    }
  }
}
```

--------------------------------

### Create a QML Component with Implicit Size based on Children

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/positioning.md

Illustrates how to define a QML component whose implicit size (base size before layouts are applied) is determined by its children. This example creates a Rectangle that wraps a Text item, ensuring the composite component behaves identically to the text itself when placed within a layout.

```qml
Rectangle {
  implicitWidth: text.implicitWidth
  implicitHeight: text.implicitHeight
  
  Text {
    id: text
    text: "hello!"
  }
}
```

--------------------------------

### Assign Single Object to QML Default Property

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Types in Quickshell's QML can have a 'default property' that accepts an object or a list of objects. This example shows how to assign a single `Item` object to the outer object's default property without explicitly naming the property, simplifying object composition.

```qml
Item {
  // normal property
  foo: 3

  // this item is assigned to the outer object's default property
  Item {
  }
}
```

--------------------------------

### Manually Position a QML Rectangle

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/positioning.md

Demonstrates how to manually position and size a QML Rectangle component using its `x`, `y`, `width`, and `height` properties. These properties are relative to the parent component. The example places a 100x100px blue rectangle at coordinates (20, 40) within its parent, ensuring the parent's implicit size accommodates its children.

```qml
Item {
  // make sure the component is large enough to fit its children
  implicitWidth: childrenRect.width
  implicitHeight: childrenRect.height
  
  Rectangle {
    color: "blue"
    x: 20
    y: 40
    width: 100
    height: 100
  }
}
```

--------------------------------

### Assign Multiple Objects to QML Default List Property

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

If a type's default property is configured to accept a list of objects, multiple objects can be assigned to it implicitly. This example demonstrates how multiple `Item` objects are added to the outer object's default list property without explicit property naming.

```qml
Item {
  // normal property
  foo: 3

  // this item is assigned to the outer object's default property
  Item {
  }

  // this one is too
  Item {
  }
}
```

--------------------------------

### Calculate QML Component Implicit Size with Multiple Children and Math

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/positioning.md

Shows how to calculate a QML component's implicit width and height based on multiple child components and custom mathematical operations. This example sums the implicit widths of two text items plus a fixed padding, and takes the maximum implicit height of both texts plus padding, demonstrating flexible sizing.

```qml
Item {
  // width of both texts plus 5
  implicitWidth: text1.implicitWidth + text2.implicitWidth + 5
  // max height of both texts plus 5
  implicitHeight: Math.min(text1.implicitHeight, text2.implicitHeight) + 5

  Text {
    id: text1
    text: "text1"
  }
  
  Text {
    id: text2
    anchors.left: text1.left
    text: "text2"
  }
}
```

--------------------------------

### Handle Property Change with Inlined Expression in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Further refines the reactive binding example by inlining the logic for updating the label's text directly within the `Text` element's `text` property. This demonstrates how complex expressions, including local variable declarations, can be used within QML bindings.

```qml
ColumnLayout {
  CheckBox {
    id: checkbox
    text: "check me"
  }

  Text {
    id: label
    text: {
      const checked = checkbox.checkState == Qt.Checked;
      return `the checkbox is checked: ${checked}`;
    }
  }
}
```

--------------------------------

### Use QML `id` Property for Object Referencing

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

The special `id` property in Quickshell's QML allows assigning a unique name to an object, making it referable throughout the current file. This example shows how a `Text` object is given an `id` and then its `color` property is modified by a `Button`'s `onClicked` handler using that `id`.

```qml
ColumnLayout {
  Text {
    id: text
    text: "Hello World!"
  }

  Button {
    text: "Make the text red";
    onClicked: text.color = "red";
  }
}
```

--------------------------------

### Remove QML Reactive Property Bindings

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Illustrates how to remove an existing reactive binding by simply assigning a new, non-bound value to the property. The example shows a Text element initially bound to a button's pressed state, and then the binding is broken upon the button's click, freezing the text at the value it had when the binding was removed.

```qml
Item {
  Text {
    id: boundText
    text: `button is pressed: ${theButton.pressed}`
  }

  Button {
    id: theButton
    text: "break the binding"
    onClicked: boundText.text = `button was pressed at the time the binding was broken: ${pressed}`
  }
}
```

--------------------------------

### Running a `date` command with Quickshell Process

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet demonstrates how to execute the `date` command using Quickshell's `Process` object. It captures the standard output, parses it with `SplitParser`, and updates a `Text` element with the current date and time. The command runs immediately upon initialization.

```qml
import Quickshell
import Quickshell.Io // for Process
import QtQuick

ShellRoot {
  PanelWindow {
    anchors {
      top: true
      left: true
      right: true
    }

    height: 30

    Text {
      // give the text an ID we can refer to elsewhere in the file
      id: clock

      anchors.centerIn: parent

      // create a process management object
      Process {
        // the command it will run, every argument is its own string
        command: ["date"]

        // run the command immediately
        running: true

        // process the stdout stream using a SplitParser
        // which returns chunks of output after a delimiter
        stdout: SplitParser {
          // listen for the read signal, which returns the data that was read
          // from stdout, then write that data to the clock's text property
          onRead: data => clock.text = data
        }
      }
    }
  }
}
```

--------------------------------

### Go Template for Dynamic Documentation Links

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/layouts/partials/qmltype.html

This template constructs URLs for various documentation types, including Qt documentation, local project documentation, and specific member types (properties, functions, signals). It handles different link formats and prefixes based on the source and member kind, ensuring correct URL generation and display text.

```Go Template
{{- if eq .type "unknown" -}} unknown {{- else -}} {{- $link := "" -}} {{- if eq .type "qt" -}} {{- $link = printf "https://doc.qt.io/qt-6/%s-%s.html" (lower (replace .module "." "-")) (lower .name) -}} {{- else if eq .type "local" -}} {{- $link = printf "/docs/types/%s/%s" (lower .module) (lower .name) -}} {{- end -}} {{- $of := "" -}} {{- if .of -}} {{- $of = printf "<%s>" (partial "qmltype.html" .of) }} {{- end -}} {{- $prefix := "" -}} {{- $member := "" -}} {{- if .mtype -}} {{- if .type -}} {{- $member = printf ".%s" .mname -}} {{- else -}} {{- $member = .mname -}} {{- end -}} {{- if eq .mtype "prop" -}} {{- if eq .type "qt" -}} {{- $link = printf "%s#%s-prop" $link .mname -}} {{- else -}} {{- $link = printf "%s#prop.%s" $link .mname -}} {{- end -}} {{- else if eq .mtype "func" -}} {{- $member = printf "%s()" $member -}} {{- if eq .type "qt" -}} {{- $link = printf "%s#%s-method" $link .mname -}} {{- else -}} {{- $link = printf "%s#func.%s" $link .mname -}} {{- end -}} {{- else if eq .mtype "signal" -}} {{- $prefix = "[signal] " -}} {{- $member = printf "%s()" $member -}} {{- if eq .type "qt" -}} {{- $link = printf "%s#%s-signal" $link .mname -}} {{- else -}} {{- $link = printf "%s#signal.%s" $link .mname -}} {{- end -}} {{- end -}} {{- end -}} [{{ $prefix }}{{ .name }}{{ $member }}]({{ $link }}){{ $of | safeHTML -}} {{- end -}}
```

--------------------------------

### Initial QML Shell for Dynamic Time Display

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML code defines a basic Quickshell application that displays the current time. It uses a `ShellRoot` with an `id` to expose a `time` property, a `Process` to execute the `date` command, and a `Timer` to trigger updates every second. The time is displayed within a `PanelWindow` using a `Text` element, explicitly referencing the `root` object's `time` property.

```QML
import Quickshell.Io
import QtQuick

ShellRoot {
  id: root

  // add a property in the root
  property string time;

  Variants {
    model: Quickshell.screens

    delegate: Component {
      PanelWindow {
        property var modelData
        screen: modelData

        anchors {
          top: true
          left: true
          right: true
        }

        height: 30

        Text {
          // remove the id as we don't need it anymore

          anchors.centerIn: parent

          // bind the text to the root's time property
          text: root.time
        }
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      // update the property instead of the clock directly
      onRead: data => root.time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Basic QML Object Definition Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet shows the fundamental syntax for defining an object in QML. It includes the object's type name, an optional `id` for referencing, and a placeholder for properties, functions, and signals, illustrating how to instantiate types from imported modules.

```qml
Name {
  id: foo
  // properties, functions, signals, etc...
}
```

--------------------------------

### Hugo Template for Module Documentation Rendering

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/layouts/shortcodes/qmlmodule.html

This template is designed for Hugo static sites to dynamically generate documentation pages for specific modules. It utilizes module data stored in `Site.Data.modules` to display the module's main description, additional details, and an iterated list of its types, each with a link and a description. The template uses Go template syntax for variable assignment, data retrieval, and conditional rendering.

```Go Template
{{- $modulename := .Get "module" -}} {{- $module := index .Site.Data.modules $modulename -}}\n\n{{ $modulename }}\\[module\\]\n===========================\n\n{{- $module.index.description | $.Page.RenderString (dict "display" "block") -}}\n\n### Types\n\n{{- range $name, $type := $module -}} {{- if ne $name "index" -}} {{- end -}} {{- end -}}\n\n[{{ $name }}](/docs/types/{{ lower $modulename }}/{{ lower $name }})\n\n{{ $type.description }}\n\n{{- $module.index.details | $.Page.RenderString (dict "display" "block") -}}
```

--------------------------------

### QML Assigning Functions and Lambdas to Properties

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Compares assigning a traditional function and a lambda expression to a property in QML, demonstrating how functions can be treated as values.

```qml
Item {
  // using functions
  function dub(number: int): int { return number * 2; }
  property var operation: dub

  // using lambdas
  property var operation: number => number * 2
}
```

--------------------------------

### QML Function Definition Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Illustrates the general syntax for defining functions in QML, including parameter types and optional return types. Functions follow the same scoping rules as properties.

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

--------------------------------

### QML Module Import Statement Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet illustrates the general syntax for importing QML modules. It shows how to specify the module name, an optional major.minor version, and an optional namespace alias, enabling the QML engine to locate and use types from external modules.

```qml
import <Module> [Major.Minor] [as <Namespace>]
```

--------------------------------

### Improve QML Singleton Time with JavaScript Date API

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet refactors the 'Time' singleton to use the built-in JavaScript 'Date' API instead of an external process. It demonstrates how to create a 'Date' object, format it using 'toLocaleString', and update it periodically with a 'Timer', showcasing efficient in-process data handling.

```QML
pragma Singleton

import Quickshell
import Quickshell.Io
import QtQuick

Singleton {
  property var date: new Date()
  property string time: date.toLocaleString(Qt.locale())

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: date = new Date()
  }
}
```

--------------------------------

### Extracting Clock Widget into a Dedicated QML File

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This snippet illustrates breaking out the visual clock component (a `Text` object) into a new `ClockWidget.qml` file. It introduces the concept of `required property` for components and updates `Bar.qml` to incorporate the new `ClockWidget`, highlighting a potential pitfall with self-binding properties.

```qml
import QtQuick

Text {
  // A property the creator of this type is required to set.
  // Note that we could just set `text` instead, but don't because your
  // clock probably will not be this simple.
  required property string time

  text: time
}
```

```qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  id: root
  property string time;

  Variants {
    model: Quickshell.screens

    PanelWindow {
      property var modelData
      screen: modelData

      anchors {
        top: true
        left: true
        right: true
      }

      height: 30

      // the ClockWidget type we just created
      ClockWidget {
        anchors.centerIn: parent
        // Warning: setting `time: time` will bind time to itself which is not what we want
        time: root.time
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      onRead: data => time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Integrate QML Widget Using a Singleton in Bar File

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet shows how to integrate the 'ClockWidget' into a Quickshell 'Bar.qml' file. Because 'ClockWidget' now relies on the 'Time' singleton, the 'Bar.qml' no longer needs to manage or pass a 'time' object, simplifying the top-level application structure.

```QML
import Quickshell

Scope {
  // no more time object

  Variants {
    model: Quickshell.screens

    PanelWindow {
      property var modelData
      screen: modelData

      anchors {
        top: true
        left: true
        right: true
      }

      height: 30

      ClockWidget {
        anchors.centerIn: parent

        // no more time binding
      }
    }
  }
}
```

--------------------------------

### Separating Clock Update Logic into a Time QML Component

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This final step demonstrates how to further modularize the application by moving the `Process` and `Timer` components, which are responsible for fetching and updating the time, into a dedicated `Time.qml` file. `Bar.qml` is then updated to use this `Time` component as the source for the `ClockWidget`'s time property, showcasing a clean separation of concerns.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  property string time;

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      onRead: data => time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

```qml
import Quickshell

Scope {
  // the Time type we just created
  Time { id: timeSource }

  Variants {
    model: Quickshell.screens

    PanelWindow {
      property var modelData
      screen: modelData

      anchors {
        top: true
        left: true
        right: true
      }

      height: 30

      ClockWidget {
        anchors.centerIn: parent
        // now using the time from timeSource
        time: timeSource.time
      }
    }
  }
}
```

--------------------------------

### Refactored QML Shell for Concise Time Display

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This refactored QML code achieves the same functionality as the initial version but with improved conciseness. It demonstrates implicit `Component` definition within `Variants.delegate`, utilizes the `Default Property` feature to simplify assignments, and leverages QML's special scoping rules to access the `time` property directly without needing an `id` for the `ShellRoot`.

```QML
import Quickshell
import Quickshell.Io
import QtQuick

ShellRoot {
  property string time;

  Variants {
    model: Quickshell.screens

    PanelWindow {
      property var modelData
      screen: modelData

      anchors {
        top: true
        left: true
        right: true
      }

      height: 30

      Text {
        anchors.centerIn: parent

        // now just time instead of root.time
        text: time
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      // now just time instead of root.time
      onRead: data => time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Define a QML Singleton for Global Time Access (External Process)

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet defines a 'Time' type as a singleton, ensuring only one instance exists and is accessible globally. It uses a 'Process' element to execute the external 'date' command and a 'Timer' to periodically update the 'time' property, demonstrating how to integrate external commands for dynamic data.

```QML
// with this line our type becomes a singleton
pragma Singleton

import Quickshell
import Quickshell.Io
import QtQuick

// your singletons should always have Singleton as the type
Singleton {
  property string time

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      onRead: data => time = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### Hugo Template for Dynamic QML API Documentation Generation

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/layouts/shortcodes/qmltype.html

This Go template, specifically for Hugo, processes structured data (e.g., from `_index.md` or data files) to generate detailed documentation for QML types. It defines partials for rendering type flags and handles the display of type descriptions, variants, properties (including gadget properties), functions, and signals, along with their detailed sections. The template ensures consistent formatting and linking within the generated documentation.

```Go Template
{{ $modulename := .Get "module" }} {{ $typename := .Get "type" }} {{ $type := index .Site.Data.modules $modulename $typename }} {{- define "partials/qmltypeflag.html" -}} {{- if eq . "default" -}} {{ . }} {{- else if eq . "singleton" -}} {{ . }} {{- else if eq . "uncreatable" -}} {{ . }} {{- else if eq . "readonly" -}} {{ . }} {{- else if eq . "writeonly" -}} {{ . }} {{- else -}} {{ . }} {{- end -}} {{- end -}} {{- define "partials/qmltypeflags.html" -}} {{- $first := true -}} \[ {{- range $flag := . }} {{- if not $first -}}, {{ end -}} {{- $first = false -}} {{ partial "qmltypeflag.html" $flag }} {{- end -}} \] {{- end -}}

{{ $typename -}} {{- if eq $type.type "class" -}} : {{ partial "qmltype.html" $type.super }} {{ if $type.flags -}} {{ partial "qmltypeflags.html" $type.flags }} {{- end -}} {{- else if eq $type.type "enum" -}} \[enum\] {{- end -}}
======================================================================================================================================================================================================================================

`_import {{ $modulename }}_` {{- if $type.description -}}  
  
{{- $type.description | $.Page.RenderString (dict "display" "inline") }} {{ if $type.details -}} [More](#details) {{- end -}} {{- end -}} {{- if $type.variants -}}

#### Variants

{{- range $name, $variant := $type.variants -}}*   [{{ $name }}](#variant.{{ $name }})
{{- end -}}

{{- end -}} {{- if $type.properties -}}

#### Properties

{{- range $propname, $prop := $type.properties -}}*   [{{ $propname }}](#prop.{{ $propname }}) {{- if not $prop.type.gadget -}} : {{ partial "qmltype.html" $prop.type }} {{- end -}} {{ if in $prop.flags "default" }} \[{{ partial "qmltypeflag.html" "default" }}\] {{ end }} {{- if $prop.type.gadget -}}
    {{- range $gadgetname, $gadgettype := $prop.type.gadget -}}*   [{{ $propname }}.{{ $gadgetname }}](#prop.{{ $propname }}): {{ partial "qmltype.html" $gadgettype }}
    {{- end -}}{{- end -}
{{- end -}}

{{- end -}} {{- if $type.functions -}}

#### Functions

{{- range $func := $type.functions -}}*   {{ partial "qmltype.html" $func.ret }} [{{ $func.name }}](#func.{{ $func.id }})( {{- partial "qmlparams.html" $func.params -}} )
{{- end -}}

{{- end -}} {{- if $type.signals -}}

#### Signals

{{- range $signame, $sig := $type.signals -}}*   [{{ $signame }}](#signal.{{ $signame }})( {{- partial "qmlparams.html" $sig.params -}} )
{{- end -}}

{{- end -}} {{- if $type.details -}}

### Detailed Description

{{- $type.details | $.Page.RenderString (dict "display" "block") -}} {{- end -}} {{- if $type.variants -}}

### Variant Details

{{ range $name, $variant := $type.variants }}

{{ $name -}}

{{- if $variant.details -}} {{- $variant.details | $.Page.RenderString (dict "display" "block") -}} {{- else -}}

_No details provided._

{{- end -}}

{{- end -}} {{- end -}} {{- if $type.properties -}}

### Property Details

{{ range $propname, $prop := $type.properties }}

{{- if $prop.flags -}} {{ partial "qmltypeflags.html" $prop.flags }} {{- end -}} {{- if $prop.type.gadget -}} {{- range $gadgetname, $gadgettype := $prop.type.gadget -}}

{{ $propname }}.{{ $gadgetname -}} : {{ partial "qmltype.html" $gadgettype -}}

{{- end -}} {{- else -}}

{{ $propname -}} : {{ partial "qmltype.html" $prop.type -}}

{{- end -}}

{{- if $prop.details -}} {{- $prop.details | $.Page.RenderString (dict "display" "block") -}} {{- else -}}

_No details provided._

{{- end -}}

{{- end -}} {{- end -}} {{- if $type.functions -}}

### Function Details

{{ range $func := $type.functions }}

{{- if $func.flags -}} {{ partial "qmltypeflags.html" $func.flags }} {{- end -}}

{{ partial "qmltype.html" $func.ret -}} {{ $func.name -}} ( {{- partial "qmlparams.html" $func.params -}} )

{{- if $func.details -}} {{- $func.details | $.Page.RenderString (dict "display" "block") -}} {{- else -}}

_No details provided._

{{- end -}}

{{- end -}} {{- end -}} {{- if $type.signals -}}

### Signal Details

{{ range $signame, $sig := $type.signals }}

{{- if $sig.flags -}} {{ partial "qmltypeflags.html" $sig.flags }} {{- end -}}

{{ $signame -}} ( {{- partial "qmlparams.html" $sig.params -}} )

{{- if $sig.details -}} {{- $sig.details | $.Page.RenderString (dict "display" "block") -}} {{- else -}}

_No details provided._

{{- end -}}

{{- end -}} {{- end -}}
```

--------------------------------

### QML Subfolder Import Statement Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet outlines the syntax for importing types from a local directory relative to the current QML file. It allows for organizing QML components into subfolders and optionally assigning a namespace for clarity.

```qml
import "<directory>" [as <Namespace>]
```

--------------------------------

### Go Template for QML Type Rendering

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/layouts/shortcodes/qmltypelink.html

This Go template snippet is utilized in the Quickshell documentation to dynamically render specific QML type details. It constructs a dictionary of parameters by retrieving values from the current page's context and then passes this dictionary to the 'qmltype.html' partial template for content generation.

```Go Template
{{- $params := dict "type" (.Get "type") "module" (.Get "module") "name" (.Get "name") "mtype" (.Get "mtype") "mname" (.Get "mname") -}} {{- partial "qmltype.html" $params -}}
```

--------------------------------

### Attempting to Centralize QML Process and Timer

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet attempts to optimize resource usage by moving the "Process" and "Timer" objects outside the "PanelWindow" delegate, placing them directly in "ShellRoot". The goal is to avoid creating multiple instances of these resources for each monitor. However, this approach introduces a "ReferenceError" because the "clock" "Text" element, which is defined within the "PanelWindow" delegate, cannot be referenced from outside its component scope.

```qml
import Quickshell
import Quickshell.Io
import QtQuick

ShellRoot {
  Variants {
    model: Quickshell.screens

    delegate: Component {
      PanelWindow {
        property var modelData
        screen: modelData

        anchors {
          top: true
          left: true
          right: true
        }

        height: 30

        Text {
          id: clock
          anchors.centerIn: parent
        }
      }
    }
  }

  Process {
    id: dateProc
    command: ["date"]
    running: true

    stdout: SplitParser {
      onRead: data => clock.text = data
    }
  }

  Timer {
    interval: 1000
    running: true
    repeat: true
    onTriggered: dateProc.running = true
  }
}
```

--------------------------------

### QML Signal Definition Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Provides the syntax for explicitly defining a signal in QML, including optional parameters with their types. Signals act as event emitters.

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

--------------------------------

### QML Lambda Expression Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Defines the concise syntax for lambda expressions in QML, covering various parameter forms (zero, one, or multiple) and single-line or multi-line expressions.

```qml
<params> => <expression>

// params can take the following forms:
() => ... // 0 parameters
<name> => ... // 1 parameter
(<name>[, ...]) => ... // 1+ parameters

// the expression can be either a single or multiline expression.
... => <result>
... => {
  return <result>;
}
```

--------------------------------

### Connect Signal to Function in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Demonstrates how to connect a signal (e.g., `button.clicked`) to a JavaScript function (`updateText`) using the `connect()` method in QML. The function updates a counter and a label's text when the button is clicked, showcasing a fundamental way to react to user interactions.

```qml
ColumnLayout {
  property int clicks: 0

  function updateText() {
    clicks += 1;
    label.text = `the button has been clicked ${clicks} times!`;
  }

  Button {
    id: button
    text: "click me"
  }

  Text {
    id: label
    text: "the button has not been clicked"
  }

  Component.onCompleted: {
    button.clicked.connect(updateText)
  }
}
```

--------------------------------

### Declare QML Type as Singleton

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Illustrates how to declare a QML type as a singleton using `pragma Singleton` at the top of the file. It also recommends using `Singleton` as the root item for correct behavior with quickshell, allowing members to be accessed by name from other files.

```qml
pragma Singleton
import ...

Singleton { ... }
```

--------------------------------

### Hugo Main Page Template Definition

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/layouts/docs/list.html

This Go HTML template (`main.html`) serves as the primary layout for documentation pages in a Hugo site. It dynamically includes a sidebar, table of contents, and breadcrumbs. It conditionally displays the page title and renders the main page content (`.Content`). Additionally, it integrates footer components such as 'last updated', 'pager', and 'comments' partials.

```Go Template
{{ define "main" }}

{{ partial "sidebar.html" (dict "context" .) }} {{ partial "toc.html" . }}

{{ partial "breadcrumb.html" . }}

{{- if not (isset .Params "hidetitle") -}}

{{ .Title }}
============

{{- end -}} {{ .Content }}

{{ partial "components/last-updated.html" . }} {{ partial "components/pager.html" . }} {{ partial "components/comments.html" . }}

{{ end }}
```

--------------------------------

### Handle Signals Indirectly with Connections Object in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Illustrates how to use a `Connections` object to handle signals when direct definition is not possible or convenient, especially useful for connecting to signals of singletons or objects defined elsewhere. The `target` property specifies the object whose signals are being handled.

```qml
Item {
  Button {
    id: myButton
    text "click me"
  }

  Connections {
    target: myButton

    function onClicked() {
      // ...
    }
  }
}
```

--------------------------------

### Define QML Property Bindings with JavaScript Expressions

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Property bindings in Quickshell's QML allow assigning JavaScript expressions to properties. These expressions can be simple, complex, or multiline, with the last line or an explicit `return` statement defining the property's value. Bindings are reactive, updating automatically when dependencies change.

```qml
Item {
  // simple expression
  property: 5

  // complex expression
  property: 5 * 20 + this.otherProperty

  // multiline expression
  property: {
    const foo = 5;
    const bar = 10;
    foo * bar
  }

  // multiline expression with return
  property: {
    // ...
    return 5;
  }
}
```

--------------------------------

### QML Javascript Import Statement Syntax

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

This snippet details the syntax for importing external JavaScript files into a QML document. It specifies how to reference the JavaScript filename and assign a namespace under which its functions and variables will be accessible within the QML context.

```qml
import "<filename>" as <Namespace>
```

--------------------------------

### Access QML Singleton Property in a Widget

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/intro.md

This QML snippet demonstrates how a 'ClockWidget' can directly access the 'time' property from the globally available 'Time' singleton. This eliminates the need for explicit property passing or bindings, simplifying component interaction and promoting a cleaner architecture.

```QML
import QtQuick

Text {
  // we no longer need time as an input

  // directly access the time property from the Time singleton
  text: Time.time
}
```

--------------------------------

### Handle Property Change Signal with Explicit Handler in QML

Source: https://github.com/quickshell-mirror/quickshell-docs/blob/master/content/docs/configuration/qml-overview.md

Demonstrates listening for property changes using the automatically generated `<propertyname>Changed` signal (e.g., `onCheckStateChanged`). This allows reacting to changes in a property's value, such as updating a label's text based on the `CheckBox`'s `checkState` property.

```qml
ColumnLayout {
  CheckBox {
    text: "check me"

    onCheckStateChanged: {
      label.text = labelText(checkState == Qt.Checked);
    }
  }

  Text {
    id: label
    text: labelText(false)
  }

  function labelText(checked): string {
    return `the checkbox is checked: ${checked}`;
  }
}
```