Preskočiť na obsah

Nastavenia a stránky nastavení

Konfiguráciu pokrývajú tri súvisiace služby: ISettings (trvalé úložisko kľúč/hodnota), IDocumentSettings (čítanie vo vrstvách so .editorconfig) a ISettingsRegistry (stránka rozhrania v dialógu Predvoľby).

ISettings — trvalá konfigurácia kľúč/hodnota

ctx.settings() vracia úložisko s rozsahom vášho zásuvného modulu: hostiteľ ho ukotví pod plugins/<plugin.id>/, takže krátke lokálne názvy kľúčov nikdy nekolidujú s editorom ani s inými modulmi. Kľúče používajú ako oddeľovač 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);

Predvolená implementácia stojí na QSettings (INI), ale to je implementačný detail — rozhranie je bez Qt a zásuvný modul v Pythone používa to isté úložisko cez ctx.settings.

Nastavenia celej aplikácie (iba na čítanie)

ctx.appSettings() je konštantný pohľad na vlastnú konfiguráciu editora. Používajte konštanty kľúčov z PluginApi/AppSettingsKeys.h, a nie reťazce napevno v kóde. Ak chcete reagovať na zmeny, prihláste sa na events::SettingsChanged (prázdny scope znamená „zmenilo sa čokoľvek“).

Nastavenia v rozsahu dokumentu (.editorconfig)

ctx.documentSettings() číta hodnoty pre daný dokument, ktoré ukladajú .editorconfig projektu ako vrstvu nad vaše uložené nastavenia: pre kľúč k vyhodnotí mte.<plugin.id>.<k> zo sekcií súboru .editorconfig platných pre cestu dokumentu, potom sa vráti k ctx.settings() a napokon k vašej predvolenej hodnote. Zápisy idú vždy cez ctx.settings() — nikdy nie späť do .editorconfig.

Stránka v dialógu Predvoľby

Rozhranie stránky pozná Qt, preto sa nachádza vo voliteľnej hlavičke PluginApi/Qt/ISettingsPage.h. Samotný register (ISettingsRegistry, SettingsPageToken) je bez Qt a nachádza sa v PluginApi/ISettingsRegistry.h — hlavička pre Qt ho zahŕňa, takže zásuvný modul implementujúci stránku potrebuje aj tak iba jeden include:

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 ju v initialize() a token si ponechajte:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));
  • category() zoskupuje stránky v strome dialógu; medziľahlé segmenty vytvárajú alebo znova používajú skupiny. Stránky zásuvných modulov sa podľa zvyklosti nachádzajú pod "Plugins/<Name>".
  • apply() je miestom, kde ukladáte; reset() je miestom, kde po zrušení načítavate znova. Nastavenia nezapisujte zo signálov widgetov — kontraktom dialógu je odložené uplatnenie.
  • Podľa zvyklosti vracia scope() hodnotu "plugins/<plugin.id>", aby iný kód mohol na zmeny vašej stránky reagovať výberovo cez events::SettingsChanged.
  • Vrátený SettingsPageToken pri zničení stránku odvolá (a uvoľní) — v shutdown() na ňom zavolajte reset() ako na každom inom tokene.

Každý reťazec na stránke lokalizujte a dodajte všetkých pätnásť katalógov — pozri Preklady.

Zásuvné moduly v Pythone

Zásuvný modul v Pythone deklaruje rovnocennú stránku deklaratívne — ako formulár JSON zostavený pomocou mte.ui a odovzdaný do ctx.settings_page.register(...); hodnoty zviazané cez binds="settings:<key>" sa uchovávajú v tom istom úložisku daného modulu. Pozri referenciu ctx pre Python.