Module settings 

Settings metadata model.

Settings are the CONFIG the user can directly edit, they have associated metadata such as display name and description, and will usually be editable in a special settings window. This module provides a basic settings data model, with category grouping, sorting and filtering. A default settings editor window is also provided.

fn register_categories() {
    SETTINGS.register_categories(|c| {
        c.entry("cat-example", |c| c.name("Example Settings"));
    });
}

fn register_settings() {
    SETTINGS.register(|s| {
        s.entry("settings.value", "cat-example", |s| {
            s.name("Value")
                .description("Example using EDITORS provided editor.")
                .value(Txt::default())
        });
        s.entry("settings.custom", "cat-example", |s| {
            s.name("Custom")
                .description("Example using custom editor.")
                .editor_fn(wgt_fn!(|_setting| {
                    TextInput! {
                        txt = CONFIG.get("settings.custom", Txt::default());
                    }
                }))
        });
    });
}

The example above demonstrates how to register a settings category and two values, one using a default editor, the other using a custom editor. When no editor_fn is set and the value config is called the zng::widget::EDITORS service is used to find an editor for the config. The editor closure parameter is a Setting that is not used in this case, as the editor already binds to the config directly.

Note that the name and description accepts variable inputs, in a full app use the l10n! macro to declare localized metadata.

In the default APP the SETTINGS_CMD command is handled and shows a settings::editor window that implements search, edit and reset features. See the config example for a full demonstration of settings.

Reset

Restoring settings to default is a common feature, you can simply update the value to a default, or with some setup, you can actually remove the config from the user file.

fn load_config() -> Box<dyn FallbackConfigReset> {
    // user edited config (settings.)
    let user = JsonConfig::sync(zng::env::config("settings.json"));
    let default = JsonConfig::read(zng::env::res("default-settings.json"));
    let settings = FallbackConfig::new(user, default);
    let settings_ref = settings.clone_boxed();

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

    CONFIG.load(SwitchConfig::new().with_prefix("settings.", settings).with_prefix("", other));

    settings_ref
}
fn register_settings(reset: Box<dyn FallbackConfigReset>) {
    SETTINGS.register(move |s| {
        s.entry("settings.value", "cat-example", |s| {
            s.name("Value").value(Txt::default()).reset(reset.clone_boxed(), "settings.")
        });
    });
}

The example above declares a config system with three files, the relevant ones are "default-settings.json" and "settings.json". The default file is deployed with the app resources and is read-only, the user file is created in the user data directory and contains only the custom values set by the user. The FallbackConfigReset has access to the user file and can remove entries from it.

The FallbackConfigReset::can_reset variable tracks the presence of the config in the user file. The default settings widget uses this to show a little reset arrow button that users can click to reset.

The FallbackConfig handles entry removal by updating the config variable back to the fallback file entry.

Full API

See zng_ext_config::settings for the full settings API.

Modules

editor

Settings editor widget.

Structs

CategoriesBuilder

Setting categories builder.

Category

Settings category.

CategoryBuilder

Category entry builder.

CategoryId

Unique ID of a Category.

SETTINGS

Settings metadata service.

Setting

Setting entry.

SettingBuilder

Setting entry builder.

SettingsBuilder

Settings builder.

Statics

SETTINGS_CMD

Represents the open settings action.

Functions

can_settings

P Defines if on_settings and on_pre_settings command handles are enabled in the context.

on_pre_settings

P Preview on_settings command.

on_settings

P On settings command.