Plugin Context & Headers

This page is the orientation map for the SDK's public surface: the umbrella headers, the IPlugin interface, and the IPluginContext your plugin is handed.

Umbrella headers

Include the umbrella that covers what you need; each pulls in the relevant individual headers.

Header	Provides
<framelift/core.h>	Plugin lifecycle (IPlugin, PluginBase), IPluginContext, the ABI macros, events, hotkeys, Log. The one most plugins include.
<framelift/ui.h>	IRenderable, UIContext, DrawList, the UI:: POD types, widgets.
<framelift/services.h>	Cross-plugin service interfaces: IHistory.
<framelift/platform.h>	Platform services: IMediaPlayer, IAppWindow, IDirWatcher.

Author-side convenience wrappers (lambdas over the POD ABI) live in <framelift/ContextHelpers.h> and <framelift/HotkeyHelpers.h>.

IPlugin

The interface the host knows your plugin by. Most authors derive from PluginBase rather than implementing this directly — see Plugin Lifecycle.

class IPlugin
{
public:
    static constexpr const char* InterfaceId = "framelift.IPlugin";
    virtual ~IPlugin() = default;

    virtual void Install(IPluginContext& ctx) {}
    virtual void BindHotkeys(Hotkeys& keys) {}
    virtual bool OnEvent(const AppEvent& e);        // dispatches KeyDown → OnKeyDownEvent
    virtual bool OnKeyDownEvent(const AppEvent&) { return false; }
    virtual void OnMediaEvent(const MediaEvent&) {}
    virtual void OnShutdown() {}
};

A plugin that also draws UI additionally implements IRenderable.

IPluginContext

Passed into Install(); PluginBase stores it as ctx_. All virtual methods use a C-compatible ABI — no STL types cross the boundary. Prefer the non-virtual template helpers (GetService, RegisterService, Publish) and the free helpers in ContextHelpers.h (Subscribe, RegisterSettingsChangeCallback, GetSettingString, GetPrefPath, RegisterKeybindEntry) over the raw virtuals.

Services

template <typename T> T* GetService() const noexcept;          // nullptr if absent
template <typename T, typename... Us> void RegisterService(T*); // register under 1+ interfaces

Keyed by T::InterfaceId. See Cross-Plugin Communication.

Pub/sub

template <typename TEvent> void Publish(const TEvent& event) noexcept;
// framelift::Subscribe<TEvent>(ctx, lambda)  — free helper in ContextHelpers.h

Keyed by TEvent::EventId. See Events.

Settings

float GetSettingFloat (const char* key) const noexcept;   // "section.name"
bool  GetSettingBool  (const char* key) const noexcept;
int   GetSettingInt   (const char* key) const noexcept;
int   GetSettingString(const char* key, char* buf, int cap) const noexcept;

// Commit (settings-menu plugin): CommitSettingFloat/Bool/Int/String + SaveSettings()
IPluginSettings& GetPluginSettings(const char* sectionName) noexcept;

GetSettingString writes up to cap-1 chars + NUL and returns the full length; pass buf=nullptr to query the required size. The framelift::GetSettingString(ctx, key) helper wraps this into a std::string. See Settings.

Settings pages & keybind entries

void RegisterSettingsPage(const char* title, renderFn, applyFn, void* ud,
                          bool visible = true, cleanup = nullptr) noexcept;
void RegisterKeybindEntry(const char* label, const char* actionName,
                          getStr, setStr, void* ud) noexcept;

PluginBase::SetupSettingsPage() and framelift::RegisterKeybindEntry() wrap these. The host also exposes EnumerateSettingsPages / EnumerateKeybindEntries for the settings-menu plugin to walk them.

Pref path

int GetPrefPath(char* buf, int cap) const noexcept;

The trailing-separator user config directory (e.g. C:/Users/foo/AppData/Roaming/FrameLift/). framelift::GetPrefPath(ctx) returns it as a std::string.

AppEvent

Platform input delivered to OnEvent. type (an AppEventType) selects the active union member; accessors are AsKey(), AsFile(), AsCustom().

AppEventType	Payload
KeyDown / KeyUp	AsKey() → { Key key; Mod mods; }
DropFile	AsFile() → { const char* filePath; } (valid only during the call)
Custom	AsCustom() → { uint32_t eventType; void* userData1; }
Quit, WindowExposed, RenderUpdate, PlayerWakeup, MouseButtonDown, MouseMotion	none

Key is an integer keycode with named constants in the Keys:: namespace (Keys::Space, Keys::F1, Keys::Left, …). Mod is an OR-able bitfield (Mod::Ctrl | Mod::Shift); test it with ModSet(state, Mod::Ctrl). All in <framelift/AppEvent.h>.