WindowFrame

用途

WindowFrameはテーマ付きのtitle areaを描画し、型付きwindow操作を返します。native windowとevent loopはアプリ側が管理します。

Galleryの画面

Galleryの全体画面 — application shellとcontent · Galleryの操作映像を開く

最小描画例

#include <imkit/window_frame.h>

imkit::WindowFrameResult DrawTitleArea(const imkit::Theme& theme,
                                       const imkit::WindowFrameContent& content,
                                       float widthPixels) {
    const auto style = imkit::MakeWindowFrameStyle(
        imkit::WindowFramePreset::Workspace, theme);
    const auto layout = imkit::LayoutWindowFrame(widthPixels, style);
    return imkit::DrawWindowFrame(style, content, layout);
}

例の種別: 完結した関数例です。現在のTheme、借用content、window幅をアプリ側で渡し、戻り値の操作を適用します。

アプリへ組み込む

任意のWin32/macOS targetでnative title barの操作を連携します。基本描画APIはnative windowを所有しません。

範囲

Icon atlasとGPU textureもアプリ側のresourceです。window生成やtexture uploadは行いません。

関連APIとガイド

• WindowFrame API map
• Iconガイド

---

imkit/window_frame.h は、プラットフォーム非依存の値型レイアウトおよび描画APIです。ウィンドウのタイトルバーやクライアント領域外装飾を、ImKitのデザインシステムと調和させてカスタマイズできます。

概要

Dear ImGui Context、バックエンド、レンダラー、フォント、テーマ、OSウィンドウハンドル、選択中プリセット、スタイル設定の永続化はすべてホスト側が所有します。 MakeWindowFrameStyle(preset, theme) は完全に独立した値のコピーを返すため、後からテーマを変更しても既存のフレームスタイルが暗黙に書き換わることはありません。生成されたスタイルの色、寸法メトリクス、各機能フラグはすべて直接編集可能です。

プリセット	特徴と既定の振る舞い
Native	カスタム非クライアント描画を行わず、OS標準のタイトルバーを使用（高さ 0）
Studio	制作ツール向けのコンパクトなタイトル、アプリアイコン、3つの標準キャプション操作ボタン
Workspace	アプリケーション名、プロジェクト名、未保存インジケーター、ワークスペース切り替えタブを内包
Tool	短いユーティリティウィンドウ向けタイトルと、閉じるボタンのみのシンプルな構成

利用方法とコード例

ホストが開始したDear ImGuiフレーム内でレイアウト計算と描画を行い、返された操作要求（最小化・最大化・閉じるなど）をOSウィンドウに適用します。

#include <imkit/imkit.h>
#include <imkit/window_frame.h>

// 1. スタイルの生成（必要に応じてカスタマイズ）
auto style = imkit::MakeWindowFrameStyle(imkit::WindowFramePreset::Workspace, currentTheme);
style.metrics.height = 38.0f;
style.features.workspaceSwitcher = true;

// 2. 表示コンテンツの準備（参照は描画中有効であること）
const std::string_view workspaces[] = {"Edit", "Color", "Deliver"};
imkit::WindowFrameContent content{
    "My App",            // アプリケーション名
    "Project A",         // プロジェクト名
    true,                // 未保存の変更フラグ
    workspaces,          // ワークスペース一覧
    selectedWorkspace    // 現在のワークスペースインデックス
};

// 3. プラットフォームアダプターからの状態取得とレイアウト計算
auto state = platformAdapter.State();
auto layout = imkit::LayoutWindowFrame(windowWidthPixels, style, state);
platformAdapter.SetLayout(layout);

// 4. タイトルバーの描画とイベント処理
auto result = imkit::DrawWindowFrame(style, content, layout, state);
if (result.action == imkit::WindowFrameAction::Close) {
    RequestAppExit();
} else if (result.hasWorkspaceSelection) {
    selectedWorkspace = result.selectedWorkspace;
}

WindowFrameContent で渡す string_view や span は非所有ポインタです。描画呼び出しが完了するまで有効なメモリ領域を指している必要があります。WindowFrameContent::iconTexture にはホスト所有のテクスチャを渡すことができ、無効な場合は組み込みの幾何学アイコンが描画されます。

API一覧

API	役割と責務契約
MakeWindowFrameStyle	テーマ設定からホスト所有の完全なスタイル値を生成
LayoutWindowFrame	DIP単位の寸法からピクセル矩形を計算し、OSボタン等の占有領域を予約
DrawWindowFrame	現在のDear ImGui Contextへ描画し、発生した型付きイベントを返却
ElideWindowFrameTitle	UTF-8の文字境界を破壊しない安全なタイトル文字列の省略処理
ValidateWindowFrameContrast	コントラスト比率と警告の算出（色の強制置換や入力拒否は行わない）
WindowFrameWin32Adapter	借用した HWND に対する明示的な Attach/Detach とサブクラス化によるウィンドウ操作
WindowFrameMacOSAdapter	借用した NSWindow に対する透明タイトルバー化とフルサイズコンテンツビュー設定

Windows Gallery Frame Lab

Windows環境で開発用ギャラリーをビルドして起動し、Window frame を選択すると動作を確認できます。

cmake -S . -B build/window-frame-public-debug
cmake --build build/window-frame-public-debug --config Debug --target imkit_gallery --parallel
.\build\window-frame-public-debug\catalog\Debug\imkit_gallery.exe

• 4つのプリセットを実行時にリアルタイムで切り替え可能です。
• Native 選択時は imkit::window_frame_win32 を Detach し、それ以外では Attach して公開描画APIを使用します。
• Win32アダプターは SetWindowSubclass を使用し、ウィンドウの四辺・四隅のリサイズ、タイトルバーのドラッグやダブルクリック、システムメニュー（Alt+Space）、Alt+F4、標準の最小化/最大化/復元/終了ルーティングを安全に維持します。
• 最大化ボタンのヒットテスト領域は、Windows 11のSnap Layoutsに対応するため HTMAXBUTTON を返します。

macOS アダプター

Apple環境（macOS）では、GLFW/OpenGLベースの軽量デモをビルドして検証できます。

cmake -S . -B build/macos-window-frame \
  -DIMKIT_BUILD_GALLERY=OFF \
  -DIMKIT_BUILD_WINDOW_FRAME_MACOS=ON \
  -DIMKIT_BUILD_WINDOW_FRAME_DEMO_MACOS=ON
cmake --build build/macos-window-frame --target imkit_window_frame_demo_macos
./build/macos-window-frame/imkit_window_frame_demo_macos

imkit::window_frame_macos は借用した Cocoa ウィンドウを扱います。カスタムプリセット適用時は透明タイトルバーとフルサイズコンテンツビューを要求し、macOS標準の信号機（traffic-light）ボタン領域を予約します。ボタン配置や全画面化、ドラッグ移動はOS側に委任し、閉じる・最大化ボタンの二重描画を防ぎます。

検証の境界

• 合成イベントによるヒットテストやCI環境でのDebugビルドは、実機OS上でのIME入力、多画面DPIスケーリング、アクセシビリティ読み上げの完全な受け入れを直接保証するものではありません。
• 現状の実装・検証状況については 検証記録 を参照してください。