gargears

Overview

gargears is the central settings application for the gardesk desktop, providing unified configuration management across all ecosystem components. It serves a similar role to GNOME Settings or KDE System Settings, but tailored for the gardesk environment.

The application is built around a panel system where each gardesk component has a dedicated configuration panel. Panels communicate with running daemons via IPC adapters to read current values and apply changes in real-time. For persistence, gargears writes configuration files in the appropriate format (Lua for gar/garbar, TOML for others).

With over 4,400 lines of panel implementations, gargears provides comprehensive configuration coverage including widgets for every setting type: toggles, number inputs with range validation, color pickers with hex input and live preview, dropdown menus, text inputs, and collapsible sections.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        gargears                              │
│                                                              │
│  ┌────────────┐   ┌─────────────┐   ┌──────────────────┐   │
│  │   Sidebar  │   │   Panel     │   │    Status Bar    │   │
│  │ (nav list) │   │ (content)   │   │ (dirty/connected)│   │
│  └─────┬──────┘   └──────┬──────┘   └────────┬─────────┘   │
│        │                 │                    │             │
│  ┌─────┴─────────────────┴────────────────────┴─────────┐  │
│  │                    Panel Manager                      │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │  │
│  │  │ GarPanel│ │BarPanel │ │ BgPanel │ │ LockPanel   │ │  │
│  │  │ ... x11 │ │ modules │ │slideshow│ │ timeout/blur│ │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └──────┬──────┘ │  │
│  └───────┼───────────┼───────────┼─────────────┼────────┘  │
│          │           │           │             │            │
│  ┌───────┴───────────┴───────────┴─────────────┴────────┐  │
│  │                   IPC Adapter Layer                   │  │
│  │  GarAdapter  GarbarAdapter  GarbgAdapter  GarlockAdapter│
│  └────────────────────────┬─────────────────────────────┘  │
│                           │                                 │
└───────────────────────────┼─────────────────────────────────┘
                            │ Unix Sockets
          ┌─────────────────┼─────────────────────┐
          ▼                 ▼                     ▼
     ┌────────┐       ┌──────────┐         ┌──────────┐
     │  gar   │       │  garbar  │         │  garbg   │
     │ daemon │       │  daemon  │         │  daemon  │
     └────────┘       └──────────┘         └──────────┘

GUI Mode

In GUI mode (default), gargears runs as a standard application with a single lifecycle:

1. User launches gargears
2. Window opens, connects to all running component daemons
3. IPC adapters query current configuration values
4. Panels render with current values populated
5. User navigates panels and modifies settings
6. Apply sends changes via IPC (immediate effect)
7. Save writes to configuration file (persistent)
8. User closes window, gargears exits

This mode is suitable for occasional configuration changes where startup time isn't critical.

Daemon Mode

Daemon mode keeps gargears running in the background with the window hidden by default. This provides instant access via keybindings without startup delay:

1. Start daemon: gargears --daemon
2. Daemon forks to background (unless --no-fork)
3. Window is created but hidden
4. IPC server listens on Unix socket
5. User presses keybinding (e.g., Super+comma)
6. Keybinding runs gargearsctl toggle
7. Window appears instantly (no startup delay)
8. User makes changes, presses Escape to hide
9. Window hides, daemon continues running
10. Subsequent toggle shows window immediately

The daemon checks for existing instances before starting, preventing multiple daemons. Stale socket files are automatically cleaned up.

Panel System

Each panel implements a common Panel trait defining 14 methods for a consistent interface:

• name(), description() - Panel identity for sidebar navigation
• is_dirty() - Check for unsaved changes
• render() - Draw panel content with gartk-render
• handle_event() - Process keyboard/mouse input, return PanelAction
• on_mouse_move() - Handle hover states, return true if redraw needed
• blur_focused() - Clear focus when switching panels
• reset() - Revert to original values
• apply() - Send changes via IPC
• update_status() - Receive daemon status updates
• save_to_config() - Write to configuration file
• instant_apply_enabled(), apply_instant() - Real-time change support

The panel manager coordinates these methods, handling navigation, action routing, and status synchronization.

IPC Adapters

Adapter Pattern

Each gardesk component has a corresponding IPC adapter in gargears. Adapters translate between the panel's UI needs and the component's IPC protocol:

• is_connected() - Check if component daemon is reachable
• status() - Query current configuration values
• Command methods - Send specific commands (show, hide, lock, next, etc.)
• subscribe() - Register for event notifications
• poll_events() - Retrieve pending events

Connection Handling

Adapters implement robust connection management:

• 5-second timeout for socket operations
• Exponential backoff for reconnection attempts
• should_reconnect() checks if reconnection is due
• reset_backoff() resets timing on successful connection
• Graceful fallback to defaults when component not running

When a component isn't running, the panel shows default values and the connection status indicator turns red. Changes can still be saved to config files for later.

Event Subscriptions

Some adapters (like GarbgAdapter) support event subscriptions for real-time updates:

This enables the wallpaper panel to show current wallpaper updates without polling.

Config Writers

Lua Writer

The Lua writer generates configuration for gar and garbar, which use Lua for maximum flexibility. It produces human-readable output that integrates with the existing init.lua structure:

-- Generated by gargears

gar.bar = {
    height = 28,
    position = "top",
    modules = {
        left = { "workspaces", "title" },
        center = { "clock" },
        right = { "cpu", "memory", "battery", "tray" },
    },
}

TOML Writer

Most components use TOML configuration. The writer produces clean, minimal output using serde with skip_serializing_if to omit unset optional values:

# ~/.config/garbg/config.toml

[[sources]]
type = "directory"
path = "~/Pictures/Wallpapers"
recursive = true

[slideshow]
enabled = true
interval_secs = 300
shuffle = true

[animation]
transition = "fade"
duration_ms = 500

XDG paths are resolved correctly (XDG_CONFIG_HOME or ~/.config fallback), and parent directories are created as needed.

Widget System

gargears provides a rich widget library for building configuration panels:

Basic Widgets

All widgets implement consistent 4-state visual feedback:

• Normal - Default appearance
• Hovered - Mouse over, subtle highlight
• Focused - Keyboard focus, blue border
• Disabled - Grayed out, non-interactive

Standard dimensions: 36px row height, 32px section headers, 16px indentation for nested content.

Color Picker

The color picker widget combines a 100px hex input field with a 24x24px live preview square:

• Accepts 6-digit (#RRGGBB) or 8-digit (#RRGGBBAA) hex colors
• Input validation filters to hex digits and # only
• Text cursor with Home/End/Left/Right navigation
• Checkerboard pattern background shows transparency
• Emits Changed event when value updates

Collapsible Sections

Section widgets group related settings and can be expanded/collapsed:

• Click header or arrow to toggle
• Remembers expanded state within session
• 32px header height with icon and label
• 16px indentation for child widgets
• Common sections: Status, Settings, Actions

Apply Modes

gargears supports multiple ways to apply configuration changes:

Instant Apply is particularly useful for visual settings like bar visibility or wallpaper changes, providing immediate feedback as users adjust controls.