Get started with Settings

Create a small settings window for a host name and port number. For an introduction to what Settings can do, see the product page.

The introduction and representative screenshot are now on the product page. This page explains how to build and launch your own schema.

What you need

• Get the Settings source, Rust / Cargo, and just. On Windows, the recipes also require sh from Git for Windows.
• The schema defines the interface; the configuration file holds the values people edit. Create separate TOML files for them.
• To try the interface first, use the downloadable demo. Its schema is fixed.

Quick start

1. Write schema.toml

Save the following as schema.toml in a working folder. key names a configuration key; label is the text shown in the window.

icon_style = "rounded"
theme      = "os"
lang       = "os"

[[tabs]]
id    = "general"
label = { en = "General", ja = "一般" }
icon  = "settings"

[[tabs.fields]]
key    = "server.host"
label  = { en = "Host", ja = "ホスト" }
type   = "string"
widget = "text_input"

[[tabs.fields]]
key    = "server.port"
label  = { en = "Port", ja = "ポート" }
type   = "number"
widget = "drag_value"
min    = 1
max    = 65535

The schema is embedded at build time. Rebuild after changing the interface definition.

2. Create config.toml

In the same working folder, create the config.toml that Settings will edit. The file must already exist and be readable when Settings starts.

[server]
host = "localhost"
port = 8080

The schema's server.host and server.port refer to these values.

3. Build with your schema

Run these commands from the Settings repository root. On the first build or after icon changes, use just init to prepare assets.

In a macOS or Linux shell, specify the absolute path of the schema:

just init
SETTINGS_SCHEMA="/path/to/schema.toml" just binary

In Windows PowerShell, set the environment variable as follows:

just init
$env:SETTINGS_SCHEMA = "C:\work\schema.toml"
just binary

The host executable is target/release/settings, or target/release/settings.exe on Windows. See Building for other targets and schema path precedence.

4. Launch with the configuration path

On macOS or Linux:

./target/release/settings "/path/to/config.toml"

In Windows PowerShell:

.\target\release\settings.exe "C:\work\config.toml"

The window shows Host and Port inputs. Change a value, then commit the edit on macOS or click OK or Apply on Windows and Linux. Open the saved config.toml to confirm the change. These are the defaults when save_button is omitted.

Launch from your app

For example, in Rust, specify the executable and configuration paths. Create the configuration file before launching Settings.

std::process::Command::new("path/to/settings")
    .arg("/path/to/config.toml")
    .spawn()?;

To apply saved settings in your app, watch the file or reload it when Settings exits. See Embedding for packaging and Schema and Widgets to add more controls.