A hotbox with marking menus for Dear ImGui applications, inspired by the hotbox in Autodesk® Maya® and drawn in the IFCStudio UI design system. This is an independent project, not affiliated with or endorsed by Autodesk (see Credits and trademarks).
A 22-second tour, rendered from the harness.
Full-resolution MP4
- Pure Dear ImGui widget library (C++20). It does not own your window, GPU device or render loop, and it has no dependency on GLFW, Dawn or WebGPU.
- Crisp at any DPI: Inter text, Lucide chrome glyphs, SVG icons rasterised per density, design-system shadows, Light / Dark / System themes.
- Ships with a GLFW + Dawn (WebGPU) harness to try it and to render deterministic screenshots.
Status: milestones M0–M5 are done (core model, drawing, motion, theming, search, recent commands, tooltips, keyboard navigation and saved state). M6, harness polish, is next.
Contents:
- What is a hotbox?
- Using the hotbox
- Try it in the harness
- Programming interface
- Build and run
- Harness reference
- Repository guide
- Credits and trademarks
- License
Most applications put their commands in a menu bar at the top of the window. In a big tool, that means a long mouse trip to the top of the screen, a search through nested menus, and a trip back. A hotbox removes the trip.
Hold a key and the whole menu bar appears around your mouse pointer. Pick a command and let go of the key, and the hotbox disappears. You never leave the spot you were working on.
A hotbox has two halves:
- Menu rows. Your application's menus, laid out as floating strips centred on the pointer. You click a menu title and choose an item, just like a normal menu bar. This half is for finding commands.
- Marking menus. The space around the rows is split into five invisible zones: North, East, South, West and Center. Pressing a mouse button in a zone and dragging in a direction picks a command. Each zone has a separate marking menu for each mouse button (left, middle, right), so there are 15 of them. This half is for speed.
Marking menus are what make the hotbox fast. Each one has up to eight commands placed on compass directions (N, NE, E, … NW). Only the direction of your drag counts, not its length, so after a little practice "press in the North zone, flick up and to the right" becomes muscle memory, like a keyboard shortcut you draw. Experts flick so fast that the menu never appears at all. That is called mark-ahead.
╲ ╱ ← zone ticks
( File Edit Create Select Modify Display Windows Cache │ Help )
( View Shading Lighting Show Renderer Panels )
( Recent Commands ) ( Modeling ) ( Hotbox Controls ) ← centre row
( Mesh Edit Mesh Mesh Tools Mesh Display │ Curves Surfaces Deform UV Generate )
( Skeleton Skin Deform Constrain Control )
╱ ╲
North
╲ ╱
╲ ╱
West ( Center ) East
╱ ╲
╱ ╲
South
The four outer zones are separated by the two diagonals through the point where the hotbox opened, and they extend to the edges of the screen, so they are impossible to miss. The short diagonal zone ticks above and below the rows are the only visible hint of those boundaries. The Center zone is a circle with a 36 pt radius around the opening point.
| To | Do this |
|---|---|
| Open | Hold ⌥ Space on macOS or Alt+Space on Windows and Linux. The hotbox opens centred on the pointer after 180 ms, or immediately if you move the mouse. |
| Keep it open | Keep holding Space. You can let go of ⌥ / Alt once it is open. |
| Close | Release Space. |
| Invoke from a menu | Release Space while the pointer is over a menu item ("release to invoke"), or click the item. |
| Cancel | Press Esc, or click empty space that has no marking menu. Esc first clears a search, or closes a dropdown you opened from the keyboard. |
| Pin it open | Press P while holding the trigger, or choose Hotbox Controls → Pin Hotbox. A pinned hotbox stays open after you release Space and after a command runs. Close it with Esc or a click outside. |
| Search | Start typing. See Search. |
A quick tap of the trigger (shorter than 180 ms, without moving the mouse) does not open the hotbox. The application receives it as a separate "tap" action, for example to maximise the viewport.
The hotbox never opens while a text field has keyboard focus, so the chord still reaches your text fields there.
- Above the centre row: the common menus (File, Edit, …) and the panel menus (View, Shading, Lighting, Show, Renderer, Panels).
- Centre row:
- Recent Commands on the left lists the last eight commands you ran, from any menu, marking menu or search. They are remembered between sessions.
- The menu-set button in the middle shows the active menu set (here "Modeling") in the accent colour. Click it to switch sets.
- Hotbox Controls on the right: Pin Hotbox, and switches for Menu Rows and Zone Ticks.
- Below the centre row: the menus of the active menu set. A menu set is a group of task-specific menus. In the demo, "Modeling" shows the mesh tools and "Rigging" shows skeleton and skin tools. Switching sets changes the rows below the centre, and nothing else.
Click a title to open its dropdown. Dropdowns show icons, check marks, shortcut hints, separators, section headers and cascading submenus. Hover a submenu row to open it.
Some items have an option box, a small square at the right edge of the row. Clicking the square runs the item's "options" variant instead (typically it opens the command's settings before running it). Holding Shift while you release Space over the row does the same.
Disabled items are drawn in the disabled text colour and give a short shake if you try to use them. Rest the pointer on one for half a second and a tooltip says why it is disabled. Other commands show their description the same way.
- With the hotbox open, press a mouse button anywhere in a zone that is not on a menu title. Which zone you press in, and which button you use, picks the marking menu.
- Drag towards the command you want. The item in that direction lights up. A thin "rubber band" line runs from the press point to the pointer.
- Release the button to run it.
Details:
- Only the angle matters once you are 12 pt from the press point. Releasing inside that small dead zone cancels.
- Click instead of drag: a quick click without moving keeps the marking menu open. Click an item to choose it. This is handy on a trackpad.
- Number keys
1–8pick items while a marking menu is shown, starting at North and going clockwise. - Hold Shift when you release to use the item's option box.
- Submenus: an item can open a nested marking menu. Pause on it for about 280 ms, or turn sharply (more than 50°) after dragging at least 40 pt. Strokes like "East, then North" can go up to three levels deep.
- More than eight items: extras appear in an overflow list below the South item.
- Center zone: a short left-click on the menu-set button opens the menu-set chooser. A left-drag that starts on it uses the Center marking menu. Middle and right buttons always use the Center marking menu.
The marking menu waits 120 ms before it draws. If you press, flick and release within 350 ms, the command runs without the menu ever appearing. You see only the ink of your stroke and a short confirmation toast with the command's name. With practice, a whole command becomes "⌥Space + flick", which is faster than any menu and needs no memorised key combinations.
With the hotbox open, just type. The menu rows fade out and a search field appears above them, listing up to eight matching commands with their menu path and shortcut.
- Matching is forgiving:
dupfinds Duplicate,extfinds Extrude, andpcubefinds Polygon Cube. Case and accents are ignored. Several words must all match, in the label, the command's description, its keywords or its menu path (mesh comb). - Commands you use often and recently rank higher.
- ↑ / ↓ move the selection, Enter runs it, Shift+Enter runs its option box. You can also click a result.
- Once you are searching you can let go of the trigger: the hotbox stays open until you run a command, press Esc twice (the first clears the field) or click outside.
- While you still hold the trigger, P pins instead of typing a "p", and Space is ignored. After pinning, or once the search has started, every key types.
- With an empty field the list shows your recent commands.
Everything in the rows works without the mouse:
| Key | Does |
|---|---|
| Tab / Shift+Tab | Move through the menu titles, row by row from the top. |
| ← → | The previous or next title in the same row. In an open dropdown, switch to the neighbouring title's dropdown, or open and close submenus. |
| ↑ ↓ | The nearest title in the row above or below. In a dropdown, the previous or next item. |
| Enter | Open the focused title's dropdown, or run the focused item. Shift+Enter runs its option box. |
| Esc | Close the innermost dropdown, then the hotbox. |
A focus ring marks the keyboard focus. It hides when you move the mouse, so the mouse and the keyboard never fight over the same highlight.
- Start with the menu rows. They work like a normal menu bar.
- Learn the marking menus of one zone and one button at a time. The application usually puts related commands in the same zone (for example view commands in the North zone).
- Say the stroke to yourself ("North, up-right") the first few times.
- Once you know where a command lives, stop looking and just flick.
- ⌥Space is taken on some Macs. Launchers such as ChatGPT, Raycast or
Alfred often register ⌥Space as a global hotkey, and the hotbox then never
sees it. Change the other app's shortcut, change
Config::trigger, or use the harness's Open Hotbox button. Some Linux window managers (GNOME) reserve Alt+Space for their window menu. - Search does not yet highlight the letters that matched.
- Only the Solid material is available. Frost needs a blurred backdrop from the renderer and is a later add-on.
Build it (see Build and run) and start
build/macos-debug/hotbox_harness. The Hotbox harness panel has an
Open Hotbox button that opens the hotbox at the centre of the window. A
hotbox opened this way stays open until you press Esc or click outside it.
Alternatively, hold ⌥Space / Alt+Space over the viewport. The last command
you ran is shown under the button.
The demo registers the menus of a fictional 3D application and these marking menus:
| Zone | Left button | Middle button | Right button |
|---|---|---|---|
| North | N Frame · NE Isometric · E Top · SE Front · S Right · SW Projection (disabled) · W Edges · NW Render SVG | S Top | N Perspective · E Cameras ▸ (submenu) |
| East | E Extrude · NE Bevel | W Separate | E Combine |
| South | S Polygon Cube · SE Polygon Sphere | N Invert Selection | S Select All |
| West | W Duplicate · NW Undo · overflow: Snap to Grid, Delete History (disabled) | E Show All | W Hide Selection |
| Center | N Outliner · E Attribute Editor | N Freeze Transformations | S Center Pivot |
Things to try:
- Edit menu: a toggle (Snap to Grid), an option box (Duplicate Special…), a disabled item (Delete History) and shortcut hints.
- View → Cameras → Additional Cameras: nested submenus.
- Menu-set button: switch between Modeling and Rigging.
- Open the hotbox and type
dup,extrorbox, then press Enter. - Press Tab, Enter and the arrow keys to walk the menus without the mouse.
- Rest the pointer on Edit → Delete History to see why it is disabled.
- Run a few commands, then open Recent Commands. The interactive
harness keeps them in
hotbox_harness.iniin the working directory. - Left-press in the North zone and flick up-right quickly: mark-ahead runs Isometric without showing the menu.
- The panel's Theme, Shape, Motion speed, Reduced motion and 0.1× slow motion controls. The harness starts in System theme. The Contrast table shows the lowest contrast ratio of each colour role.
All public types are in namespace hotbox. Include the umbrella header:
#include <hotbox/hotbox.hpp>Requirements: C++20, CMake ≥ 3.24 and Dear ImGui 1.92 or newer (the
vendored copy is v1.92.9b-docking). The library uses ImGui 1.92's dynamic
fonts, so it needs a renderer backend that supports
ImGuiBackendFlags_RendererHasTextures.
#include <hotbox/hotbox.hpp>
// 1. Once, after ImGui::CreateContext() and before the first frame.
auto faces = hotbox::fonts::load_embedded(*ImGui::GetIO().Fonts);
ImGui::GetIO().FontDefault = faces.regular; // optional: use Inter for your UI too
// 2. Register commands, then place them in menus and marking menus.
hotbox::Registry registry;
std::vector<hotbox::ItemHandle> items;
items.push_back(registry.add({.id = "edit.undo", .label = "Undo", .shortcut = "Ctrl+Z",
.on_invoke = [&](const hotbox::InvokeContext&) { app.undo(); }}));
items.push_back(registry.add({.id = "edit.redo", .label = "Redo", .shortcut = "Ctrl+Shift+Z",
.on_invoke = [&](const hotbox::InvokeContext&) { app.redo(); }}));
registry.menu("edit", "Edit").item("edit.undo").item("edit.redo");
registry.marking_menu(hotbox::Zone::West)
.set(hotbox::Dir::W, "edit.undo")
.set(hotbox::Dir::E, "edit.redo");
// 3. Create the widget. The registry must outlive it.
hotbox::Hotbox widget(registry);
widget.set_theme_mode(hotbox::ThemeMode::System);
// 4. Every frame.
ImGui::NewFrame();
hotbox::begin_frame(); // advances the hotbox animations
draw_my_ui();
widget.frame(); // after your own UI, before Render()
ImGui::Render();That is a complete integration. Hold ⌥Space / Alt+Space, then left-drag left in the West zone to undo.
The API separates what a command is from where it appears.
| Concept | API | Purpose |
|---|---|---|
| Command (item) | Registry::add(ItemDesc) |
A command's id, label, icon, callbacks and state. |
| Menu | Registry::menu(id, label) |
An ordered list of item ids, separators, headers and submenus. Shown as a title in a row. |
| Menu set | Registry::define_menu_set(id, menus) |
A named group of menus shown below the centre row. One set is active. |
| Marking menu | Registry::marking_menu(zone, button) |
Up to eight item ids on compass directions, plus an overflow list. |
The same command can appear in any number of menus and marking menus.
Menu ids and item ids are separate namespaces, so a menu called edit and
an item called edit do not clash.
hotbox::ItemDesc desc{
.id = "edit.duplicate", // required, unique, stable
.label = "Duplicate",
.alt_text = "Duplicate the selected objects",
.disabled_reason = "Select one or more objects first",
.icon = hotbox::Icon::svg_file("icons/duplicate.svg"),
.shortcut = "Ctrl+D", // display only
.keywords = {"copy", "clone"},
.on_invoke = [&](const hotbox::InvokeContext&) { scene.duplicate(); },
.on_option = [&](const hotbox::InvokeContext&) { ui.open_duplicate_options(); },
.is_enabled = [&] { return !scene.selection().empty(); },
};
auto handle = registry.add(std::move(desc));Designated initialisers must follow the declaration order shown in this table.
| Field | Meaning |
|---|---|
id |
Required. Unique, stable id such as "edit.duplicate". add() logs and returns an empty handle for a duplicate. |
label |
Text shown in rows and menus. May be empty for an icon-only item. |
alt_text |
Required when label is empty. Used as the fallback label and the monogram source, searched, and shown in the tooltip when there is no tooltip. Kept for a future accessibility bridge. |
tooltip |
Longer description, shown after the hover delay. **bold** and `code` markers are accepted and drawn as plain text. |
disabled_reason |
Why the item is disabled. Replaces the tooltip text while is_enabled returns false. |
icon |
See Icons. Default Icon::none(). |
shortcut |
Shortcut hint drawn at the right of menu rows. It does not bind a key. |
keywords |
Extra search terms. |
kind |
Action (default), Toggle, Radio, Submenu, Separator or Header. |
radio_group |
Group name for Radio items. The host decides which one is checked. |
on_invoke |
Runs when the command is chosen. |
on_option |
Enables the option box and runs when it is used. |
is_enabled |
Polled while visible. Default: always enabled. |
is_checked |
Polled for Toggle and Radio items to draw the check mark. |
is_visible |
Hidden items are left out of menus and marking menus. Default: visible. |
user_data |
Passed back in InvokeContext::user_data. |
Predicates are called every frame while the hotbox is open, so keep them cheap. Exceptions thrown from predicates and callbacks are caught and logged with the command id.
hotbox::ItemHandle handle = registry.add(desc); // [[nodiscard]]
registry.update("edit.duplicate", [](hotbox::ItemDesc& item) { item.label = "Duplicate…"; });
const hotbox::ItemDesc* found = registry.find("edit.duplicate");
registry.remove("edit.duplicate");ItemHandleis RAII: destroying it unregisters that exact registration. It may safely outlive the registry. Callrelease()to keep the item registered for the registry's lifetime, which is handy for static commands.- The registry is main-thread only. Changes made during a frame (for example from a callback) become visible at the start of the next frame.
- Menus and marking menus refer to items by id. An id that is not registered, or whose item is hidden, is simply skipped. You can build the menus first and register commands later, for example when a plugin loads.
registry.menu("edit", "Edit")
.item("edit.undo").item("edit.redo")
.separator()
.header("Duplicate")
.item("edit.duplicate")
.submenu("edit.group", "Group", [](hotbox::MenuBuilder& m) {
m.item("edit.group.make").item("edit.group.ungroup");
});
registry.define_menu_set("Modeling", {"mesh", "edit-mesh", "mesh-tools"});
registry.define_menu_set("Rigging", {"skeleton", "skin", "constrain"});
registry.set_active_menu_set("Modeling");Calling menu() again with an existing id appends to that menu. Rows are
filled like this:
| Row | Menus |
|---|---|
| Top rows | Every top-level menu that is not in any menu set, in registration order. The panel menus view, shading, lighting, show, renderer and panels get a row of their own under the common menus. |
| Centre row | Recent Commands, the menu-set button (labelled with the active set), Hotbox Controls. |
| Rows below | The active menu set's menus, in the order given, wrapped at about 700 pt per row. |
The menu-set button lists every set in definition order and lets the user switch.
using hotbox::Dir;
registry.marking_menu(hotbox::Zone::North) // left button by default
.set(Dir::N, "view.frame").set(Dir::E, "view.top").set(Dir::W, "view.side");
registry.marking_menu(hotbox::Zone::North, ImGuiMouseButton_Right)
.set(Dir::E, "view.cameras") // a menu id: opens as a submenu
.overflow({"view.back", "view.bottom"}); // listed below the South item- 5 zones (
North,East,South,West,Center) × 3 buttons (ImGuiMouseButton_Left,_Middle,_Right) = 15 independent slots. Each can be empty. - Directions are
N, NE, E, SE, S, SW, W, NW. Keyboard indices 1–8 follow the same clockwise order. - A direction that names a menu id (or an item of kind
Submenu) opens that menu as a nested marking menu. - Leave room for growth: users learn positions, so moving a command to a different direction later breaks their muscle memory.
The whole arrangement (menus, menu sets and marking menus, but not the commands themselves) can be saved and loaded as a line-based text format, which is easy to diff and to hand-edit:
std::string text = registry.save_layout();
registry.load_layout(text); // throws std::invalid_argument; the old layout is kept on error# Comments start with #. Quote labels that contain spaces.
menu edit "Edit"
item edit.undo
item edit.redo
separator
header "Duplicate"
item edit.duplicate
submenu edit.group "Group"
item edit.group.make
end
menu mesh "Mesh"
item mesh.combine
menu-set Modeling mesh edit-mesh mesh-tools
menu-set Rigging skeleton skin
active-menu-set Modeling
marking north left
N view.frame
E view.top
overflow view.back view.bottom
marking center right
S modify.center
| Line | Meaning |
|---|---|
menu <id> "<label>" |
Start a top-level menu. |
submenu <id> "<label>" … end |
A nested menu inside the current one. |
item <id> / separator / header "<text>" |
Menu entries. |
submenu-ref <id> |
Reuse a menu defined elsewhere as a submenu. |
menu-set <id> <menu ids…> |
Define a menu set. |
active-menu-set <id> |
Select the active set. |
marking <zone> <button> |
Start a marking-menu slot: zone `north |
<DIR> <id> |
Assign a direction (N … NW) in the current slot. |
overflow <ids…> |
Overflow list of the current slot. |
A layout loaded from text has no menu icons. Commands still have to be
registered in code with Registry::add.
hotbox::Icon::none();
hotbox::Icon::glyph(lucide_codepoint); // codepoint in the bundled Lucide font
hotbox::Icon::glyph(codepoint, my_font); // codepoint in your own ImFont
hotbox::Icon::svg(svg_text); // rasterised per DPI and cached
hotbox::Icon::svg_file("icons/cube.svg");
hotbox::Icon::svg_pair(regular_32, compact_16); // two optical masters
hotbox::Icon::texture(tex_ref, {16, 16}); // your own texture, size in pt
hotbox::Icon::monogram("PC"); // 1–2 letters in a rounded square- Monochrome glyphs and SVGs are tinted with the current text colour, so
they follow the theme. Call
.tintable(false)for colour artwork, or.color(IM_COL32(...))for a fixed colour. svg_pairuses the 16 px compact master below 24 pt and the 32 px regular master above, independent of screen density. SVGs are rendered with lunasvg at the device resolution and packed into the ImGui font atlas, so they are never scaled bitmaps and need no renderer integration.- Disabled items draw SVG icons in greyscale and colour textures at 40 %.
- With
Config::monogram_fallbackon, icon-only items without artwork get a monogram made from theiralt_text.
hotbox::Config config;
config.trigger = ImGuiMod_Ctrl | ImGuiKey_H; // any modifier + key chord
config.can_open = [&] { return !app.modal_open(); };
hotbox::Hotbox widget(registry, config);
widget.on_open = [] { /* … */ };
widget.on_close = [] { /* … */ };
widget.on_trigger_tap = [&] { viewport.toggle_maximised(); };
widget.on_invoked = [&](const hotbox::InvokeContext& ctx) { analytics.record(ctx.id); };
widget.open(ImGui::GetMousePos()); // open from code (a toolbar button, a gamepad…)
widget.close(); // close(false) skips the animation
widget.set_pinned(true);
bool open = widget.is_open();| Member | Purpose |
|---|---|
frame() |
Submit once per frame, after your UI and before ImGui::Render(). Handles input, draws on the foreground draw list and runs queued callbacks at the end. |
open(pos) / close(animated) / is_open() |
Control from code. A hotbox opened with open() stays open until Esc, a click outside or a command runs, because no trigger key is being held. open() does nothing while a text field is active or can_open returns false. |
set_pinned(bool) |
Keep the hotbox open after the trigger is released. |
on_open, on_close |
Called when it opens or closes. |
on_trigger_tap |
A quick tap of the trigger that did not open the hotbox. |
on_invoked |
Global observer for every invocation (logging, analytics, macro recording). Called in addition to the item's own callback. |
recent_commands() |
The last eight commands run, most recent first. |
clear_history() |
Forget recent commands and the use counts that rank search results. |
export_state() / import_state(text) |
The saved state as text, for hosts that keep settings outside imgui.ini. |
set_motion, motion_prefs, is_animating |
See Motion. |
set_theme, set_theme_mode, set_system_appearance_provider, current_theme |
See Theming. |
While the hotbox is open it sets io.WantCaptureMouse and
io.WantCaptureKeyboard, so your application should check those flags as
usual and ignore input. It takes the typed characters for its search, owns
Tab, the arrow keys, Enter, Backspace and Esc for the frame, and on macOS
swallows the non-breaking space that ⌥Space types.
Each hotbox saves its recent commands, use times (which rank search
results), active menu set and the Menu Rows and Zone Ticks switches in the
host's imgui.ini, as a [Hotbox][Default] section. Nothing else is
needed if your application already uses io.IniFilename.
- Construct the
Hotboxbefore the firstImGui::NewFrame()so ImGui hands it its section while loading. A hotbox created later reads the section fromio.IniFilenameitself. - Give a second hotbox in the same context its own
Config::settings_id. An empty ID turns saving off. - If you keep settings elsewhere, store
export_state()and pass it back toimport_state(). The text is the samekey=valuelines as in the ini file.
| Field | Default | Meaning |
|---|---|---|
trigger |
ImGuiMod_Alt | ImGuiKey_Space |
Chord that opens the hotbox. Registered with ImGui::Shortcut(..., ImGuiInputFlags_RouteGlobal). Plain ImGuiKey_Space without a modifier is not supported yet and is ignored. |
hold_threshold_ms |
180 | Shorter presses without pointer movement count as a tap. |
reveal_delay_ms |
120 | Delay before a marking menu is drawn (mark-ahead window starts). |
markahead_window_ms |
350 | A stroke released within this time fires without the menu. |
submenu_dwell_ms |
280 | Dwell time that opens a marking submenu. |
dead_zone_pt |
12 | Radius around the press point where nothing is selected. |
show_menu_rows |
true | Show the menu rows (the user can toggle this in Hotbox Controls). |
show_zone_ticks |
true | Show the diagonal zone ticks. |
enable_search |
true | Typing while the hotbox is open searches all registered commands. |
monogram_fallback |
true | Draw monograms for icon-less, label-less items. |
scrim_opacity |
0.35 | Multiplied with the theme's scrim alpha. |
tooltip_delay_ms |
500 | How long the pointer or keyboard focus rests on a command before its tooltip appears. |
settings_id |
"Default" |
Section name in imgui.ini (see Saved state). Empty disables saving. |
can_open |
empty | Return false to veto opening. |
Callbacks receive the context of the invocation:
| Field | Meaning |
|---|---|
id |
The command id. |
source |
MarkingMenu, MarkAhead, MenuRow, Search, Keyboard, Recent or Api. |
button |
Mouse button of the marking menu. |
modifiers |
Modifier keys at the time of invocation. |
invoke_pos |
Screen position where the hotbox was opened, for example to place a new object there. |
option_box |
true when the option box was used (on_option is called instead of on_invoke). |
user_data |
The item's user_data. |
Callbacks never run in the middle of drawing. They are queued and run at the
end of frame(), after the close animation has started, so a callback may
open a modal, change the registry or destroy items.
auto light = hotbox::Theme::IFCStudioLight();
auto dark = hotbox::Theme::IFCStudioDark();
light.shape = dark.shape = hotbox::ShapeSetting::Square; // or Rounded (default)
widget.set_theme(light, dark);
widget.set_theme_mode(hotbox::ThemeMode::System); // Light, Dark (default) or System
// Optional: follow your application's own appearance instead of the OS.
widget.set_system_appearance_provider([&] {
return app.dark_ui() ? hotbox::ThemeMode::Dark : hotbox::ThemeMode::Light;
});
// Optional: style the rest of your ImGui UI with the same tokens.
hotbox::ApplyImGuiTheme(widget.current_theme(), ImGui::GetStyle());- System mode follows the OS appearance live on macOS, Windows and Linux
(through the desktop portal when built with GLib). A provider that returns
ThemeMode::System, or an empty provider, falls back to the OS. - Theme and shape changes animate.
- A
Themeholds the generated design tokens (tokens.color("surface/app"),tokens.text("type/caption")), the hotbox colour roles (colors), the shape setting, the material and the motion timings. Editcolorsto customise individual roles. CheckSolidContrast(theme)reports the lowest contrast ratio of each role across its painted states, useful for checking a customised theme.
widget.set_motion({.speed = 1.0f, .reduced_motion = false}); // speed 0.1 = slow motion, 0 = instant
if (widget.is_animating())
request_redraw(); // for event-driven render loops- Animations use ImAnim. Call
hotbox::begin_frame()once afterImGui::NewFrame(). If your application already advances ImAnim itself, callbegin_frame(true)after your update instead. - In System theme mode the widget also follows the OS "reduce motion"
setting until you call
set_motion(). - If you only redraw on input, keep rendering while
is_animating()is true.
The hotbox draws with Inter (Regular, Medium, SemiBold) and Lucide. They are embedded in the library by default:
auto faces = hotbox::fonts::load_embedded(*io.Fonts); // HOTBOX_EMBED_FONTS=ON
auto faces = hotbox::fonts::load_from_files(*io.Fonts, vendor_dir); // HOTBOX_EMBED_FONTS=OFF
if (!faces) { /* a face failed to load */ }Load them before the first frame. If the faces are missing, the hotbox falls back to ImGui's current font and loses its chrome glyphs.
Dear ImGui sizes fonts by ascent + descent, while design tools size them by
em. hotbox::fonts::imgui_size(font, em) converts a design size so text
matches the design:
ImGui::PushFont(faces.semibold, hotbox::fonts::imgui_size(faces.semibold, 13));The library logs to an spdlog logger named "hotbox" (open/close and
invocations at info, gesture decisions at debug, duplicate ids and missing
icons at warn). Route it into your own logging with
hotbox::set_logger(my_logger); an empty pointer restores the default.
Build with HOTBOX_WITH_SPDLOG=OFF to drop spdlog entirely.
set(HOTBOX_BUILD_HARNESS OFF CACHE BOOL "" FORCE)
set(HOTBOX_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(HOTBOX_IMGUI_TARGET my_imgui CACHE STRING "" FORCE) # optional: your own ImGui target
add_subdirectory(third_party/imgui-hotbox)
target_link_libraries(my_app PRIVATE hotbox::hotbox)| Option | Default | Effect |
|---|---|---|
HOTBOX_BUILD_HARNESS |
ON | Build the GLFW + Dawn harness. Off: no GLFW, Dawn or WebGPU needed. |
HOTBOX_BUILD_TESTS |
ON | Build hotbox_tests (doctest). |
HOTBOX_WITH_SPDLOG |
ON | Log through spdlog. |
HOTBOX_WITH_FREETYPE |
ON | Use ImGui's FreeType loader. Turn off if your ImGui target already compiles it, and let the host select the loader. |
HOTBOX_EMBED_FONTS |
ON | Embed Inter and Lucide. Off: load them with fonts::load_from_files. |
HOTBOX_IMGUI_TARGET |
vendored | Link against your existing, compatible ImGui target to avoid duplicate ImGui symbols. |
HOTBOX_DAWN_PREBUILT_DIR |
empty | Use a pre-built static Dawn for the harness. |
git submodule update --init -- vendor/dawn
bash scripts/vendor.sh
cmake --preset macos-debug
cmake --build --preset macos-debug
ctest --preset macos-debug
build/macos-debug/hotbox_harnessUse windows-debug in a Visual Studio developer shell or linux-debug on
Linux. The macOS harness uses Metal, the Windows harness D3D12, and the Linux
harness Vulkan with X11 and Wayland. On Ubuntu, install
xorg-dev libx11-xcb-dev libwayland-dev wayland-protocols libxkbcommon-dev,
and libglib2.0-dev to enable live desktop-portal appearance.
The first configure needs network access for Dawn's pinned dependencies. The vendor script restores missing snapshots. CMake applies the version-file patch to a copy of Dawn in the build tree.
Turn off HOTBOX_BUILD_HARNESS to build without GLFW or Dawn. The asan
and ubsan presets exercise this build.
Point HOTBOX_DAWN_PREBUILT_DIR to the install prefix of a compatible
monolithic static Dawn package. To install the package from the macOS
source build:
cmake --build --preset macos-debug --target webgpu_upstream_cpp_headers_gen
cmake --install build/macos-debug/vendor/dawn --prefix "$PWD/build/dawn-install"
cmake -S . -B build/prebuilt -G Ninja -DCMAKE_BUILD_TYPE=Debug \
-DHOTBOX_DAWN_PREBUILT_DIR="$PWD/build/dawn-install"
cmake --build build/prebuilthotbox_harness [--theme dark|light|system] [--shape rounded|square]
[--scenario NAME --scale N --time S] [--motion N]
[--reduced-motion on|off] [--icons public|private]
[--frames N] [--out FILE | --sequence DIR]
Without --scenario the harness opens an interactive window. With a
scenario it renders offscreen and writes a PNG at the native framebuffer
size, which makes captures repeatable:
build/macos-debug/hotbox_harness --scenario menu-edit --theme dark --scale 1.5 \
--time 0.15 --out build/menu-edit-dark-1.5x.pngSave every frame of a scripted transition with --sequence; --motion 0.1
slows it down tenfold:
build/macos-debug/hotbox_harness --scenario open-close --theme light --scale 2 \
--motion 0.1 --frames 246 --sequence build/open-close| Scenario | Shows |
|---|---|
open-layout |
The open hotbox with all rows. |
menu-edit |
The Edit dropdown. |
submenu, submenu-cameras |
Cascading dropdowns (View → Cameras). |
marking-n2 |
The North left-button marking menu. |
marking-invoke, marking-disabled |
Invoking an item, and trying a disabled one. |
mark-ahead |
A mark-ahead stroke with its ink and toast. |
open-close |
The open and close transitions. |
theme-shape |
An animated theme and shape change. |
search |
Typing du and its results. |
keyboard |
Tab, arrows and Enter down the Edit menu, with the focus ring and a disabled item's tooltip. |
recent |
The Recent Commands dropdown, opened from the keyboard. |
tour |
The scripted 22-second tour at the top of this README, with a drawn pointer, key caps and captions. |
scripts/record_tour.sh renders the tour scenario and writes
docs/media/hotbox-tour.gif (shown inline above) and
docs/media/hotbox-tour.mp4. GitHub plays a video inline in a README only
when it is uploaded as an attachment, so the MP4 is linked rather than
embedded.
Use --shape square to check zero-radius shells, targets and menus, and
--icons public to force the bundled demo icons in harness/icons.
| Path | Contents |
|---|---|
| include/hotbox | Public headers. |
| src | Library implementation. |
| harness | GLFW + Dawn harness and demo commands. |
| tests | doctest unit, interaction and paint tests. |
| vendor/VENDOR.md | Exact dependency pins and local patches. |
| THIRD_PARTY_NOTICES.md | Third-party licences. |
| AGENTS.md | Instructions for coding agents. |
| scripts/record_tour.sh | Re-records the demo animation at the top of this file. |
The interaction design follows the hotbox and marking menus of Autodesk® Maya® and the research behind them:
- G. Kurtenbach and W. Buxton, "The Limits of Expert Performance Using Hierarchic Marking Menus", Proceedings of INTERCHI '93.
- G. Kurtenbach, G. W. Fitzmaurice, R. N. Owen and T. Baudel, "The Hotbox: Efficient Access to a Large Number of Menu-items", Proceedings of CHI '99.
ImGui Hotbox is an independent implementation of that publicly described behaviour. It contains no Autodesk code, artwork, icons, screenshots or documentation, and it is not affiliated with, endorsed by or sponsored by Autodesk, Inc. The menu names in the demo are generic examples.
Autodesk and Maya are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. They are used here only to describe where the interaction style comes from. All other trademarks are the property of their respective owners.
Third-party components (Dear ImGui, ImAnim, Inter, Lucide, lunasvg, FreeType and others) keep their own licences, listed in THIRD_PARTY_NOTICES.md.
ImGui Hotbox is released under the MIT License.