Einstellungen & Einstellungsseiten

Drei verwandte Dienste decken die Konfiguration ab: ISettings (persistente Schlüssel/Wert-Speicherung), IDocumentSettings (.editorconfig-geschichtete Lesezugriffe) und ISettingsRegistry (eine UI-Seite im Einstellungen-Dialog).

ISettings — persistente Schlüssel/Wert-Konfiguration

ctx.settings() liefert einen Speicher, der auf Ihr Plugin beschränkt ist: Der Host verankert ihn unter plugins/<plugin.id>/, sodass kurze lokale Schlüsselnamen niemals mit dem Editor oder anderen Plugins kollidieren. Schlüssel verwenden / als Pfadtrenner ("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);

Die Standardimplementierung ist QSettings-basiert (INI), aber das ist ein Implementierungsdetail — die Schnittstelle ist Qt-frei, und ein Python-Plugin verwendet denselben Speicher über ctx.settings.

App-weite Einstellungen (nur lesend)

ctx.appSettings() ist eine const-Sicht auf die eigene Konfiguration des Editors. Verwenden Sie die Schlüsselkonstanten aus PluginApi/AppSettingsKeys.h, statt Strings fest zu codieren. Um auf Änderungen zu reagieren, abonnieren Sie events::SettingsChanged (ein leerer scope bedeutet „irgendetwas hat sich geändert“).

Dokumentbezogene Einstellungen (.editorconfig)

ctx.documentSettings() liest Werte pro Dokument, die die .editorconfig eines Projekts über Ihre gespeicherten Einstellungen schichten: Für einen Schlüssel k löst es mte.<plugin.id>.<k> aus den .editorconfig-Abschnitten auf, die auf den Pfad des Dokuments zutreffen, fällt auf ctx.settings() zurück und dann auf Ihren Standardwert. Schreibzugriffe laufen immer über ctx.settings() — niemals zurück in die .editorconfig.

Eine Seite im Einstellungen-Dialog

Die Seiten-Schnittstelle kennt Qt und liegt daher im Opt-in-Header PluginApi/Qt/ISettingsPage.h:

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

Registrieren Sie sie in initialize() und behalten Sie das Token:

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

• category() gruppiert Seiten im Baum des Dialogs; Zwischensegmente erzeugen Gruppen oder verwenden sie wieder. Plugin-Seiten liegen per Konvention unter "Plugins/<Name>".
• In apply() persistieren Sie; in reset() laden Sie nach einem Abbrechen neu. Schreiben Sie keine Einstellungen aus Widget-Signalen — der Dialogvertrag ist verzögertes Anwenden.
• Per Konvention gibt scope() "plugins/<plugin.id>" zurück, damit anderer Code über events::SettingsChanged selektiv auf Änderungen Ihrer Seite reagieren kann.
• Das zurückgegebene SettingsPageToken widerruft die Seite (und gibt sie frei) bei seiner Zerstörung — rufen Sie in shutdown() reset() darauf auf, wie bei jedem anderen Token.

Lokalisieren Sie jeden String auf der Seite und liefern Sie alle vier Kataloge aus — siehe Übersetzungen.

Python-Plugins

Ein Python-Plugin deklariert die entsprechende Seite deklarativ — ein mit mte.ui gebautes JSON-Formular, das an ctx.settings_page.register(...) übergeben wird; mit binds="settings:<key>" gebundene Werte persistieren in denselben Pro-Plugin-Speicher. Siehe die Python-ctx-Referenz.