Eventos¶

Los plugins reaccionan a la actividad del editor a través de IEventBus. Los eventos son estructuras simples definidas en PluginEvents.h:

Evento	Carga útil
`DocumentOpened`	`DocumentId`, `std::filesystem::path`
`DocumentAboutToClose`	`DocumentId`: el usuario está cerrando el documento y el cierre es seguro; se publica justo antes de que desaparezca su última vista, mientras aún se puede leer por completo. No al salir. Solo plugins nativos; consulta más abajo
`DocumentClosed`	`DocumentId`
`DocumentSaved`	`DocumentId`
`DocumentPrinted`	`DocumentId`, `pages` — se publica después de que un trabajo de impresión llegue al dispositivo (Archivo ▸ Imprimir, o Imprimir dentro de la vista previa); `pages` cuenta las páginas del documento impresas, menos de las que tiene el documento cuando se eligió una selección o un intervalo de páginas. Un diálogo cancelado no publica nada. De momento, solo plugins de C++
`DocumentAboutToSave`	`DocumentId`, `path` — síncrono, con el búfer todavía editable (recortar espacios, añadir el salto de línea final); sin diálogos
`DocumentEncodingChanged`	`DocumentId`, `DocumentEncoding` — ha cambiado la codificación con la que el anfitrión volverá a escribir el documento (archivo recién identificado, o llamada a `setDocumentEncoding`)
`DocumentLineEndingChanged`	`DocumentId`, `LineEnding` — ha cambiado el terminador de línea que usa el documento (archivo recién leído o recargado, un `end_of_line` de `.editorconfig` aplicado al guardar, o llamada a `setLineEnding`)
`DocumentModifiedChanged`	`DocumentId`, `modified` — el indicador de limpio/sucio ha cambiado (no en cada pulsación)
`TextChanged`	`DocumentId`, `pos`, `addedBytes`, `removedBytes`
`SelectionChanged`	`DocumentId`
`ActiveDocumentChanged`	`DocumentId`
`HostWindowShown`	(ninguna) — una vez por ejecución, después de que el primer fotograma esté en pantalla; programa aquí el trabajo lento de arranque
`SettingsChanged`	`scope` — `""` = de todo el editor, `"plugins/<id>"` = se ha aplicado la página de ese plugin
`WorkspaceRootChanged`	`root` (vacío = carpeta cerrada) — lo publica el plugin Espacio de trabajo
`WorkspaceFilesChanged`	`files[]` de `{path, displayPath}` — lo publica el plugin Espacio de trabajo
`ThemeChanged`	`variant` (`"light"` / `"dark"` / `""`)
`AppAboutToQuit`	(ninguna)
`CommandShortcutChanged`	`commandId`, `sequence` (la nueva combinación portátil; `""` = sin asignar)
`MarginClicked`	`DocumentId`, `line`, `margin` (`EditorMargin::Symbol`), `modifiers`: un clic izquierdo en la columna de marcadores de un editor, en cada clic de ese tipo; consulta Marcas de línea

Los plugins también pueden publicar eventos (ctx.events().publish(e)): así es como el plugin Espacio de trabajo difunde WorkspaceRootChanged / WorkspaceFilesChanged para que los consuman Buscar en archivos y la paleta de comandos.

Un documento, un identificador¶

Un DocumentId nombra un documento, no un panel. Dividir documento muestra un archivo en dos paneles, y ambos llevan el mismo DocumentId, de modo que:

DocumentOpened se publica una vez por archivo: dividir no publica nada;
DocumentClosed se publica solo cuando se cierra la última vista del documento, así que cerrar un panel nunca desmonta el estado que el otro todavía necesita;
activeDocument() responde con ese único identificador sea cual sea el panel que esté al frente, y openDocuments() lista el documento una sola vez.

Deliberadamente no hay ningún evento por panel ni forma de preguntar qué panel está activo: los paneles son asunto del anfitrión, y todo lo que un plugin puede observar —texto, cursor, selección, codificación, final de línea, estado de modificado— pertenece al documento, que los paneles comparten.

DocumentAboutToClose¶

Se publica una vez por documento, inmediatamente antes de que desaparezca su última vista, cuando el cierre es seguro: cualquier pregunta de guardado se ha respondido y no se ha cancelado. Dentro del manejador el documento sigue entero: text(), filePath(), caret(), bookmarkedLines() y la codificación responden. Después viene el desmontaje y luego DocumentClosed. Toda forma de cerrar una pestaña lo publica (Cerrar, Cerrar todo, Cerrar los demás / Cerrar los de la derecha, un clic central, Cerrar la carpeta, el closeDocument() de un plugin), incluidos los documentos sin título; cerrar un panel de un documento que sigue visible en otro no lo publica.

Salir del programa no lo publica. La aplicación publica AppAboutToQuit una vez, mientras todos los documentos siguen abiertos, y ningún evento de cierre por documento: un plugin que guarda estado por documento entre sesiones recorre openDocuments() en su manejador de AppAboutToQuit. DocumentAboutToClose significa, por tanto, siempre «este documento se está cerrando», nunca «el programa está terminando».

Los manejadores se ejecutan de forma síncrona, dentro del cierre: sé rápido, no muestres diálogos y trata el conjunto de documentos como de solo lectura: no abras, cierres ni actives documentos, y no edites el texto del documento que se está cerrando.

Es solo nativo por diseño: la entrega a los plugins Python es asíncrona, así que allí no podría cumplirse la promesa de «aún se puede leer», y el evento no se les ofrece (consulta Eventos de Python).

CommandShortcutChanged¶

CommandShortcutChanged se dispara cuando cambia el atajo efectivo de un comando: una reasignación del usuario en la Asignación de atajos, una importación o un restablecimiento de mapa de teclado, o la entrada o salida de una supresión por conflicto. Los comandos ligados a menús no necesitan nada (el anfitrión reasigna su acción); los comandos registrados con scope = command_scope::kPluginWindow se suscriben y vuelven a aplicar la secuencia a sus propios widgets (consulta Comandos y menús).

Suscribirse¶

subscribe es una plantilla que devuelve una Subscription (RAII). Mantén viva la suscripción como miembro mientras quieras que la retrollamada se dispare; destruirla cancela la suscripción.

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

Guarda todas las Subscription como miembros del plugin para que todas las retrollamadas se desmonten automáticamente en shutdown().