Reference událostí

Každá událost, kterou hostitel publikuje pro nativní zásuvné moduly (PluginEvents.h), dorazí i do Pythonu, s jednou výjimkou uvedenou níže. Každé téma doručí vaší obsluze malou typovanou dataclass. Tyto dataclass jsou definovány v Python/mte/events.py a lze je importovat z balíku mte na nejvyšší úrovni.

Tabulka téma ↔ dataclass

Téma	Dataclass s daty	Pole	Dekorátor
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 ("" = celý editor, "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 (bity mte.MODIFIER_SHIFT / MODIFIER_CONTROL / MODIFIER_ALT / MODIFIER_META) — kliknutí do sloupce záložek, viz ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = složka zavřena)	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	(bez polí) — jednou za běh, po prvním snímku	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(bez polí)	on_app_about_to_quit

document je neprůhledné celočíselné id přidělené hostitelem. Id porovnávejte pomocí ==; neuchovávejte je přes restarty editoru. text.changed se spouští při každé úpravě — držte tuto obsluhu triviální.

Odběr sladkým dekorátorem

Doporučené — název dekorátoru odpovídá tématu a typ dat se odvodí:

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

Odběr surovým rozhraním

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

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

• Vrací místně přidělené handler_id (řetězec "py-ev/N").
• Neznámá témata vyhodí ValueError už při odběru — žádná tichá prázdná operace.

Až vás to přestane zajímat, odběr zrušte:

ctx.events.unsubscribe(handler_id)

Poznámka: po unsubscribe vám hostitel dané téma přestane doručovat, ale místní rozdělovač pracovníka si svou položku ponechá, dokud se modul neukončí. Nespoléhejte na unsubscribe při úklidu paměti — je to signál o zásadách, nikoli primitivum pro uvolňování paměti.

Sémantika doručování

• Události se spouštějí poté, co odpovídající akce skončila. Při document.saved je soubor už na disku. Při document.closed je id dokumentu už neplatné.
• Několik odběratelů téhož tématu se spustí všichni, v nedefinovaném pořadí.
• Výjimky vyhozené ve vaší obsluze pracovník zachytí a zapíše na stderr (v protokolu hostitele viditelné jako [worker stderr] …). Špatně se chovající obsluha nebrání spuštění ostatních odběratelů.
• Dataclass s daty jsou neměnné; pole ev neměňte.

Publikování

ctx.events.publish(topic, payload) umístí událost na sdílenou sběrnici, kde ji obdrží nativní i pythonovští odběratelé. Přijímají se pouze dvě témata, která mají být modulem publikována — dvojice o pracovním prostoru, kterou modul Pracovní prostor rozhlašuje pro Najít v souborech a Paletu příkazů:

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

Kterékoli jiné téma vyhodí ValueError: zbytek jsou vlastní tvrzení hostitele o skutečnosti (dokument byl uložen, motiv se změnil), do kterých zásuvnému modulu nic není. Pro předávání zpráv mezi moduly nad rámec těchto zaregistrujte příkaz a nechte druhou stranu, ať jej vyvolá.

Není k dispozici

Dvě události hostitele nemají téma v Pythonu:

• document.aboutToSave: hostitel ji publikuje synchronně a uložení je zablokováno, dokud se každý odběratel nevrátí, a dostát tomu přes RPC pracovníka vyžaduje totéž ošetření termínem jako u poskytovatelů dokončování, než to bude bezpečné. Nativní moduly ji dnes používat mohou.
• DocumentAboutToClose — záměrně jen nativní. Celý její slib spočívá v tom, že dokument jde uvnitř obslužné rutiny ještě přečíst, a doručení modulu v Pythonu je asynchronní, takže by obslužná rutina běžela až po zavření. Použijte místo ní document.closed a to, co o dokumentu potřebujete vědět, udržujte aktuální z dřívějších událostí, místo abyste to četli při zavírání.