Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

QML Components Overview

Fern Shell's UI is built with QML (Qt Modeling Language) using the QuickShell framework.

Component Architecture

shell.qml                    # Entry point
├── bar/
│   ├── BarWrapper.qml      # Expand/collapse state machine
│   ├── BarInteractions.qml # Mouse hover detection
│   ├── Bar.qml             # Module layout
│   ├── Border.qml          # Curved screen frame
│   └── Backgrounds.qml     # Bar background
├── components/
│   ├── StyledRect.qml      # Base animated rectangle
│   └── ModuleContainer.qml # Pill-shaped container
├── modules/
│   ├── Clock.qml           # Time display
│   └── Workspaces.qml      # Workspace indicators
├── services/
│   └── Hyprland.qml        # Hyprland IPC integration
└── config/
    ├── Theme.qml           # Design token singleton
    └── ConfigLoader.qml    # TOML configuration loader

Key Patterns

Singleton Services

Theme and Hyprland are singletons accessed via imports:

import "../config" as Config
import "../services" as Services

// Usage
color: Config.Theme.accent
activeWorkspace: Services.Hyprland.activeWsId

Required Properties

Components declare explicit dependencies:

Item {
    required property ShellScreen screen
    required property Item bar
}

Reactive Bindings

State flows through property bindings, not imperative updates:

// This automatically updates when bar.implicitWidth changes
width: bar.implicitWidth

Sections