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 (named after PluginName()). You read and write these directly through IPluginSettings.
2. Host settings — values owned by the host, addressed by a "section.name" key (e.g. "playback.hwdec"). You read these through the context's typed getters, and only the settings menu commits them.

Per-plugin settings

Override LoadSettings and SaveSettings on PluginBase. They are handed an IPluginSettings bound to your section, with typed get/set methods that take a default:

class MyPlugin : public PluginBase
{
    bool  showPanel_   = true;
    int   maxItems_    = 50;
    float panelWidth_  = 320.f;
    std::string title_ = "My Panel";

protected:
    const char* PluginName() const override { return "MyPlugin"; }

    void LoadSettings(IPluginSettings& 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(IPluginSettings& ps) override
    {
        ps.SetBool  ("showPanel", showPanel_);
        ps.SetInt   ("maxItems", maxItems_);
        ps.SetFloat ("panelWidth", panelWidth_);
        ps.SetString("title", title_.c_str());
    }
};

LoadSettings runs automatically during install. SaveSettings runs when the user presses Save on your settings page (see below). Setters write to memory only — the host persists everything to disk on Save.

note

IPluginSettings::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

To appear in the settings menu, call SetupSettingsPage(ctx) from OnInstall and override RenderSettings:

void OnInstall(IPluginContext& ctx) override
{
    SetupSettingsPage(ctx);   // wires the page to RenderSettings()/SaveSettings()
}

void RenderSettings(UIContext& ui) override
{
    ui.Checkbox("Show panel", &showPanel_);
    ui.SliderInt("Max items", &maxItems_, 1, 200);
    ui.SliderFloat("Panel width", &panelWidth_, 100.f, 800.f);
    ui.InputText("Title", title_);   // std::string overload
}

RenderSettings draws into the host's settings window each frame the page is visible; see Rendering UI for the UIContext API. When the user presses Save, the host calls your SaveSettings (and SaveKeybinds), then persists. SetupSettingsPage(ctx, /*visible=*/false) registers a page whose Save logic still runs but which is not shown — useful for plugins that have settings but no UI of their own.

Reading host settings

To read a value the host owns, use the context's typed getters with a "section.name" key:

bool  hwdec = ctx.GetSettingBool("playback.hwdec");
float width = ctx.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 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

CommitSetting* and SaveSettings() on the context mutate host settings and are intended for the settings-menu plugin. Ordinary plugins persist their own state through IPluginSettings (per-plugin section) instead.