Hyppää sisältöön

mte.ui — lomakemäärittelyn rakentajat

Jokainen vaiheen 3 käyttöliittymäpinta — ctx.docks.add_panel ja ctx.settings_page.register — ottaa lomakemäärittelyn: tavallisen sanakirjan, joka kuvaa ohjausobjektipuun. Rakenna nämä määrittelyt mte.ui.*-apureilla, jottei sinun tarvitse kirjoittaa JSONia käsin.

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

Mikään mte.ui-moduulissa ei puhu Qt:n tai PySiden kanssa — kukin apuri palauttaa sanakirjan, joka noudattaa sitä muotoa, jota isännän C++-lomakejäsennin odottaa. Saat vapaasti koota niitä, liittää luetteloita tai tuottaa niitä ohjelmallisesti:

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

Määrittely tarkistetaan isännän puolella; tuntemattomat ohjausobjektityypit tai puuttuvat pakolliset kentät tuottavat InvalidParams-virheen, jonka näet lokissa.

Lomakemäärittelyn nimiöitä ei käännetä

Jokainen otsikko, jonka laitat määrittelyyn — paneelien otsikot, valintaruutujen nimiöt, ryhmäotsikot — näytetään täsmälleen sellaisena kuin kirjoitit sen, riippumatta käyttöliittymän kielestä. Ne ovat dataa, jonka liitännäisesi lähettää editorille, eivätkä merkkijonoja, jotka editori voisi hakea käännösluettelosta. Jos liitännäisesi pitäisi puhua useampaa kuin yhtä kieltä, valitse merkkijonot itse ennen kuin kutsut funktiota register; nykyinen käyttöliittymäkieli on ctx.app_settings.get_string(mte.keys.UI_LANGUAGE) (tyhjä tarkoittaa »seuraa järjestelmää«). Sama koskee kenttiä name ja description, jotka plugin.json-tiedostosi näyttää kohdassa Asetukset ▸ Liitännäiset.

Asettelut

Asettelurakentajat ottavat luettelon lapsisanakirjoja ja järjestävät ne pysty- tai vaakasuoraan.

Column(children)

Pinoaa lapset ylhäältä alas ja lisää loppuun venymän — ohjausobjektit pysyvät luonnollisessa korkeudessaan sen sijaan että paisuisivat täyttämään korkean telakan.

Row(children)

Sama ajatus, vasemmalta oikealle, loppuun lisätyn vaakavenymän kera.

Group(children, *, title="")

Otsikoitu kehys (piirrettynä QGroupBox-oliona), joka sisältää pystysuoran pinon. Käytä sitä ryhmitelläksesi toisiinsa liittyviä ohjausobjekteja visuaalisesti:

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

Asettelut voivat olla vapaasti sisäkkäisiä — Row Column-olion sisällä Group-olion sisällä käy hyvin.

Yksittäiset ohjausobjektit

Kukin yksittäinen ohjausobjekti hyväksyy samat neljä yhteistä sidontaa avainsana-argumentteina:

Argumentti Merkitys
id= Vakaa tunniste, jota ctx.ui.get / ctx.ui.set ja (epäsuorasti) binds käyttävät.
binds= "settings:<key>" — tallentuu automaattisesti kohteen ctx.settings kautta.
on_click= Kutsuttavan komennon tunniste — vain painikkeet.
on_change= Käsittelijätunniste (ctx.docks.on_change(...)) — jokainen muu ohjausobjekti.

Vain ne yksittäiset ohjausobjektit, jotka paljastavat »arvon«, tukevat kenttiä binds ja on_change.

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

Staattista tekstiä.

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

Painike. Kentän on_click laukaiseminen kutsuu rekisteröityä komentoa; jos haluat pitää painikkeen tahdissa jonkin muun kanssa, voit käyttää funktiota ctx.ui.set sen text-kenttään.

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

Totuusarvo-ohjausobjekti. default on alkutila; binds ohittaa sen tallennetulla arvolla, jos sellainen on.

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

Yksirivinen tekstinsyöttö.

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

Kokonaislukuvalitsin. min ja max rajaavat välin (molemmat valinnaisia; taustalla oleva QSpinBox käyttää oletusväliään, kun niitä ei ole asetettu). step on nuolien askel.

int-väli

NumberSpin nojaa luokkaan QSpinBox, joka tallentaa int-arvon (32-bittinen). Arvot välin -2_147_483_648 … 2_147_483_647 ulkopuolella kyllästyvät alustan rajaan.

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

Pudotusvalikko. items on luettelo — kukin kohta voi olla joko tavallinen merkkijono tai objekti kuten {"value": "cpp", "label": "C++"} (vain value on tänään käytössä; label on varattu tulevaa hienosäätöä varten).

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

Luettelo-ohjausobjekti yksittäisvalinnalla. on_change laukeaa uuden valitun kohdan tekstillä. Ei binds-kenttää — tallenna valinta itse, jos tarvitset sitä.

Ajonaikainen pääsy

Kun paneeli on rekisteröity, ohjaa sitä mistä tahansa komennosta:

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)

Katso koko dokumentaatio kohdasta ctx.ui.

Arvojen tallentaminen

binds="settings:<key>" on lyhin tapa tallentaa ohjausobjektin arvo:

  • Paneelia rakennettaessa ohjausobjekti lukee alkuarvonsa kutsusta ctx.settings.get(key, <default>).
  • Jokaisella käyttäjän muokkauksella ohjausobjekti kirjoittaa takaisin kutsulla ctx.settings.set(key, new_value).

Koska sekä paneelit että asetussivut jakavat kohteen ctx.settings, kaksi ohjausobjektia, joilla on sama binds-merkkijono, peilaavat toisiaan reaaliajassa. Siten HelloPythonin telakka ja asetussivu pitävät »Loud«-valintaruudun tahdissa.

Jos sinun täytyy tallentaa jotain, mitä sanasto ei kata (esimerkiksi List-valinta), lue ja kirjoita suoraan kohteen ctx.settings kautta on_change-takaisinkutsussa.