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;
    bool rebuildPlaylist = false; // true = rescan the directory and rebuild; false = just play this file
};

A request to open a file for playback. Published by History (entry selected), the host (file drop, open dialog, resume-last), or any other plugin; Playlist (or any other handler) subscribes to actually open it. Use this to request playback without depending on the Playlist service directly.

CliCommandEvent​

struct CliCommandEvent
{
    static constexpr const char* EventId = "framelift.CliCommandEvent";
    int argc = 0;
    const char* const* argv = nullptr;
};

Published once by the host at startup, after every plugin has loaded and subscribed, carrying the process command line verbatim (argv[0] is the program name). The host itself only consumes the first positional argument as a file/URL to open — everything else is yours to interpret. Subscribe to add your own subcommands, flags, or batch/analysis tasks without the host needing to know about them:

framelift::Subscribe<CliCommandEvent>(ctx, [](const CliCommandEvent& e) {
    for (int i = 1; i < e.argc; ++i) {
        // parse your own flags from e.argv[i]
    }
});

The argv array comes from main() and stays valid for the process lifetime, but copy any strings you retain past the callback to keep with the lifetime rule above.

Others​

<framelift/Events.h> also ships OpenNetworkStreamRequestEvent (prompt for a remote URL), PanelLayoutEvent (a panel's animated width changed), and SettingsVisibilityEvent (the settings dialog opened/closed). They follow the same POD + EventId shape.

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.