| 1 |
# Settings Window |
| 2 |
|
| 3 |
tarmac includes a native macOS settings window for adjusting configuration visually. Open it from the [system tray](/docs/system-tray) menu by clicking **Settings...**. |
| 4 |
|
| 5 |
<div className="screenshot-placeholder"> |
| 6 |
<p className="text-lg font-medium mb-2">Screenshot: Settings window</p> |
| 7 |
<p className="text-sm">The tarmac settings window showing the General tab</p> |
| 8 |
<p className="text-xs mt-4 italic">[ placeholder — add settings-window.png to public/ ]</p> |
| 9 |
</div> |
| 10 |
|
| 11 |
## Tabs |
| 12 |
|
| 13 |
The settings window has four tabs: **General**, **Keybindings**, **Rules**, and **About**. |
| 14 |
|
| 15 |
## General tab |
| 16 |
|
| 17 |
The General tab provides live controls for all core settings. Changes take effect immediately and are persisted to your `~/.config/tarmac/init.lua`. |
| 18 |
|
| 19 |
### Layout section |
| 20 |
|
| 21 |
| Control | Range | Description | |
| 22 |
|---------|-------|-------------| |
| 23 |
| Inner Gap | 0–50px (slider) | Space between adjacent windows | |
| 24 |
| Outer Gap | 0–50px (slider) | Space between windows and screen edges | |
| 25 |
| Bar Height | 0–60px (slider) | Reserved space at top for external status bars | |
| 26 |
|
| 27 |
### Borders section |
| 28 |
|
| 29 |
| Control | Range | Description | |
| 30 |
|---------|-------|-------------| |
| 31 |
| Width | 0–10px (slider) | Border thickness. 0 disables ers. | |
| 32 |
| Radius | 0–30px (slider) | Corner radius for borders | |
| 33 |
| Focused Color | color picker | Border color for the focused window | |
| 34 |
| Unfocused Color | color picker | Border color for unfocused windows | |
| 35 |
|
| 36 |
### Behavior section |
| 37 |
|
| 38 |
| Control | Type | Description | |
| 39 |
|---------|------|-------------| |
| 40 |
| Focus follows mouse | checkbox | Auto-focus window under cursor | |
| 41 |
| Mouse follows focus | checkbox | Warp cursor to newly focused window | |
| 42 |
|
| 43 |
### Modifier key |
| 44 |
|
| 45 |
A dropdown to select the primary modifier key: |
| 46 |
- **Command** (default) |
| 47 |
- **Option** |
| 48 |
- **Control** |
| 49 |
|
| 50 |
## Keybindings tab |
| 51 |
|
| 52 |
Displays all currently configured keybindings in a read-only list. Shows the key combination and action side by side. |
| 53 |
|
| 54 |
If no keybindings are configured in your Lua config, it shows "No keybindings configured." (the built-in defaults still work but aren't displayed here since they're implicit). |
| 55 |
|
| 56 |
## Rules tab |
| 57 |
|
| 58 |
Displays all window rules in a read-only list. Shows match criteria and actions. |
| 59 |
|
| 60 |
If no rules are defined, it shows "No window rules configured." |
| 61 |
|
| 62 |
## About tab |
| 63 |
|
| 64 |
Shows: |
| 65 |
- Application name and version (from Cargo.toml) |
| 66 |
- Build info: "Rust 2024 edition · objc2 + SkyLight" |
| 67 |
- GitHub repository link |
| 68 |
- Config file path (`~/.config/tarmac/init.lua`) |
| 69 |
|
| 70 |
## Persistence |
| 71 |
|
| 72 |
When you change a setting through the GUI: |
| 73 |
|
| 74 |
1. The change takes effect immediately (layout is recalculated, borders are updated, etc.) |
| 75 |
2. The corresponding `gar.set()` line in your `init.lua` is updated via regex pattern matching |
| 76 |
3. If the setting line doesn't exist in your config file, the change is applied in memory but not written to disk |
| 77 |
|
| 78 |
This means the settings window works best when your `init.lua` already contains `gar.set()` calls for the settings you want to adjust. Example: |
| 79 |
|
| 80 |
```lua |
| 81 |
-- These lines will be updated by the settings window |
| 82 |
gar.set("gap_inner", "8") |
| 83 |
gar.set("gap_outer", "8") |
| 84 |
gar.set("border_width", "4") |
| 85 |
gar.set("border_color_focused", "#5294e2") |
| 86 |
gar.set("focus_follows_mouse", "true") |
| 87 |
``` |
| 88 |
|
| 89 |
If you later open the settings window and change the inner gap to 12, the line becomes: |
| 90 |
|
| 91 |
```lua |
| 92 |
gar.set("gap_inner", "12") |
| 93 |
``` |
| 94 |
|
| 95 |
## Opening the settings window |
| 96 |
|
| 97 |
The settings window is opened from the tray menu (**Settings...**). If the window is already open, clicking Settings again brings it to the front. |
| 98 |
|
| 99 |
The window is non-modal — you can continue using other apps while it's open. |
| 100 |
|