Przejdź do treści

mte.ui — kreatory specyfikacji formularzy

Każda powierzchnia UI Fazy 3 — ctx.docks.add_panel i ctx.settings_page.register — przyjmuje specyfikację formularza: zwykły dict opisujący drzewo widżetów. Buduj te specyfikacje pomocnikami mte.ui.*, żeby nie pisać JSON-a ręcznie.

from mte.ui import (
    Column, Row, Group,
    Label, Button, Checkbox, LineEdit, NumberSpin, ComboBox, List,
)

Nic w mte.ui nie rozmawia z Qt ani PySide — każdy pomocnik zwraca dict zgodny ze schematem przewodowym, jakiego oczekuje parser formularzy C++ po stronie hosta. Możesz je swobodnie składać, sklejać listy albo generować programowo:

from mte.ui import Column, Row, Label, Button

def make_toolbar(commands):
    return Row([Button(text=c["label"], on_click=c["id"])
                for c in commands])

form = Column([Label(text="Actions:"),
               make_toolbar(my_commands)])

Specyfikacja jest walidowana po stronie hosta; nieznane typy kontrolek albo brakujące pola wymagane dają błąd InvalidParams widoczny w logu.

Layouty

Kreatory layoutów przyjmują listę dictów potomnych i układają je pionowo lub poziomo.

Column(children)

Układa dzieci z góry na dół z końcowym rozciągnięciem — kontrolki zachowują naturalną wysokość, zamiast puchnąć na cały wysoki dok.

Row(children)

To samo, od lewej do prawej, z końcowym rozciągnięciem poziomym.

Group(children, *, title="")

Ramka z tytułem (renderowana jako QGroupBox) zawierająca pionowy stos. Używaj do wizualnego grupowania powiązanych kontrolek:

Group([
    Checkbox(id="cs", label="Case sensitive", binds="settings:cs"),
    Checkbox(id="ww", label="Whole words",    binds="settings:ww"),
], title="Search options")

Layouty zagnieżdżają się dowolnie — Row w Column w Group jest w porządku.

Kontrolki-liście

Każdy liść przyjmuje te same cztery wspólne wiązania przez argumenty nazwane:

Argument Znaczenie
id= Stabilny id używany przez ctx.ui.get / ctx.ui.set i (niejawnie) binds.
binds= "settings:<klucz>" — automatyczna trwałość przez ctx.settings.
on_click= Id polecenia do wywołania — tylko Button.
on_change= Id handlera (ctx.docks.on_change(...)) — każda inna kontrolka.

Tylko liście udostępniające „wartość" wspierają binds i on_change.

Label(*, text="", id=None)

Tekst statyczny.

Button(*, text, on_click=None, id=None)

Przycisk. Odpalenie on_click wywołuje zarejestrowane polecenie; jeśli chcesz synchronizować przycisk z czymś innym, możesz ctx.ui.set jego text.

Checkbox(*, label="", default=False, id=None, binds=None, on_change=None)

Kontrolka logiczna. default to stan początkowy; binds nadpisuje go wartością utrwaloną, jeśli istnieje.

LineEdit(*, placeholder="", default="", id=None, binds=None, on_change=None)

Jednolinijkowe pole tekstowe.

NumberSpin(*, default=0, min=None, max=None, step=1, id=None, binds=None, on_change=None)

Spinbox liczb całkowitych. min i max przycinają zakres (oba opcjonalne; bazowy QSpinBox używa swojego domyślnego zakresu, gdy nieustawione). step to przyrost strzałek.

Zakres int

NumberSpin opiera się na QSpinBox, który przechowuje int (32-bitowy). Wartości poza -2_147_483_648 … 2_147_483_647 nasycą się na limicie platformy.

ComboBox(*, items, default="", id=None, binds=None, on_change=None)

Lista rozwijana. items to lista — każdy wpis może być zwykłym łańcuchem albo obiektem w rodzaju {"value": "cpp", "label": "C++"} (dziś używane jest tylko value; label jest zarezerwowany na przyszłe rozszerzenie).

List(*, items, id=None, on_change=None)

Widżet listy z pojedynczym wyborem. on_change odpala się z tekstem nowo wybranej pozycji. Bez binds — utrwal wybór samodzielnie, jeśli go potrzebujesz.

Dostęp w czasie działania

Po zarejestrowaniu panelu steruj nim z dowolnego polecenia:

panel_id = ctx.docks.add_panel(id="my.panel", ..., form=Column([
    LineEdit(id="needle"),
    Checkbox(id="cs"),
]))

# Read current values
needle = ctx.ui.get(panel_id, "needle")
cs     = ctx.ui.get(panel_id, "cs") == "true"

# Write values (does NOT fire on_change)
ctx.ui.set(panel_id, "needle", "hello")
ctx.ui.set(panel_id, "cs", True)

Pełną dokumentację znajdziesz w ctx.ui.

Utrwalanie wartości

binds="settings:<klucz>" to najkrótsza droga do utrwalenia wartości kontrolki:

  • Przy budowie panelu widżet czyta wartość początkową z ctx.settings.get(klucz, <default>).
  • Przy każdej edycji użytkownika widżet zapisuje przez ctx.settings.set(klucz, nowa_wartość).

Ponieważ panele i strony Preferencji współdzielą ctx.settings, dwie kontrolki z tym samym łańcuchem binds odzwierciedlają się nawzajem w czasie rzeczywistym. Tak właśnie dok HelloPythona i jego strona Preferencji synchronizują pole „Loud".

Jeśli musisz utrwalić coś, czego słownik nie pokrywa (np. wybór w List), czytaj/zapisuj bezpośrednio przez ctx.settings w callbacku on_change.