278 lines
13 KiB
Markdown
278 lines
13 KiB
Markdown
# Configuration
|
||
|
||
Edit `~/.config/ferese/config.toml` (or `$XDG_CONFIG_HOME/ferese/config.toml`),
|
||
or open **Control Center → Settings**. Start with the [example](../packaging/config.toml).
|
||
All supported configuration sections are listed below; [desktop widgets](desktop-widgets.md)
|
||
covers the complete clock and sticky-note fields separately.
|
||
|
||
## Saving and validation
|
||
|
||
Settings saves automatically: text on Enter/focus loss, sliders when released.
|
||
Undo restores the previous save; Reload picks up external edits without merging
|
||
unfinished drafts. Wallpaper browsing needs `zenity`; a path can also be entered.
|
||
Settings keeps `config.toml.settings-backup` before saving.
|
||
|
||
File edits reload automatically, including atomic editor saves. Invalid changes
|
||
keep the last working configuration. Appearance, wallpaper, motion, input,
|
||
bindings, rules, layouts, displays, widgets and login items update live.
|
||
|
||
```sh
|
||
feresectl reload-config # reload with error feedback
|
||
ferese --check-config PATH # validate without applying
|
||
ferese-settings --config PATH # edit a separate preview config
|
||
```
|
||
|
||
Defaults below are built-in defaults, not your personal or packaged overrides.
|
||
Dimensions are logical pixels unless noted; numbers must be finite. Optional
|
||
values are omitted, not `null`. Colors use `#RRGGBB` or `#RRGGBBAA`.
|
||
Live config is limited to 60 KiB.
|
||
|
||
## Layout
|
||
|
||
| `[layout]` key | Type / values | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `mode` | `"scrolling"`, `"tree"` | `"scrolling"` | Workspace layout |
|
||
| `inner_gap` | number ≥ 0 | `10` | Between windows |
|
||
| `outer_gap` | number ≥ 0 | `4` | Around workspace edges |
|
||
| `smart_gaps` | boolean | `false` | Remove outer gaps for one tiled window |
|
||
|
||
| `[scrolling]` key | Type / values | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `default_column_width` | proportion > 0; or `"full"` | `0.5` | Width of new columns |
|
||
| `focus_strategy` | `"minimal"`, `"center_on_focus"`, `"paged"` | `"minimal"` | Viewport movement on focus |
|
||
| `width_presets` | array of widths | `[0.3333333333333333, 0.5, 0.6666666666666666, "full"]` | Super+R cycle; empty uses defaults |
|
||
|
||
`minimal` scrolls only to reveal the focused window. `center_on_focus` centers
|
||
it. `paged` packs columns into viewport-sized pages: halves form pairs, thirds
|
||
form triples; mixed widths and client minimum sizes determine actual boundaries.
|
||
Changing default width preserves manually resized columns.
|
||
|
||
## Motion
|
||
|
||
| Section / key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `animations.enabled` | boolean | `true` | Enable motion |
|
||
| `animations.reduced_motion` | boolean | `false` | Disable animated motion |
|
||
| `animations.speed` | number > 0 | `1` | Higher is faster; `0.75` is slower |
|
||
| `animations.spring.mass` | number > 0 | `1` | Window-motion spring mass |
|
||
| `animations.spring.stiffness` | number > 0 | `700` | Spring stiffness |
|
||
| `animations.spring.damping` | number ≥ 0 | `53` | Spring damping |
|
||
| `animations.viewport_spring.mass` | number > 0 | `1` | Scrolling spring mass |
|
||
| `animations.viewport_spring.stiffness` | number > 0 | `320` | Scrolling stiffness |
|
||
| `animations.viewport_spring.damping_ratio` | number > 0 | `1` | `1` is critically damped |
|
||
|
||
## Appearance
|
||
|
||
| Section / key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `appearance.corner_radius` | number ≥ 0 | `14` | Shell material/card radius |
|
||
| `appearance.inactive_dim.enabled` | boolean | `false` | Dim unfocused windows |
|
||
| `appearance.inactive_dim.amount` | number 0–1 | `0.15` | Darkening strength |
|
||
| `appearance.inactive_dim.duration_ms` | number ≥ 0 | `150` | Dimming and focus-ring transition; 0 snaps |
|
||
| `theme.typography.font_family` | string | system sans-serif | Shell, Settings and overview font |
|
||
| `theme.background.path` | string | omitted | Wallpaper image path |
|
||
| `theme.background.mode` | `"fill"`, `"fit"` | `"fill"` | Crop or letterbox |
|
||
| `theme.material.style` | `"solid"`, `"translucent"` | `"solid"` | Shell background material |
|
||
| `theme.material.blur_radius` | number ≥ 0 | `12` | Translucent backdrop blur, capped at 32; 0 disables |
|
||
|
||
| `[theme.colors]` key | Default | Meaning |
|
||
| --- | --- | --- |
|
||
| `surface_base` | `"#111821"` | Material/card base color |
|
||
| `text_primary` | `"#F4F7FB"` | Main text |
|
||
| `text_muted` | `"#7F8A98"` | Secondary text |
|
||
| `accent` | `"#5B8CFF"` | Active controls and solid focus ring |
|
||
| `border` | `"#FFFFFF18"` | Unfocused window border |
|
||
| `shadow` | `"#00000055"` | Window shadow color |
|
||
|
||
| `[theme.geometry]` key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `border_width` | number ≥ 0 | `1` | Window border thickness |
|
||
| `focus_ring_width` | number ≥ 0 | `2` | Focused border thickness |
|
||
| `window_radius` | number ≥ 0 | `14` | Managed-window corners |
|
||
| `top_bar_height` | number > 0 | `28` | Menu-bar height |
|
||
| `top_bar_margin_top` | integer ≥ 0 | `0` | Space above bar |
|
||
| `top_bar_window_gap` | integer ≥ 0 | `0` | Clearance below bar |
|
||
| `top_bar_margin_horizontal` | integer ≥ 0 | `0` | Bar side margins |
|
||
| `top_bar_radius` | number ≥ 0 | `0` | Bar corners |
|
||
| `panel_padding` | number ≥ 0 | `12` | Bar inner padding |
|
||
| `control_gap` | number ≥ 0 | `12` | Right-side control spacing |
|
||
|
||
| Section / key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `theme.surface.bar.background` | color | `"#1C202EF2"` | Shell fallback background; compositor materials use `surface_base` |
|
||
| `theme.surface.bar.opacity` | number 0–1 | omitted | Material opacity defaults to `0.78`; fallback retains background alpha |
|
||
| `theme.surface.bar.text_primary` | color | `"#F0F3FA"` | Bar text/icons |
|
||
| `theme.surface.bar.text_muted` | color | `"#AAB4C7"` | Inactive bar foreground |
|
||
| `theme.surface.popover.opacity` | number 0–1 | `0.96` | Shell popover fill alpha |
|
||
| `theme.shadow.soft.offset_y` | number | `4` | Window shadow vertical offset |
|
||
| `theme.shadow.soft.blur` | number ≥ 0 | `18` | Window shadow softness |
|
||
| `theme.shadow.soft.opacity` | number 0–1 | `0.20` | Window shadow strength |
|
||
|
||
Solid materials omit blur; translucent materials blur behind the surface color.
|
||
True fullscreen removes decorations. Focus transitions never scale the content.
|
||
|
||
Optional `[theme.focus_ring.gradient]` and `[theme.border.gradient]` use the same
|
||
keys: required `from` and `to` colors, and `angle` (number, default `0`). Angles
|
||
are clockwise: 0 is left-to-right, 90 top-to-bottom. Omit the gradient section
|
||
for solid `accent` or `border` colors.
|
||
|
||
```toml
|
||
[theme.focus_ring.gradient]
|
||
from = "#e5c890"
|
||
to = "#b98d58"
|
||
angle = 135.0
|
||
```
|
||
|
||
## Input
|
||
|
||
| `[input]` key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `focus_follows_mouse` | boolean | `false` | Focus windows under the pointer |
|
||
| `xkb_layout` | nonempty string | `"us"` | XKB layout |
|
||
| `xkb_variant` | string | `""` | XKB variant |
|
||
| `xkb_options` | string array | `[]` | XKB options |
|
||
| `repeat_rate` | integer > 0 | `25` | Repeats per second |
|
||
| `repeat_delay_ms` | integer ≥ 0 | `600` | Delay before repeat |
|
||
|
||
`[input.touchpad]` has three boolean keys, all defaulting to `true`: `tap`,
|
||
`natural_scroll` and `disable_while_typing`. These apply to DRM devices; nested
|
||
previews use the host's physical input settings.
|
||
|
||
## Commands and bindings
|
||
|
||
`[commands]` maps arbitrary names to nonempty argument arrays. The built-in
|
||
`terminal = ["foot"]` can be overridden. Commands run directly, without a shell.
|
||
|
||
| `[[bindings]]` key | Type / values | Default |
|
||
| --- | --- | --- |
|
||
| `keys` | chord string, e.g. `"Super+Enter"` | required |
|
||
| `match` | `"keysym"`, `"physical"` | `"keysym"` |
|
||
| `action` | action name below | required unless disabled |
|
||
| `argument` | string | required only for actions listed below |
|
||
| `disabled` | boolean | `false` |
|
||
|
||
Modifiers: `Super`/`Logo`/`Mod4`, `Ctrl`/`Control`, `Alt`, `Shift`.
|
||
Keys use XKB keysyms (`Enter`, letters, `[`/`]`) or physical XKB names (`AD06`).
|
||
A binding replaces the same normalized chord/match mode. Duplicate bindings are
|
||
invalid. A disabled binding must omit `action` and `argument`.
|
||
|
||
| Actions | Argument |
|
||
| --- | --- |
|
||
| `spawn` | Name in `[commands]` |
|
||
| `focus`, `move`, `resize` | `"left"`, `"right"`, `"up"`, `"down"` |
|
||
| `workspace`, `move-to-workspace` | Workspace number string, 1–255 |
|
||
| `close`, `exit`, `toggle-maximized`, `toggle-fullscreen`, `toggle-layout`, `cycle-column-width`, `center-column`, `consume`, `expel`, `toggle-floating`, `toggle-overview` | None |
|
||
|
||
```toml
|
||
[commands]
|
||
terminal = ["foot"]
|
||
|
||
[[bindings]]
|
||
keys = "Super+Enter"
|
||
action = "spawn"
|
||
argument = "terminal"
|
||
```
|
||
|
||
Defaults: Super+Enter terminal; Super+Q close; Super+H/J/K/L focus;
|
||
Super+Shift+H/J/K/L move; Super+Ctrl+H/J/K/L resize; Super+1–9 workspace;
|
||
Super+Shift+1–9 move to workspace; Super+R width cycle; Super+C center;
|
||
Super+[/] consume/expel; Super+F maximize; Super+Shift+F fullscreen;
|
||
Super+M layout; Super+Shift+Space floating; Super+Tab overview;
|
||
Super+Shift+E immediate logout.
|
||
|
||
## Window rules
|
||
|
||
| `[[window_rules]]` key | Type | Default / meaning |
|
||
| --- | --- | --- |
|
||
| `app_id` | nonempty string | Optional exact match; case-insensitive, `.desktop` suffix ignored |
|
||
| `title` | nonempty string | Optional exact, case-sensitive match |
|
||
| `transient` | boolean | Optional parent-dialog match |
|
||
| `workspace` | integer > 0 | Leave placement unchanged |
|
||
| `floating` | boolean | Leave placement unchanged |
|
||
| `width`, `height` | numbers > 0 | Application-chosen floating size |
|
||
| `fullscreen` | boolean | Leave fullscreen state unchanged |
|
||
|
||
At least one matcher is required; supplied matchers must all match. Rules apply
|
||
in order, with later fields overriding earlier ones. Dimensions imply floating
|
||
when `floating` is omitted. Floating apps without dimensions choose their own
|
||
size and open centered on the output. Title changes do not trigger new rules;
|
||
config rule changes apply to existing windows.
|
||
|
||
```toml
|
||
[[window_rules]]
|
||
app_id = "dev.ferese.Settings"
|
||
floating = true
|
||
```
|
||
|
||
## Displays
|
||
|
||
`[[output_profiles]]` has a required unique nonempty `name` and one or more
|
||
`[[output_profiles.outputs]]` entries. The first profile whose listed monitors
|
||
are connected wins. Find connector names and persistent identities using
|
||
`feresectl get-outputs`.
|
||
|
||
| `[[output_profiles.outputs]]` key | Type | Default |
|
||
| --- | --- | --- |
|
||
| `match` | nonempty connector or persistent identity string | required; unique within profile |
|
||
| `enabled` | boolean | `true` |
|
||
| `mode` | `"WIDTHxHEIGHT"` or `"WIDTHxHEIGHT@HZ"` | Preferred mode |
|
||
| `scale` | number > 0 | `1` |
|
||
| `transform` | enum below | `"normal"` |
|
||
| `position` | `[integer, integer]` | Automatic horizontal placement |
|
||
|
||
Transforms: `normal`, `rotate_90`, `rotate_180`, `rotate_270`, `flipped`,
|
||
`flipped_90`, `flipped_180`, `flipped_270`. Unspecified connected displays stay
|
||
enabled with defaults. Disabling every usable output is rejected.
|
||
|
||
```toml
|
||
[[output_profiles]]
|
||
name = "docked"
|
||
|
||
[[output_profiles.outputs]]
|
||
match = "HDMI-A-1"
|
||
scale = 1.5
|
||
position = [0, 0]
|
||
```
|
||
|
||
With a usable external display, closing the lid disables internal panels.
|
||
Workspaces move to a remaining display and return when their original output
|
||
returns. Ferese does not change the system's suspend policy.
|
||
|
||
## Status controls
|
||
|
||
| `[status]` key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `battery_percentage` | boolean | `true` | Show percentage beside icon |
|
||
| `low_battery_threshold` | integer 0–100 | `20` | Warning-color threshold |
|
||
| `settings_command` | argument array | `["ferese-settings"]` | Settings launcher; `[]` hides the action |
|
||
|
||
## Login items and locking
|
||
|
||
| `[[autostart]]` key | Type | Default | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `command` | nonempty argument array | required | Foreground process, not a self-daemonizing command |
|
||
| `enabled` | boolean | `true` | Start service |
|
||
| `restart` | boolean | `true` | Restart after exit, with a five-second retry delay |
|
||
| `nested` | boolean | `false` | Also run in nested previews |
|
||
|
||
Unchanged services keep running on reload; removed/disabled items stop. To lock
|
||
after five minutes and before sleep:
|
||
|
||
```toml
|
||
[[autostart]]
|
||
command = ["swayidle", "-w", "timeout", "300", "ferese-lock", "before-sleep", "ferese-lock", "lock", "ferese-lock"]
|
||
```
|
||
|
||
`ferese-lock` uses swaylock/swaylock-effects and optional
|
||
`~/.config/ferese/swaylock.conf`. Test unlock in a nested preview before enabling
|
||
automatic locking. A crashed locker leaves the session locked; recovery requires
|
||
ending the session from another TTY.
|
||
|
||
## Optional session protocols
|
||
|
||
These are launch-time environment switches, not TOML keys. Enable only for
|
||
trusted clients: `FERESE_ENABLE_INPUT_METHOD=1`,
|
||
`FERESE_ENABLE_SHORTCUT_INHIBIT=1`, `FERESE_ENABLE_SCREENCOPY=1`.
|
||
Text input is available by default; Ctrl+Alt+Escape releases an active shortcut
|
||
inhibitor. Use `feresectl --help` for runtime control commands.
|