Skip to content

CONFIG_GUIDE.md

Latest commit

 

History

History
76 lines (65 loc) · 2.71 KB

CONFIG_GUIDE.md

File metadata and controls

76 lines (65 loc) · 2.71 KB

Workspace Orchestrator JSON Configuration

The WorkEnvLauncher.py uses JSON files to define workspaces, applications, and their layouts across different monitor setups.

Mandatory Structure

A valid configuration must contain three top-level keys: meta, apps, and layout.

1. meta

Defines global settings for the workspace.

  • name: (String) Workspace identifier.
  • gaps: (Object)
    • outer: (Int) Margin between windows and screen edges.
    • inner: (Int) Margin between adjacent windows.
  • safe_margins: (Object)
    • top_bar: (Int) Height of the system panel (e.g., GNOME Top Bar) to avoid overlap.

2. apps

A list of applications to be launched.

  • id: (String) Unique identifier used in the layout section.
  • cmd: (String) The shell command to start the application.
  • wait: (Boolean) If true, the script waits for the window to appear before proceeding.
  • match_class: (String) Case-insensitive string to match against the window's wm_class. Mandatory if wait is true.

3. layout

Defines how windows are arranged in single and dual monitor modes.

  • single / dual: List of layout rules.
    • ref: (String) Matches the id from the apps section.
    • monitor: (String) large or small. In single mode, both resolve to the same monitor.
    • geo: (Object) Defining the window bounds:
      • x, y, w, h: (String/Int) Supports percentages (e.g., "50%") or absolute pixels.
    • layer: (String) Optional.
      • maximize: Maximizes the window after moving.
      • top: Focuses/Activates the window.
    • workspace: (String) Note: Currently present in config but ignored by the launcher script.

Feature Support

Percentage Geometry

The geo values can be strings ending in %. The script automatically calculates the pixel values based on the target monitor's dimensions.

Smart Gaps

The engine automatically distinguishes between "outer" gaps (touching the screen edge) and "inner" gaps (between windows) to ensure a perfectly symmetrical layout.

Top Bar Awareness

If a window is placed at the top of the primary monitor (y: 0), the top_bar margin is automatically applied to prevent the window from being hidden under the system panel.

Example

{
  "meta": {
    "name": "example",
    "gaps": { "outer": 4, "inner": 6 },
    "safe_margins": { "top_bar": 32 }
  },
  "apps": [
    {
      "id": "browser",
      "cmd": "firefox",
      "match_class": "firefox",
      "wait": true
    }
  ],
  "layout": {
    "single": [
      {
        "ref": "browser",
        "monitor": "large",
        "geo": { "x": "0%", "y": "0%", "w": "100%", "h": "100%" },
        "layer": "maximize"
      }
    ],
    "dual": []
  }
}