Deckstride/docs/interfaces/settings.md

198 lines
15 KiB
Markdown
Raw Permalink 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/deckstride` (otherwise
`~/.config/deckstride`) on Linux. `directories::ProjectDirs` with qualifier `com`,
organization `Beffroi`, application `Deckstride` supplies other platforms' standard
per-user config/cache directories. On first start after the rename, Deckstride
copies valid settings from the former application directory when the new file does
not exist. It keeps using an existing warm slide cache until the new cache has been
populated, avoiding a forced rerender. 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_keep_fitted_area`: boolean, default false, added in 0.1.55. Missing fields
migrate to screen-adapting zoom: preserve aspect ratio while expanding into the
viewport, cropping overflow. True retains the original fitted page area. This
global preference does not change cached render resolution or enable zoom.
- `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.
- `autoplay_enabled`: boolean, default false; `autoplay_seconds`: finite floating
seconds from 0.25 through 3600, default 5; and `autoplay_loop`: boolean, default
false (0.1.95). The interval begins only after the requested slide is visible on
Slides, so rendering delays do not consume a slide's display time. With no Slides
route, a ready Presenter/single-screen frame counts as visible. Manual navigation,
zoom and blank/unblank restart the interval. Blanking, loading, display trials,
startup recovery, file dialogs, notes editing/import and quit confirmation pause
autoplay and resume with a fresh interval. At the final slide autoplay stops unless
loop is enabled; a one-slide deck never repeatedly navigates. The enabled state,
timing and loop preference are global and saved immediately. Runtime deadlines and
final-slide state are transient. Older v1 files use the defaults; older binaries
ignore and discard these additive fields on resave.
- `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`, `fr`, `es`, `ja`, `zh_cn`, `de` or `pt_br`.
Spanish, Japanese, Simplified Chinese, German and Brazilian Portuguese were added
in 0.1.92. Native OS locale selects a supported language by language/script and
region; Traditional Chinese and unsupported Portuguese regions fall back to
English rather than silently selecting a different written standard.
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.
Catalog lookup is compiled, allocation-free and never reads files on the input or
render path. Theme and font state is rebuilt only when the selection changes.
- `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 explicit navigation, zoom or output-visibility
action; passively displaying the initial output frame does not start timing.
Pause disables pending autostart; later actions never resume a paused timer. Reset
returns to the configured initial value and arms autostart for the next navigation,
zoom or visibility action. Countdown uses ceiling seconds, stops at zero and never wraps; explicit
Start after expiry restarts the configured duration immediately.
- `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. These remain the shared timer
settings and the legacy visual fallback for displays without profiles.
- `display_layouts`: optional map added in 0.1.76; keys are the same monitor IDs
used by routes (`native-name#occurrence`), not presenter indexes or primary status.
At most 128 profiles; keys are nonempty UTF-8 strings of at most 1024 bytes.
Each profile contains `layout` (all-project visual default) and `projects`
(canonical-path SHA keys to visual overrides). At most 4096 display/project
overrides in total. All nested Layout fields use the existing units, ranges and
validation above, including finite sizes. Missing maps are empty; old v1 files
require no rewrite/migration. Older binaries ignore these additive profiles and
discard them on resave.
Resolution is display/project override → display default → legacy project/global
layout if there is no display profile. The first save creates a profile whose
default is copied from the legacy global layout; Save all projects replaces that
display default, Save this project stores only that display's project override,
and Use all-project layout removes only that display's project override.
The three timer-behavior fields (`timer_mode`, `countdown_seconds`,
`timer_autostart`) in display layouts are compatibility copies, not independent
timers. Their authoritative values remain the shared legacy project/global
layout; scoped saves also save those shared timer fields. Timer visibility, size
and position are independent per display. Use all-project layout only resets the
current display's visuals and leaves shared timer behavior unchanged.
Runtime edits are retained by display ID across ordinary window recreation and
hotplug, but only explicit Save persists them. Successful source/settings loads
resolve saved profiles afresh; failed source loads preserve current edits.
Session view state is bounded to 128 retained displays, pruning disconnected
entries when that limit is reached. Menus/panel visibility are per presenter and
transient. Reordering monitors/roles does not copy a layout to another ID;
indistinguishable native names still share the existing route identifier limits.
- `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.
- `single_screens`: optional array added in 0.1.89, default empty. Up to 32 unique
monitor IDs, each a nonempty UTF-8 string of at most 1024 bytes; no units.
A marker is active only while its monitor is in `routes.presenter`; those
windows retain operator-process ownership but use the slide-first single-screen
view. Audience routes never use this marker to reveal operator controls.
Displays presents this combination as the separate Single screen role. Choosing
another role removes that connected monitor's marker. Disconnected markers are
retained; group swaps leave active Single screen monitors in place.
Apply previews routes and markers together; Keep changes persists both, while
Revert, timeout or hotplug discards trial values. Single-screen windows use the
global `presentation_fullscreen` default and per-screen `screen_modes` overrides.
Existing presenter layouts are preserved and restored when switching back.
Old v1 files migrate with an empty array; older binaries ignore this additive
field and show the ordinary Presenter view on the operator-owned route.
The startup offer/decision is transient, never serialized. It is eligible only
on the first native monitor discovery with exactly one screen, after settings
load, and is suppressed for an already configured Single screen monitor. A
topology change withdraws it permanently for that run; later disconnects or
reconnections never create an offer. Round-trip and invalid-boundary tests cover
the saved array; startup/hotplug tests cover the transient decision.
- `presenter_fullscreen`, `presentation_fullscreen`: booleans, default true.
- `screen_modes`: optional monitor-ID map added in 0.1.87. Values are
`follow_global`, `always_fullscreen`, or `always_windowed`; unknown values fail
deserialization. At most 128 entries, with nonempty UTF-8 keys of at most 1024
bytes. No units. Missing maps/entries follow the role's global fullscreen flag;
old v1 files need no migration. Forced choices override global fullscreen
commands and the `--windowed` global startup default. Choices stay attached to
the monitor ID across role swaps, mirrors, disconnects and reconnects, including
unused monitors. The All slides auxiliary window remains windowed.
Apply previews the map in the timed display trial; only Keep changes saves it.
Revert, timeout and hotplug restore confirmed preferences. The UI removes an
entry when Follow global is selected; explicit `follow_global` entries also
round-trip unchanged. Older binaries ignore this additive map and discard it
on resave. See the example and settings round-trip/boundary tests.
- `browser_monitor`: optional monitor ID; missing/unavailable means presenter screen.
- `thumbnail_size`: logical width in pixels, finite 100–400; default 220.
- `disk_cache.max_mib`: integer 64–1048576 MiB, default 10240 (10 GiB).
- `disk_cache.max_days`: integer 1–3650 days, default 30. Added in 0.1.70;
missing table/fields in v1 settings use defaults. Invalid limits are rejected.
Global options persist asynchronously; older binaries ignore these fields. See
[cache retention](extraction-cache.md) for age, active-deck protection and cleanup.
- `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`.
- `blank_picture`: optional boolean (0.1.77), default false. True selects the
managed [blank picture](blank-picture.md); false uses solid black. Missing or
invalid assets fall back to black. Existing v1 files migrate by defaulting false.