Hendelser

Programtillegg reagerer på aktivitet i redigereren gjennom IEventBus. Hendelser er alminnelige strukturer definert i PluginEvents.h:

Hendelse	Innhold
DocumentOpened	DocumentId, std::filesystem::path
DocumentAboutToClose	DocumentId — brukeren lukker dokumentet, og lukkingen er sikker; publiseres like før den siste visningen forsvinner, mens det ennå kan leses fullt ut. Ikke ved avslutning. Bare innebygde programtillegg; se nedenfor
DocumentClosed	DocumentId
DocumentSaved	DocumentId
DocumentPrinted	DocumentId, pages — publiseres etter at en utskriftsjobb har nådd fram til enheten (Fil ▸ Skriv ut, eller Skriv ut inne i forhåndsvisningen); pages teller de utskrevne dokumentsidene og er færre enn dokumentet har når en merking eller et sideområde ble valgt. Et avbrutt vindu publiserer ingenting. Bare C++-programtillegg inntil videre
DocumentAboutToSave	DocumentId, path — synkron, bufferen kan fortsatt redigeres (fjern blanktegn, legg til et avsluttende linjeskift); ingen vinduer
DocumentEncodingChanged	DocumentId, DocumentEncoding — den tegnkodingen verten vil skrive dokumentet tilbake i, har endret seg (filen ble nettopp bestemt, eller setDocumentEncoding ble kalt)
DocumentLineEndingChanged	DocumentId, LineEnding — det linjeskiftet dokumentet bruker, har endret seg (filen ble nettopp lest eller lastet inn på nytt, en end_of_line fra .editorconfig ble tatt i bruk ved lagring, eller setLineEnding ble kalt)
DocumentModifiedChanged	DocumentId, modified — flagget for ren eller endret snudde (ikke ved hvert tastetrykk)
TextChanged	DocumentId, pos, addedBytes, removedBytes
SelectionChanged	DocumentId
ActiveDocumentChanged	DocumentId
HostWindowShown	(ingen) — én gang per kjøring, etter at det første bildet er på skjermen; legg tregt oppstartsarbeid i kø ut fra denne
SettingsChanged	scope — "" = hele redigereren, "plugins/<id>" = det programtilleggets side ble tatt i bruk
WorkspaceRootChanged	root (tom = mappen ble lukket) — publiseres av Arbeidsområde-programtillegget
WorkspaceFilesChanged	files[] av {path, displayPath} — publiseres av Arbeidsområde-programtillegget
ThemeChanged	variant ("light" / "dark" / "")
AppAboutToQuit	(ingen)
CommandShortcutChanged	commandId, sequence (den nye flyttbare kombinasjonen; "" = uten binding)
MarginClicked	DocumentId, line, margin (EditorMargin::Symbol), modifiers — et venstreklikk i bokmerkekolonnen i en redigerer, ved hvert slikt klikk; se Linjemerker

Programtillegg kan også publisere hendelser (ctx.events().publish(e)) — det er slik Arbeidsområde-programtillegget kringkaster WorkspaceRootChanged og WorkspaceFilesChanged, som Søk i filer og kommandopaletten tar imot.

Ett dokument, én id

En DocumentId navngir et dokument og ikke en rute. Del dokumentet til høyre viser én fil i to ruter, og begge rutene bærer samme DocumentId, så:

• DocumentOpened publiseres én gang per fil — en deling publiserer ingenting;
• DocumentClosed publiseres bare når den siste visningen av dokumentet lukkes, så det å lukke én rute aldri river ned tilstand den andre fortsatt trenger;
• activeDocument() svarer med den ene id-en uansett hvilken rute som er fremst, og openDocuments() lister dokumentet én gang.

Det finnes med vilje ingen hendelse per rute og ingen måte å spørre hvilken rute som er aktiv: ruter er vertens anliggende, og alt et programtillegg kan iaktta — tekst, markør, merking, tegnkoding, linjeskift, endret tilstand — hører til dokumentet, som rutene deler.

DocumentAboutToClose

Publiseres én gang per dokument, rett før den siste visningen forsvinner, når lukkingen er sikker — et eventuelt spørsmål om lagring er besvart og ikke avbrutt. Inne i behandleren er dokumentet fortsatt helt: text(), filePath(), caret(), bookmarkedLines() og tegnkodingen svarer alle. Deretter følger nedrivingen, så DocumentClosed. Alle måter å lukke en fane på publiserer den (Lukk, Lukk alle, Lukk de andre / Lukk dem til høyre, et midtklikk, Lukk mappen, et programtilleggs closeDocument()), også for dokumenter uten navn; å lukke én rute for et dokument som fortsatt vises i en annen, gjør det ikke.

Avslutning publiserer den ikke. Programmet publiserer AppAboutToQuit én gang, mens alle dokumentene ennå er åpne, og ingen lukkehendelser per dokument: et programtillegg som tar vare på tilstand per dokument mellom økter, går gjennom openDocuments() i AppAboutToQuit-behandleren sin. DocumentAboutToClose betyr derfor alltid «dette dokumentet lukkes», aldri «programmet avsluttes».

Behandlere kjører synkront, midt i lukkingen: vær rask, vis ingen dialogvinduer, og behandle mengden dokumenter som skrivebeskyttet — ikke åpne, lukk eller aktiver dokumenter, og ikke rediger teksten i dokumentet som lukkes.

Den er med vilje bare for innebygde programtillegg: leveringen til Python-programtillegg er asynkron, så løftet «kan fortsatt leses» kunne ikke holdes der, og hendelsen tilbys dem ikke (se Python-hendelser).

CommandShortcutChanged

CommandShortcutChanged utløses når en kommandos faktiske hurtigtast endrer seg — en omtildeling i hurtigtasttildelingen, en importert eller tilbakestilt tastaturoppsett, eller at en konfliktundertrykkelse trer inn eller faller bort. Menybundne kommandoer trenger ingenting (verten gir handlingen deres en ny binding); kommandoer som er registrert med scope = command_scope::kPluginWindow, abonnerer og tar sekvensen i bruk på nytt på sine egne kontroller (se Kommandoer og menyer).

Å abonnere

subscribe er en mal som gir et Subscription tilbake (RAII). Hold abonnementet i live som et medlem så lenge du vil at tilbakekallet skal utløses; ødelegger man det, avmeldes 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 av programtillegget, så alle tilbakekall rives ned av seg selv i shutdown().