Gebeurtenissen

Plug-ins reageren op activiteit in de editor via IEventBus. Gebeurtenissen zijn eenvoudige structs die in PluginEvents.h gedefinieerd zijn:

Gebeurtenis	Inhoud
DocumentOpened	DocumentId, std::filesystem::path
DocumentAboutToClose	DocumentId — de gebruiker sluit het document en het sluiten staat vast; gepubliceerd vlak voordat de laatste weergave verdwijnt, terwijl het nog volledig leesbaar is. Niet bij afsluiten. Alleen native plug-ins; zie hieronder
DocumentClosed	DocumentId
DocumentSaved	DocumentId
DocumentPrinted	DocumentId, pages — gepubliceerd nadat een afdruktaak het apparaat bereikt heeft (Bestand ▸ Afdrukken, of Afdrukken binnen het voorbeeld); pages telt de afgedrukte documentpagina's, minder dan het document heeft wanneer er een selectie of een paginabereik gekozen was. Een geannuleerd venster publiceert niets. Voorlopig alleen C++-plug-ins
DocumentAboutToSave	DocumentId, path — synchroon, de buffer is nog bewerkbaar (witruimte weghalen, een afsluitende nieuwe regel toevoegen); geen vensters
DocumentEncodingChanged	DocumentId, DocumentEncoding — de tekencodering waarin de host het document zal terugschrijven is veranderd (bestand zojuist herkend, of setDocumentEncoding aangeroepen)
DocumentLineEndingChanged	DocumentId, LineEnding — het regeleindeteken dat het document gebruikt is veranderd (bestand zojuist gelezen of herladen, een end_of_line uit .editorconfig bij het opslaan toegepast, of setLineEnding aangeroepen)
DocumentModifiedChanged	DocumentId, modified — de vlag schoon/vuil is gekanteld (niet bij elke toetsaanslag)
TextChanged	DocumentId, pos, addedBytes, removedBytes
SelectionChanged	DocumentId
ActiveDocumentChanged	DocumentId
HostWindowShown	(geen) — één keer per uitvoering, nadat het eerste beeld op het scherm staat; plan traag opstartwerk hierop
SettingsChanged	scope — "" = de hele editor, "plugins/<id>" = de pagina van die plug-in is toegepast
WorkspaceRootChanged	root (leeg = map gesloten) — gepubliceerd door de plug-in Werkruimte
WorkspaceFilesChanged	files[] van {path, displayPath} — gepubliceerd door de plug-in Werkruimte
ThemeChanged	variant ("light" / "dark" / "")
AppAboutToQuit	(geen)
CommandShortcutChanged	commandId, sequence (nieuwe draagbare combinatie; "" = losgekoppeld)
MarginClicked	DocumentId, line, margin (EditorMargin::Symbol), modifiers — een linkerklik in de bladwijzerkolom van een editor, bij elke zulke klik; zie Regelmarkeringen

Ook plug-ins kunnen gebeurtenissen publiceren (ctx.events().publish(e)) — zo zendt de plug-in Werkruimte WorkspaceRootChanged / WorkspaceFilesChanged uit, zodat Zoeken in bestanden en het Opdrachtenpalet ze kunnen afnemen.

Eén document, één id

Een DocumentId benoemt een document, geen deelvenster. Document splitsen toont één bestand in twee deelvensters, en beide dragen dezelfde DocumentId, dus:

• DocumentOpened wordt één keer per bestand gepubliceerd — splitsen publiceert niets;
• DocumentClosed wordt alleen gepubliceerd wanneer de laatste weergave van het document sluit, zodat één deelvenster sluiten nooit staat afbreekt die het andere nog nodig heeft;
• activeDocument() antwoordt met die ene id, welk deelvenster ook vooraan staat, en openDocuments() somt het document één keer op.

Er is met opzet geen gebeurtenis per deelvenster en geen manier om te vragen welk deelvenster actief is: deelvensters zijn een zaak van de host, en alles wat een plug-in kan waarnemen — tekst, cursor, selectie, tekencodering, regeleinde, staat van wijziging — hoort bij het document, dat de deelvensters delen.

DocumentAboutToClose

Eén keer per document gepubliceerd, direct voordat de laatste weergave verdwijnt, wanneer het sluiten vaststaat — een eventuele vraag om op te slaan is beantwoord en niet geannuleerd. In de handler is het document nog heel: text(), filePath(), caret(), bookmarkedLines() en de tekencodering antwoorden allemaal. Daarna volgt de afbraak en dan DocumentClosed. Elke manier om een tabblad te sluiten publiceert haar (Sluiten, Alles sluiten, Andere sluiten / Rechts hiervan sluiten, een middelklik, Map sluiten, de closeDocument() van een plug-in), naamloze documenten inbegrepen; het sluiten van één deelvenster van een document dat nog in een ander te zien is, niet.

Afsluiten publiceert haar niet. De toepassing publiceert één keer AppAboutToQuit, terwijl alle documenten nog open zijn, en geen sluitgebeurtenissen per document: een plug-in die per document staat over sessies heen bewaart, loopt in zijn AppAboutToQuit-handler door openDocuments(). DocumentAboutToClose betekent daarom altijd «dit document wordt gesloten», nooit «het programma wordt afgesloten».

Handlers draaien synchroon, midden in het sluiten: wees snel, toon geen dialoogvensters en behandel de verzameling documenten als alleen-lezen — open, sluit of activeer geen documenten en bewerk de tekst van het document dat wordt gesloten niet.

Ze is bewust alleen native: de aflevering aan Python-plug-ins is asynchroon, dus de belofte «nog leesbaar» zou daar niet na te komen zijn, en de gebeurtenis wordt hun niet aangeboden (zie Python-gebeurtenissen).

CommandShortcutChanged

CommandShortcutChanged gaat af wanneer de effectieve sneltoets van een opdracht verandert — een gebruiker die opnieuw toewijst in de sneltoetstoewijzing, een toetsindeling importeren of terugzetten, of een conflictonderdrukking die aanslaat of wegvalt. Menu-gebonden opdrachten hebben niets nodig (de host koppelt hun actie opnieuw); opdrachten die met scope = command_scope::kPluginWindow geregistreerd zijn schrijven zich in en passen de reeks opnieuw op hun eigen widgets toe (zie Opdrachten en menu's).

Inschrijven

subscribe is een sjabloon dat een Subscription (RAII) oplevert. Houd de inschrijving als lid in leven zolang u wilt dat de callback afgaat; hem vernietigen schrijft u uit.

m_sub = ctx.events().subscribe<MTE::plugin::DocumentSaved>(
    [this](const MTE::plugin::DocumentSaved& e) {
        // react to e.id ...
    });

class IEventBus {
public:
    template <class Event>
    Subscription subscribe(std::function<void(const Event&)> cb);
    // Forwards to a type-erased subscribeRaw(std::type_index, ...) internally.
};

Tip

Houd elke Subscription als lid van de plug-in vast, zodat alle callbacks in shutdown() automatisch afgebroken worden.