Asetukset ja asetussivut

Kolme toisiinsa liittyvää palvelua kattaa kokoonpanon: ISettings (pysyvä avain–arvo-tallennus), IDocumentSettings (.editorconfig-kerroksiset luvut) ja ISettingsRegistry (käyttöliittymäsivu asetusikkunassa).

ISettings — pysyvä avain–arvo-kokoonpano

ctx.settings() palauttaa varaston, joka on rajattu liitännäiseesi: isäntä juurruttaa sen polkuun plugins/<plugin.id>/, joten lyhyet paikalliset avainnimet eivät koskaan törmää editorin tai muiden liitännäisten avaimiin. Avaimet käyttävät merkkiä / polkuerottimena ("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);

Oletustoteutus nojaa QSettingsiin (INI), mutta se on toteutusyksityiskohta — rajapinta on Qt-vapaa, ja Python-liitännäinen käyttää samaa varastoa kohteen ctx.settings kautta.

Sovelluksenlaajuiset asetukset (vain luettava)

ctx.appSettings() on const-näkymä editorin omaan kokoonpanoon. Käytä avainvakioita tiedostosta PluginApi/AppSettingsKeys.h merkkijonojen kovakoodaamisen sijaan. Reagoidaksesi muutoksiin tilaa tapahtuma events::SettingsChanged (tyhjä scope tarkoittaa »jokin muuttui«).

Asiakirjaan rajatut asetukset (.editorconfig)

ctx.documentSettings() lukee asiakirjakohtaisia arvoja, jotka kerrostavat projektin .editorconfig-tiedoston tallennettujen asetustesi päälle: avaimelle k se ratkaisee avaimen mte.<plugin.id>.<k> niistä .editorconfig-osioista, jotka koskevat asiakirjan polkua, turvautuu sitten kohteeseen ctx.settings() ja sitten oletusarvoosi. Kirjoitukset kulkevat aina kohteen ctx.settings() kautta — ei koskaan takaisin .editorconfig-tiedostoon.

Sivu asetusikkunassa

Sivun rajapinta tuntee Qt:n, joten se sijaitsee valinnaisessa otsikkotiedostossa PluginApi/Qt/ISettingsPage.h. Itse rekisteri (ISettingsRegistry, SettingsPageToken) on Qt-vapaa ja sijaitsee tiedostossa PluginApi/ISettingsRegistry.h — Qt-otsikkotiedosto sisällyttää sen, joten sivun toteuttava liitännäinen tarvitsee silti vain sen yhden sisällytyksen:

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

Rekisteröi se funktiossa initialize() ja säilytä poletti:

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

• category() ryhmittelee sivut ikkunan puussa; välitasot luovat tai käyttävät uudelleen ryhmiä. Liitännäissivut sijaitsevat tapaan "Plugins/<Name>".
• apply() on se, missä tallennat; reset() on se, missä lataat uudelleen peruutuksen jälkeen. Älä kirjoita asetuksia ohjausobjektien signaaleista — ikkunan sopimus on viivästetty käyttöönotto.
• Tavan mukaan scope() palauttaa arvon "plugins/<plugin.id>", jotta muu koodi voi reagoida valikoivasti sivusi muutoksiin tapahtuman events::SettingsChanged kautta.
• Palautettu SettingsPageToken peruu sivun (ja vapauttaa sen) tuhoutuessaan — kutsu reset() sille funktiossa shutdown() kuten jokaiselle muullekin poletille.

Käännä jokainen sivun merkkijono ja toimita kaikki viisitoista luetteloa — katso Käännökset.

Python-liitännäiset

Python-liitännäinen ilmoittaa vastaavan sivun kuvailevasti — JSON-lomakkeena, joka on rakennettu välineellä mte.ui ja välitetty funktiolle ctx.settings_page.register(...); arvot, jotka on sidottu merkinnällä binds="settings:<key>", tallentuvat samaan liitännäiskohtaiseen varastoon. Katso Pythonin ctx-dokumentaatio.