Files
craft-libs/crates/ui-patterns/src/patterns/form_dialogs/param.rs
T
aiongg 20e0bcf93b dialogs-w2: net change of 3 commits
- dialogs-w2: written by an agent
- Integration: ParamRows keeps dialogs-w1's preview_colors beside the patterns rows (dialogs-w1 7a195af4a)
- dialogs-w2: review fixes (review-1)
2026-11-15 04:46:07 +00:00

966 lines
39 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! The parameter model of the form dialogs: [`Param`] and [`ParamKind`] describe one row of a parameter form,
//! [`Param::parse_list`] builds a list from a spec string, and the requests a row can make of its host
//! (`runtime::requests`) are plain values.
mod parse;
use super::fields::{DialogFields, FieldValue};
use crate::patterns::blend_keys::BlendKeyEntry;
use crate::runtime::env::{Label, UnitKind};
use crate::runtime::requests::{ColorRequest, EyedropperRequest, ListingRequest, PathKind};
use crate::value_drag::SliderScale;
use craft_host::PickRequest;
use craft_theme::Srgba;
use egui::{Response, Ui};
use std::fmt;
use std::path::PathBuf;
use std::sync::Arc;
/// What a parameter is and which control edits it. Defaults are the values a form opens with when nothing is
/// remembered and the host gave no values. Build a kind with its constructor (`ParamKind::range`, ...).
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum ParamKind {
/// A slider with a number field. [`SliderScale::Log`] for ranges over three decades.
#[non_exhaustive]
Range {
/// Lowest value.
min: f64,
/// Highest value.
max: f64,
/// The value shown when nothing is remembered.
default: f64,
/// How the slider maps position to value.
scale: SliderScale,
},
/// A whole-number field; `None` bounds are unbounded.
#[non_exhaustive]
Int {
/// Lowest value, or `None` for no lower bound.
min: Option<i64>,
/// Highest value, or `None` for no upper bound.
max: Option<i64>,
/// The value shown when nothing is remembered.
default: i64,
},
/// A number field without a slider. A `None` bound is open on that side. Arrow keys and scrubs move by `step`;
/// `decimals` is the most digits shown after the decimal mark, so an integer is `decimals: 0`. The field holds a
/// [`FieldValue::Number`].
#[non_exhaustive]
Number {
/// Lowest value, or `None` for no lower bound.
min: Option<f64>,
/// Highest value, or `None` for no upper bound.
max: Option<f64>,
/// The value shown when nothing is remembered.
default: f64,
/// How far a scrub step or an arrow key moves the value.
step: f64,
/// The most digits shown after the decimal mark; 0 for an integer.
decimals: u32,
},
/// A check box.
#[non_exhaustive]
Bool {
/// Whether the box starts checked.
default: bool,
},
/// A select of `(id, label)` options; the field holds the id.
#[non_exhaustive]
Choice {
/// The `(id, label)` pairs in list order.
options: Vec<(String, Label)>,
/// The id selected when nothing is remembered; `None` selects the first option.
default: Option<String>,
},
/// A group of radio buttons over `(id, label)` options; the field holds the id. The row is its own section, titled
/// by the parameter's label, so it needs no `Param::section` before it.
#[non_exhaustive]
Radio {
/// The `(id, label)` pairs in list order.
options: Vec<(String, Label)>,
/// The id selected when nothing is remembered; `None` selects the first option.
default: Option<String>,
},
/// An angle dial with its field, in degrees.
#[non_exhaustive]
Angle {
/// The angle in degrees shown when nothing is remembered.
default: f64,
},
/// A colour the host's picker chooses; `None`: unset until picked.
#[non_exhaustive]
Color {
/// The colour as RGB in 0 to 1; `None` leaves it unset.
default: Option<[f32; 3]>,
},
/// A grid of `cells` integer fields, [`grid_side`](ParamKind::grid_side) per row (`int[25]` is 5×5). A `cells`
/// that is not square wraps every `round(sqrt(cells))` fields and the last row is short.
#[non_exhaustive]
Grid {
/// The number of fields.
cells: usize,
/// The value every cell starts with.
default: i64,
},
/// A point picked over the preview image plus X and Y fields, in percent of the image.
#[non_exhaustive]
Point {
/// `[x, y]` in percent of the image.
default: [f64; 2],
},
/// One of the document's channels by index, shown by name.
#[non_exhaustive]
Channel {
/// The channel names in index order.
names: Vec<String>,
/// The index selected when nothing is remembered.
default: usize,
},
/// A text field.
#[non_exhaustive]
Text {
/// The text shown when nothing is remembered.
default: String,
},
/// A number that may be unset: a "Custom" check box switches the field on. Unset the key is absent from the
/// [`DialogFields`]. `initial` is what the field shows the first time the box is checked; `decimals` is the most
/// digits shown after the decimal mark (`0` for an integer, as in [`ParamKind::Number`]).
#[non_exhaustive]
OptionalNumber {
/// Lowest value.
min: f64,
/// Highest value.
max: f64,
/// The value when nothing is remembered; `None` leaves the number unset.
default: Option<f64>,
/// The value the field shows the first time the box is checked.
initial: f64,
/// The most digits shown after the decimal mark; 0 for an integer.
decimals: u32,
},
/// Read-only text the user can select and copy: see [`Param::read_only_text`]. It has no value.
#[non_exhaustive]
ReadOnlyText {
/// The text shown; line breaks start new lines.
text: Label,
},
/// A row the host draws: see [`Param::custom`]. It has no value of its own.
Custom(CustomRow),
/// A select of blend modes, each with the Shift+Alt key that picks it.
#[non_exhaustive]
Blend {
/// The modes: their key entries (id and shortcut) and labels.
modes: Vec<(BlendKeyEntry<String>, Label)>,
/// The id of the mode shown when nothing is remembered; the first mode when `None`.
default: Option<String>,
},
/// A pattern chosen from the dialog's pattern list (`ParamDialog::patterns`); its value is the pattern's id.
#[non_exhaustive]
Pattern {
/// The id of the pattern shown when nothing is remembered.
default: Option<String>,
},
/// A list of files or one folder (a `FileListPicker`); its value is a `{files, folder, useFolder}` object.
#[non_exhaustive]
Files {
/// Whether the list picks a folder.
folder_mode: bool,
/// The file dialog request Browse makes.
request: PickRequest,
/// The paths of the documents already open, which the list offers to add.
open_files: Vec<PathBuf>,
},
/// A section heading over the rows that follow it: see [`Param::section`]. It has no value.
Section,
}
impl ParamKind {
/// A slider and field over `min..=max`.
pub fn range(min: f64, max: f64, default: f64, scale: SliderScale) -> Self {
ParamKind::Range { min, max, default, scale }
}
/// A whole-number field.
pub fn int(min: Option<i64>, max: Option<i64>, default: i64) -> Self {
ParamKind::Int { min, max, default }
}
/// A number field.
pub fn number(min: Option<f64>, max: Option<f64>, default: f64, step: f64, decimals: u32) -> Self {
ParamKind::Number { min, max, default, step, decimals }
}
/// A check box.
pub fn bool(default: bool) -> Self {
ParamKind::Bool { default }
}
/// A select of `(id, label)` options.
pub fn choice(options: Vec<(String, Label)>, default: Option<String>) -> Self {
ParamKind::Choice { options, default }
}
/// A group of radio buttons over `(id, label)` options, in a section of its own titled by the parameter's label.
pub fn radio(options: Vec<(String, Label)>, default: Option<String>) -> Self {
ParamKind::Radio { options, default }
}
/// An angle dial with its field.
pub fn angle(default: f64) -> Self {
ParamKind::Angle { default }
}
/// A colour the host's picker chooses.
pub fn color(default: Option<[f32; 3]>) -> Self {
ParamKind::Color { default }
}
/// A grid of `cells` integer fields.
pub fn grid(cells: usize, default: i64) -> Self {
ParamKind::Grid { cells, default }
}
/// A point in percent of the image.
pub fn point(default: [f64; 2]) -> Self {
ParamKind::Point { default }
}
/// A channel by index, shown by name.
pub fn channel(names: Vec<String>, default: usize) -> Self {
ParamKind::Channel { names, default }
}
/// A text field.
pub fn text(default: impl Into<String>) -> Self {
ParamKind::Text { default: default.into() }
}
/// A number that a check box switches on.
pub fn optional_number(min: f64, max: f64, default: Option<f64>, initial: f64, decimals: u32) -> Self {
ParamKind::OptionalNumber { min, max, default, initial, decimals }
}
/// A select of blend `modes` with their keys; `default` is the id of the mode shown at first.
pub fn blend(modes: Vec<(BlendKeyEntry<String>, Label)>, default: Option<String>) -> Self {
ParamKind::Blend { modes, default }
}
/// A pattern chosen from the dialog's pattern list; `default` is the id shown at first.
pub fn pattern(default: Option<String>) -> Self {
ParamKind::Pattern { default }
}
/// Fields per row of a [`ParamKind::Grid`] of `cells`: `round(sqrt(cells))`, at least 1.
pub fn grid_side(cells: usize) -> usize {
((cells as f32).sqrt().round() as usize).max(1)
}
/// The value a field of this kind starts with.
pub fn default_value(&self) -> Option<FieldValue> {
Some(match self {
ParamKind::Range { default, .. } | ParamKind::Angle { default } => FieldValue::Number(*default),
ParamKind::Int { default, .. } => FieldValue::Int(*default),
ParamKind::Number { default, .. } => FieldValue::Number(*default),
ParamKind::Bool { default } => FieldValue::Bool(*default),
ParamKind::Choice { options, default } | ParamKind::Radio { options, default } => {
let initial = default.as_deref().or_else(|| options.first().map(|(id, _)| id.as_str()));
FieldValue::Text(initial.unwrap_or_default().to_owned())
}
ParamKind::Color { default } => FieldValue::Color((*default)?),
ParamKind::Grid { cells: count, default } => {
let mut cells = vec![*default; *count];
// A grid that starts at 0 is a kernel: the identity, 1 in the centre.
if *default == 0
&& let Some(centre) = cells.get_mut(count / 2)
{
*centre = 1;
}
FieldValue::Grid(cells)
}
ParamKind::Point { default } => FieldValue::Point(*default),
ParamKind::Channel { default, .. } => FieldValue::Int(i64::try_from(*default).unwrap_or(0)),
ParamKind::Text { default } => FieldValue::Text(default.clone()),
ParamKind::OptionalNumber { default, .. } => FieldValue::Number((*default)?),
ParamKind::Blend { modes, default } => {
let initial = default.as_deref().or_else(|| modes.first().map(|(entry, _)| entry.key.as_str()));
FieldValue::Text(initial.unwrap_or_default().to_owned())
}
ParamKind::Pattern { default } => FieldValue::Text(default.clone()?),
ParamKind::Files { open_files, .. } => path_list(open_files),
ParamKind::ReadOnlyText { .. } | ParamKind::Custom(_) | ParamKind::Section => return None,
})
}
/// Whether `value` is one this kind can hold (a remembered value must, or it is dropped).
pub fn fits(&self, value: &FieldValue) -> bool {
let number = |value: &FieldValue| match value {
FieldValue::Number(n) => Some(*n),
FieldValue::Int(i) => Some(*i as f64),
_ => None,
};
match (self, value) {
(ParamKind::Range { min, max, .. }, v) => number(v).is_some_and(|n| n.is_finite() && n >= *min && n <= *max),
(ParamKind::Angle { .. }, v) => number(v).is_some_and(f64::is_finite),
(ParamKind::Int { min, max, .. }, FieldValue::Int(i)) => min.is_none_or(|m| *i >= m) && max.is_none_or(|m| *i <= m),
(ParamKind::Number { min, max, .. }, v) => {
number(v).is_some_and(|n| n.is_finite() && min.is_none_or(|m| n >= m) && max.is_none_or(|m| n <= m))
}
(ParamKind::Bool { .. }, FieldValue::Bool(_)) => true,
(ParamKind::Choice { options, .. } | ParamKind::Radio { options, .. }, FieldValue::Text(id)) => {
options.iter().any(|(option, _)| option == id)
}
(ParamKind::Color { .. }, FieldValue::Color(c)) => c.iter().all(|v| v.is_finite()),
(ParamKind::Grid { cells: count, .. }, FieldValue::Grid(cells)) => cells.len() == *count,
(ParamKind::Point { .. }, FieldValue::Point(p)) => p.iter().all(|v| v.is_finite()),
(ParamKind::Channel { names, .. }, FieldValue::Int(i)) => usize::try_from(*i).is_ok_and(|i| i < names.len()),
(ParamKind::Text { .. }, FieldValue::Text(_)) => true,
(ParamKind::OptionalNumber { min, max, .. }, v) => number(v).is_some_and(|n| n.is_finite() && n >= *min && n <= *max),
(ParamKind::Custom(_), FieldValue::Json(_)) => true,
(ParamKind::Blend { modes, .. }, FieldValue::Text(id)) => modes.iter().any(|(entry, _)| entry.key == *id),
(ParamKind::Pattern { .. }, FieldValue::Text(_)) => true,
(ParamKind::Files { .. }, v) => is_path_list(v),
_ => false,
}
}
}
type CustomDraw = dyn Fn(&mut Ui, &mut DialogFields, &mut CustomContext) -> Response + Send + Sync;
/// What draws a [`ParamKind::Custom`] row: it gets the row's control cell, the form's values and the row's
/// [`CustomContext`], and returns the response the row label names. Equal only to itself.
#[derive(Clone)]
pub struct CustomRow(Arc<CustomDraw>);
impl CustomRow {
/// Wraps `draw`, which draws the row and edits the values it owns through the [`DialogFields`].
pub fn new(draw: impl Fn(&mut Ui, &mut DialogFields, &mut CustomContext) -> Response + Send + Sync + 'static) -> Self {
Self(Arc::new(draw))
}
/// Draws the row.
pub(crate) fn draw(&self, ui: &mut Ui, fields: &mut DialogFields, context: &mut CustomContext) -> Response {
(self.0)(ui, fields, context)
}
}
impl fmt::Debug for CustomRow {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("CustomRow")
}
}
impl PartialEq for CustomRow {
fn eq(&self, other: &Self) -> bool {
Arc::ptr_eq(&self.0, &other.0)
}
}
/// What a [`Param::custom`] row can ask of the host besides editing the values.
#[derive(Debug)]
#[non_exhaustive]
pub struct CustomContext {
title: Label,
colors: DialogFields,
request: Option<ColorRequest>,
canvas: Option<egui::Id>,
eyedropper: Option<EyedropperRequest>,
sampling: bool,
}
impl CustomContext {
/// The context of a row labelled `title` over `colors`, the values at the start of the pass.
pub(crate) fn new(title: Label, colors: DialogFields, canvas: Option<egui::Id>) -> Self {
CustomContext { title, colors, request: None, canvas, eyedropper: None, sampling: false }
}
/// Arms the host's eyedropper for the colour under `request.key`, as a colour row's dropper toggle does.
pub fn arm_eyedropper(&mut self, request: EyedropperRequest) {
self.eyedropper = Some(request);
}
/// Whether the row's dropper samples now: `true` while the row wants canvas presses to pick colours.
pub fn sampling(&mut self, on: bool) {
self.sampling = on;
}
/// The canvas the dialog's rows work on (`ParamDialog::canvas`), when it has one.
pub fn canvas(&self) -> Option<egui::Id> {
self.canvas
}
/// Asks the host for its colour picker for the value under `key`, which needs no row of its own. The picker opens
/// at the colour the form holds under `key` (black without one), titled with the row's label. The request is
/// reported once, as a colour row's press is (`ParamRowsOutput::pick_color`); the host answers by writing the
/// colour under `key`.
pub fn pick_color(&mut self, key: &str) {
let color = Srgba::from_rgb_array(self.colors.color(key).unwrap_or([0.0; 3]));
self.request = Some(ColorRequest::new(key, color).title(self.title.clone()));
}
/// The dropper the row armed, once.
pub(crate) fn take_eyedropper(&mut self) -> Option<EyedropperRequest> {
self.eyedropper.take()
}
/// Whether the row asked for canvas presses to pick colours.
pub(crate) fn is_sampling(&self) -> bool {
self.sampling
}
/// The colour request the row made, once.
pub(crate) fn take_request(&mut self) -> Option<ColorRequest> {
self.request.take()
}
}
/// One unit of a number row with units ([`Param::number_with_units`]).
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct NumberUnit {
/// What the form result carries as the chosen unit (`"ppi"`).
pub id: String,
/// The kind of unit the number is read and shown in. The units of one row have different kinds.
pub kind: UnitKind,
/// The name in the unit menu (`"pixels/inch"`).
pub label: Label,
/// How many base units one of this unit is: the base value is the shown value times `factor` (pixels/cm is `2.54`
/// over a base of pixels/inch). Must be positive and finite.
pub factor: f64,
}
impl NumberUnit {
/// A unit `id` of `kind` named `label` that is `factor` base units.
pub fn new(id: impl Into<String>, kind: UnitKind, label: impl Into<Label>, factor: f64) -> Self {
Self { id: id.into(), kind, label: label.into(), factor }
}
}
/// Options a row may carry beyond its kind.
#[derive(Clone, Debug, Default, PartialEq)]
pub(crate) struct RowOptions {
range_decimals: Option<u32>,
randomize: bool,
eyedropper: bool,
eyedropper_armed: bool,
full_width: bool,
not_remembered: bool,
/// The lines a multi-line text row shows.
lines: Option<usize>,
units: Option<UnitChoices>,
/// The ids of the options a choice row shows disabled.
disabled_options: Vec<String>,
/// The row's select has a search field.
searchable: bool,
}
/// The units of a number row ([`Param::number_with_units`]).
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct UnitChoices {
units: Vec<NumberUnit>,
/// The field key the chosen unit's id is stored under.
key: String,
initial: usize,
}
/// The value that holds `paths`: a list of text, the shape a [`Param::files`] row keeps its files in.
pub(crate) fn path_list(paths: &[PathBuf]) -> FieldValue {
FieldValue::List(paths.iter().map(|path| FieldValue::Text(path.to_string_lossy().into_owned())).collect())
}
/// Whether `value` is a list of paths. An empty list stored and read back is a `Grid` of no cells.
fn is_path_list(value: &FieldValue) -> bool {
match value {
FieldValue::List(items) => items.iter().all(|item| matches!(item, FieldValue::Text(_))),
FieldValue::Grid(cells) => cells.is_empty(),
_ => false,
}
}
/// Texts a row may carry beyond its label.
#[derive(Clone, Debug, Default, PartialEq)]
struct RowTexts {
hint: Option<Label>,
tooltip: Option<Label>,
}
/// One row of a parameter form.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct Param {
/// The key in [`DialogFields`] and in the command the app runs (`"radius"`).
pub key: String,
/// The label without its colon (`"Radius"`).
pub label: Label,
/// Which control edits the value, and its default.
pub kind: ParamKind,
/// Shown after the number (`px`, `%`, `°`); formats through the locale.
pub unit: Option<UnitKind>,
/// The row takes input only while `fields[key]` equals one of the values.
pub enabled_when: Option<(String, Vec<FieldValue>)>,
/// The row is shown only while `fields[key]` equals the value ([`Param::visible_when`]). A hidden row takes no
/// space; its value stays in the fields and in the result.
pub visible_when: Option<(String, FieldValue)>,
/// A Browse button after a [`ParamKind::Text`] field.
pub browse: Option<PathKind>,
/// The hint and tooltip, boxed so rows without them stay small.
texts: Option<Box<RowTexts>>,
/// The named options, boxed for the same reason.
options: Option<Box<RowOptions>>,
}
impl Param {
/// A row with the field `key`, the `label` and the control `kind`.
pub fn new(key: impl Into<String>, label: impl Into<Label>, kind: ParamKind) -> Self {
Self {
key: key.into(),
label: label.into(),
kind,
unit: None,
enabled_when: None,
visible_when: None,
browse: None,
texts: None,
options: None,
}
}
/// A row of files or one folder: a [`ParamKind::Files`] list the user fills with Browse.
pub fn files(key: impl Into<String>, label: impl Into<Label>) -> Param {
let key = key.into();
let kind = ParamKind::Files { folder_mode: false, request: PickRequest::open_many(key.clone()), open_files: Vec::new() };
Self::new(key, label, kind)
}
/// Whether a [`Param::files`] row picks one folder instead of files.
#[must_use]
pub fn folder_mode(mut self, on: bool) -> Self {
if let ParamKind::Files { folder_mode, .. } = &mut self.kind {
*folder_mode = on;
}
self
}
/// The paths of the documents already open, which a [`Param::files`] row offers to add.
#[must_use]
pub fn open_files(mut self, paths: Vec<PathBuf>) -> Self {
if let ParamKind::Files { open_files, .. } = &mut self.kind {
*open_files = paths;
}
self
}
/// Shows the options `ids` of a choice row disabled.
#[must_use]
pub fn disabled_options(mut self, ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.options.get_or_insert_default().disabled_options = ids.into_iter().map(Into::into).collect();
self
}
/// Whether the option `id` of a choice row takes a pick.
pub fn option_enabled(&self, id: &str) -> bool {
self.options.as_deref().is_none_or(|options| !options.disabled_options.iter().any(|disabled| disabled == id))
}
/// Gives a choice row's select a search field.
#[must_use]
pub fn searchable(mut self) -> Self {
self.options.get_or_insert_default().searchable = true;
self
}
/// The row takes input only while `fields[key]` equals one of `values`; otherwise it is shown disabled.
#[must_use]
pub fn enabled_when_in(mut self, key: impl Into<String>, values: impl IntoIterator<Item = impl Into<FieldValue>>) -> Self {
self.enabled_when = Some((key.into(), values.into_iter().map(Into::into).collect()));
self
}
/// A bare number row: a [`ParamKind::Number`] open on both sides. Bound it with [`Param::bounds`].
pub fn number(key: impl Into<String>, label: impl Into<Label>, default: f64, step: f64, decimals: u32) -> Self {
Self::new(key, label, ParamKind::number(None, None, default, step, decimals))
}
/// Bounds a [`ParamKind::Number`] row (`None`: open on that side); other kinds are unchanged.
#[must_use]
pub fn bounds(mut self, lo: Option<f64>, hi: Option<f64>) -> Self {
if let ParamKind::Number { min, max, .. } = &mut self.kind {
(*min, *max) = (lo, hi);
}
self
}
/// A row the host draws. `draw` gets the control cell, the form's values and the row's [`CustomContext`] (to ask
/// for the host's colour picker); the row label names the response it returns. The row has no default and
/// nothing remembered; `draw` reads and writes [`DialogFields`] under whatever keys it likes.
pub fn custom(
key: impl Into<String>,
label: impl Into<Label>,
draw: impl Fn(&mut Ui, &mut DialogFields, &mut CustomContext) -> Response + Send + Sync + 'static,
) -> Self {
Self::new(key, label, ParamKind::Custom(CustomRow::new(draw)))
}
/// A row of read-only `text` beside the label, wrapped to the form's width: the user can select and copy it, and
/// Tab passes over it. It has no value, so nothing is remembered or in the result. With
/// [`full_width`](Param::full_width) it has no label and spans the form (a note over the rows).
pub fn read_only_text(key: impl Into<String>, label: impl Into<Label>, text: impl Into<Label>) -> Self {
Self::new(key, label, ParamKind::ReadOnlyText { text: text.into() })
}
/// A section heading: the label as the title of a section whose body is the rows that follow, up to the next
/// section. It has no value and no control.
pub fn section(label: impl Into<Label>) -> Self {
let label = label.into();
Self::new(format!("section:{}", label.as_str()), label, ParamKind::Section)
}
/// A number row with a unit menu after the field. `base` is the value in base units; the field shows
/// `base / factor` of the chosen unit, and an edit stores `shown * factor`. The first of `units` is chosen at
/// first (see [`Param::default_unit`]).
///
/// The result holds the base-unit value under the row's key and the chosen unit's [`id`](NumberUnit::id) as text
/// under [`Param::unit_key`] (`"{key}.unit"`). [`Param::bounds`] are in base units. Both keys are remembered with
/// the form.
pub fn number_with_units(key: impl Into<String>, label: impl Into<Label>, base: f64, step: f64, decimals: u32, units: Vec<NumberUnit>) -> Self {
let key = key.into();
let mut param = Self::number(key.clone(), label, base, step, decimals);
param.options.get_or_insert_default().units = Some(UnitChoices { units, key: format!("{key}.unit"), initial: 0 });
param
}
/// The unit of a [`Param::number_with_units`] row that is chosen when the form opens; an id the row does not have
/// leaves the first.
#[must_use]
pub fn default_unit(mut self, id: &str) -> Self {
if let Some(choices) = self.options.get_or_insert_default().units.as_mut()
&& let Some(at) = choices.units.iter().position(|unit| unit.id == id)
{
choices.initial = at;
}
self
}
/// The key a [`Param::number_with_units`] row stores its chosen unit's id under: `"{key}.unit"`.
pub fn unit_key(&self) -> Option<&str> {
self.options.as_deref()?.units.as_ref().map(|units| units.key.as_str())
}
/// The row is shown only while `fields[key]` equals `value`, as [`enabled_when`](Param::enabled_when) enables it;
/// otherwise it takes no space. Its value stays in the fields and in the result.
#[must_use]
pub fn visible_when(mut self, key: impl Into<String>, value: impl Into<FieldValue>) -> Self {
self.visible_when = Some((key.into(), value.into()));
self
}
/// The row takes input only while `fields[key]` equals `value`; otherwise it is shown disabled. The one-value case
/// of [`enabled_when_in`](Param::enabled_when_in).
#[must_use]
pub fn enabled_when(mut self, key: impl Into<String>, value: impl Into<FieldValue>) -> Self {
self.enabled_when = Some((key.into(), vec![value.into()]));
self
}
/// A Browse button after the field of a [`ParamKind::Text`] row. The press comes back as
/// `ParamRowsOutput::path`.
#[must_use]
pub fn browse(mut self, kind: PathKind) -> Self {
self.browse = Some(kind);
self
}
/// The text shown while a [`ParamKind::Text`] field is empty; other kinds are unchanged.
#[must_use]
pub fn hint(mut self, text: impl Into<Label>) -> Self {
self.texts.get_or_insert_default().hint = Some(text.into());
self
}
/// Hover text for the whole row, label and control, of any kind.
#[must_use]
pub fn tooltip(mut self, text: impl Into<Label>) -> Self {
self.texts.get_or_insert_default().tooltip = Some(text.into());
self
}
/// The most digits shown after the decimal mark on a [`ParamKind::OptionalNumber`] or [`ParamKind::Range`] row
/// (`0` for an integer); other kinds are unchanged. A Range row stores its value rounded to these digits, and `0`
/// stores a [`FieldValue::Int`].
#[must_use]
pub fn decimals(mut self, places: u32) -> Self {
match &mut self.kind {
ParamKind::OptionalNumber { decimals, .. } => *decimals = places,
ParamKind::Range { .. } => self.options.get_or_insert_default().range_decimals = Some(places),
_ => {}
}
self
}
/// A Random button after the field of a [`ParamKind::Int`] row (a seed): it sets a random value within the row's
/// bounds (an open side is `0` or `i32::MAX`); other kinds are unchanged.
#[must_use]
pub fn randomize(mut self) -> Self {
self.options.get_or_insert_default().randomize = true;
self
}
/// A pipette toggle after the colour control of a [`ParamKind::Color`] row. A press comes back as
/// `ParamRowsOutput::eyedropper`, and the host arms or disarms its own dropper from it; other kinds are
/// unchanged.
#[must_use]
pub fn eyedropper(mut self) -> Self {
self.options.get_or_insert_default().eyedropper = true;
self
}
/// Arms the [`eyedropper`](Param::eyedropper) toggle of a colour row when `armed` becomes true (it opens armed if
/// it starts true) and disarms it when it becomes false. Only one row is armed at a time. Rows without an
/// eyedropper are unchanged.
#[must_use]
pub fn armed(mut self, armed: bool) -> Self {
self.options.get_or_insert_default().eyedropper_armed = armed;
self
}
/// For a [`Param::custom`] or [`Param::read_only_text`] row: no label, and the body spans the width of the form;
/// other kinds are unchanged.
#[must_use]
pub fn full_width(mut self) -> Self {
self.options.get_or_insert_default().full_width = true;
self
}
/// A [`ParamKind::Text`] row without a Browse button edits multi-line text in a field `lines` lines tall: Enter
/// inserts a line break and the dialog's default button leaves it to the field. `lines` below 2 keeps a
/// single-line field, whose Enter answers the default button. Other kinds are unchanged.
#[must_use]
pub fn multiline(mut self, lines: usize) -> Self {
self.options.get_or_insert_default().lines = Some(lines);
self
}
/// Leaves the row out of the remembered values: a choice that refers to something in the document (a depth
/// channel, a menu of open documents) opens from its default every time.
#[must_use]
pub fn not_remembered(mut self) -> Self {
self.options.get_or_insert_default().not_remembered = true;
self
}
/// Sets the unit shown after the number.
#[must_use]
pub fn unit(mut self, unit: UnitKind) -> Self {
self.unit = Some(unit);
self
}
/// Parses the registry notation into a list, labels from the keys in Title Case with two fixed names (`cellSize`
/// is `Cell Size`, `bpc` is `Black Point Compensation`;
/// `{"radius":0.1..1000=1,"method":"spin|zoom","monochromatic":bool,"seed":u32=0}`). Apps with their own command
/// registry build [`Param`]s directly.
pub fn parse_list(spec: &str) -> Vec<Param> {
parse::list(spec)
}
/// The value the row opens with: its kind's default, stored by the same rule as an edit (a Range row's
/// [`decimals`](Param::decimals)).
pub(crate) fn default_value(&self) -> Option<FieldValue> {
match (&self.kind, self.option().range_decimals) {
(ParamKind::Range { default, .. }, Some(places)) => Some(rounded(*default, Some(places))),
_ => self.kind.default_value(),
}
}
/// The row's options, or the defaults.
pub(crate) fn option(&self) -> RowOptions {
self.options.as_deref().cloned().unwrap_or_default()
}
/// The hint text.
pub(crate) fn hint_text(&self) -> Option<&Label> {
self.texts.as_deref()?.hint.as_ref()
}
/// The row's tooltip text.
pub(crate) fn tooltip_text(&self) -> Option<&Label> {
self.texts.as_deref()?.tooltip.as_ref()
}
/// Whether the row's value is saved with the form.
pub fn is_remembered(&self) -> bool {
!self.option().not_remembered
}
/// Whether `value` is one the field `key` of this row can hold: the row's own value, or the unit id of a row with
/// units.
pub fn accepts(&self, key: &str, value: &FieldValue) -> bool {
if self.key == key {
return self.kind.fits(value) && self.option_allowed(value);
}
if matches!(self.kind, ParamKind::Files { .. }) {
return match value {
FieldValue::Text(_) => key == self.folder_key(),
FieldValue::Bool(_) => key == self.use_folder_key(),
other => key == self.folder_files_key() && is_path_list(other),
};
}
match (self.options.as_deref().and_then(|o| o.units.as_ref()), value) {
(Some(units), FieldValue::Text(id)) => units.key == key && units.units.iter().any(|u| &u.id == id),
_ => false,
}
}
/// The key a [`Param::files`] row stores its folder under: `"{key}.folder"`.
pub(crate) fn folder_key(&self) -> String {
format!("{}.folder", self.key)
}
/// The key a [`Param::files`] row stores whether the folder is used under: `"{key}.useFolder"`.
pub(crate) fn use_folder_key(&self) -> String {
format!("{}.useFolder", self.key)
}
/// The listing a [`Param::files`] row asks for when `before` becomes `after`: one of the folder in `after` when
/// that folder is in use and the folder or the use of it differs from `before`.
pub(crate) fn listing_after(&self, before: &DialogFields, after: &DialogFields) -> Option<ListingRequest> {
let (folder_key, use_key) = (self.folder_key(), self.use_folder_key());
let uses = |fields: &DialogFields| fields.bool(&use_key).unwrap_or(false);
let folder = after.text(&folder_key).filter(|_| uses(after))?;
let changed = before.text(&folder_key) != Some(folder) || !uses(before);
changed.then(|| ListingRequest::new(&self.key, PathBuf::from(folder)))
}
/// The key the host's listing of a [`Param::files`] row's folder is written under: `"{key}.folderFiles"`.
pub(crate) fn folder_files_key(&self) -> String {
format!("{}.folderFiles", self.key)
}
/// Whether `value` names no disabled option of a Radio, Choice or Blend row.
fn option_allowed(&self, value: &FieldValue) -> bool {
match (&self.kind, value) {
(ParamKind::Radio { .. } | ParamKind::Choice { .. } | ParamKind::Blend { .. }, FieldValue::Text(id)) => self.option_enabled(id),
_ => true,
}
}
/// Whether the row is shown with `fields`.
pub fn visible(&self, fields: &DialogFields) -> bool {
self.visible_when.as_ref().is_none_or(|(key, value)| fields.get(key) == Some(value))
}
/// Whether the row takes input with `fields`.
pub fn enabled(&self, fields: &DialogFields) -> bool {
self.enabled_when.as_ref().is_none_or(|(key, values)| fields.get(key).is_some_and(|held| values.contains(held)))
}
}
impl RowOptions {
/// The decimals a range row stores, or `None` for as typed.
pub(crate) fn range_places(&self) -> Option<u32> {
self.range_decimals
}
/// Whether an int row has a Random button.
pub(crate) fn randomize(&self) -> bool {
self.randomize
}
/// Whether a colour row has an eyedropper toggle.
pub(crate) fn eyedropper(&self) -> bool {
self.eyedropper
}
/// Whether the eyedropper toggle opens armed.
pub(crate) fn armed(&self) -> bool {
self.eyedropper_armed
}
/// Whether a custom row spans the width of the form.
pub(crate) fn full_width(&self) -> bool {
self.full_width
}
/// The lines of a multi-line text row; `None` for a single line.
pub(crate) fn lines(&self) -> Option<usize> {
self.lines
}
/// Whether a choice row's select has a search field.
pub(crate) fn searchable(&self) -> bool {
self.searchable
}
/// The units of a number row.
pub(crate) fn units(&self) -> Option<&UnitChoices> {
self.units.as_ref()
}
}
impl UnitChoices {
/// The units in menu order.
pub(crate) fn list(&self) -> &[NumberUnit] {
&self.units
}
/// The key the chosen unit's id is stored under.
pub(crate) fn key(&self) -> &str {
&self.key
}
/// The index of the unit chosen when nothing is stored.
pub(crate) fn initial(&self) -> usize {
self.initial
}
}
/// `value` rounded to `places` digits (`None`: as is); no digits stores an integer.
pub(crate) fn rounded(value: f64, places: Option<u32>) -> FieldValue {
match places {
None => FieldValue::Number(value),
Some(0) => FieldValue::Int(value.round() as i64),
Some(n) => {
let scale = 10f64.powi(n as i32);
FieldValue::Number((value * scale).round() / scale)
}
}
}
/// An sRGB component in 0..=1 as a byte.
pub fn encode(component: f32) -> u8 {
(component.clamp(0.0, 1.0) * 255.0).round() as u8
}
/// Writes `color` into the colour parameter `key` of `params`, or into a key no parameter has when a
/// [`Param::custom`] row can have asked for it; other keys are ignored.
pub fn set_color_field(params: &[Param], fields: &mut DialogFields, key: &str, color: Srgba) {
let colour_row = params.iter().any(|param| param.key == key && matches!(param.kind, ParamKind::Color { .. }));
let custom_request = params.iter().any(|param| matches!(param.kind, ParamKind::Custom(_))) && params.iter().all(|param| param.key != key);
if colour_row || custom_request {
fields.set(key, FieldValue::Color(color.to_rgb_array()));
}
}
/// Fills the keys `params` have defaults for and `fields` lack, and takes the opening snapshot.
pub fn open_fields(params: &[Param], fields: &mut DialogFields) {
fill_defaults(params, fields);
fields.snapshot();
}
/// Fills the keys `params` have defaults for and `fields` lack, including the unit key of a row with units.
pub(crate) fn fill_defaults(params: &[Param], fields: &mut DialogFields) {
for param in params {
if !fields.contains(&param.key)
&& let Some(value) = param.default_value()
{
fields.set(param.key.as_str(), value);
}
if let Some(units) = param.options.as_deref().and_then(|o| o.units())
&& !fields.contains(units.key())
&& let Some(unit) = units.list().get(units.initial())
{
fields.set(units.key(), FieldValue::Text(unit.id.clone()));
}
}
}