Tapahtumadokumentaatio

Jokainen tapahtuma, jonka isäntä julkaisee natiiveille liitännäisille (PluginEvents.h), yltää myös Pythoniin, yhtä alla mainittua poikkeusta lukuun ottamatta. Kukin aihe toimittaa pienen tyypitetyn dataluokan käsittelijällesi. Dataluokat on määritelty tiedostossa Python/mte/events.py ja ne voi tuoda ylätason mte-paketista.

Aihe ↔ dataluokka -taulukko

Aihe	Hyötykuorman dataluokka	Kentät	Koriste
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 ("" = koko editori, "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 (bitit mte.MODIFIER_SHIFT / MODIFIER_CONTROL / MODIFIER_ALT / MODIFIER_META) — napsautus kirjanmerkkisarakkeessa, katso ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = kansio suljettiin)	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	(ei kenttiä) — kerran ajoa kohti, ensimmäisen ruudun jälkeen	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(ei kenttiä)	on_app_about_to_quit

document on isännän antama läpinäkymätön kokonaislukutunniste. Vertaa tunnisteita operaattorilla ==; älä säilytä niitä editorin uudelleenkäynnistysten yli. text.changed laukeaa jokaisella muokkauksella — pidä tuo käsittelijä hyvin yksinkertaisena.

Tilaaminen kevyellä koristeella

Suositeltu — koristeen nimi vastaa aihetta ja hyötykuorman tyyppi päätellään:

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

Tilaaminen raa'alla API:lla

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

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

• Palauttaa paikallisesti varatun tunnisteen handler_id (merkkijono muotoa "py-ev/N").
• Tuntemattomat aiheet heittävät poikkeuksen ValueError tilaushetkellä — ei hiljaista tyhjäkäyntiä.

Peru tilaus, kun et enää välitä:

ctx.events.unsubscribe(handler_id)

Huomaa: funktion unsubscribe jälkeen isäntä lakkaa toimittamasta aihetta sinulle, mutta työntekijän paikallinen välittäjä säilyttää kohtansa, kunnes liitännäinen sammuu. Älä luota funktioon unsubscribe muistin siivoamisessa — se on käytäntösignaali eikä roskienkeruun rakennuspalikka.

Toimituksen ehdot

• Tapahtumat laukeavat sen jälkeen, kun vastaava toiminto on valmistunut. Tapahtumassa document.saved tiedosto on jo levyllä. Tapahtumassa document.closed asiakirjan tunniste on jo virheellinen.
• Useat saman aiheen tilaajat laukeavat kaikki, määrittelemättömässä järjestyksessä.
• Käsittelijässäsi heitetyt poikkeukset nappaa työntekijä ja kirjoittaa ne stderriin (näkyvät isännän lokissa muodossa [worker stderr] …). Huonosti käyttäytyvä käsittelijä ei estä muita tilaajia laukeamasta.
• Hyötykuorman dataluokat ovat muuttumattomia; älä muuta olion ev kenttiä.

Julkaiseminen

ctx.events.publish(topic, payload) lähettää tapahtuman jaettuun väylään, jossa sekä natiivit että Python-tilaajat vastaanottavat sen. Vain ne kaksi aihetta, jotka on tarkoitettu liitännäisen julkaistaviksi, hyväksytään — työtilapari, jonka Työtila-liitännäinen lähettää Etsi tiedostoista -toiminnolle ja komentopaletille:

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

Mikä tahansa muu aihe heittää poikkeuksen ValueError: loput ovat isännän omia toteamuksia tosiasioista (asiakirja tallennettiin, teema muuttui), joita liitännäisen ei kuulu väittää. Liitännäisten väliseen viestintään näiden lisäksi rekisteröi komento ja anna toisen puolen kutsua sitä.

Ei käytettävissä

Kahdella isäntätapahtumalla ei ole Python-aihetta:

• document.aboutToSave: isäntä julkaisee sen synkronisesti tallennus estettynä, kunnes jokainen tilaaja palaa, ja tuon noudattaminen työntekijä-RPC:n yli vaatii saman määräaikakäsittelyn kuin täydennystoimittajat, ennen kuin se on turvallista. Natiivit liitännäiset voivat käyttää sitä tänään.
• DocumentAboutToClose — tarkoituksella vain natiivi. Sen koko lupaus on, että asiakirjan voi vielä lukea käsittelijän sisällä, ja toimitus Python-liitännäiselle on asynkroninen, joten käsittelijä ajettaisiin vasta sulkemisen jälkeen. Käytä sen sijaan document.closed-aihetta ja pidä asiakirjasta tarvitsemasi tieto ajan tasalla aiempien tapahtumien perusteella sen sijaan, että lukisit sen sulkemishetkellä.