Settings

A plugin has two distinct kinds of configuration, and it is important not to confuse them:

1. Per-plugin settings — your own values, stored under your own INI section (derived from ModuleName()). You declare these as a table, or read/write them through IModuleSettings.
2. Host settings — values owned by the host, addressed by a "section.name" key (e.g. "playback.hwdec"). You read these through the ISettingsStore service, and only the settings menu commits them.

Per-plugin settings

To persist your own members, override LoadSettings/SaveSettings. They are handed an IModuleSettings bound to your section, with typed get/set methods that take a default:

void LoadSettings(IModuleSettings& ps) override
{
    showPanel_  = ps.GetBool ("showPanel", true);
    maxItems_   = ps.GetInt  ("maxItems", 50);
    panelWidth_ = ps.GetFloat("panelWidth", 320.f);
    title_      = ps.GetString("title", "My Panel");
}

void SaveSettings(IModuleSettings& ps) override
{
    ps.SetBool  ("showPanel", showPanel_);
    ps.SetInt   ("maxItems", maxItems_);
    ps.SetFloat ("panelWidth", panelWidth_);
    ps.SetString("title", title_.c_str());
}

Setters write to memory only — the host persists everything to disk on Save.

note

IModuleSettings::GetString returns a const char* into the host's storage that is valid only until the next SetString on that key. Copy it into a std::string if you need to keep it, as above.

A settings page

A settings page is its own Qt Quick (QML) page plus a QObject view-model, registered with the ISettingsPageRegistry service from OnInstall. The registry stores the view-model non-owning and never unregisters, so the model must outlive the app session — own it as a member created in OnInstall:

void OnInstall(IModuleContext& ctx) override
{
    if (auto* pages = ctx.GetService<ISettingsPageRegistry>())
    {
        settingsPage_ = std::make_unique<MyPluginSettings>(*this);
        pages->RegisterSettingsPage(
            "myplugin", "My Plugin",
            "qrc:/qt/qml/FrameLift/Plugins/MyPlugin/MyPluginSettings.qml",
            settingsPage_.get(), 330);
    }
}

RegisterSettingsPage(id, title, qmlUrl, viewModel, order) adds your page to the settings menu; order controls where it sorts. The QML page binds to the view-model's Q_PROPERTY/Q_INVOKABLE surface exactly like a rendered panel. When the user presses Save, the host calls your SaveSettings (and SaveKeybinds), then persists. Pass nullptr as the view-model for a page whose UI is pure QML.

Reading host settings

Host settings live on the ISettingsStore service. Discover it and use the typed getters with a "section.name" key (always null-check the service):

if (auto* store = ctx.GetService<ISettingsStore>())
{
    bool  hwdec = store->GetSettingBool("playback.hwdec");
    float width = store->GetSettingFloat("ui.panelWidth");
}

For strings, the raw getter uses a caller-provided buffer; the <framelift/ContextHelpers.h> helper wraps it into a std::string:

#include <framelift/ContextHelpers.h>

std::string path = framelift::GetSettingString(ctx, "playback.lastFile");

Reacting to settings changes

To run code whenever any host setting is committed, register a change callback — again via the lambda helper:

#include <framelift/ContextHelpers.h>

framelift::RegisterSettingsChangeCallback(ctx, [this] {
    // re-read whatever you depend on
});

The closure is freed automatically when your plugin unloads.

caution

ISettingsStore::CommitSetting* and SaveSettings() mutate host settings and are intended for the settings-menu plugin. Ordinary plugins persist their own state through their per-plugin section (LoadSettings/SaveSettings over IModuleSettings) instead.