Preskočiť na obsah

mte.ui — tvorcovia špecifikácií formulárov

Každá plocha rozhrania z fázy 3 — ctx.docks.add_panel a ctx.settings_page.register — prijíma špecifikáciu formulára: obyčajný slovník opisujúci strom widgetov. Tieto špecifikácie zostavujte pomocníkmi mte.ui.*, aby ste JSON nemuseli písať ručne.

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

Nič v mte.ui nekomunikuje s Qt ani s PySide — každý pomocník vracia slovník podľa prenosovej schémy, akú očakáva parser formulárov v C++ na strane hostiteľa. Pokojne ich skladajte, vkladajte do zoznamov alebo generujte programovo:

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)])

Špecifikácia sa overuje na strane hostiteľa; neznáme typy ovládacích prvkov alebo chýbajúce povinné polia vyvolajú chybu InvalidParams, ktorú uvidíte v logu.

Popisy v špecifikácii formulára sa neprekladajú

Každý popis, ktorý do špecifikácie vložíte — názvy panelov, popisy začiarkavacích políčok, nadpisy skupín — sa zobrazí presne tak, ako ste ho napísali, nech je jazyk rozhrania akýkoľvek. Sú to údaje, ktoré váš modul posiela editoru, nie reťazce, ktoré by editor vedel vyhľadať v prekladovom katalógu. Ak má váš modul hovoriť viac než jedným jazykom, zvoľte reťazce sami pred volaním register; aktuálny jazyk rozhrania získate cez ctx.app_settings.get_string(mte.keys.UI_LANGUAGE) (prázdna hodnota znamená „riadiť sa systémom“). To isté platí pre name a description, ktoré váš plugin.json zobrazuje v Predvoľby ▸ Zásuvné moduly.

Rozloženia

Tvorcovia rozložení prijímajú zoznam podriadených slovníkov a usporiadajú ich zvislo alebo vodorovne.

Column(children)

Ukladá podriadené prvky zhora nadol s koncovou výplňou — ovládacie prvky si tak ponechajú prirodzenú výšku, namiesto aby sa nafúkli a vyplnili vysoký panel.

Row(children)

Tá istá myšlienka zľava doprava, s koncovou vodorovnou výplňou.

Group(children, *, title="")

Rámček s názvom (vykreslený ako QGroupBox) obsahujúci zvislý stĺpec. Použite ho na vizuálne zoskupenie súvisiacich ovládacích prvkov:

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

Rozloženia sa dajú voľne vnárať — Row vnútri Column vnútri Group je v poriadku.

Koncové ovládacie prvky

Každý koncový prvok prijíma cez kľúčové argumenty tie isté štyri spoločné väzby:

Argument Význam
id= Stabilné id používané metódami ctx.ui.get a ctx.ui.set a (implicitne) väzbou binds.
binds= "settings:<key>" — automatické uchovanie cez ctx.settings.
on_click= Id príkazu, ktorý sa má vyvolať — iba pri tlačidlách.
on_change= Id obslužného kódu (ctx.docks.on_change(...)) — pri každom inom ovládacom prvku.

binds a on_change podporujú iba koncové prvky, ktoré sprístupňujú „hodnotu“.

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

Statický text.

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

Tlačidlo. Vyvolaním on_click sa spustí zaregistrovaný príkaz; ak chcete tlačidlo držať v súlade s niečím iným, môžete mu cez ctx.ui.set nastaviť text.

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

Logický ovládací prvok. default je počiatočný stav; binds ho prekryje uchovanou hodnotou, ak nejaká existuje.

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

Jednoriadkové textové pole.

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

Číselné pole pre celé čísla. min a max orezávajú rozsah (obidva voliteľné; keď nie sú nastavené, použije podkladový QSpinBox svoj predvolený rozsah). step je prírastok pri šípkach.

Rozsah typu int

NumberSpin stojí na QSpinBox, ktorý uchováva int (32-bitový). Hodnoty mimo -2_147_483_648 … 2_147_483_647 sa nasýtia na limite platformy.

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

Rozbaľovací zoznam. items je zoznam — každá položka môže byť buď obyčajným reťazcom, alebo objektom ako {"value": "cpp", "label": "C++"} (dnes sa používa iba value; label je vyhradené pre budúce spresnenie).

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

Zoznamový widget s jednoduchým výberom. on_change sa vyvolá s textom novo vybranej položky. Bez binds — ak výber potrebujete uchovať, urobte to sami.

Prístup za behu

Keď je panel zaregistrovaný, ovládajte ho z ktoréhokoľvek príkazu:

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)

Úplnú referenciu nájdete v ctx.ui.

Uchovávanie hodnôt

binds="settings:<key>" je najkratšou cestou, ako uchovať hodnotu ovládacieho prvku:

  • Pri zostavení panela si widget načíta počiatočnú hodnotu z ctx.settings.get(key, <default>).
  • Pri každej úprave používateľom widget zapíše späť cez ctx.settings.set(kľúč, nová_hodnota).

Keďže panely aj stránky Predvolieb zdieľajú ctx.settings, dva ovládacie prvky s rovnakým reťazcom binds sa navzájom zrkadlia v reálnom čase. Presne takto drží HelloPython svoj panel a stránku Predvolieb v súlade pri začiarkavacom políčku „Loud“.

Ak potrebujete uchovať niečo, čo slovník nepokrýva (napríklad výber v List), čítajte a zapisujte priamo cez ctx.settings v obslužnom kóde on_change.