Module config 

Config service, sources and other types.

The configuration service CONFIG separates config using from config writing. A config is a variable of a serializable type, widgets and other components request a config using an unique text name and then simply use the variable like any other. The app optionally sets one or more config sources that are automatically updated when a config variable changes and are monitored for changes that are propagated back to the config variables.

Sources

The default config source is the MemoryConfig that only lives for the app process lifetime, this can be used to connect different UI components, more importantly it also means that the CONFIG service always works.

use zng::prelude::*;

fn txt_input() -> UiNode {
    TextInput!(CONFIG.get("example-txt", Txt::from("")))
}

fn txt_display() -> UiNode {
    Text!(CONFIG.get("example-txt", Txt::from("")))
}

Container! {
    child = txt_input();
    child_spacing = 20;
    child_bottom = txt_display();
}

The example above uses a config key "example-txt", no config source is set so this config will only last for the duration of the app instance, but both widgets are synchronized because they are bound to the same config.

The example below setups a JsonConfig that persists the configs to a JSON file. The file updates when a config variable is modified and the variables are updated when the file is modified externally.

let cfg = zng::config::JsonConfig::sync("target/tmp/example.config.json");
CONFIG.load(cfg);

Other Sources

The JSON, TOML, YAML and RON are available behind a feature flags, you can also implement your own source.

Some meta sources are also provided, they enables composite sources, such as having two sources, default config and user config where the user config file only records the non-default values.

The next example demonstrates a more complex setup:

use zng::config::*;

fn load_config() -> Box<dyn FallbackConfigReset> {
    // config file for the app, keys with prefix "main." are saved here.
    let user_cfg = JsonConfig::sync("target/tmp/example.config.json");
    // entries not found in `user_cfg` bind to this file first before going to embedded fallback.
    let default_cfg = JsonConfig::read("examples/config/res/defaults.json");

    // the app settings.
    let main_cfg = FallbackConfig::new(user_cfg, default_cfg);

    // Clone a ref that can be used to reset specific entries.
    let main_ref = main_cfg.clone_boxed();

    // any other configs (Window::save_state for example)
    let other_cfg = JsonConfig::sync("target/tmp/example.config.other.json");

    CONFIG.load(SwitchConfig::new().with_prefix("main.", main_cfg).with_prefix("", other_cfg));

    main_ref
}

Full API

See zng_ext_config for the full config API.

Modules

settings

Settings metadata model.

Structs

CONFIG

Represents the app main config.

FallbackConfig

Represents a copy-on-write config source that wraps two other sources, a read-write config and a read-only fallback config.

MemoryConfig

Memory only config.

RawConfigValue

Represents any entry type in a config.

ReadOnlyConfig

Config wrapper that only provides read-only variables from the inner config.

SwapConfig

Represents a config source that can swap its backing config source without disconnecting any bound keys.

SwitchConfig

Represents multiple config sources that are matched by key.

Enums

ConfigStatus

Represents the current IO status of the config.

SaveState

Window or widget persistence config.

Traits

AnyConfig

Represents one or more config sources behind a dynamic reference.

Config

Represents one or more config sources.

ConfigValue

Marker trait for types that can stored in a Config.

FallbackConfigReset

Reset controls of a FallbackConfig.

Functions

save_state_node

Helper node for implementing widget state saving.

Type Aliases

ConfigKey

Unique key to a config entry.

JsonConfig

Represents a config source that synchronizes with a JSON file.

RonConfig

Represents a config source that synchronizes with a RON file.

TomlConfig

Represents a config source that synchronizes with a TOML file.

YamlConfig

Represents a config source that synchronizes with a YAML file.