Händelsereferens

Varje händelse värden publicerar för inhemska insticksmoduler (PluginEvents.h) når även Python, med ett undantag som nämns nedan. Varje ämne levererar en liten typad dataklass till din hanterare. Dataklasserna definieras i Python/mte/events.py och går att importera från toppnivåpaketet mte.

Tabell ämne ↔ dataklass

Ämne	Innehållets dataklass	Fält	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 ("" = hela redigeraren, "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 (bitar mte.MODIFIER_SHIFT / MODIFIER_CONTROL / MODIFIER_ALT / MODIFIER_META) — ett klick i bokmärkeskolumnen, se ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = mappen stängd)	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	(inga fält) — en gång per körning, efter den första bilden	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(inga fält)	on_app_about_to_quit

document är ett ogenomskinligt heltals-id som värden tilldelar. Jämför id:n med ==; spara dem inte mellan omstarter av redigeraren. text.changed utlöses vid varje ändring — håll den hanteraren trivial.

Prenumerera med sockerdekorator

Rekommenderat — dekoratorns namn stämmer med ämnet och innehållets typ härleds:

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

Prenumerera med det råa API:t

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

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

• Returnerar det lokalt tilldelade handler_id (en sträng "py-ev/N").
• Okända ämnen kastar ValueError vid prenumerationen — ingen tyst nulloperation.

Avsluta prenumerationen när du inte längre bryr dig:

ctx.events.unsubscribe(handler_id)

Observera: efter unsubscribe slutar värden leverera ämnet till dig, men arbetarens lokala fördelare behåller sin post tills insticksmodulen avslutas. Förlita dig inte på unsubscribe för att städa minne — det är en policysignal, inte en primitiv för skräpsamling.

Leveranssemantik

• Händelser utlöses efter att motsvarande åtgärd slutförts. Vid document.saved ligger filen redan på disken. Vid document.closed är dokument-id:t redan ogiltigt.
• Flera prenumeranter på samma ämne utlöses alla, i odefinierad ordning.
• Undantag som din hanterare kastar fångas av arbetaren och skrivs till stderr (synliga i värdens logg som [worker stderr] …). En hanterare som beter sig illa hindrar inte andra prenumeranter från att utlösas.
• Innehållets dataklasser är oföränderliga; ändra inte fälten i ev.

Publicera

ctx.events.publish(topic, payload) lägger en händelse på den delade bussen, där inhemska och Python-prenumeranter tar emot den lika. Bara de två ämnen som är avsedda att publiceras av en insticksmodul godtas — arbetsytans par, som insticksmodulen Arbetsyta sänder ut för Sök i filer och 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"},
]})

Varje annat ämne kastar ValueError: de övriga är värdens egna konstateranden (ett dokument sparades, temat ändrades) som en insticksmodul inte har med att göra. För meddelanden mellan insticksmoduler därutöver registrerar du ett kommando och låter andra sidan anropa det.

Inte tillgängligt

Två värdhändelser saknar Python-ämne:

• document.aboutToSave: värden publicerar den synkront med sparandet blockerat tills varje prenumerant återvänt, och att uppfylla det över arbetarens RPC kräver samma deadlinebehandling som kompletteringsleverantörer innan det är säkert. Inhemska insticksmoduler kan använda den redan i dag.
• DocumentAboutToClose — avsiktligt bara för inbyggda moduler. Hela dess löfte är att dokumentet fortfarande går att läsa i hanteraren, och leveransen till en Python-modul är asynkron, så hanteraren skulle köras först efter stängningen. Använd document.closed i stället, och håll det du behöver veta om ett dokument aktuellt utifrån de tidigare händelserna i stället för att läsa det vid stängningen.