105 lines
6.2 KiB
Markdown
105 lines
6.2 KiB
Markdown
# Midra Layout application settings, version 3
|
||
|
||
Implementation: `crates/midra-layout/src/settings.rs`. This per-user JSON file is
|
||
independent of the [project JSON and SVG contracts](midra-layout.md).
|
||
[Complete default example](midra-layout-settings-v3.example.json).
|
||
Version 1 files migrate automatically: the saved theme becomes the only entry in
|
||
`recent_themes`, with all other preferences preserved. The [version 1 example](midra-layout-settings-v1.example.json)
|
||
remains a migration fixture. Version 2 files then migrate by adding disabled
|
||
snapping with all target types enabled. The [version 2 example](midra-layout-settings-v2.example.json)
|
||
remains a migration fixture too. Saving writes version 3; old applications reject it.
|
||
|
||
The `directories` 6 crate resolves `ProjectDirs::from("org", "beffroi", "midra-layout")`.
|
||
The filename is `settings.json` beneath `config_dir()`:
|
||
|
||
| Platform | Location |
|
||
| --- | --- |
|
||
| Linux | `$XDG_CONFIG_HOME/midra-layout/settings.json`, otherwise `~/.config/midra-layout/settings.json` |
|
||
| Windows | `%APPDATA%\beffroi\midra-layout\config\settings.json` (Roaming AppData) |
|
||
| macOS | `~/Library/Application Support/org.beffroi.midra-layout/settings.json` |
|
||
|
||
UTF-8, pretty-printed JSON with a trailing newline; maximum input size 64 KiB.
|
||
Every field is required, unknown fields are rejected, and unknown versions or
|
||
unknown theme names are rejected. There are no numeric coordinates or units.
|
||
|
||
| Field | Values / default |
|
||
| --- | --- |
|
||
| `version` | Integer `3` |
|
||
| `theme` | Theme ID from the catalog below; default `"midra"` |
|
||
| `recent_themes` | 1–3 unique theme IDs, newest first; first must equal `theme`; default `["midra"]` |
|
||
| `show_toolbar_icon_names` | Boolean; default false |
|
||
| `keep_aspect_ratio` | Boolean; default true |
|
||
| `show_source_pattern` | Boolean; default false |
|
||
| `snapping` | Object with required boolean fields `enabled` (false), `pixels` (true), `screen_edges` (true), `layer_edges` (true); unknown fields rejected |
|
||
|
||
Loaded once at startup before the editor appears. Explicit Options changes save
|
||
the current preferences and theme history immediately. The directory is created lazily;
|
||
missing files do not trigger a write until the user changes an option. Writes
|
||
use a temporary file in the same directory, file sync and atomic replacement.
|
||
Multiple application instances use last-successful-write wins; no merging or
|
||
live reloading is performed. Selecting a theme moves it to the front, removes any
|
||
previous occurrence, and trims the list to three. Starting the app does not reorder
|
||
the restored history. Opening or dismissing the full picker changes nothing.
|
||
|
||
Project JSON v1/v2 remains unchanged. Opening a project can restore its embedded
|
||
caption, aspect-ratio and source-preview preferences for that document; it never
|
||
writes application settings. Theme remains global. Editing an option afterward
|
||
saves all currently active preferences as the next startup defaults. Snapping remains
|
||
an application preference and is not read from or written into project JSON.
|
||
|
||
Invalid/unreadable settings fall back to defaults, report the failure in Options,
|
||
and disable writes for that run to preserve the original file. Repair/move the
|
||
file and restart to recover. A write failure retains in-memory preferences and
|
||
the previous destination where atomic publication failed; Options offers a retry.
|
||
Failure to locate a configuration directory also disables persistence with an
|
||
Options error. Tests use temporary directories and never touch user settings.
|
||
|
||
No layer geometry, source crops, camera state, project paths, image bytes, device
|
||
addresses or clipboard contents are stored. No settings are exported to SVG.
|
||
Breaking or additive schema changes under this strict contract require a version
|
||
bump, updated documentation/examples/tests, and either an explicit migration or
|
||
an actionable unsupported-version error.
|
||
|
||
## Bundled theme catalog
|
||
|
||
All 18 CSS themes in `SOTV_Websites/sotv/song_database/styles/themes/` are
|
||
represented, alongside Midra Dark. Palettes are bundled in `src/theme.rs`:
|
||
no sibling checkout or CSS interpreter is required at build or runtime. Corporate
|
||
uses the website's base defaults. The existing three palettes retain their
|
||
hand-tuned viewport colors; other palettes map body/panel/sidebar/tab surfaces,
|
||
main/subtle text, button accent and border tokens into the editor. Action fills
|
||
blend accent and panel; light-theme text/accent colors are darkened for contrast.
|
||
The picker includes both light and dark themes with color swatches.
|
||
|
||
| Theme | Settings ID | Source CSS |
|
||
| --- | --- | --- |
|
||
| Midra Dark | `midra` | Original editor palette |
|
||
| Corporate Light | `corporate_light` | `theme-corporate.css` and `../base/variables.css` |
|
||
| Foxified Dark | `foxified_dark` | `theme-foxified-dark.css` |
|
||
| Bluecore | `bluecore` | `theme-bluecore.css` |
|
||
| Dupont Monsanto | `dupont_monsanto` | `theme-dupont-monsanto.css` |
|
||
| Eden Green | `eden_green` | `theme-eden-green.css` |
|
||
| Foxified Light | `foxified_light` | `theme-foxified-light.css` |
|
||
| HCI | `hci` | `theme-hci.css` |
|
||
| Iron Docks | `iron_docks` | `theme-iron-docks.css` |
|
||
| Peaceframe | `peaceframe` | `theme-peaceframe.css` |
|
||
| Rebel | `rebel` | `theme-rebel.css` |
|
||
| Sirius Mind | `sirius_mind` | `theme-sirius-mind.css` |
|
||
| Solarized | `solarized` | `theme-solarized.css` |
|
||
| Sons Of Banard | `sons_of_banard` | `theme-sons-of-banard.css` |
|
||
| Storm Pilot | `storm_pilot` | `theme-storm-pilot.css` |
|
||
| Tessier Ashpol | `tessier_ashpol` | `theme-tessier-ashpol.css` |
|
||
| USTF | `ustf` | `theme-ustf.css` |
|
||
| Verdant Rebel | `verdant_rebel` | `theme-verdant-rebel.css` |
|
||
| Weicat Industrial | `weicat_industrial` | `theme-weicat-industrial.css` |
|
||
|
||
The Preferences window and quick menus share the same settings. Changes apply
|
||
and save immediately; closing the window requires no Apply step. Restore default
|
||
preferences resets all values, including theme history and snapping, without
|
||
changing layer geometry or pending position/size text fields. Snapping uses a
|
||
fixed six-logical-pixel proximity radius converted by viewport scale. It affects
|
||
layer movement and resize handles; numeric entry, nudges and crop-content gestures
|
||
bypass it. Resize snapping preserves anchors and proportions and shows guides only
|
||
when the resulting edge actually reaches its target.
|
||
Alt temporarily disables it without changing the saved option.
|