ImKit 3.2 API

Declarations below are extracted from the public headers, including defaults and return types. Re-run python tools/generate_v32_api.py after editing a covered declaration.

State and lifetime

The application owns all state, values, IDs, strings, spans, icon atlases and textures. Borrowed views must stay valid during each call; textures must also remain valid until the submitted draw commands finish. Accessibility text must also survive publication of the host semantic frame. Keep each state instance associated with its context and destroy scopes before the context.

WorkspaceTabs and ChoiceGroup return a requested stable ID (zero means no request). HierarchyRow returns an action; HierarchyGroupHeader edits the supplied open value and writes the optional action flag. SettingToggleRow returns a toggle request: the host must flip its own value. CompactActionRow returns None, Primary or Settings; the host handles each operation. DragVector3WithUnit edits the supplied three floats and returns whether any axis changed. Disabled controls do not issue edit requests.

Always call EndInspectorCard, even when BeginInspectorCard returns false. This differs from BeginSettingRow, whose End is called only after a true return.

Toast strings are borrowed; state stores IDs and timing, not strings or callbacks. Process the bounded ToastEventBuffer, then remove dismissed/expired IDs in the host. Reset buffer count/overflow for each frame and call ToastViewport once per viewport per frame with monotonic host time. Keep the same ID when changing Loading to Message/Success. See the toast guide for duration, pause and overflow rules.

Binary compatibility

WindowFrameContent now has an iconTexture member. Recompile applications and every linked ImKit static library against the 3.2 headers. Do not mix 3.1 objects with 3.2 structures. The Dear ImGui revision and matching configuration requirement are unchanged.

WorkspaceTab

Header: <imkit/workflow.h>

struct WorkspaceTab {
    StableId id=0;
    const char* label="";
    const char* description="";
    IconId icon=IconId::Count;
    bool disabled=false;
};

ChoiceItem

Header: <imkit/workflow.h>

struct ChoiceItem {
    StableId id=0;
    const char* label="";
    const char* description="";
    IconId icon=IconId::Count;
    ImVec4 accent{};
    bool disabled=false;
    const char* disabledReason="";
};

ChoiceGroupOptions

Header: <imkit/workflow.h>

struct ChoiceGroupOptions {
    int maximumColumns=3;
    const IconAtlas* icons=nullptr;
};

HierarchyRowView

Header: <imkit/workflow.h>

struct HierarchyRowView {
    StableId id=0;
    const char* label="";
    const char* detail="";
    IconId icon=IconId::Count;
    int depth=0;
    bool selected=false, visible=true, locked=false, disabled=false;
    const char* visibleLabel="Visible";
    const char* hiddenLabel="Hidden";
    const char* lockedLabel="Locked";
    const char* unlockedLabel="Unlocked";
    const char* moreLabel="More actions";
    bool visibilityAvailable=true, lockAvailable=true;
};

HierarchyRowAction

Header: <imkit/workflow.h>

enum class HierarchyRowAction { None, Select, ToggleVisibility, ToggleLock, More };

WorkspaceTabs

Header: <imkit/workflow.h>

StableId WorkspaceTabs(const char* id, std::span<const WorkspaceTab> tabs,
                       StableId selected, const IconAtlas* icons=nullptr,
                       ComponentOptions options={});

ChoiceGroup

Header: <imkit/workflow.h>

StableId ChoiceGroup(const char* id,const char* title,std::span<const ChoiceItem> items,
                     StableId current,ChoiceGroupOptions layout={},ComponentOptions options={});

HierarchyGroupHeader

Header: <imkit/workflow.h>

bool HierarchyGroupHeader(const char* id, const char* label, int count,
                          bool* open, const IconAtlas* icons=nullptr,
                          IconId icon=IconId::Count, ComponentOptions options={},
                          bool* actionRequested=nullptr, const char* actionLabel="Add");

HierarchyRow

Header: <imkit/workflow.h>

HierarchyRowAction HierarchyRow(const char* id, const HierarchyRowView& row,
                               const IconAtlas* icons=nullptr,
                               ComponentOptions options={});

BeginInspectorCard

Header: <imkit/workflow.h>

bool BeginInspectorCard(const char* id, const char* title, const char* description="",
                        const IconAtlas* icons=nullptr, IconId icon=IconId::Count,
                        ComponentOptions options={});

EndInspectorCard

Header: <imkit/workflow.h>

void EndInspectorCard();

SettingToggleRow

Header: <imkit/workflow.h>

bool SettingToggleRow(const char* id, const char* label, const char* description,
                      bool current, bool disabled=false, const char* disabledReason="",
                      ComponentOptions options={});

CompactActionRowOptions

Header: <imkit/components.h>

struct CompactActionRowOptions {
    const char *statusText = nullptr;
    StatusKind statusKind = StatusKind::Neutral;
    const char *primaryLabel = nullptr;
    ActionVariant primaryVariant = ActionVariant::Primary;
    const char *settingsLabel = "Settings";
    ActionVariant settingsVariant = ActionVariant::Ghost;
    bool primaryEnabled = true;
    bool settingsEnabled = true;
    const char *primaryDisabledReason = nullptr;
    const char *settingsDisabledReason = nullptr;
    ComponentOptions components{};
};

CompactActionRowRequest

Header: <imkit/components.h>

enum class CompactActionRowRequest { None, Primary, Settings };

DragVector3WithUnit

Header: <imkit/components.h>

bool DragVector3WithUnit(const char *label, float value[3], const char *unit, float speed = 1.f,
                         float minimum = 0.f, float maximum = 0.f, const char *format = "%.3f",
                         ImGuiSliderFlags flags = 0);

CompactActionRow

Header: <imkit/components.h>

CompactActionRowRequest CompactActionRow(const char *id, const CompactActionRowOptions &options);

ToastPosition

Header: <imkit/toast.h>

enum class ToastPosition { TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, BottomRight };

ToastPhase

Header: <imkit/toast.h>

enum class ToastPhase { Message, Loading };

ToastEventKind

Header: <imkit/toast.h>

enum class ToastEventKind { Dismiss, Expired, Action };

ToastView

Header: <imkit/toast.h>

struct ToastView {
    StableId id=0;
    const char* title="";
    const char* description="";
    FeedbackKind kind=FeedbackKind::Info;
    // Negative selects the kind default; zero persists; positive is seconds.
    double duration=-1;
    bool dismissible=true;
    const char* action="";
    bool actionDisabled=false;
    ToastPhase phase=ToastPhase::Message;
    // Negative or nonfinite means indeterminate. Otherwise clamped to [0,1].
    float progress=-1;
};

ToastEvent

Header: <imkit/toast.h>

struct ToastEvent { StableId id=0; ToastEventKind kind=ToastEventKind::Dismiss; };

ToastEventBuffer

Header: <imkit/toast.h>

struct ToastEventBuffer {
    std::span<ToastEvent> storage{};
    std::size_t count=0;
    bool overflow=false;
    bool Push(ToastEvent event);
};

ToastViewportOptions

Header: <imkit/toast.h>

struct ToastViewportOptions {
    ToastPosition position=ToastPosition::TopRight;
    float width=0; // Zero uses font-relative width.
    float margin=-1, gap=-1; // Negative uses theme/style spacing.
    std::size_t maximum=4;
};

ToastViewportState

Header: <imkit/toast.h>

struct ToastViewportState {
    static constexpr std::size_t Capacity=64;
    struct Entry {
        StableId id=0;
        std::uint64_t order=0;
        FeedbackKind kind=FeedbackKind::Info;
        ToastPhase phase=ToastPhase::Message;
        double duration=-1, remaining=0, shownSeconds=0;
        bool visible=false, paused=false, retired=false, pendingExpiry=false;
    };
    std::array<Entry,Capacity> entries{};
    double lastTime=0;
    std::uint64_t nextOrder=0;
    bool hasTime=false, overflow=false;
    void Reset();
};

UpdateToastViewport

Header: <imkit/toast.h>

void UpdateToastViewport(std::span<const ToastView> items, ToastViewportState& state,
                         double now, std::size_t maximum, ToastEventBuffer& events,
                         std::span<const StableId> paused={});

ToastViewport

Header: <imkit/toast.h>

void ToastViewport(const char* id, std::span<const ToastView> items,
                   ToastViewportState& state, double now, ToastEventBuffer& events,
                   ToastViewportOptions layout={}, ComponentOptions options={});

WindowFrameContent

Header: <imkit/window_frame.h>

struct WindowFrameContent {
    std::string_view applicationName{};
    std::string_view projectName{};
    bool unsaved = false;
    std::span<const std::string_view> workspaces{};
    std::size_t selectedWorkspace = 0;
    ImTextureRef iconTexture{};
};