Hændelser

Udvidelsesmoduler reagerer på aktivitet i editoren gennem IEventBus. Hændelser er almindelige strukturer defineret i PluginEvents.h:

Hændelse	Indhold
DocumentOpened	DocumentId, std::filesystem::path
DocumentAboutToClose	DocumentId — brugeren lukker dokumentet, og lukningen er sikker; udgives lige før dets sidste visning forsvinder, mens det stadig kan læses fuldt ud. Ikke ved afslutning. Kun indbyggede moduler; se nedenfor
DocumentClosed	DocumentId
DocumentSaved	DocumentId
DocumentPrinted	DocumentId, pages — udgives, efter at et udskriftsjob er nået frem til enheden (Filer ▸ Udskriv, eller Udskriv inde i forhåndsvisningen); pages tæller de udskrevne dokumentsider og er lavere end dokumentets antal, når en markering eller et sideområde blev valgt. Et annulleret vindue udgiver ingenting. Kun C++-udvidelsesmoduler indtil videre
DocumentAboutToSave	DocumentId, path — synkron, bufferen kan stadig redigeres (fjern blanktegn, tilføj et afsluttende linjeskift); ingen vinduer
DocumentEncodingChanged	DocumentId, DocumentEncoding — den tegnkodning, værten vil skrive dokumentet tilbage i, har ændret sig (filen blev netop bestemt, eller setDocumentEncoding blev kaldt)
DocumentLineEndingChanged	DocumentId, LineEnding — det linjeskift, dokumentet bruger, har ændret sig (filen blev netop læst eller genindlæst, et end_of_line fra .editorconfig blev anvendt ved gemning, eller setLineEnding blev kaldt)
DocumentModifiedChanged	DocumentId, modified — flaget for ren eller ændret vendte (ikke ved hvert tastetryk)
TextChanged	DocumentId, pos, addedBytes, removedBytes
SelectionChanged	DocumentId
ActiveDocumentChanged	DocumentId
HostWindowShown	(ingen) — én gang pr. kørsel, efter at det første billede er på skærmen; læg langsomt opstartsarbejde i kø ud fra denne
SettingsChanged	scope — "" = hele editoren, "plugins/<id>" = det moduls side blev anvendt
WorkspaceRootChanged	root (tom = mappen blev lukket) — udgives af Arbejdsområde-udvidelsesmodulet
WorkspaceFilesChanged	files[] af {path, displayPath} — udgives af Arbejdsområde-udvidelsesmodulet
ThemeChanged	variant ("light" / "dark" / "")
AppAboutToQuit	(ingen)
CommandShortcutChanged	commandId, sequence (den nye flytbare kombination; "" = uden tildeling)
MarginClicked	DocumentId, line, margin (EditorMargin::Symbol), modifiers — et venstreklik i en editors bogmærkekolonne, ved hvert sådant klik; se Linjemærker

Udvidelsesmoduler kan også udgive hændelser (ctx.events().publish(e)) — det er sådan Arbejdsområde-udvidelsesmodulet udsender WorkspaceRootChanged og WorkspaceFilesChanged, som Søg i filer og kommandopaletten tager imod.

Ét dokument, ét id

Et DocumentId navngiver et dokument og ikke en rude. Opdel dokumentet viser én fil i to ruder, og begge ruder bærer det samme DocumentId, så:

• DocumentOpened udgives én gang pr. fil — en opdeling udgiver ingenting;
• DocumentClosed udgives kun, når den sidste visning af dokumentet lukkes, så det at lukke én rude aldrig river tilstand ned, som den anden stadig har brug for;
• activeDocument() svarer med det ene id, uanset hvilken rude der er forrest, og openDocuments() opregner dokumentet én gang.

Der findes med vilje ingen hændelse pr. rude og ingen måde at spørge, hvilken rude der er aktiv: ruder er værtens anliggende, og alt, hvad et udvidelsesmodul kan iagttage — tekst, markør, markering, tegnkodning, linjeskift, ændret tilstand — hører til dokumentet, som ruderne deler.

DocumentAboutToClose

Udgives én gang pr. dokument, umiddelbart før dets sidste visning forsvinder, når lukningen er sikker — et eventuelt spørgsmål om at gemme er besvaret og ikke annulleret. Inde i behandleren er dokumentet stadig helt: text(), filePath(), caret(), bookmarkedLines() og tegnkodningen svarer alle. Derefter følger nedbrydningen og så DocumentClosed. Enhver måde at lukke et faneblad på udgiver den (Luk, Luk alle, Luk de andre / Luk dem til højre, et midterklik, Luk mappe, et moduls closeDocument()), også for unavngivne dokumenter; at lukke én rude af et dokument, der stadig vises i en anden, gør ikke.

Afslutning udgiver den ikke. Programmet udgiver AppAboutToQuit én gang, mens alle dokumenter stadig er åbne, og ingen lukkehændelser pr. dokument: et modul, der gemmer tilstand pr. dokument mellem sessioner, gennemløber openDocuments() i sin AppAboutToQuit-behandler. DocumentAboutToClose betyder derfor altid »dette dokument lukkes«, aldrig »programmet afsluttes«.

Behandlere kører synkront, midt i lukningen: vær hurtig, vis ingen dialogbokse, og behandl mængden af dokumenter som skrivebeskyttet — åbn, luk eller aktivér ingen dokumenter, og redigér ikke teksten i det dokument, der lukkes.

Den er med vilje kun for indbyggede moduler: leveringen til Python-moduler er asynkron, så løftet »kan stadig læses« kunne ikke holdes der, og hændelsen tilbydes dem ikke (se Python-hændelser).

CommandShortcutChanged

CommandShortcutChanged udløses, når en kommandos faktiske genvejstast ændrer sig — en omtildeling i genvejstastoversigten, en import eller nulstilling af en tastaturopsætning, eller at en konfliktundertrykkelse træder til eller bortfalder. Menubundne kommandoer behøver ingenting (værten tildeler deres handling en ny tast); kommandoer, der er registreret med scope = command_scope::kPluginWindow, abonnerer og anvender sekvensen på deres egne kontroller igen (se Kommandoer og menuer).

At abonnere

subscribe er en skabelon, der giver et Subscription tilbage (RAII). Hold abonnementet i live som et medlem, så længe du vil have tilbagekaldet til at udløses; ødelægger man det, afmeldes abonnementet.

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

Hold hvert Subscription som et medlem af udvidelsesmodulet, så alle tilbagekald rives ned af sig selv i shutdown().