Referencia udalostí¶

Každá udalosť, ktorú hostiteľ zverejňuje pre natívne zásuvné moduly (PluginEvents.h), sa dostane aj do Pythonu, s jedinou výnimkou uvedenou nižšie. Každá téma doručuje vášmu obslužnému kódu malú typovanú dátovú triedu. Dátové triedy sú definované v Python/mte/events.py a dajú sa importovať z balíka mte na najvyššej úrovni.

Tabuľka téma ↔ dátová trieda¶

Téma	Dátová trieda obsahu	Polia	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` (`""` = v celom editore, `"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`) — kliknutie do stĺpca záložiek, pozri `ctx.line_markers`	`on_margin_clicked`
`workspace.rootChanged`	`mte.WorkspaceRootChanged`	`root: str` (`""` = priečinok zatvorený)	`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í) — raz za spustenie, po prvej snímke	`on_host_window_shown`
`app.aboutToQuit`	`mte.AppAboutToQuit`	(bez polí)	`on_app_about_to_quit`

document je nepriehľadné celé číslo, ktoré priradil hostiteľ. Id porovnávajte pomocou ==; neuchovávajte ich naprieč reštartmi editora. text.changed sa vyvolá pri každej úprave — tento obslužný kód majte triviálny.

Odber cez pohodlný dekorátor¶

Odporúčané — názov dekorátora zodpovedá téme a typ obsahu sa 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")

Odber cez surové API¶

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

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

Vracia lokálne pridelený handler_id (reťazec "py-ev/N").
Neznáme témy pri odbere vyvolajú ValueError — žiadna tichá prázdna operácia.

Keď vás téma prestane zaujímať, odber zrušte:

ctx.events.unsubscribe(handler_id)

Poznámka: po unsubscribe vám hostiteľ tému prestane doručovať, ale lokálny rozdeľovač pracovného procesu si svoju položku ponechá až do ukončenia zásuvného modulu. Nespoliehajte sa na unsubscribe pri upratovaní pamäte — je to signál o zámere, nie primitívum na zber odpadu.

Sémantika doručovania¶

Udalosti sa vyvolávajú po dokončení príslušnej akcie. Pri document.saved je súbor už na disku. Pri document.closed je id dokumentu už neplatné.
Viacerí odberatelia tej istej témy sa vyvolajú všetci, v nešpecifikovanom poradí.
Výnimky vyvolané vo vašom obslužnom kóde zachytí pracovný proces a zapíše ich na stderr (v logu hostiteľa ich vidieť ako [worker stderr] …). Zle sa správajúci obslužný kód nezabráni vyvolaniu ostatných odberateľov.
Dátové triedy obsahu sú nemenné; polia ev neupravujte.

Zverejňovanie¶

ctx.events.publish(topic, payload) umiestni udalosť na zdieľanú zbernicu, kde ju prijmú natívni aj pythonovskí odberatelia. Prijímajú sa iba dve témy, ktoré zásuvný modul zverejňovať má — dvojica z pracovného priestoru, ktorú modul Pracovný priestor rozosiela pre Nájsť v súboroch a Paletu príkazov:

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

Ktorákoľvek iná téma vyvolá ValueError: ostatné sú vlastnými konštatovaniami hostiteľa (dokument bol uložený, motív sa naozaj zmenil), ktoré zásuvnému modulu neprináleží tvrdiť. Na posielanie správ medzi zásuvnými modulmi nad tento rámec zaregistrujte príkaz a nechajte druhú stranu, nech ho vyvolá.

Nie je k dispozícii¶

Dve udalosti hostiteľa nemajú tému v Pythone:

document.aboutToSave: hostiteľ ju zverejňuje synchrónne s ukladaním zablokovaným, kým sa nevrátia všetci odberatelia, a jej rešpektovanie cez RPC pracovného procesu si vyžaduje rovnaké zaobchádzanie s termínmi ako pri poskytovateľoch dopĺňania, než bude bezpečné. Natívne zásuvné moduly ju používať môžu už dnes.
DocumentAboutToClose — zámerne iba natívna. Celý jej prísľub spočíva v tom, že dokument sa dá v obslužnej rutine ešte prečítať, a doručenie modulu v Pythone je asynchrónne, takže obslužná rutina by bežala až po zatvorení. Namiesto nej použite document.closed a to, čo o dokumente potrebujete vedieť, udržiavajte aktuálne z predchádzajúcich udalostí, namiesto toho, aby ste to čítali pri zatváraní.