Events-Referenz¶

Jedes Event, das der Host für native Plugins veröffentlicht (PluginEvents.h), erreicht auch Python — mit einer unten genannten Ausnahme. Jedes Topic liefert eine kleine typisierte Dataclass an Ihren Handler. Die Dataclasses sind in Python/mte/events.py definiert und aus dem Top-Level-Paket mte importierbar.

Topic-↔-Dataclass-Tabelle¶

Topic	Payload-Dataclass	Felder	Decorator
`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` (`""` = editorweit, `"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` (Bits `mte.MODIFIER_SHIFT` / `MODIFIER_CONTROL` / `MODIFIER_ALT` / `MODIFIER_META`) — ein Klick in die Lesezeichenspalte, siehe `ctx.line_markers`	`on_margin_clicked`
`workspace.rootChanged`	`mte.WorkspaceRootChanged`	`root: str` (`""` = Ordner geschlossen)	`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`	(keine Felder) — einmal pro Lauf, nach dem ersten Frame	`on_host_window_shown`
`app.aboutToQuit`	`mte.AppAboutToQuit`	(keine Felder)	`on_app_about_to_quit`

document ist eine opake ganzzahlige Id, die der Host vergibt. Vergleichen Sie Ids mit ==; persistieren Sie sie nicht über Editor-Neustarts hinweg. text.changed feuert bei jeder Änderung — halten Sie diesen Handler trivial.

Abonnieren per Sugar-Decorator¶

Empfohlen — der Decorator-Name entspricht dem Topic, und der Payload-Typ wird abgeleitet:

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

Abonnieren über die Roh-API¶

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

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

Liefert die lokal vergebene handler_id zurück (ein "py-ev/N"-String).
Unbekannte Topics werfen zum Abonnementzeitpunkt ValueError — kein stilles No-op.

Bestellen Sie ab, wenn es Sie nicht mehr interessiert:

ctx.events.unsubscribe(handler_id)

Hinweis: Nach unsubscribe liefert der Host das Topic nicht mehr an Sie, aber der lokale Dispatcher des Workers behält seinen Eintrag, bis das Plugin herunterfährt. Verlassen Sie sich für die Speicherbereinigung nicht auf unsubscribe — es ist ein Policy-Signal, kein Garbage-Collection-Primitiv.

Zustellsemantik¶

Events feuern, nachdem die entsprechende Aktion abgeschlossen ist. Bei document.saved liegt die Datei bereits auf der Platte. Bei document.closed ist die Dokument-Id bereits ungültig.
Mehrere Abonnenten desselben Topics feuern alle, in undefinierter Reihenfolge.
Ausnahmen, die in Ihrem Handler geworfen werden, fängt der Worker ab und schreibt sie nach stderr (im Log des Hosts sichtbar als [worker stderr] …). Ein fehlverhaltender Handler hindert andere Abonnenten nicht am Feuern.
Payload-Dataclasses sind unveränderlich; mutieren Sie keine ev-Felder.

Veröffentlichen¶

ctx.events.publish(topic, payload) legt ein Event auf den gemeinsamen Bus, wo native und Python-Abonnenten es gleichermaßen empfangen. Akzeptiert werden nur die zwei Topics, die von einem Plugin veröffentlicht werden sollen — das Workspace-Paar, das das Arbeitsbereich-Plugin für In Dateien suchen und die Befehlspalette sendet:

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

Jedes andere Topic wirft ValueError: die übrigen sind Tatsachenaussagen des Hosts (ein Dokument wurde gespeichert, das Theme hat gewechselt), die ein Plugin nicht behaupten darf. Für Plugin-zu-Plugin-Nachrichten darüber hinaus registrieren Sie einen Befehl und lassen ihn von der anderen Seite aufrufen.

Nicht verfügbar¶

Zwei Host-Events haben kein Python-Topic:

document.aboutToSave: Der Host veröffentlicht es synchron, mit blockiertem Speichern, bis jeder Abonnent zurückkehrt — das über die Worker-RPC einzuhalten braucht erst dieselbe Deadline-Behandlung wie Completion-Provider. Native Plugins können es heute schon nutzen.
DocumentAboutToClose — absichtlich nur nativ. Sein ganzes Versprechen ist, dass das Dokument im Handler noch lesbar ist, und die Zustellung an ein Python-Plugin ist asynchron, sodass der Handler erst nach dem Schließen liefe. Verwenden Sie stattdessen document.closed und halten Sie alles, was Sie über ein Dokument brauchen, anhand der früheren Events aktuell, statt es beim Schließen zu lesen.