ImKit 3.2 API

以下は公開ヘッダーから抽出した宣言です。既定値と戻り値の型を含みます。対象の宣言を変更したときは python tools/generate_v32_api.py を実行します。

状態と寿命

状態、値、ID、文字列、span、アイコンatlas、textureはアプリが所有します。参照先は各呼び出し中に有効に保ちます。textureは送信した描画コマンドが完了するまで保持します。アクセシビリティ用の文字列はホストのsemantic frameを公開する間も保持します。状態は使用するContextごとに管理し、scopeをContextより先に破棄します。

WorkspaceTabs と ChoiceGroup は選択要求のIDを返します。0は要求なしです。HierarchyRow は操作種別を返し、HierarchyGroupHeader は渡された開閉値を更新して任意の操作フラグを書き込みます。SettingToggleRow は切り替え要求を返すので、アプリ側で値を反転します。CompactActionRow の None、Primary、Settings に応じてアプリが処理します。DragVector3WithUnit は渡された3要素を編集し、いずれかが変化したかを返します。disabledの操作から編集要求は発生しません。

BeginInspectorCard がfalseでも必ず EndInspectorCard を呼びます。BeginSettingRow のEndはtrueの場合だけ必要です。

トーストの文字列は参照で、状態にはIDと時間を保持します。容量付き ToastEventBuffer を処理してから、削除・期限切れIDをアプリのqueueから取り除きます。countとoverflowを毎フレーム初期化し、単調増加するホスト時刻で ToastViewport をviewportごとに1回呼びます。LoadingからMessage/Successへ切り替える際もIDを維持します。期限、停止、overflowの規則はトーストガイドに記載しています。

バイナリ互換性

WindowFrameContent に iconTexture が追加されています。3.2のヘッダーを使い、アプリとリンクするImKit静的ライブラリを再コンパイルしてください。3.1のobjectと3.2の構造体を混在させないでください。Dear ImGuiの対応revisionと設定一致の要件は変わりません。

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{};
};