Přeskočit obsah

Nastavení a stránky nastavení

Konfiguraci pokrývají tři související služby: ISettings (trvalé úložiště klíč/hodnota), IDocumentSettings (čtení s vrstvami z .editorconfig) a ISettingsRegistry (stránka rozhraní v okně Předvolby).

ISettings — trvalá konfigurace klíč/hodnota

ctx.settings() vrací úložiště omezené na váš zásuvný modul: hostitel jej ukotví pod plugins/<plugin.id>/, takže se krátké místní názvy klíčů nikdy nesrazí s editorem ani s jinými moduly. Klíče používají jako oddělovač cesty / ("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);

Výchozí implementace stojí na QSettings (INI), ale to je implementační detail — rozhraní je bez Qt a modul v Pythonu používá totéž úložiště přes ctx.settings.

Nastavení celé aplikace (jen ke čtení)

ctx.appSettings() je konstantní pohled na vlastní konfiguraci editoru. Používejte konstanty klíčů z PluginApi/AppSettingsKeys.h, místo abyste zadrátovávali řetězce. Chcete-li na změny reagovat, odebírejte events::SettingsChanged (prázdný scope znamená »něco se změnilo«).

Nastavení v rozsahu dokumentu (.editorconfig)

ctx.documentSettings() čte hodnoty pro daný dokument, které kladou projektový .editorconfig nad vaše uložená nastavení: pro klíč k vyhodnotí mte.<plugin.id>.<k> ze sekcí .editorconfig platných pro cestu dokumentu, vrátí se k ctx.settings() a pak k vaší výchozí hodnotě. Zápisy jdou vždy přes ctx.settings() — nikdy zpět do .editorconfig.

Stránka v okně Předvolby

Rozhraní stránky zná Qt, takže bydlí ve volitelné hlavičce PluginApi/Qt/ISettingsPage.h. Samotný registr (ISettingsRegistry, SettingsPageToken) je bez Qt a bydlí v PluginApi/ISettingsRegistry.h — hlavička pro Qt jej vkládá, takže modul implementující stránku potřebuje stále jen jedno vložení:

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

Zaregistrujte ji v initialize() a token si podržte:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));
  • category() seskupuje stránky ve stromu okna; mezilehlé segmenty skupiny vytvoří nebo použijí znovu. Stránky modulů bydlí podle zvyklosti pod "Plugins/<Name>".
  • apply() je místo, kde ukládáte; reset() je místo, kde po zrušení znovu načítáte. Nezapisujte nastavení ze signálů widgetů — kontraktem okna je odložené uplatnění.
  • Podle zvyklosti vrací scope() hodnotu "plugins/<plugin.id>", aby ostatní kód mohl na změny vaší stránky reagovat vybíravě přes events::SettingsChanged.
  • Vrácený SettingsPageToken stránku při zániku odvolá (a uvolní) — ve shutdown() na něm zavolejte reset() jako na každém jiném tokenu.

Každý řetězec na stránce lokalizujte a dodejte všech patnáct katalogů — viz Překlady.

Zásuvné moduly v Pythonu

Modul v Pythonu deklaruje odpovídající stránku deklarativně — formulář JSON postavený pomocí mte.ui a předaný do ctx.settings_page.register(...); hodnoty svázané pomocí binds="settings:<key>" se ukládají do téhož úložiště daného modulu. Viz reference ctx v Pythonu.