Ustawienia i strony ustawień

Konfigurację obsługują trzy powiązane usługi: ISettings (trwały magazyn klucz/wartość), IDocumentSettings (odczyty warstwowane przez .editorconfig) oraz ISettingsRegistry (strona UI w oknie Preferencji).

ISettings — zapisywana konfiguracja klucz/wartość

ctx.settings() zwraca magazyn ograniczony do Twojej wtyczki: host zakotwicza go pod plugins/<plugin.id>/, więc krótkie lokalne nazwy kluczy nigdy nie kolidują z edytorem ani innymi wtyczkami. Klucze używają / jako separatora ścieżki ("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);

Domyślna implementacja oparta jest na QSettings (INI), ale to szczegół implementacyjny — interfejs jest wolny od Qt, a wtyczka w Pythonie korzysta z tego samego magazynu przez ctx.settings.

Ustawienia globalne aplikacji (tylko do odczytu)

ctx.appSettings() to widok const własnej konfiguracji edytora. Używaj stałych kluczy z PluginApi/AppSettingsKeys.h, zamiast hardkodować stringi. Aby reagować na zmiany, zasubskrybuj events::SettingsChanged (puste scope znaczy „zmieniło się cokolwiek").

Ustawienia w zakresie dokumentu (.editorconfig)

ctx.documentSettings() czyta wartości per dokument, w których projektowy .editorconfig nakłada się warstwą na Twoje zapisane ustawienia: dla klucza k rozwiązuje mte.<plugin.id>.<k> z sekcji .editorconfig obejmujących ścieżkę dokumentu, potem cofa się do ctx.settings(), a na końcu do Twojej wartości domyślnej. Zapisy zawsze idą przez ctx.settings() — nigdy z powrotem do .editorconfig.

Strona w oknie Preferencji

Interfejs strony jest świadomy Qt, więc żyje w opcjonalnym nagłówku 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)
};

Zarejestruj ją w initialize() i zatrzymaj token:

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

• category() grupuje strony w drzewie okna; pośrednie segmenty tworzą lub wykorzystują istniejące grupy. Strony wtyczek zwyczajowo żyją pod "Plugins/<Name>".
• apply() to miejsce utrwalania; reset() to miejsce ponownego wczytania po anulowaniu. Nie zapisuj ustawień z sygnałów widżetów — kontrakt okna to odroczone zastosowanie zmian.
• Zwyczajowo scope() zwraca "plugins/<plugin.id>", aby inny kod mógł selektywnie reagować na zmiany z Twojej strony przez events::SettingsChanged.
• Zwrócony SettingsPageToken cofa rejestrację strony (i zwalnia ją) przy destrukcji — wykonaj na nim reset() w shutdown(), jak na każdym innym tokenie.

Zlokalizuj każdy string na stronie i dostarcz wszystkie cztery katalogi — zobacz Tłumaczenia.

Wtyczki w Pythonie

Wtyczka w Pythonie deklaruje odpowiednik takiej strony deklaratywnie — formularz JSON zbudowany przy pomocy mte.ui przekazany do ctx.settings_page.register(...); wartości powiązane przez binds="settings:<key>" trafiają do tego samego magazynu per wtyczka. Zobacz dokumentację ctx w Pythonie.