Hendelsesdokumentasjon

Hver hendelse verten publiserer for innebygde programtillegg (PluginEvents.h), når også fram til Python, med ett unntak som er nevnt nedenfor. Hvert emne leverer en liten typet dataklasse til behandleren din. Dataklassene er definert i Python/mte/events.py og kan importeres fra mte-pakken på øverste nivå.

Tabell over emne ↔ dataklasse

Emne	Innholdets dataklasse	Felter	Dekorator
document.opened	mte.DocumentOpened	document: int, path: str	on_document_opened
document.closed	mte.DocumentClosed	document: int	on_document_closed
document.saved	mte.DocumentSaved	document: int	on_document_saved
document.encodingChanged	mte.DocumentEncodingChanged	document: int, encoding: mte.DocumentEncoding	on_document_encoding_changed
document.lineEndingChanged	mte.DocumentLineEndingChanged	document: int, ending: mte.LineEnding	on_document_line_ending_changed
document.modifiedChanged	mte.DocumentModifiedChanged	document: int, modified: bool	on_document_modified_changed
document.activeChanged	mte.ActiveDocumentChanged	document: int	on_active_document_changed
text.changed	mte.TextChanged	document, position, added_bytes, removed_bytes	on_text_changed
selection.changed	mte.SelectionChanged	document: int	on_selection_changed
settings.changed	mte.SettingsChanged	scope: str ("" = hele redigereren, "plugins/<id>")	on_settings_changed
theme.changed	mte.ThemeChanged	variant: str ("light" / "dark" / "")	on_theme_changed
margin.clicked	mte.MarginClicked	document: int, line: int, margin: str ("symbol"), modifiers: int (biter mte.MODIFIER_SHIFT / MODIFIER_CONTROL / MODIFIER_ALT / MODIFIER_META) — et klikk i bokmerkekolonnen, se ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = mappen ble lukket)	on_workspace_root_changed
workspace.filesChanged	mte.WorkspaceFilesChanged	files: list[mte.WorkspaceFile] (path, display_path)	on_workspace_files_changed
command.shortcutChanged	mte.CommandShortcutChanged	command_id: str, sequence: str	on_command_shortcut_changed
host.windowShown	mte.HostWindowShown	(ingen felter) — én gang per kjøring, etter det første bildet	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(ingen felter)	on_app_about_to_quit

document er en ugjennomsiktig heltalls-id som verten tildeler. Sammenlign id-er med ==; ta dem ikke vare på på tvers av omstarter av redigereren. text.changed utløses ved hver endring — hold den behandleren helt enkel.

Å abonnere med den lette dekoratoren

Anbefalt — dekoratorens navn passer til emnet, og innholdets type utledes:

import mte

def register(ctx):

    @ctx.events.on_document_saved
    def _saved(ev: mte.DocumentSaved):
        ctx.log.info(f"saved doc {ev.document}")

    @ctx.events.on_document_opened
    def _opened(ev: mte.DocumentOpened):
        ctx.log.info(f"opened {ev.document} at {ev.path}")

    @ctx.events.on_app_about_to_quit
    def _quit(_ev: mte.AppAboutToQuit):
        ctx.log.info("editor is closing")

Å abonnere med det rå API-et

def _saved(ev):
    ctx.log.info(f"saved {ev.document}")

handler_id = ctx.events.subscribe("document.saved", _saved)

• Gir den lokalt tildelte handler_id tilbake (en "py-ev/N"-tekststreng).
• Ukjente emner kaster ValueError ved abonneringen — ingen stille ingenting.

Meld deg av når du ikke lenger er interessert:

ctx.events.unsubscribe(handler_id)

Merk: etter unsubscribe slutter verten å levere emnet til deg, men arbeiderens lokale fordeler beholder posten sin inntil programtillegget stenges ned. Regn ikke med unsubscribe til å rydde opp i minnet — det er et signal om retningslinjer og ikke en byggestein for søppelrydding.

Leveringens vilkår

• Hendelser utløses etter at den tilsvarende handlingen er fullført. Ved document.saved er filen alt på disken. Ved document.closed er dokumentets id alt ugyldig.
• Flere abonnenter på det samme emnet utløses alle sammen, i udefinert rekkefølge.
• Unntak som kastes i behandleren din, fanges av arbeideren og skrives til stderr (synlig i vertens logg som [worker stderr] …). En behandler som oppfører seg galt, hindrer ikke de andre abonnentene i å bli utløst.
• Innholdets dataklasser kan ikke endres; endre ikke felter på ev.

Å publisere

ctx.events.publish(topic, payload) kringkaster til både innebygde og Python-abonnenter — det tas bare imot for de to emnene om arbeidsområdet (workspace.rootChanged, workspace.filesChanged), som Arbeidsområde-programtillegget kringkaster til Søk i filer og kommandopaletten:

ctx.events.publish("workspace.rootChanged", {"root": "/home/me/project"})
ctx.events.publish("workspace.filesChanged", {"files": [
    {"path": "/home/me/project/a.txt", "displayPath": "a.txt"},
]})

Ethvert annet emne kaster ValueError: resten er vertens egne utsagn om hva som har skjedd (et dokument ble lagret, temaet endret seg), og som et programtillegg ikke har noen grunn til å påstå. Vil du ha meldinger mellom programtillegg utover disse, så registrer en kommando, og la den andre siden kalle den.

Ikke tilgjengelig

To vertshendelser har ikke noe Python-emne:

• document.aboutToSave: verten publiserer den synkront, mens lagringen er sperret inntil hver abonnent vender tilbake, og å innfri det over arbeider-RPC-en krever den samme behandlingen med frister som fullføringsleverandører, før det er trygt. Innebygde programtillegg kan bruke den i dag.
• DocumentAboutToClose — bare for innebygde programtillegg, med vilje. Hele løftet er at dokumentet fortsatt kan leses inne i behandleren, og leveringen til et Python-programtillegg er asynkron, så behandleren ville kjøre etter at dokumentet er lukket. Bruk document.closed i stedet, og hold det du trenger å vite om et dokument oppdatert ut fra de tidligere hendelsene i stedet for å lese det ved lukking.