Skip to main content

Events

Events are POD structs broadcast over the context's publish/subscribe bus. Each declares a stable EventId used as its key. This page lists the events shipped in <framelift/Events.h>.

Publish with ctx.Publish<T>({...}); subscribe with framelift::Subscribe<T>(ctx, lambda) from <framelift/ContextHelpers.h>. See Cross-Plugin Communication.

Lifetime

All const char* fields are valid only during the subscriber callback. Copy into your own storage if you need them afterward. Fields are POD — no heap allocation crosses the boundary.

Built-in events​

NotificationEvent​

struct NotificationEvent
{
    static constexpr const char* EventId = "framelift.NotificationEvent";
    const char* text = nullptr;
};

Any plugin publishes this to show the user a transient message; the Overlay plugin subscribes and displays it.

ctx.Publish<NotificationEvent>({"Saved settings"});

FileOpenedEvent​

struct FileOpenedEvent
{
    static constexpr const char* EventId = "framelift.FileOpenedEvent";
    const char* path = nullptr;
};

Published by Playlist when a file begins playing.

FileEndedEvent​

struct FileEndedEvent
{
    static constexpr const char* EventId = "framelift.FileEndedEvent";
    const char* path = nullptr;
    double position = 0.0;
};

Published by Playlist when a file ends, or when its position is flushed on shutdown. position is the playback position in seconds — useful for saving a resume point.

OpenFileRequestEvent​

struct OpenFileRequestEvent
{
    static constexpr const char* EventId = "framelift.OpenFileRequestEvent";
    const char* path = nullptr;
};

Published by History when the user selects an entry to play; Playlist (or any other handler) subscribes to actually open the file. Use this to request playback without depending on the Playlist service directly.

Defining your own​

Any POD struct with a unique EventId is a valid event:

struct MyThingHappened
{
    static constexpr const char* EventId = "me.MyThingHappened";  // unique
    int   code = 0;
    float value = 0.f;
};

Keep it POD: numeric fields, fixed-size char arrays, and const char* (with documented call-only lifetime). No std::string, std::vector, or other STL types. See the ABI rules.