ウィジェットリファレンス

Settings (v0.2.2)

各ウィジェットの TOML 例は，全ウィジェットを網羅したテスト用スキーマ repos/settings/demo/schema.toml を正とします。

一覧

widget	用途	主なオプション
text_input	一行テキスト	min_width / max_width
secret_input	マスク入力（表示切替アイコン付き）	—
multiline	複数行テキスト	rows
checkbox	チェックボックス	bool。sublabel
toggle	トグルスイッチ	bool。sublabel
select	ドロップダウン	options / options_from。option_states
segmented_control	セグメント選択	同上。max_width
exclusive_radio	モード切替＋子ウィジェット	exclusive テーブル必須
hotkey	ショートカット記録	—
slider	スライダー	min / max / step / suffix
drag_value	数値ドラッグ入力	同上
separator	区切り線	key / label / type 不要
file_path	パス入力＋参照ボタン	is_directory / file_filter / file_extensions
color_picker	カラー選択	値は #rrggbb
key_value_map	文字列の Key-Value テーブル	key_label / value_label

---

テキスト系

text_input

一行テキスト入力です。min_width / max_width で幅を調整できます。

[[tabs.fields]]
key       = "text.constrained"
label     = { en = "Width-constrained", ja = "幅制限付き" }
type      = "string"
widget    = "text_input"
max_width = 220

secret_input

マスク入力です。表示／非表示を切り替えるアイコンが付きます。

[[tabs.fields]]
key    = "text.password"
label  = { en = "Secret input", ja = "シークレット入力" }
type   = "string"
widget = "secret_input"

multiline

複数行テキスト入力です。rows で表示行数を指定します。

[[tabs.fields]]
key    = "text.notes"
label  = { en = "Multiline text", ja = "複数行テキスト" }
type   = "string"
widget = "multiline"
rows   = 5

真偽値系

checkbox

チェックボックスです。sublabel を指定すると，ラベルがチェックボックスの右側に配置されます。

[[tabs.fields]]
key      = "booleans.check_sublabel"
label    = ""
type     = "bool"
widget   = "checkbox"
sublabel = { en = "With sublabel (label sits to the right of the checkbox)", ja = "サブラベル付き（ラベルがチェックボックスの右に配置される）" }

toggle

トグルスイッチです。

[[tabs.fields]]
key    = "booleans.toggle_hint"
label  = { en = "Toggle with hint", ja = "ヒント付きトグル" }
type   = "bool"
widget = "toggle"
hint   = { en = "Enabling this option changes the behavior", ja = "このオプションを有効にすると挙動が変わります" }

選択系

select

ドロップダウンです。options（静的な選択肢配列）または options_from（section_map のキー一覧から動的に生成）で選択肢を指定します。option_states で個々の選択肢を無効化できます（検証を参照）。

[[tabs.fields]]
key     = "selection.dropdown"
label   = { en = "Dropdown (select)", ja = "ドロップダウン（select）" }
type    = "string"
widget  = "select"
options = ["alpha", "beta", "gamma", "delta"]

segmented_control

セグメント選択です。オプションは select と同様（options / options_from / option_states）で，さらに max_width で全体幅を制限できます。

[[tabs.fields]]
key       = "selection.segment5"
label     = { en = "Segmented control (5 items · width-constrained)", ja = "セグメンテッドコントロール（5 項目 · 幅制限）" }
type      = "string"
widget    = "segmented_control"
options   = ["XS", "S", "M", "L", "XL"]
max_width = 280

type = "number" を指定した場合の挙動は後述を参照してください。

exclusive_radio

モードを切り替えながら，バリアントごとに異なる子ウィジェットを表示するウィジェットです。exclusive テーブルが必須です。完全な例は後述を参照してください。

数値系

slider

スライダーです。min / max / step で範囲と刻み幅，suffix で表示する単位を指定します。

[[tabs.fields]]
key    = "numeric.slider_suffix"
label  = { en = "Slider (with suffix)", ja = "スライダー（接尾辞付き）" }
type   = "number"
widget = "slider"
min    = 100
max    = 400
step   = 10
suffix = " px"

drag_value

数値をドラッグして増減させる入力です。オプションは slider と同様です。

[[tabs.fields]]
key       = "numeric.drag_suffix"
label     = { en = "Drag value (with suffix)", ja = "ドラッグ値（接尾辞付き）" }
type      = "number"
widget    = "drag_value"
min       = 5
max       = 72
step      = 0.5
suffix    = " pt"
max_width = 120

レイアウト

separator

区切り線です。key / label / type は不要です。

[[tabs.fields]]
widget = "separator"

その他

hotkey

キーボードショートカットを記録するウィジェットです。

[[tabs.fields]]
key    = "misc.hotkey"
label  = { en = "Hotkey", ja = "ホットキー" }
type   = "string"
widget = "hotkey"

color_picker

カラー選択ウィジェットです。値は #rrggbb 形式（アルファ値なし）で保存されます。

[[tabs.fields]]
key    = "misc.color"
label  = { en = "Color picker", ja = "カラーピッカー" }
type   = "string"
widget = "color_picker"

file_path

パス入力欄と参照ボタンの組み合わせです。is_directory = true でディレクトリ選択になり，file_filter / file_extensions でファイル種別を絞り込めます。

[[tabs.fields]]
key             = "misc.file"
label           = { en = "File path", ja = "ファイルパス" }
type            = "string"
widget          = "file_path"
file_filter     = { en = "TOML files", ja = "TOML ファイル" }
file_extensions = ["toml", "txt"]

[[tabs.fields]]
key          = "misc.directory"
label        = { en = "Directory path", ja = "ディレクトリパス" }
type         = "string"
widget       = "file_path"
is_directory = true

key_value_map

文字列のキーと値からなるテーブルを編集するウィジェットです。key_label / value_label で列の見出しを指定します。

[[tabs.fields]]
key         = "misc.kv_map"
label       = { en = "Key-value map", ja = "キーと値のマップ" }
type        = "string"
widget      = "key_value_map"
key_label   = { en = "Key", ja = "キー" }
value_label = { en = "Value", ja = "値" }

---

segmented_control と type

segmented_control は既定では文字列（type を省略，または type = "string"）として読み書きされます。type = "number" を指定すると TOML の数値として保存されます。このとき options はラベルと保存値を兼ねる数値の文字列表現で，整数として書き込むか浮動小数点として書き込むかは，オプション文字列に . が含まれているかどうかで決まります（詳細はコードベースを参照してください）。

[[tabs.fields]]
key       = "numeric.segment_count"
label     = { en = "Segmented control (number)", ja = "セグメンテッド（数値）" }
type      = "number"
widget    = "segmented_control"
options   = ["0", "1", "2", "3", "4", "5"]
max_width = 280

exclusive_radio の例

「API キーを直接入力するか，環境変数名で指定するか」のように，モードに応じて異なる子ウィジェットを切り替えたいときに使います。

[[tabs.fields]]
key    = "api_key"
widget = "exclusive_radio"
hint_direct = "設定ファイルに平文で保存されます。"
hint_env    = "環境変数名を指定します。"

[tabs.fields.exclusive]
mode_key     = "api_key_mode"
mode_default = "direct"
variants = [
  { value = "direct", label = { en = "Direct", ja = "直接" }, field_key = "api_key", widget = "secret_input" },
  { value = "env",    label = { en = "Env var", ja = "環境変数" }, field_key = "api_key_env", widget = "text_input" },
]

フィールド	説明
mode_key	選択中のバリアントを保存する設定キー
mode_default	バリアント未設定時の既定値
variants	バリアントの配列。各要素は value（保存値）・label（表示名，ローカライズ可）・field_key（値を保存するキー）・widget（子ウィジェットの種別）を持つ
hint_direct / hint_env	バリアントごとの補助テキスト（フィールド側に指定）

選択されていない側のバリアントのキーは，設定ファイルから削除されます。