Saltar a contenido

Ajustes y páginas de ajustes

Tres servicios relacionados cubren la configuración: ISettings (almacenamiento persistente clave/valor), IDocumentSettings (lecturas en capas con .editorconfig) e ISettingsRegistry (una página de interfaz en el diálogo de Preferencias).

ISettings — configuración persistente clave/valor

ctx.settings() devuelve un almacén acotado a tu plugin: el anfitrión lo enraíza bajo plugins/<plugin.id>/, de modo que los nombres de clave locales y cortos nunca chocan con el editor ni con otros plugins. Las claves usan / como separador de ruta ("ui/fontSize").

class ISettings {
public:
    bool contains(std::string_view key) const;
    void remove(std::string_view key);

    // Typed accessors -- defaultValue is returned when the key is missing
    // or the stored value cannot convert to the requested type.
    bool         getBool  (std::string_view key, bool defaultValue = false) const;
    std::int64_t getInt   (std::string_view key, std::int64_t defaultValue = 0) const;
    double       getDouble(std::string_view key, double defaultValue = 0.0) const;
    std::string  getString(std::string_view key, std::string_view defaultValue = {}) const;
    std::vector<std::uint8_t> getBytes(std::string_view key) const;

    void setBool / setInt / setDouble / setString / setBytes(...);

    void sync();   // flush now; the host also syncs on shutdown
};

ctx.settings().setBool("wrap", true);
bool wrap = ctx.settings().getBool("wrap", false);

La implementación predeterminada se apoya en QSettings (INI), pero eso es un detalle de implementación: la interfaz está libre de Qt y un plugin de Python usa el mismo almacén a través de ctx.settings.

Ajustes de toda la aplicación (solo lectura)

ctx.appSettings() es una vista constante de la configuración propia del editor. Usa las constantes de clave de PluginApi/AppSettingsKeys.h en lugar de codificar cadenas a mano. Para reaccionar a los cambios, suscríbete a events::SettingsChanged (un scope vacío significa «ha cambiado algo»).

Ajustes con ámbito de documento (.editorconfig)

ctx.documentSettings() lee valores por documento que superponen el .editorconfig de un proyecto a tus ajustes guardados: para una clave k resuelve mte.<plugin.id>.<k> a partir de las secciones del .editorconfig que se aplican a la ruta del documento, recurre después a ctx.settings() y luego a tu valor predeterminado. Las escrituras van siempre a través de ctx.settings(), nunca de vuelta al .editorconfig.

Una página en el diálogo de Preferencias

La interfaz de la página conoce Qt, así que vive en la cabecera opcional PluginApi/Qt/ISettingsPage.h. El registro en sí (ISettingsRegistry, SettingsPageToken) está libre de Qt y vive en PluginApi/ISettingsRegistry.h; la cabecera de Qt lo incluye, así que un plugin que implemente una página sigue necesitando una única inclusión:

class ISettingsPage {
public:
    std::string category() const;              // tree path, e.g. "Plugins/Hello World"
    std::string title() const;                 // page heading
    QWidget*    createWidget(QWidget* parent); // built lazily, at most once per dialog
    void        apply();                       // OK/Apply -> write widget state to ISettings
    void        reset();                       // Cancel/re-show -> reload from ISettings (optional)
    std::string scope() const;                 // published via events::SettingsChanged (optional)
};

Regístrala en initialize() y conserva el testigo:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));
  • category() agrupa las páginas en el árbol del diálogo; los segmentos intermedios crean o reutilizan grupos. Las páginas de plugin viven por convención bajo "Plugins/<Name>".
  • apply() es donde persistes; reset() es donde recargas tras una cancelación. No escribas los ajustes desde señales de los widgets: el contrato del diálogo es de aplicación diferida.
  • Por convención, scope() devuelve "plugins/<plugin.id>" para que otro código pueda reaccionar de forma selectiva a los cambios de tu página mediante events::SettingsChanged.
  • El SettingsPageToken devuelto revoca la página (y la libera) al destruirse; hazle reset() en shutdown(), como con cualquier otro testigo.

Traduce todas las cadenas de la página y entrega los quince catálogos; consulta Traducciones.

Plugins de Python

Un plugin de Python declara la página equivalente de forma declarativa: un formulario JSON construido con mte.ui que se pasa a ctx.settings_page.register(...); los valores enlazados con binds="settings:<key>" se guardan en el mismo almacén por plugin. Consulta la referencia de ctx en Python.