Skip to content

Settings

UI Settings

The UI behaviour might be modified via an settings object. This can be passed to the run function or defined through a config file. Settings defined in the config file have bigger priority. Every interface has its own settings object.

Passing the settings to the run method:

from mininterface.settings import MininterfaceSettings

opt = MininterfaceSettings()
run(settings=opt)

Specifying only the GuiSettings: 

from mininterface.settings import MininterfaceSettings, GuiSettings

opt = MininterfaceSettings(gui=GuiSettings(combobox_since=1))
run(settings=opt)

Config file special section

In a YAML config file, use a special section 'mininterface' to set up the UI. For example, this stub will enforce your program to use the Tui interface.

mininterface:
    interface: tui

Complete example

Source of program.py, we have one single attribute foo:

from typing import Annotated
from dataclasses import dataclass
from mininterface import run, Options

@dataclass
class Env:
    foo: Annotated["str", Options("one", "two")] = "one"

m = run(Env)
m.form()

Source of program.yaml will enforce the comboboxes:

number: 5
mininterface:
    gui:
        combobox_since: 1

The difference when using such configuration file.

Configuration not used Configuration used

Inheritance

The individual setting items are inherited, while the descendants have the higher priority. Ex. TuiSettings works as a default for TextSettings and TextualSettings.

graph LR
GuiSettings --> UiSettings
TuiSettings  --> UiSettings
TextualSettings --> TuiSettings
TextSettings --> TuiSettings

Ex. this config file sets the UiSettings item mnemonic to None for TuiSettings and more specifically to False for TextSettings.

mininterface:
    tui:
        mnemonic: null
    text:
        mnemonic: False

For the different interfaces, the value varies this way:

interface mnemonic value
gui True (the UiSettings item default)
textual None
text False

The settings object

MininterfaceSettings

interface: Optional[InterfaceName] = None

Enforce an interface. By default, we choose automatically.

UiSettings

toggle_widget: str = 'f4'

Shortcuts to toggle ex. calendar or file picker.

mnemonic: Optional[bool] = True

Allow users to access fields with the Alt+char shortcut.

  • True: All Tags with Tag(mnemonic=char|True|None) will have a mnemonic enabled.
  • False: All mnemonic is disabled, even if configured via Tag(mnemonic=char).
  • None: All Tags with Tag(mnemonic=char|True) will have a mnemonic enabled.

mnemonic_hidden: bool = False

If True, the field label is not underlined to mark the mnemonic.

GuiSettings

combobox_since: int = 10

The threshold to switch from radio buttons to a combobox.

radio_select_on_focus: bool = False

Select the radio button on focus. Ex. when navigating by arrows.

TuiSettings

TextualSettings

TextSettings

mnemonic_over_number: Optional[bool] = None

Even when mnemonic can be determined, use rather number as a shortcut.

By default if None, determine those with Tag(mnemonic=char|True):

>     ok
[1] foo1: ×
[2] foo2: ×
[g] foo3: ×

If True, determine also those having Tag(mnemonic=None):

>     ok
[f] foo1: ×
[o] foo2: ×
[g] foo3: ×

If False, we prefer numbers:

>     ok
[1] foo1: ×
[2] foo2: ×
[3] foo3: ×

The original code:

from dataclasses import dataclass
from typing import Annotated
from mininterface import Tag, run
from mininterface.settings import MininterfaceSettings, TextSettings


@dataclass
class Env:
    foo1: bool = False
    foo2: bool = False
    foo3: Annotated[bool, Tag(mnemonic="g")] = False


m = run(Env, settings=MininterfaceSettings(text=TextSettings(mnemonic_over_number=True)))
m.form()
quit()