Udalosti

Zásuvné moduly reagujú na dianie v editore cez IEventBus. Udalosti sú obyčajné štruktúry definované v PluginEvents.h:

Udalosť	Obsah
DocumentOpened	DocumentId, std::filesystem::path
DocumentAboutToClose	DocumentId — používateľ zatvára dokument a zatvorenie je isté; zverejňuje sa tesne predtým, než zmizne jeho posledné zobrazenie, kým sa dokument ešte dá celý prečítať. Nie pri ukončení programu. Iba natívne moduly; pozri nižšie
DocumentClosed	DocumentId
DocumentSaved	DocumentId
DocumentPrinted	DocumentId, pages — zverejnená po tom, čo tlačová úloha dorazila k zariadeniu (Súbor ▸ Vytlačiť, prípadne Tlačiť vnútri náhľadu); pages počíta vytlačené strany dokumentu, teda menej, než ich dokument má, keď bol zvolený výber alebo rozsah strán. Zrušený dialóg nezverejní nič. Zatiaľ iba zásuvné moduly v C++
DocumentAboutToSave	DocumentId, path — synchrónna, buffer je stále upraviteľný (orezanie bielych znakov, pridanie koncového nového riadka); žiadne dialógy
DocumentEncodingChanged	DocumentId, DocumentEncoding — zmenilo sa kódovanie, v ktorom hostiteľ zapíše dokument späť (súbor bol práve rozpoznaný alebo bolo zavolané setDocumentEncoding)
DocumentLineEndingChanged	DocumentId, LineEnding — zmenil sa ukončovač riadkov, ktorý dokument používa (súbor bol práve načítaný či znova načítaný, pri uložení sa uplatnilo end_of_line zo .editorconfig, alebo bolo zavolané setLineEnding)
DocumentModifiedChanged	DocumentId, modified — prepol sa príznak čistý/zmenený (nie pri každom stlačení klávesu)
TextChanged	DocumentId, pos, addedBytes, removedBytes
SelectionChanged	DocumentId
ActiveDocumentChanged	DocumentId
HostWindowShown	(žiadny) — raz za spustenie, po tom, čo je prvá snímka na obrazovke; naplánujte odtiaľto pomalú prácu pri štarte
SettingsChanged	scope — "" = v celom editore, "plugins/<id>" = bola uplatnená stránka daného modulu
WorkspaceRootChanged	root (prázdne = priečinok zatvorený) — zverejňuje zásuvný modul Pracovný priestor
WorkspaceFilesChanged	files[] s prvkami {path, displayPath} — zverejňuje zásuvný modul Pracovný priestor
ThemeChanged	variant ("light" / "dark" / "")
AppAboutToQuit	(žiadny)
CommandShortcutChanged	commandId, sequence (nová prenosná kombinácia; "" = bez priradenia)
MarginClicked	DocumentId, line, margin (EditorMargin::Symbol), modifiers — kliknutie ľavým tlačidlom do stĺpca záložiek editora, pri každom takom kliknutí; pozri Značky riadkov

Udalosti môžu zverejňovať aj zásuvné moduly (ctx.events().publish(e)) — takto modul Pracovný priestor rozosiela WorkspaceRootChanged a WorkspaceFilesChanged, aby ich prevzali Nájsť v súboroch a Paleta príkazov.

Jeden dokument, jedno id

DocumentId pomenúva dokument, nie tablu. Rozdeliť dokument zobrazuje jeden súbor v dvoch tablách a obidve nesú to isté DocumentId, takže:

• DocumentOpened sa zverejňuje raz na súbor — rozdelenie nezverejní nič;
• DocumentClosed sa zverejní, až keď sa zatvorí posledné zobrazenie dokumentu, takže zatvorením jednej tably sa nikdy nezruší stav, ktorý tá druhá ešte potrebuje;
• activeDocument() odpovedá týmto jedným id bez ohľadu na to, ktorá tabla je vpredu, a openDocuments() uvedie dokument raz.

Zámerne neexistuje udalosť pre jednotlivé tably ani spôsob, ako zistiť, ktorá tabla je aktívna: tably sú vecou hostiteľa a všetko, čo zásuvný modul môže pozorovať — text, kurzor, výber, kódovanie, konce riadkov, príznak zmeny — patrí dokumentu, ktorý tably zdieľajú.

DocumentAboutToClose

Zverejňuje sa raz pre každý dokument, bezprostredne predtým, než zmizne jeho posledné zobrazenie, keď je zatvorenie isté — prípadná otázka na uloženie bola zodpovedaná a nebola zrušená. V obslužnej rutine je dokument ešte celý: text(), filePath(), caret(), bookmarkedLines() aj kódovanie odpovedajú. Potom nasleduje upratovanie a napokon DocumentClosed. Zverejňuje ju každý spôsob zatvorenia karty (Zavrieť, Zavrieť všetko, Zavrieť ostatné / Zavrieť vpravo, kliknutie prostredným tlačidlom, Zavrieť priečinok, closeDocument() volané modulom), vrátane dokumentov bez názvu; zatvorenie jedného tabla dokumentu, ktorý je ešte zobrazený v inom, nie.

Ukončenie programu ju nezverejňuje. Aplikácia raz zverejní AppAboutToQuit, kým sú všetky dokumenty ešte otvorené, a žiadne udalosti zatvorenia jednotlivých dokumentov: modul, ktorý si medzi reláciami uchováva stav dokumentov, prejde vo svojej obslužnej rutine AppAboutToQuit zoznam openDocuments(). DocumentAboutToClose preto vždy znamená „tento dokument sa zatvára“, nikdy „program končí“.

Obslužné rutiny bežia synchrónne, uprostred zatvárania: buďte rýchli, nezobrazujte dialógové okná a s množinou dokumentov zaobchádzajte iba na čítanie — neotvárajte, nezatvárajte ani neaktivujte dokumenty a neupravujte text zatváraného dokumentu.

Je zámerne iba natívna: doručenie modulom v Pythone je asynchrónne, takže sľub „ešte sa dá prečítať“ by sa tam nedal dodržať, a udalosť sa im neponúka (pozri Udalosti v Pythone).

CommandShortcutChanged

CommandShortcutChanged sa vyvolá, keď sa zmení skutočná skratka príkazu — pri premapovaní používateľom v Mapovaní skratiek, pri importe či obnovení mapy klávesov alebo pri zapnutí či zrušení potlačenia kvôli konfliktu. Príkazy viazané na ponuku nepotrebujú nič (hostiteľ ich akciu premapuje); príkazy zaregistrované so scope = command_scope::kPluginWindow sa prihlásia na odber a kombináciu znova uplatnia na vlastné widgety (pozri Príkazy a ponuky).

Prihlásenie na odber

subscribe je šablóna, ktorá vracia Subscription (RAII). Odber udržiavajte nažive ako člen tak dlho, ako chcete, aby sa zavolanie vyvolávalo; jeho zničením sa odber zruší.

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

Každý Subscription si držte ako člen zásuvného modulu, aby sa všetky zavolania v shutdown() zrušili automaticky.