Impostazioni e pagine delle impostazioni

Tre servizi correlati coprono la configurazione: ISettings (archivio chiave/valore persistente), IDocumentSettings (letture stratificate con .editorconfig) e ISettingsRegistry (una pagina dell'interfaccia nella finestra delle Preferenze).

ISettings — configurazione chiave/valore persistente

ctx.settings() restituisce un archivio circoscritto al tuo plugin: l'host lo radica sotto plugins/<plugin.id>/, così i nomi di chiave locali brevi non collidono mai con l'editor o con altri plugin. Le chiavi usano / come separatore di percorso ("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);

L'implementazione predefinita si appoggia a QSettings (INI), ma è un dettaglio implementativo: l'interfaccia è priva di Qt e un plugin Python usa lo stesso archivio tramite ctx.settings.

Impostazioni globali dell'applicazione (sola lettura)

ctx.appSettings() è una vista const della configurazione dell'editor stesso. Usa le costanti di chiave da PluginApi/AppSettingsKeys.h invece di scrivere le stringhe nel codice. Per reagire ai cambiamenti, sottoscrivi events::SettingsChanged (uno scope vuoto significa «è cambiato qualcosa»).

Impostazioni con ambito di documento (.editorconfig)

ctx.documentSettings() legge valori per documento che stratificano l'.editorconfig di un progetto sopra le tue impostazioni memorizzate: per una chiave k risolve mte.<plugin.id>.<k> dalle sezioni di .editorconfig che si applicano al percorso del documento, ripiega su ctx.settings() e poi sul tuo valore predefinito. Le scritture passano sempre da ctx.settings() — mai di ritorno in .editorconfig.

Una pagina nella finestra delle Preferenze

L'interfaccia della pagina conosce Qt, quindi vive nell'intestazione opzionale PluginApi/Qt/ISettingsPage.h. Il registro in sé (ISettingsRegistry, SettingsPageToken) è privo di Qt e vive in PluginApi/ISettingsRegistry.h — l'intestazione Qt lo include, quindi a un plugin che implementa una pagina serve comunque una sola inclusione:

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

Registrala in initialize() e conserva il token:

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

• category() raggruppa le pagine nell'albero della finestra; i segmenti intermedi creano o riusano dei gruppi. Per convenzione le pagine dei plugin vivono sotto "Plugins/<Name>".
• apply() è il punto in cui rendi persistente; reset() è quello in cui ricarichi dopo un annullamento. Non scrivere le impostazioni dai segnali dei widget: il contratto della finestra prevede un'applicazione differita.
• Per convenzione scope() restituisce "plugins/<plugin.id>", così che altro codice possa reagire in modo selettivo ai cambiamenti della tua pagina tramite events::SettingsChanged.
• Il SettingsPageToken restituito revoca la pagina (e la libera) quando viene distrutto: esegui il suo reset() in shutdown() come per ogni altro token.

Localizza ogni stringa della pagina e distribuisci tutti e quindici i cataloghi — vedi Traduzioni.

Plugin Python

Un plugin Python dichiara la pagina equivalente in modo dichiarativo: un modulo JSON costruito con mte.ui e passato a ctx.settings_page.register(...); i valori legati con binds="settings:<key>" vengono resi persistenti nello stesso archivio per plugin. Vedi la documentazione di ctx per Python.