Tag

`mininterface.Tag`

Wrapper around a value that encapsulates a description, validation etc.

Bridge between the input values and a UI widget. The widget is created with the help of this object, then transforms the value back (str to int conversion etc).

For dataclasses, use in as an annotation:

from mininterface import run
@dataclass
class Env:
    my_str: Annotated[str, Tag(validation=not_empty)]

m = run(Env)

For dicts, use it as a value:

m.form({"My string": Tag(annotation=str, validation=not_empty)})

`val: TagValue = None`

The value wrapped by Tag. It can be any value.

from mininterface import run, Tag

tag = Tag(True, "This is my boolean", bool)
m = run()
m.form({"My boolean": tag})
print(tag.val)  # True/False
print()

Image title

The encapsulated value is True, tag.description is 'This is my boolean', tag.annotation is bool and 'My boolean' is used as tag.label.

Tip

If the Tag is nested, the info is fetched to the outer Tag. When updated, the inner Tag value updates accordingly.

tag = Tag(Tag(True))

`description: str = ''`

The description displayed in the UI.

`annotation: type[TagValue] | None = None`

Used for validation (ex. to convert an empty string to None). If not set, will be determined automatically from the val type.

`validation: Iterable[ValidationCallback] | ValidationCallback | None = None`

When the user submits the form, the values are validated (and possibly transformed) with a ValidationCallback function (or several of them). If the validation fails, user is prompted to edit the value.

The ValidationResult is either a boolean or an error message. Optionally, you may add a second argument to specify the tag value (to ex. recommend a better value).

`label: str | None = None`

Name displayed in the UI. If not set, it is taken from the dict key or the field name.

m.form({"label": ...})

@dataclass
class Form:
    my_field: str
m.form(Form)  # label=my_field

`on_change: Callable[[Tag], Any] | None = None`

Accepts a callback that launches whenever the value changes (if the validation succeeds). The callback runs while the dialog is still running. The return value of the callback is currently not used.

In the following example, we alter the heading title according to the chosen value.

from mininterface import run
from mininterface.tag import SelectTag

def callback(tag: Tag):
    tag.facet.set_title(f"Value changed to {tag.val}")

m = run()
m.facet.set_title("Click the checkbox")
m.form({
    "My choice": SelectTag(options=["one", "two"], on_change=callback)
})

Choice with on change callback

`facet: Facet`

Access to the UI facet from the front-end side. (Read Mininterface.facet to access from the back-end side.)

Use the UI facet from within a callback, ex. from a validator.

from mininterface import run, Tag

def my_check(tag: Tag):
    tag.facet.set_title("My form title")
    return "Validation failed"

with run(title='My window title') as m:
    m.form({"My form": Tag(1, validation=my_check)})

This happens when you click ok.

Facet front-end

`original_val: TagValue`

Meant to be read only in callbacks. The original value, preceding UI change. Handy while validating.

def check(tag.val):
    if tag.val != tag.original_val:
        return "You have to change the value."
m.form({"number", Tag(8, validation=check)})

`update`

Update the tag value with type conversion and checks.

UI → Tag → the object of origin.

Parameters:

Name	Type	Description	Default
`ui_value`	`UiValue \| str`	The value as it has been updated in a UI. Update accordingly the value in the original linked dict/object the mininterface was invoked with. Validates the type and do the transformation. (Ex: Some values might be nulled from "".)	required

bool

Type	Description
`bool`	Whether the value was succesfully changed or whether the revision is needed.