Naslag voor gebeurtenissen

Elke gebeurtenis die de host voor inheemse plug-ins publiceert (PluginEvents.h) bereikt ook Python, op één hieronder genoemde uitzondering na. Elk onderwerp levert een kleine getypeerde dataclass aan uw afhandelaar. De dataclasses zijn in Python/mte/events.py gedefinieerd en kunnen uit het pakket mte op het hoogste niveau ingevoerd worden.

Tabel onderwerp ↔ dataclass

Onderwerp	Dataclass van de inhoud	Velden	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 ("" = de hele 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 (bits mte.MODIFIER_SHIFT / MODIFIER_CONTROL / MODIFIER_ALT / MODIFIER_META) — een klik in de bladwijzerkolom, zie ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = map gesloten)	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	(geen velden) — één keer per uitvoering, na het eerste beeld	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(geen velden)	on_app_about_to_quit

document is een ondoorzichtige gehele id die de host toekent. Vergelijk id's met ==; bewaar ze niet over herstarts van de editor heen. text.changed gaat bij elke bewerking af — houd die afhandelaar triviaal.

Inschrijven met een zoete decorator

Aanbevolen — de naam van de decorator komt overeen met het onderwerp en het type van de inhoud wordt afgeleid:

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

Inschrijven met de kale API

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

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

• Levert de lokaal toegekende handler_id op (een tekenreeks "py-ev/N").
• Onbekende onderwerpen werpen bij het inschrijven een ValueError — geen stille niet-bewerking.

Schrijf u uit wanneer het u niet meer kan schelen:

ctx.events.unsubscribe(handler_id)

Let op: na unsubscribe levert de host het onderwerp niet meer bij u af, maar de lokale verdeler van de worker houdt zijn item totdat de plug-in afsluit. Vertrouw niet op unsubscribe om geheugen op te ruimen — het is een beleidssignaal, geen primitief voor geheugenbeheer.

Afleversemantiek

• Gebeurtenissen gaan nadat de bijbehorende actie voltooid is af. Bij document.saved staat het bestand al op de schijf. Bij document.closed is de document-id al ongeldig.
• Zijn er meerdere inschrijvers op hetzelfde onderwerp, dan gaan ze allemaal af, in ongedefinieerde volgorde.
• Uitzonderingen die uw afhandelaar werpt worden door de worker opgevangen en naar stderr geschreven (in het logboek van de host zichtbaar als [worker stderr] …). Een afhandelaar die zich misdraagt weerhoudt andere inschrijvers er niet van af te gaan.
• Dataclasses van de inhoud zijn onveranderlijk; wijzig de velden van ev niet.

Publiceren

ctx.events.publish(topic, payload) zet een gebeurtenis op de gedeelde bus, waar inheemse en Python-inschrijvers haar gelijkelijk ontvangen. Alleen de twee onderwerpen die bedoeld zijn om door een plug-in gepubliceerd te worden worden aanvaard — het paar van de werkruimte, dat de plug-in Werkruimte uitzendt voor Zoeken in bestanden en het Opdrachtenpalet:

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

Elk ander onderwerp werpt een ValueError: de rest zijn de eigen vaststellingen van de host (een document is opgeslagen, het thema is veranderd) die een plug-in niet mag beweren. Voor berichten van plug-in tot plug-in die verder gaan, registreert u een opdracht en laat u de andere kant die aanroepen.

Niet beschikbaar

Twee hostgebeurtenissen hebben geen Python-onderwerp:

• document.aboutToSave: de host publiceert haar synchroon met het opslaan geblokkeerd totdat elke inschrijver teruggekeerd is, en dat over de worker-RPC eerbiedigen vergt dezelfde behandeling met een deadline als bij aanvullingsleveranciers voordat het veilig is. Inheemse plug-ins kunnen haar vandaag al gebruiken.
• DocumentAboutToClose — bewust alleen native. Haar hele belofte is dat het document in de handler nog leesbaar is, en de aflevering aan een Python-plug-in is asynchroon, zodat de handler pas na het sluiten zou lopen. Gebruik in plaats daarvan document.closed, en houd wat je over een document nodig hebt bij aan de hand van de eerdere gebeurtenissen in plaats van het bij het sluiten te lezen.