Hændelsesdokumentation

Hver hændelse, værten udgiver til indbyggede udvidelsesmoduler (PluginEvents.h), når også frem til Python med én undtagelse, der er nævnt nedenfor. Hvert emne leverer en lille typet dataklasse til din håndtering. Dataklasserne er defineret i Python/mte/events.py og kan importeres fra mte-pakken på øverste niveau.

Tabel over emne ↔ dataklasse

Emne	Indholdets dataklasse	Felter	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 ("" = hele editoren, "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) — et klik i bogmærkekolonnen, se ctx.line_markers	on_margin_clicked
workspace.rootChanged	mte.WorkspaceRootChanged	root: str ("" = mappen blev lukket)	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	(ingen felter) — én gang pr. kørsel, efter det første billede	on_host_window_shown
app.aboutToQuit	mte.AppAboutToQuit	(ingen felter)	on_app_about_to_quit

document er et uigennemsigtigt heltals-id, værten tildeler. Sammenlign id'er med ==; gem dem ikke på tværs af genstarter af editoren. text.changed udløses ved hver ændring — hold den håndtering ganske enkel.

At abonnere med den lette dekorator

Anbefalet — dekoratorens navn passer til emnet, og indholdets type udledes:

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

At abonnere med den rå API

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

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

• Giver det lokalt tildelte handler_id tilbage (en "py-ev/N"-tekststreng).
• Ukendte emner kaster ValueError ved abonneringen — ingen tavs ingenting.

Afmeld, når du ikke længere er interesseret:

ctx.events.unsubscribe(handler_id)

Bemærk: efter unsubscribe holder værten op med at levere emnet til dig, men arbejderens lokale fordeler beholder sin post, indtil udvidelsesmodulet lukkes ned. Regn ikke med unsubscribe til at rydde op i hukommelsen — det er et signal om politik og ikke en byggesten til affaldsindsamling.

Leveringens vilkår

• Hændelser udløses, efter at den tilsvarende handling er fuldført. Ved document.saved er filen allerede på disken. Ved document.closed er dokumentets id allerede ugyldigt.
• Flere abonnenter på det samme emne udløses alle sammen, i udefineret rækkefølge.
• Undtagelser, der kastes i din håndtering, opfanges af arbejderen og skrives til stderr (synligt i værtens log som [worker stderr] …). En håndtering, der opfører sig forkert, forhindrer ikke de andre abonnenter i at blive udløst.
• Indholdets dataklasser er uforanderlige; ændr ikke felter på ev.

At udgive

ctx.events.publish(topic, payload) lægger en hændelse på den fælles bus, hvor både indbyggede og Python-abonnenter modtager den. Kun de to emner, der er ment til at blive udgivet af et udvidelsesmodul, tages der imod — parret om arbejdsområdet, som Arbejdsområde-udvidelsesmodulet udsender til Søg i filer og 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"},
]})

Ethvert andet emne kaster ValueError: resten er værtens egne udsagn om, hvad der er sket (et dokument blev gemt, temaet ændrede sig), og som et udvidelsesmodul ikke har nogen grund til at påstå. Vil du have beskeder mellem udvidelsesmoduler ud over disse, så registrér en kommando, og lad den anden side kalde den.

Ikke til rådighed

To værtshændelser har intet Python-emne:

• document.aboutToSave: værten udgiver den synkront, mens gemningen er spærret, indtil hver abonnent vender tilbage, og at leve op til det over arbejder-RPC'en kræver den samme behandling med frister som fuldførelsesleverandører, inden det er trygt. Indbyggede udvidelsesmoduler kan bruge den i dag.
• DocumentAboutToClose — med vilje kun for indbyggede moduler. Hele dens løfte er, at dokumentet stadig kan læses inde i behandleren, og leveringen til et Python-modul er asynkron, så behandleren ville køre efter lukningen. Brug document.closed i stedet, og hold det, du har brug for at vide om et dokument, ajour ud fra de tidligere hændelser i stedet for at læse det ved lukningen.