Eventos

Os plugins reagem à atividade do editor pelo IEventBus. Os eventos são structs simples definidos em PluginEvents.h:

Evento	Carga útil
DocumentOpened	DocumentId, std::filesystem::path
DocumentAboutToClose	DocumentId — o usuário está fechando o documento e o fechamento é certo; publicado logo antes de sua última visão desaparecer, enquanto ele ainda pode ser lido por inteiro. Não ao sair do programa. Só plugins nativos; veja abaixo
DocumentClosed	DocumentId
DocumentSaved	DocumentId
DocumentPrinted	DocumentId, pages — publicado depois de um trabalho de impressão chegar ao dispositivo (Arquivo ▸ Imprimir, ou Imprimir dentro da visualização); pages conta as páginas do documento impressas, menos do que o documento tem quando uma seleção ou intervalo de páginas foi escolhido. Uma caixa de diálogo cancelada não publica nada. Por enquanto, apenas plugins C++
DocumentAboutToSave	DocumentId, path — síncrono, com o buffer ainda editável (aparar espaços em branco, acrescentar nova linha final); sem caixas de diálogo
DocumentEncodingChanged	DocumentId, DocumentEncoding — a codificação com que o host gravará o documento de volta mudou (arquivo recém-identificado, ou setDocumentEncoding chamado)
DocumentLineEndingChanged	DocumentId, LineEnding — o terminador de linha que o documento usa mudou (arquivo recém-lido ou recarregado, um end_of_line do .editorconfig aplicado ao salvar, ou setLineEnding chamado)
DocumentModifiedChanged	DocumentId, modified — o sinalizador de limpo/sujo mudou (não a cada tecla)
TextChanged	DocumentId, pos, addedBytes, removedBytes
SelectionChanged	DocumentId
ActiveDocumentChanged	DocumentId
HostWindowShown	(nenhuma) — uma vez por execução, depois que o primeiro quadro está na tela; agende aqui o trabalho lento de inicialização
SettingsChanged	scope — "" = de todo o editor, "plugins/<id>" = a página daquele plugin foi aplicada
WorkspaceRootChanged	root (vazio = pasta fechada) — publicado pelo plugin Espaço de trabalho
WorkspaceFilesChanged	files[] de {path, displayPath} — publicado pelo plugin Espaço de trabalho
ThemeChanged	variant ("light" / "dark" / "")
AppAboutToQuit	(nenhuma)
CommandShortcutChanged	commandId, sequence (a nova combinação portátil; "" = sem associação)
MarginClicked	DocumentId, line, margin (EditorMargin::Symbol), modifiers — um clique esquerdo na coluna de marcadores de um editor, a cada clique desse tipo; veja Marcas de linha

Os plugins também podem publicar eventos (ctx.events().publish(e)) — é assim que o plugin Espaço de trabalho transmite WorkspaceRootChanged / WorkspaceFilesChanged para o Localizar em arquivos e a paleta de comandos consumirem.

Um documento, um id

Um DocumentId nomeia um documento, não um painel. Dividir documento exibe um arquivo em dois painéis, e os dois carregam o mesmo DocumentId, então:

• DocumentOpened é publicado uma vez por arquivo — dividir não publica nada;
• DocumentClosed é publicado apenas quando a última visualização do documento fecha, então fechar um painel nunca desmonta estado de que o outro ainda precisa;
• activeDocument() responde com aquele único id, seja qual for o painel na frente, e openDocuments() lista o documento uma vez.

Deliberadamente não há evento por painel e nem forma de perguntar qual painel está ativo: painéis são assunto do host, e tudo o que um plugin pode observar — texto, cursor, seleção, codificação, fim de linha, estado de modificado — pertence ao documento, que os painéis compartilham.

DocumentAboutToClose

Publicado uma vez por documento, imediatamente antes de sua última visão desaparecer, quando o fechamento é certo — qualquer pergunta sobre salvar foi respondida e não cancelada. Dentro do manipulador o documento ainda está inteiro: text(), filePath(), caret(), bookmarkedLines() e a codificação respondem. Em seguida vem a desmontagem e depois DocumentClosed. Toda forma de fechar uma aba o publica (Fechar, Fechar tudo, Fechar os outros / Fechar os à direita, um clique do meio, Fechar a pasta, o closeDocument() de um plugin), inclusive documentos sem título; fechar um painel de um documento ainda exibido em outro não o publica.

Sair do programa não o publica. O aplicativo publica AppAboutToQuit uma vez, enquanto todos os documentos ainda estão abertos, e nenhum evento de fechamento por documento: um plugin que guarda estado por documento entre sessões percorre openDocuments() no seu manipulador de AppAboutToQuit. Portanto, DocumentAboutToClose sempre significa "este documento está sendo fechado", nunca "o programa está terminando".

Os manipuladores rodam de forma síncrona, dentro do fechamento: seja rápido, não mostre caixas de diálogo e trate o conjunto de documentos como somente leitura — não abra, feche nem ative documentos, e não edite o texto do documento que está sendo fechado.

Ele é só nativo, por projeto: a entrega a plugins Python é assíncrona, então a promessa de "ainda pode ser lido" não poderia ser cumprida lá, e o evento não é oferecido a eles (veja Eventos em Python).

CommandShortcutChanged

CommandShortcutChanged dispara quando o atalho efetivo de um comando muda — um remapeamento do usuário no Mapeamento de atalhos, uma importação/redefinição de mapa de teclado, ou uma supressão por conflito entrando/saindo. Comandos ligados a menus não precisam de nada (o host remapeia a ação deles); comandos registrados com scope = command_scope::kPluginWindow assinam e reaplicam a sequência aos próprios widgets (veja Comandos e menus).

Assinando

subscribe é um template que devolve uma Subscription (RAII). Mantenha a assinatura viva como membro enquanto quiser que a retrochamada dispare; destruí-la cancela a assinatura.

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

Guarde toda Subscription como membro do plugin, para que todas as retrochamadas sejam desmontadas automaticamente no shutdown().