Gå till innehållet

Inställningar och inställningssidor

Tre besläktade tjänster täcker konfigurationen: ISettings (bestående nyckel/värde-lagring), IDocumentSettings (läsningar skiktade med .editorconfig) och ISettingsRegistry (en gränssnittssida i dialogrutan Inställningar).

ISettings — bestående nyckel/värde-konfiguration

ctx.settings() returnerar ett lager som är begränsat till din insticksmodul: värden rotar det under plugins/<plugin.id>/, så att korta lokala nyckelnamn aldrig krockar med redigeraren eller med andra insticksmoduler. Nycklar använder / som sökvägsavskiljare ("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);

Standardimplementationen bygger på QSettings (INI), men det är ett implementationsdetalj — gränssnittet är fritt från Qt och en Python-insticksmodul använder samma lager genom ctx.settings.

Programövergripande inställningar (skrivskyddade)

ctx.appSettings() är en const-vy av redigerarens egen konfiguration. Använd nyckelkonstanterna från PluginApi/AppSettingsKeys.h i stället för att hårdkoda strängar. För att reagera på ändringar prenumererar du på events::SettingsChanged (ett tomt scope betyder «något ändrades»).

Inställningar med dokumentomfattning (.editorconfig)

ctx.documentSettings() läser värden per dokument som skiktar ett projekts .editorconfig över dina lagrade inställningar: för en nyckel k löser den mte.<plugin.id>.<k> från de .editorconfig-avsnitt som gäller för dokumentets sökväg, faller tillbaka på ctx.settings(), och sedan på ditt standardvärde. Skrivningar går alltid genom ctx.settings() — aldrig tillbaka in i .editorconfig.

En sida i dialogrutan Inställningar

Sidgränssnittet känner Qt, så det bor i den valfria headern PluginApi/Qt/ISettingsPage.h. Själva registret (ISettingsRegistry, SettingsPageToken) är fritt från Qt och bor i PluginApi/ISettingsRegistry.h — Qt-headern inkluderar det, så en insticksmodul som implementerar en sida behöver ändå bara den ena 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)
};

Registrera den i initialize() och behåll symbolen:

m_page = ctx.settingsRegistry().registerPage(
    std::make_unique<MySettingsPage>(ctx.settings()));
  • category() grupperar sidor i dialogrutans träd; mellanliggande segment skapar eller återanvänder grupper. Insticksmodulers sidor bor enligt konvention under "Plugins/<Name>".
  • apply() är där du sparar; reset() är där du läser om efter ett avbrott. Skriv inte inställningar från widgetarnas signaler — dialogrutans kontrakt är fördröjt verkställande.
  • Enligt konvention returnerar scope() "plugins/<plugin.id>" så att annan kod selektivt kan reagera på din sidas ändringar genom events::SettingsChanged.
  • Den returnerade SettingsPageToken återkallar sidan (och frigör den) när den förstörs — kör reset() på den i shutdown() som på varje annan symbol.

Lokalisera varje sträng på sidan och leverera alla femton katalogerna — se Översättningar.

Python-insticksmoduler

En Python-insticksmodul deklarerar den motsvarande sidan deklarativt: ett JSON-formulär byggt med mte.ui och skickat till ctx.settings_page.register(...); värden som bundits med binds="settings:<key>" sparas till samma lager per insticksmodul. Se Python-referensen för ctx.