Pular para conteúdo

Configurações e páginas de configurações

Três serviços relacionados cobrem a configuração: ISettings (armazenamento persistente chave/valor), IDocumentSettings (leituras em camadas com .editorconfig) e ISettingsRegistry (uma página de interface na caixa de diálogo Preferências).

ISettings — configuração persistente chave/valor

ctx.settings() devolve um armazenamento restrito ao seu plugin: o host o enraíza sob plugins/<plugin.id>/, então nomes de chave locais e curtos nunca colidem com o editor ou com outros plugins. As chaves usam / como separador de caminho ("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);

A implementação padrão se apoia no QSettings (INI), mas isso é um detalhe de implementação — a interface é livre de Qt e um plugin Python usa o mesmo armazenamento por ctx.settings.

Configurações de todo o aplicativo (somente leitura)

ctx.appSettings() é uma visão constante da configuração do próprio editor. Use as constantes de chave de PluginApi/AppSettingsKeys.h em vez de fixar cadeias no código. Para reagir a alterações, assine events::SettingsChanged (um scope vazio significa "algo mudou").

Configurações com escopo de documento (.editorconfig)

ctx.documentSettings() lê valores por documento que sobrepõem o .editorconfig de um projeto às suas configurações armazenadas: para uma chave k, ele resolve mte.<plugin.id>.<k> a partir das seções do .editorconfig que se aplicam ao caminho do documento, recorre a ctx.settings() e depois ao seu padrão. As gravações sempre passam por ctx.settings() — nunca de volta ao .editorconfig.

Uma página na caixa de diálogo Preferências

A interface da página conhece o Qt, então ela fica no cabeçalho opcional PluginApi/Qt/ISettingsPage.h. O registro em si (ISettingsRegistry, SettingsPageToken) é livre de Qt e fica em PluginApi/ISettingsRegistry.h — o cabeçalho do Qt o inclui, então um plugin que implementa uma página ainda precisa de uma única inclusão:

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)
};

Registre-a em initialize() e guarde o token:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));
  • category() agrupa as páginas na árvore da caixa de diálogo; segmentos intermediários criam ou reaproveitam grupos. Páginas de plugin vivem por convenção sob "Plugins/<Name>".
  • apply() é onde você persiste; reset() é onde você recarrega depois de um cancelamento. Não grave configurações a partir de sinais dos widgets — o contrato da caixa de diálogo é de aplicação diferida.
  • Por convenção, scope() devolve "plugins/<plugin.id>", para que outro código possa reagir seletivamente às alterações da sua página via events::SettingsChanged.
  • O SettingsPageToken devolvido revoga a página (e a libera) ao ser destruído — faça reset() nele no shutdown(), como em qualquer outro token.

Traduza todas as cadeias da página e distribua os quinze catálogos — veja Traduções.

Plugins Python

Um plugin Python declara a página equivalente de forma declarativa — um formulário JSON construído com mte.ui passado a ctx.settings_page.register(...); valores vinculados com binds="settings:<key>" persistem no mesmo armazenamento por plugin. Veja a referência de ctx em Python.