Struct AppConfig 

#[repr(C)]
pub struct AppConfig {

    pub log_level: AppLogLevel,
    pub natural_scroll: NaturalScroll,
    pub enable_visual_panic_hook: bool,
    pub enable_logging_on_panic: bool,
    pub synthesize_pinch_from_ctrl_wheel: bool,
    pub expose_system_media_controls: bool,
    pub termination_behavior: AppTerminationBehavior,
    pub icon_provider: IconProviderHandle,
    pub bundled_fonts: NamedFontVec,
    pub font_loading: FontLoadingConfig,
    pub mock_css_environment: OptionCssMockEnvironment,
    pub system_style: SystemStyle,
    pub component_libraries: ComponentLibraryVec,
    pub routes: RouteVec,
    pub system_animations: SystemAnimations,
    pub custom_e2e_op: CustomE2eOpCallback,
    pub updates: UpdateSettings,
    pub changelog_md: OptionString,
    pub report_problem: OptionEmailAddress,
}

Configuration for optional features, such as whether to enable logging or panic hooks

Fields

log_level: AppLogLevel

If enabled, logs error and info messages.

Default is LevelFilter::Error to log all errors by default

natural_scroll: NaturalScroll

NATURAL SCROLLING (9b-ii-b-i-a; USER RULING 2026-09-04: a field here, default off, the app enables it or loads the system’s setting).

The engine’s own scroll sign: Disabled never flips a delta, Enabled flips every wheel / trackpad delta (in-app natural scrolling regardless of the OS), System reads the platform’s preference at startup and keeps it readable (CallbackInfo::get_natural_scroll) - WITHOUT a second flip, because every desktop platform already applies the user’s preference to the deltas it hands over (macOS, the Windows precision touchpad, libinput on Wayland and X11); flipping again would undo it. Where the platform reports nothing the answer is unknown and System behaves as Disabled.

enable_visual_panic_hook: bool

If the app crashes / panics, a window with a message box pops up. Setting this to false disables the popup box.

enable_logging_on_panic: bool

If this is set to true (the default), a backtrace + error information gets logged to stdout and the logging file (only if logging is enabled).

synthesize_pinch_from_ctrl_wheel: bool

Whether Ctrl+wheel is synthesized into a pinch gesture. Default true.

A Windows PRECISION TOUCHPAD does not deliver pinch through WM_GESTURE - that message is the touchSCREEN path. A touchpad reports pinch as Ctrl+WM_MOUSEWHEEL, which is the same thing every browser zooms on, so synthesizing a pinch from it is what makes pinch-to-zoom work on the overwhelming majority of Windows laptops.

The cost of that is a real MOUSE with a real Ctrl key produces the same message, and cannot be told apart from a touchpad at this layer - so an app where Ctrl+wheel means something else (a CAD zoom step, a font-size nudge) receives a pinch it did not want. Setting this to false turns the synthesis off and leaves Ctrl+wheel as a plain wheel event with the Ctrl modifier set, which such an app can read directly.

Ignored on every platform but Windows: macOS and Wayland report real pinch gestures, so nothing has to be inferred there.

expose_system_media_controls: bool

Whether the app publishes itself to the OS as a media player. Default false.

On Linux the desktop environment usually GRABS the media keys, so XF86AudioPlay and friends never reach the application as keysyms at all (the 9h-i table only sees them when nothing grabbed them). The transport in that case is MPRIS over D-Bus: the desktop calls Play/Pause/Next on whatever players are registered, and azul turns those calls back into ordinary VirtualKeyCode presses.

OFF by default because registering has a VISIBLE side effect: the app appears in the desktop’s media controls (GNOME’s system menu, KDE’s media applet) as a player. That is correct for a music app and wrong for a text editor, and no engine-side signal distinguishes them - so the app says which it is.

macOS is the same bargain under a different name: MPRemoteCommandCenter delivers the media keys, but only to the app the system considers “now playing”, so registering puts the app in Control Center and the Now Playing widget.

Ignored on Windows, which delivers media keys as WM_APPCOMMAND to the focused window and publishes nothing.

termination_behavior: AppTerminationBehavior

Determines what happens when all windows are closed. Default: EndProcess (terminate when last window closes).

icon_provider: IconProviderHandle

Icon provider for the application. Register icons here before calling App::run(). Each window will clone this provider (cheap, Arc-based).

bundled_fonts: NamedFontVec

Fonts bundled with the application. These fonts are loaded into memory and take priority over system fonts.

font_loading: FontLoadingConfig

Configuration for how system fonts should be loaded. Default: LoadAllSystemFonts (scan all system fonts at startup)

mock_css_environment: OptionCssMockEnvironment

Optional mock environment for CSS evaluation.

When set, this overrides the auto-detected system properties (OS, theme, etc.) for CSS @-rules and dynamic selectors. This is useful for:

• Testing OS-specific styles on a different platform
• Screenshot testing with consistent environment
• Previewing how the app looks on different systems

Default: None (use auto-detected system properties)

system_style: SystemStyle

System style detected at startup (theme, colors, fonts, etc.)

This is detected once at AppConfig::create() and passed to all windows. You can override this after creation to use a custom system style, for example to test how your app looks on a different platform.

component_libraries: ComponentLibraryVec

Component libraries registered at startup.

Use add_component() to register individual components, or add_component_library() to register entire libraries. User-registered (and built-in) component libraries.

The 52 built-in HTML elements are automatically registered by AppConfig::create() via register_builtin_components. Additional libraries can be added with add_component_library.

routes: RouteVec

Registered routes mapping URL patterns to layout callbacks.

Cross-platform: on desktop, the active route determines which layout callback runs. On web, routes map to HTTP endpoints and browser URLs.

The first route (or "/") is the default. Use add_route() to register.

system_animations: SystemAnimations

System-animation configuration (scroll physics override, caret / selection tween hooks). See SystemAnimations.

custom_e2e_op: CustomE2eOpCallback

Handler for E2E ops the engine does not implement, letting a scenario drive application-level actions (“now load the document”) that the engine cannot express on the app’s behalf.

The default recognises nothing, so a scenario naming a custom op fails unless the app installed a handler.

updates: UpdateSettings

Update configuration: manifest URL, requested mode, the running version. Drives CallbackInfo::check_for_updates and the SysDialogType::UpdateVersion dialog. Default: no manifest (checks disabled), NotifyOnly.

changelog_md: OptionString

URL of the app’s changelog in Markdown. The UpdateVersion dialog shows it before installing when a release carries no changelog link of its own.

report_problem: OptionEmailAddress

Support mailbox that problem reports (SysDialogType::ReportProblem) and manual crash reports go to. None = the ReportProblem dialog saves reports to disk instead of mailing them.

Implementations

impl AppConfig

pub fn create() -> Self

pub fn with_mock_environment(self, env: CssMockEnvironment) -> Self

Create config with a mock CSS environment for testing

This allows you to simulate how your app would look on a different OS, with a different theme, language, or accessibility settings.

Example

let config = AppConfig::create()
    .with_mock_environment(CssMockEnvironment {
        os: OptionOsCondition::Some(OsCondition::Linux),
        theme: OptionThemeCondition::Some(ThemeCondition::Dark),
        ..Default::default()
    });

pub fn add_component<R: Into<RegisterComponentFn>>( &mut self, library: AzString, register_fn: R, )

Register a single component into a named library.

Calls register_fn immediately and adds the returned ComponentDef to the library named library. If no library with that name exists, a new one is created. If a component with the same id.name already exists in the library, it is replaced.

C API

AzAppConfig_addComponent(&config, AzString_fromConstStr("mylib"), my_register_fn);

pub fn add_component_library<R: Into<RegisterComponentLibraryFn>>( &mut self, name: AzString, register_fn: R, )

Register an entire component library.

Calls register_fn immediately and adds the returned ComponentLibrary to the config. Uses name as the library name (overriding whatever the function sets). If a library with the same name already exists, it is replaced wholesale.

C API

AzAppConfig_addComponentLibrary(&config, AzString_fromConstStr("vendor"), my_lib_fn);

pub fn add_route<P: Into<AzString>, L: Into<LayoutCallback>>( &mut self, pattern: P, layout_fn: L, )

Register a route mapping a URL pattern to a layout callback.

On web: each route becomes an HTTP endpoint. On desktop: the first route (or "/") is the initial layout, and CallbackInfo::switch_route() swaps the active callback.

C API

AzAppConfig_addRoute(&config, AzString_fromConstStr("/user/:id"), layout_user);

pub fn match_route_for_path(&self, path: &str) -> Option<(&Route, RouteMatch)>

Find the route matching a given URL path.

Returns the matched Route and a RouteMatch with extracted parameters.

Trait Implementations

impl Clone for AppConfig

fn clone(&self) -> AppConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AppConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AppConfig

fn default() -> Self

Returns the “default value” for a type.