A form: a sequence of input fields that manipulate the fields of an underlying state that you choose. This value must be stored in the Brick application's state.

Type variables are as follows:

• s - the data type of your choosing containing the values manipulated by the fields in this form.
• e - your application's event type
• n - your application's resource name type

A form field state accompanied by the fields that manipulate that state. The idea is that some record field in your form state has one or more form fields that manipulate that value. This data type maps that state field (using a lens into your state) to the form input fields responsible for managing that state field, along with a current value for that state field and an optional function to control how the form inputs are rendered.

Most form fields will just have one input, such as text editors, but others, such as radio button collections, will have many, which is why this type supports more than one input corresponding to a state field.

Type variables are as follows:

• s - the data type containing the value manipulated by these form fields.
• e - your application's event type
• n - your application's resource name type

A form field. This represents an interactive input field in the form. Its user input is validated and thus converted into a type of your choosing.

Type variables are as follows:

• a - the type of the field in your form state that this field manipulates
• b - the form field's internal state type
• e - your application's event type
• n - your application's resource name type

Create a new form with the specified input fields and an initial form state. The fields are initialized from the state using their state lenses and the first form input is focused initially.

The focus ring for the form, indicating which form field has input focus.

The current state of the form. Forms guarantee that only valid inputs ever get stored in the state, and that after each input event on a form field, if that field contains a valid state value then the value is immediately saved to its corresponding field in this state value using the form field's lens over s.

Dispatch an event to the currently focused form field. This handles the following events in this order:

• On Tab keypresses, this changes the focus to the next field in the form.
• On Shift-Tab keypresses, this changes the focus to the previous field in the form.
• On mouse button presses (regardless of button or modifier), the focus is changed to the clicked form field and the event is forwarded to the event handler for the clicked form field.
• On Left or Up, if the currently-focused field is part of a collection (e.g. radio buttons), the previous entry in the collection is focused.
• On Right or Down, if the currently-focused field is part of a collection (e.g. radio buttons), the next entry in the collection is focused.
• All other events are forwarded to the currently focused form field.

In all cases where an event is forwarded to a form field, validation of the field's input state is performed immediately after the event has been handled. If the form field's input state succeeds validation using the field's validator function, its value is immediately stored in the form state using the form field's state lens. The external validation flag is ignored during this step to ensure that external validators have a chance to get the intermediate validated value.

Render a form.

For each form field, each input for the field is rendered using the implementation provided by its FormField. The inputs are then concatenated with the field's concatenation function (see setFieldConcat) and are then augmented using the form field's rendering augmentation function (see @@=). Fields with invalid inputs (either due to built-in validator failure or due to external validation failure via setFieldValid) will be displayed using the invalidFormInputAttr attribute.

Finally, all of the resulting field renderings are concatenated with the form's concatenation function (see setFormConcat). A visibility request is also issued for the currently-focused form field in case the form is rendered within a viewport.

Render a single form field collection. This is called internally by renderForm but is exposed in cases where a form field state needs to be rendered outside of a Form, so renderForm is probably what you want.

Compose a new rendering augmentation function with the one in the form field collection. For example, we might put a label on the left side of a form field:

(str "Please check: " <+>) @@= checkboxField alive AliveField "Alive?"

This can also be used to add multiple augmentations and associates right:

(withDefAttr someAttribute) @@=
(str "Please check: " <+>) @@=
  checkboxField alive AliveField "Alive?"

Returns whether all form fields in the form currently have valid values according to the fields' validation functions. This is useful when we need to decide whether the form state is up to date with respect to the form input fields.

Returns the resource names associated with all form input fields that currently have invalid inputs. This is useful when we need to force the user to repair invalid inputs before moving on from a form editing session.

Manually indicate that a field has invalid contents. This can be useful in situations where validation beyond the form element's validator needs to be performed and the result of that validation needs to be fed back into the form state.

Set a form's concatenation function.

Set a form field's concatenation function.

Set the focused field of a form.

Update the state contained in a form.

This updates all form fields to be consistent with the new form state. Where possible, this attempts to maintain other input state, such as text editor cursor position.

Note that since this updates the form fields, this means that any field values will be completely overwritten! This may or may not be what you want, since a user actively using the form could get confused if their edits go away. Use carefully.

A form field using an editor to edit a text value. Since the value is free-form text, it is always valid.

This field's attributes are governed by those exported from Edit.

This field responds to all events handled by editor, including mouse events.

A form field using a single-line editor to edit the Show representation of a state field value of type a. This automatically uses its Read instance to validate the input. This field is mostly useful in cases where the user-facing representation of a value matches the Show representation exactly, such as with Int.

This field's attributes are governed by those exported from Edit.

This field responds to all events handled by editor, including mouse events.

A form field using a single-line editor to edit the Show representation of a state field value of type a. This automatically uses its Read instance to validate the input, and also accepts an additional user-defined pass for validation. This field is mostly useful in cases where the user-facing representation of a value matches the Show representation exactly, such as with Int, but you don't want to accept just any Int.

This field's attributes are governed by those exported from Edit.

This field responds to all events handled by editor, including mouse events.

A form field using a single-line editor to edit a free-form text value represented as a password. The value is always considered valid and is always represented with one asterisk per password character.

This field's attributes are governed by those exported from Edit.

This field responds to all events handled by editor, including mouse events.

A form field for selecting a single choice from a set of possible choices. Each choice has an associated value and text label.

This field responds to Space keypresses to select a radio button option and to mouse clicks.

A form field for manipulating a boolean value. This represents True as [X] label and False as [ ] label.

This field responds to Space keypresses to toggle the checkbox and to mouse clicks.

A form field for selecting a single choice from a set of possible choices in a scrollable list. This uses a List internally.

This field's attributes are governed by those exported from List.

This field responds to the same input events that a List does.

A form field for using an editor to edit the text representation of a value. The other editing fields in this module are special cases of this function.

This field's attributes are governed by those exported from Edit.

This field responds to all events handled by editor, including mouse events.

A form field for selecting a single choice from a set of possible choices. Each choice has an associated value and text label. This function permits the customization of the [*] notation characters.

This field responds to Space keypresses to select a radio button option and to mouse clicks.

A form field for manipulating a boolean value. This represents True as [X] label and False as [ ] label. This function permits the customization of the [X] notation characters.

This field responds to Space keypresses to toggle the checkbox and to mouse clicks.

The namespace for the other form attributes.

The attribute for form input fields with invalid values. Note that this attribute will affect any field considered invalid and will take priority over any attributes that the field uses to render itself.

The attribute for form input fields that have the focus. Note that this attribute only affects fields that do not already use their own attributes when rendering, such as editor- and list-based fields. Those need to be styled by setting the appropriate attributes; see the documentation for field constructors to find out which attributes need to be configured.