Innstillinger og innstillingssider

Tre beslektede tjenester dekker oppsettet: ISettings (varig nøkkel/verdi-lager), IDocumentSettings (oppslag i lag med .editorconfig) og ISettingsRegistry (en side i innstillingsvinduet).

ISettings — varig nøkkel/verdi-oppsett

ctx.settings() gir et lager tilbake som er avgrenset til programtillegget ditt: verten forankrer det under plugins/<plugin.id>/, så korte lokale nøkkelnavn aldri kolliderer med redigererens eller andre programtilleggs. Nøkler bruker / 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);

Standardimplementasjonen bygger på QSettings (INI), men det er en implementasjonsdetalj — grensesnittet er fritt for Qt, og et Python-programtillegg bruker det samme lageret gjennom ctx.settings.

Innstillinger for hele programmet (skrivebeskyttet)

ctx.appSettings() er en const-visning av redigererens eget oppsett. Bruk nøkkelkonstantene fra PluginApi/AppSettingsKeys.h i stedet for å hardkode tekststrenger. Vil du reagere på endringer, så abonner på events::SettingsChanged (et tomt scope betyr «noe som helst endret seg»).

Innstillinger avgrenset til dokumentet (.editorconfig)

ctx.documentSettings() leser verdier per dokument som legger et prosjekts .editorconfig oppå de lagrede innstillingene dine: for en nøkkel k finner den mte.<plugin.id>.<k> i de .editorconfig-avsnittene som gjelder for dokumentets sti, faller tilbake på ctx.settings() og deretter på standardverdien din. Skrivninger går alltid gjennom ctx.settings() — aldri tilbake i .editorconfig.

En side i innstillingsvinduet

Sidens grensesnitt kjenner til Qt, så det ligger i den valgfrie hodefilen PluginApi/Qt/ISettingsPage.h. Selve registeret (ISettingsRegistry, SettingsPageToken) er fritt for Qt og ligger i PluginApi/ISettingsRegistry.h — Qt-hodefilen inkluderer det, så et programtillegg som implementerer en side, trenger fortsatt bare den ene inkluderingen:

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

Registrer den i initialize(), og behold symbolet:

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

• category() grupperer sidene i vinduets tre; mellomliggende ledd lager eller gjenbruker grupper. Programtilleggssider ligger etter sedvane under "Plugins/<Name>".
• apply() er der du lagrer; reset() er der du laster inn på nytt etter en avbrytelse. Skriv ikke innstillinger fra kontrollenes signaler — vinduets kontrakt er at endringene først tas i bruk til slutt.
• Etter sedvane gir scope() "plugins/<plugin.id>" tilbake, så annen kode kan reagere selektivt på endringer fra siden din gjennom events::SettingsChanged.
• Det SettingsPageToken du får tilbake, tilbakekaller siden (og frigir den) når det ødelegges — kall reset() på det i shutdown() som på hvert annet symbol.

Oversett hver tekststreng på siden, og lever alle femten katalogene — se Oversettelser.

Python-programtillegg

Et Python-programtillegg erklærer den tilsvarende siden deklarativt — et JSON-skjema bygget med mte.ui som gis til ctx.settings_page.register(...); verdier som er bundet med binds="settings:<key>", lagres i det samme lageret per programtillegg. Se Python-dokumentasjonen for ctx.