API Reference

The API reference documents generated signatures and contracts for the UI routing layer and the CSV data layer. Read Architecture and the Guides first; use this tab while implementing to confirm types, parameters, and return values.

Routing & navigation

Module	Source	Purpose	Use when	Related docs
Route paths	ui/route_paths.py	Canonical "/…" constants for every route.	Declaring or comparing paths without string typos.	Adding a screen
Route URLs	ui/route_url.py	Parse, build, and compare route URLs with query params.	Encoding file_name or mode in navigation calls.	Navigation guide
Route registry	ui/route_registry.py	RouteDef entries, enums, drawer builder, get_route.	Registering a route or inspecting registry metadata.	Routing concept
Navigation	ui/navigation.py	navigate_to, push_view, go_back, go_search.	Moving between routes from screen and control code.	Navigation guide
In-place search	ui/inplace_search.py	Host SearchControl in the AppBar over shared tile bodies.	Debugging search chrome or calling search outside go_search.	Body registry, Navigation guide
Router	ui/router.py	Route-change handlers, view construction, layout dispatch.	Wiring app.py or debugging stack replacement and push.	Routing concept, Startup

Layout & chrome

Module	Source	Purpose	Use when	Related docs
Routable screens	ui/routable_screen.py	apply_layout protocol and active-view lookup.	Implementing responsive shell or deep controls.	Layout guide
Chrome configuration	ui/chrome_config.py	ShellChromeConfig and per-route chrome map.	Tuning app bar, FAB, or bottom bar for a shell route.	Chrome and wrappers
App chrome	ui/app_chrome.py	Registry of live AppBar / bottom bar / FAB / drawer refs.	Applying Shell chrome or attaching shared controls to views.	Chrome and wrappers, Startup
App drawer	ui/app_drawer.py	Shared NavigationDrawer for Shell destinations.	Changing drawer navigation or lock behavior.	Chrome and wrappers
Layout host	ui/layout_host.py	Body-wrapper builders and width sync helpers.	Choosing or extending BodyWrapperKind hosts.	Chrome and wrappers
Layout metrics	ui/layout_metrics.py	LayoutMetrics, store, and field-width helpers.	Reading breakpoints and computed widths in apply_layout.	Layout guide

Shared state

Module	Source	Purpose	Use when	Related docs
Body registry	ui/body_registry.py	Shared home and export TilesContainer accessors.	Search, export, or navigation that reuses tile bodies.	Body registry concept
App session	ui/app_session.py	Shared Page, export FilePicker, TTS playback, and navigation lock.	Wiring chrome/export/TTS at startup or locking navigation briefly.	State and persistence
Preferences	ui/preferences.py	SharedPreferences factory for durable settings.	Reading or writing user settings outside a screen instance.	State and persistence
App theme	ui/app_theme.py	Theme mode and preference-backed page bgcolor.	Applying or persisting content background / mode.	State and persistence, Startup
TTS preferences	ui/tts_preferences.py	App-default TTS language, auto-speak, and speaker flags.	Applying or persisting pronunciation defaults.	State and persistence, Startup
Learn preferences	ui/learn_preferences.py	App-default retry flag and practice-queue sizes.	Applying or persisting learn-session defaults.	State and persistence, Startup

Data & learning

Module	Source	Purpose	Use when	Related docs
File path manager	data/file_path_manager.py	Storage roots, csv_files/, and tts_cache/ path helpers.	Resolving where catalogs, set CSVs, and TTS files live.	Data and storage
App data	data/app_data.py	Catalog CRUD, load/save, empty sets, AppData.	Creating, listing, or learning a set on disk.	Data and storage, Learning algorithm
Set settings	data/set_settings.py	Per-set learning and TTS overrides on files.csv.	Reading or storing one set's language, speakers, retry, or queue size.	Per-set settings
Constants	data/constants.py	Column enums, MAX_ROWS, import messages.	Matching CSV schemas or import error text.	Data and storage, Import and export
CSV processor	data/csv_processor.py	Validate, repair catalog, import save helpers.	Importing a set or checking files.csv.	Import and export
Demo sets	data/demo_sets.py	Bundled demos, reserved names, install into storage.	Adding sample sets or protecting demo basenames.	Data and storage
TTS	tts/	Providers, MP3 cache, live phrases, and TtsService.	Synthesizing audio, swapping providers, or pruning the cache.	Data and storage, App session

Suggested order for new contributors

1. Route paths and Route URLs — vocabulary for paths and parameters.
2. Route registry — where routes are declared.
3. Navigation — what screen code calls day to day.
4. In-place search — when tracing search UI without a route.
5. Routable screens, Layout metrics, and Layout host — responsive behavior.
6. Chrome configuration and App chrome — declarative Shell chrome vs live control registry (App drawer when changing drawer navigation).
7. File path manager, Constants, App data, and Set settings — where sets live on disk and how one set overrides app defaults; read Learning algorithm with AppData.
8. CSV processor and Demo sets — import/catalog repair and bundled sample install.
9. TTS — pronunciation cache and providers; TTS preferences for the app language and auto-speak, Set settings when a set stores its own.
10. Preferences, App theme, and Learn preferences — durable settings, content background, and learn-queue retry.
11. Router — only when you change startup wiring or trace a route event.

Private _build_* factories and internal layout dispatchers are hidden from these pages. They remain in source for router maintainers.