Indstillinger og indstillingssider

Tre beslægtede tjenester dækker opsætningen: ISettings (vedvarende nøgle/værdi-lager), IDocumentSettings (opslag i lag med .editorconfig) og ISettingsRegistry (en side i indstillingsvinduet).

ISettings — vedvarende nøgle/værdi-opsætning

ctx.settings() giver et lager tilbage, der er afgrænset til dit udvidelsesmodul: værten forankrer det under plugins/<plugin.id>/, så korte lokale nøglenavne aldrig støder sammen med editorens eller andre moduler. Nøgler bruger / som stiskilletegn ("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);

Standardimplementeringen bygger på QSettings (INI), men det er en implementeringsdetalje — grænsefladen er fri for Qt, og et Python-udvidelsesmodul bruger det samme lager gennem ctx.settings.

Indstillinger for hele programmet (skrivebeskyttede)

ctx.appSettings() er en const-visning af editorens egen opsætning. Brug nøglekonstanterne fra PluginApi/AppSettingsKeys.h i stedet for at hardkode tekststrenge. Vil du reagere på ændringer, så abonnér på events::SettingsChanged (et tomt scope betyder »noget som helst ændrede sig«).

Indstillinger afgrænset til dokumentet (.editorconfig)

ctx.documentSettings() læser værdier pr. dokument, der lægger et projekts .editorconfig oven på dine gemte indstillinger: for en nøgle k finder den mte.<plugin.id>.<k> i de .editorconfig-afsnit, der gælder for dokumentets sti, falder tilbage på ctx.settings() og derefter på din standardværdi. Skrivninger går altid gennem ctx.settings() — aldrig tilbage i .editorconfig.

En side i indstillingsvinduet

Sidens grænseflade kender til Qt, så den ligger i den valgfri headerfil PluginApi/Qt/ISettingsPage.h. Selve registret (ISettingsRegistry, SettingsPageToken) er fri for Qt og ligger i PluginApi/ISettingsRegistry.h — Qt-headerfilen inkluderer den, så et udvidelsesmodul, der implementerer en side, stadig kun behøver den ene inkludering:

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

Registrér den i initialize(), og behold symbolet:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));

• category() grupperer siderne i vinduets træ; mellemliggende led opretter eller genbruger grupper. Modulsider ligger efter sædvane under "Plugins/<Name>".
• apply() er der, du gemmer; reset() er der, du indlæser igen efter en annullering. Skriv ikke indstillinger fra kontrollernes signaler — vinduets kontrakt er, at ændringerne først anvendes til sidst.
• Efter sædvane giver scope() "plugins/<plugin.id>" tilbage, så anden kode kan reagere selektivt på ændringer fra din side via events::SettingsChanged.
• Det SettingsPageToken, du får tilbage, tilbagekalder siden (og frigiver den), når det ødelægges — kald reset() på det i shutdown() som på hvert andet symbol.

Oversæt hver tekststreng på siden, og lever alle femten kataloger — se Oversættelser.

Python-udvidelsesmoduler

Et Python-udvidelsesmodul erklærer den tilsvarende side deklarativt — en JSON-formular bygget med mte.ui, der gives til ctx.settings_page.register(...); værdier, der er bundet med binds="settings:<key>", gemmes i det samme lager pr. udvidelsesmodul. Se Python-dokumentationen for ctx.