Deckstride/docs/interfaces/settings.md

102 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Native settings, version 1
`settings.toml` is stored in `$XDG_CONFIG_HOME/pdf-presenter` (otherwise
`~/.config/pdf-presenter`) on Linux. `directories::ProjectDirs` with qualifier `com`,
organization `Beffroi`, application `PdfPresenter` supplies other platforms' standard
per-user config/cache directories. The UI reports the actual configuration path.
There is no separate project file or source-side settings write.
The top-level `version = 1` is mandatory semantically (omitted defaults to 1).
Unknown versions fail clearly; malformed settings fall back to in-memory defaults
with an error, without rewriting the bad file. Missing files use defaults. Reads are
bounded to 4 MiB. Writes validate then atomically replace using a same-directory
flushed temporary file. Unknown fields are ignored and not preserved on round trip.
- `zoom_enabled`: boolean, default false, added in 0.1.54. Global opt-in for
presenter/current-slide and output zoom gestures. Missing fields in older v1
files retain normal non-zoom behavior. Menu → Preferences saves this setting
immediately. Crop/scale, gesture serials and warning state are transient and are
never saved in global/project layouts; each newly opened slide starts fitted.
- `slide_colors.page_background` and `slide_colors.fit_padding`: opaque sRGB
arrays of exactly three integers, each 0–255, added in 0.1.26. Defaults are
`[255, 255, 255]` (white beneath transparent slide pixels) and `[0, 0, 0]`
(black around the aspect-fitted slide). Missing tables/fields in older v1 files
use these defaults; malformed lengths/out-of-range channels fail deserialization.
Both are global, round-trip unchanged, persist asynchronously and apply immediately
to all previews and audience windows. They do not alter source or cached pixels,
project layouts, or manual/emergency black blanking.
- `auto_show`: boolean, default true (0.1.14). Enables output on startup and successful
document open; false starts/opens blanked. Manual navigation preserves blanking.
Since 0.1.51, display topology/fullscreen changes and host recovery preserve
the current output visibility; only explicit blank controls change it.
- `theme`: built-in palette enum in snake_case, default `midra` (0.1.14). Values:
`midra`, `high_contrast`, `foxified_dark`, `corporate_light`, `bluecore`,
`dupont_monsanto`, `eden_green`, `foxified_light`, `hci`, `iron_docks`, `peaceframe`,
`rebel`, `sirius_mind`, `solarized`, `sons_of_banard`, `storm_pilot`,
`tessier_ashpol`, `ustf`, `verdant_rebel`, `weicat_industrial`.
- `language`: `system` (default), `en` or `fr` (0.1.14). Native OS locale selects
French for `fr*`, English otherwise. Unknown theme/language values are rejected.
Missing new fields in older v1 files use these defaults; no migration is required.
Theme, language and automatic-output changes persist asynchronously, globally.
- `layout`: `previous`, `current`, `next`, `notes`, `elapsed`, `clock`, each with
boolean `show` and finite floating `size`; plus boolean `header`/`footer`.
Previous/next sizes are relative weights 30–160, current 60–200; notes size
is percentage 12–65; elapsed/clock sizes are logical pixels 16–320. Defaults are in `settings.rs`. Since 0.1.35, the previous-slide widget defaults
to hidden; an explicitly saved `previous.show` value is preserved.
- `layout.elapsed_position` and `layout.clock_position`: `header` (default),
`above_slides`, or `below_notes`, added in 0.1.24; `left_of_notes`,
`right_of_notes`, `left_of_slides`, `right_of_slides` added in 0.1.48. Independent presenter-only
placement presets; unknown values are rejected. Body timer rows reserve space
and remain visible with hidden bars. Header timers follow header visibility. Side timers reserve up to 32% of their
pane per side, stack if sharing a side, and fit their text to available space.
If the target pane is hidden, side timers use the remaining body. Notes refit
to the reduced pane. Existing layouts retain their sizes/positions; older binaries
reject the new positions and sizes over 72.
- `layout.slide_progress`: boolean, default false, added in 0.1.24. Shows requested
slide / total and its fraction in a reserved bottom body row; empty decks show
0 / 0 with zero fill. This is navigation progress, not render/output readiness.
- Since 0.1.49, `layout.slide_progress_height`: finite logical pixels 8–120,
default 24. Height is capped to 25% of available body height on small windows.
- Since 0.1.49, `layout.timer_mode`: `elapsed` (default) or `countdown`;
`layout.countdown_seconds`: integer 1–86400, default 1200;
`layout.timer_autostart`: boolean, default true. These preferences and bar size
round-trip through both global and project layouts. Missing fields use defaults.
Older v1 binaries ignore these additive fields and lose them on resave.
Running/paused state, monotonic timestamps and elapsed time are transient,
never saved. Successful source loads reset the timer to its waiting state;
failed loads preserve the current timer. Mode/duration/autostart edits reset it.
Automatic start uses the first matching, unblanked output frame acknowledgement;
without output monitors, explicit navigation/show starts rehearsal timing.
Pause disables pending autostart; later slide changes never resume a paused timer.
Restart resets and runs immediately. Countdown uses ceiling seconds, stops at
zero and never wraps; Start after expiry restarts the configured duration.
- `projects`: at most 4096 SHA-256 canonical-path keys mapping to full layouts.
Path identity uses OS encoded bytes, not source content. Moving files or switching
platforms may therefore select a different layout. Project overrides win globally.
- `routes.presenter` and `routes.presentation`: arrays of monitor identifiers
(`native-name#occurrence`), disjoint and unique, at most 32 entries combined.
Saved preferences are not overwritten by temporary missing-monitor fallback.
- `presenter_fullscreen`, `presentation_fullscreen`: booleans, default true.
- `browser_monitor`: optional monitor ID; missing/unavailable means presenter screen.
- `thumbnail_size`: logical width in pixels, finite 100–400; default 220.
- `buffer_mib`: integer 64–16384, adaptive default, added in 0.1.13. Decoded slide RAM
allowance for each presenter/output process; one MiB = 1048576 bytes. Additional
worker/texture/UI memory is not included. Since 0.1.46, missing budgets use 15% of available physical RAM measured once at
process startup, raised toward 512 MiB only within a 20% ceiling. The operational
minimum is 64 MiB, maximum 16384 MiB; failed memory detection uses 256 MiB.
Explicit saved budgets (including the old 1024 MiB default) remain unchanged.
Saving preferences persists the chosen numeric budget; it is not continuously
retuned. Older binaries reject budgets below their former 256 MiB minimum. The menu
persists changes asynchronously. Since 0.1.19, lowering evicts non-active frames
while reserving room for outstanding renders; increasing allows RAM refill.
Display assignments and fullscreen choices are previewed in a 15-second transient
trial before persistence. Only Keep changes updates their saved values. Timeout,
Escape, Revert now and hotplug discard the trial. Unrelated preference saves during
a trial serialize the previously confirmed display values. No v1 schema change.
Transient display trials/startup recovery eligibility, reveals, blank/current/selected slides, elapsed time, loaded document,
Change on click and worker state are not persisted. HTML prototype localStorage is
separate and is not automatically imported. See `examples/settings-v1.toml` and
round-trip/invalid-version tests in `tests/settings.rs`.