Instellingen en instellingenpagina's

Drie verwante diensten dekken de configuratie: ISettings (blijvende sleutel/waarde-opslag), IDocumentSettings (met .editorconfig gelaagde lezingen) en ISettingsRegistry (een interfacepagina in het venster Voorkeuren).

ISettings — blijvende sleutel/waarde-configuratie

ctx.settings() levert een opslag op die tot uw plug-in beperkt is: de host wortelt haar onder plugins/<plugin.id>/, zodat korte lokale sleutelnamen nooit botsen met de editor of met andere plug-ins. Sleutels gebruiken / als padscheiding ("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);

De standaardimplementatie steunt op QSettings (INI), maar dat is een implementatiedetail — de interface is vrij van Qt en een Python-plug-in gebruikt dezelfde opslag via ctx.settings.

Instellingen van de hele toepassing (alleen-lezen)

ctx.appSettings() is een const kijk op de eigen configuratie van de editor. Gebruik de sleutelconstanten uit PluginApi/AppSettingsKeys.h in plaats van tekenreeksen hard in de code te schrijven. Om op wijzigingen te reageren schrijft u zich in op events::SettingsChanged (een lege scope betekent «er is iets veranderd»).

Instellingen met documentbereik (.editorconfig)

ctx.documentSettings() leest waarden per document die de .editorconfig van een project over uw bewaarde instellingen leggen: voor een sleutel k lost hij mte.<plugin.id>.<k> op uit de .editorconfig-secties die op het pad van het document van toepassing zijn, valt terug op ctx.settings(), en dan op uw standaardwaarde. Schrijfacties gaan altijd via ctx.settings() — nooit terug de .editorconfig in.

Een pagina in het venster Voorkeuren

De pagina-interface kent Qt, dus zij woont in de optionele header PluginApi/Qt/ISettingsPage.h. Het register zelf (ISettingsRegistry, SettingsPageToken) is vrij van Qt en woont in PluginApi/ISettingsRegistry.h — de Qt-header voegt hem in, dus een plug-in die een pagina implementeert heeft alsnog maar één invoeging nodig:

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

Registreer haar in initialize() en houd het token vast:

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

• category() groepeert pagina's in de boom van het venster; tussenliggende segmenten maken groepen aan of hergebruiken ze. Plug-inpagina's wonen volgens afspraak onder "Plugins/<Name>".
• apply() is waar u wegschrijft; reset() is waar u na een annulering opnieuw laadt. Schrijf geen instellingen vanuit signalen van widgets — het contract van het venster is uitgesteld toepassen.
• Volgens afspraak levert scope() "plugins/<plugin.id>" op, zodat andere code selectief op de wijzigingen van uw pagina kan reageren via events::SettingsChanged.
• Het teruggegeven SettingsPageToken trekt de pagina in (en geeft haar vrij) wanneer het vernietigd wordt — voer er reset() op uit in shutdown(), net als bij elk ander token.

Lokaliseer elke tekenreeks op de pagina en lever alle vijftien catalogi mee — zie Vertalingen.

Python-plug-ins

Een Python-plug-in verklaart de gelijkwaardige pagina declaratief: een JSON-formulier gebouwd met mte.ui en doorgegeven aan ctx.settings_page.register(...); waarden die met binds="settings:<key>" gekoppeld zijn worden naar dezelfde opslag per plug-in weggeschreven. Zie de Python-naslag voor ctx.