etui - v1.0.0

etui/widgets/form

Types

Field

</>

A single form field.

pub type Field(id) {
  Field(
    id: id,
    label: String,
    value: String,
    validator: fn(String) -> Result(Nil, String),
    error: String,
    max_length: Int,
  )
}

Constructors 

  • Field(
  id: id,
  label: String,
  value: String,
  validator: fn(String) -> Result(Nil, String),
  error: String,
  max_length: Int,
)

    Arguments

    max_length

    Number of graphemes / cells allowed (0 = unlimited within display width).

Form

</>

Form state: ordered list of fields plus focus index.

pub type Form(id) {
  Form(
    fields: List(Field(id)),
    focused: Int,
    submitted: Bool,
    label_width: Int,
    fg: style.Color,
    bg: style.Color,
    focused_fg: style.Color,
    focused_bg: style.Color,
    error_fg: style.Color,
  )
}

Constructors

Validator

</>

Validator: Ok(Nil) if valid, Error(String) with message if not.

pub type Validator =
  fn(String) -> Result(Nil, String)

Values

add_field

</> 
pub fn add_field(
  f: Form(id),
  id: id,
  label: String,
  default_value: String,
  validator: fn(String) -> Result(Nil, String),
) -> Form(id)

Append a field with a validator.

add_optional

</> 
pub fn add_optional(
  f: Form(id),
  id: id,
  label: String,
  default_value: String,
) -> Form(id)

Append an optional field (always valid).

add_required

</> 
pub fn add_required(
  f: Form(id),
  id: id,
  label: String,
  default_value: String,
) -> Form(id)

Append a required text field (non-empty validator).

backspace

</> 
pub fn backspace(f: Form(id)) -> Form(id)

Backspace on the currently focused field.

clear_focused

</> 
pub fn clear_focused(f: Form(id)) -> Form(id)

Clear the currently focused field’s value.

focus_index

</> 
pub fn focus_index(f: Form(id), idx: Int) -> Form(id)

Move focus to a specific field by index.

focus_next

</> 
pub fn focus_next(f: Form(id)) -> Form(id)

Move focus to the next field (wraps around).

focus_prev

</> 
pub fn focus_prev(f: Form(id)) -> Form(id)

Move focus to the previous field (wraps around).

form_new

</> 
pub fn form_new() -> Form(id)

Empty form with default styles.

get_value

</> 
pub fn get_value(f: Form(id), id: id) -> String

Get a field’s current value by id. Returns “” if not found.

is_submitted

</> 
pub fn is_submitted(f: Form(id)) -> Bool

True if the form was successfully submitted.

is_valid

</> 
pub fn is_valid(f: Form(id)) -> Bool

True if all fields are valid (no errors after validation).

render

</> 
pub fn render(
  buf: buffer.Buffer,
  area: geometry.Rect,
  f: Form(id),
) -> buffer.Buffer

Render all fields as label + value rows. Each field takes 2 rows (value row + optional error row). Focused field is highlighted.

reset

</> 
pub fn reset(f: Form(id)) -> Form(id)

Reset all fields to empty, clear errors and submitted flag.

set_value

</> 
pub fn set_value(f: Form(id), id: id, value: String) -> Form(id)

Set a field’s value by id.

submit

</> 
pub fn submit(f: Form(id)) -> Form(id)

Validate then mark as submitted if valid. Returns the form.

type_char

</> 
pub fn type_char(f: Form(id), ch: String) -> Form(id)

Type a character into the currently focused field.

validate

</> 
pub fn validate(f: Form(id)) -> Form(id)

Validate all fields. Returns form with error messages populated.

values

</> 
pub fn values(f: Form(id)) -> List(#(id, String))

Get all field values as #(id, value) pairs.

with_colors

</> 
pub fn with_colors(
  f: Form(id),
  fg: style.Color,
  bg: style.Color,
) -> Form(id)

Set base foreground/background.

with_error_color

</> 
pub fn with_error_color(f: Form(id), fg: style.Color) -> Form(id)

Set validation error text color.

with_field_max_length

</> 
pub fn with_field_max_length(f: Form(id), max: Int) -> Form(id)

Set max grapheme length for the most-recently added field.

with_focused_colors

</> 
pub fn with_focused_colors(
  f: Form(id),
  fg: style.Color,
  bg: style.Color,
) -> Form(id)

Set focused field highlight colors.

with_label_width

</> 
pub fn with_label_width(f: Form(id), w: Int) -> Form(id)

Override label column width (auto-computed from labels if 0).

✨ Search Document