Gå till innehållet

mte.ui — byggare av formulärspecifikationer

Varje gränssnittsyta från fas 3 — ctx.docks.add_panel och ctx.settings_page.register — tar en formulärspecifikation: en vanlig ordbok som beskriver ett widgetträd. Bygg de specifikationerna med hjälparna mte.ui.* så att du slipper skriva JSON för hand.

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

Inget i mte.ui talar med Qt eller PySide — varje hjälpare returnerar en ordbok som följer det protokollschema värdens C++-formulärtolk förväntar sig. Kombinera dem gärna, foga in listor, eller generera dem programmatiskt:

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

Specifikationen valideras på värdsidan; okända kontrolltyper eller saknade obligatoriska fält ger ett fel InvalidParams som du ser i loggen.

Etiketterna i en formulärspecifikation översätts inte

Varje etikett du lägger i en specifikation — paneltitlar, kryssrutsetiketter, grupprubriker — visas exakt som du skrev den, vilket gränssnittsspråket än är. De är data som din insticksmodul skickar till redigeraren, inte strängar som redigeraren kan slå upp i en översättningskatalog. Ska din modul tala mer än ett språk, välj strängarna själv innan du anropar register; det aktuella gränssnittsspråket är ctx.app_settings.get_string(mte.keys.UI_LANGUAGE) (tomt betyder «följ systemet»). Detsamma gäller name och description som din plugin.json visar i Inställningar ▸ Insticksmoduler.

Layouter

Layoutbyggarna tar en lista med barnordböcker och ordnar dem lodrätt eller vågrätt.

Column(children)

Staplar barnen uppifrån och ned med en avslutande sträckning — kontrollerna behåller sin naturliga höjd i stället för att svälla för att fylla en hög docka.

Row(children)

Samma idé, från vänster till höger, med en avslutande vågrät sträckning.

Group(children, *, title="")

En ram med titel (återgiven som QGroupBox) som innehåller en lodrät stapel. Använd den för att visuellt gruppera besläktade kontroller:

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

Layouter nästlas fritt — en Row inuti en Column inuti en Group går bra.

Lövkontroller

Varje löv godtar samma fyra delade bindningar genom namngivna argument:

Argument Betydelse
id= Stabilt id som ctx.ui.get / ctx.ui.set och (underförstått) binds använder.
binds= "settings:<key>" — sparas automatiskt genom ctx.settings.
on_click= Id för det kommando som anropas — endast för Button.
on_change= Id för hanteraren (ctx.docks.on_change(...)) — för varje annan kontroll.

Bara löv som exponerar ett «värde» stöder binds och on_change.

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

Statisk text.

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

En tryckknapp. Att utlösa on_click anropar det registrerade kommandot; vill du hålla knappen i takt med något annat kan du sätta dess text med ctx.ui.set.

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

Boolesk kontroll. default är starttillståndet; binds åsidosätter det med det sparade värdet om ett sådant finns.

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

Textinmatning på en rad.

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

Snurrruta för heltal. min och max klämmer intervallet (båda valfria; den underliggande QSpinBox använder sitt standardintervall när de inte är satta). step är steget på pilarna.

int-intervall

NumberSpin bygger på QSpinBox, som lagrar en int (32 bitar). Värden utanför -2_147_483_648 … 2_147_483_647 mättas vid plattformens gräns.

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

Rullgardinslista. items är en lista — varje post får vara antingen en vanlig sträng eller ett objekt som {"value": "cpp", "label": "C++"} (i dag används bara value; label är reserverat för en framtida förfining).

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

Listwidget med enkelmarkering. on_change utlöses med texten i den nyss markerade posten. Inget binds — spara markeringen själv om du behöver den.

Åtkomst under körning

När panelen väl är registrerad styr du den från vilket kommando som helst:

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)

Se ctx.ui för hela referensen.

Spara värden

binds="settings:<key>" är det kortaste sättet att spara en kontrolls värde:

  • När panelen byggs läser widgeten sitt startvärde från ctx.settings.get(key, <default>).
  • Vid varje användarändring skriver widgeten tillbaka genom ctx.settings.set(key, new_value).

Eftersom både paneler och Inställningssidor delar ctx.settings speglar två kontroller med samma binds-sträng varandra i realtid. Det är så HelloPythons docka och Inställningssida håller kryssrutan «Loud» i takt.

Behöver du spara något som vokabulären inte täcker (till exempel markeringen i en List), läs och skriv direkt genom ctx.settings i ett återanrop on_change.