Menus
One menu engine behind dropdowns, menubars, context menus and selects, plus a navigation menu with rich panels.


In the galleryMenumenuDropdown Menudropdown_menuContext Menucontext_menuMenubarmenubarSelectselectNavigation Menunavigation_menu
They live in isolenui/kit/menus.h and come in through isolenui/kit/kit.h. Every *_begin returns true while its menu is open, and only then do you declare the entries and call the end. A false begin has nothing to close, so skip the end. There are no block macros for this group.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
struct editor {
bool wrap = true;
uint32_t zoom = 1u;
uint32_t sort = 0u;
uint32_t font = 0u;
};
static void open_file(editor*) {}
static void quit(editor*) {}
static void menus(ui::ctx* u, editor* e)
{
// one menu open at a time, hover walks the bar once one is open
if (ui::menubar_begin(u, "main")) {
if (ui::menubar_menu(u, "File")) {
if (ui::menu_item(u, "Open", "Ctrl+O")) {
open_file(e);
}
if (ui::submenu_begin(u, "Recent")) {
ui::menu_item(u, "notes.deck");
ui::menu_item(u, "talk.deck");
ui::submenu_end(u);
}
ui::menu_separator(u);
if (ui::menu_item(u, "Quit", "Ctrl+Q")) {
quit(e);
}
ui::menu_end(u);
}
if (ui::menubar_menu(u, "View")) {
ui::menu_check(u, "Word wrap", &e->wrap);
ui::menu_label(u, "Zoom");
ui::menu_radio(u, "Small", 0u, &e->zoom);
ui::menu_radio(u, "Normal", 1u, &e->zoom);
ui::menu_radio(u, "Large", 2u, &e->zoom);
ui::menu_end(u);
}
ui::menubar_end(u);
}
// a button whose menu drops below it
if (ui::dropdown_begin(u, "Sort")) {
ui::menu_radio(u, "Name", 0u, &e->sort);
ui::menu_radio(u, "Date", 1u, &e->sort);
ui::menu_end(u);
}
// a right click or the menu key on the element just declared
ui::text(u, "right click me");
if (ui::context_menu_begin(u)) {
ui::menu_item(u, "Copy", "Ctrl+C");
ui::menu_item(u, "Paste", "Ctrl+V", false);
ui::menu_end(u);
}
// a listbox, the trigger shows the current item
static const char* const fonts[] = { "Objectivity", "Inter", "Mono" };
if (ui::select(u, "font", fonts, 3u, &e->font)) {
ui::text(u, "font changed");
}
}The engine
Only one menu is open at a time, and its state lives in the store under kit menu. Opening another closes the first. menu_open(u, id, by_keys) opens the menu rooted at id, menu_close shuts it and menu_is_open asks. menu_begin(u, id, anchor) returns true only while id is the open root, and places the panel as a popover against the anchor. Pair it with menu_end, which warns when called without a menu. A menu that is not declared on a frame closes itself and logs it.
| Call | Returns true when |
|---|---|
menu_item(u, label, shortcut, enabled) | The item is activated. The shortcut is drawn dim at the right, it binds no key. |
menu_check(u, label, &on, ...) | The item is activated. It flips on first and shows a tick while it is set. |
menu_radio(u, label, option, &value, ...) | value changed to option. In a select it is true on any pick. |
menu_label, menu_separator | Never. A dim caption and a rule. |
submenu_begin(u, label, enabled) | The submenu is open. Declare its entries, then submenu_end. |
Activating any item closes the whole menu, submenus included.
- Keys. Up and Down step, Page Up and Page Down move a page, Home and End go to the ends. Enter or Space activates. Right opens a submenu and Left closes it. Typeahead and the arrows skip disabled items.
- Typeahead. Printable letters jump to the next item whose label starts with what was typed, ignoring case. The typed text resets after one second.
- Submenus. A sub row opens on hover or Right and sits at the
side_endof its row. Menus nest at most 6 deep, deeper ones warn and stay shut. - Dismissal. Escape at any level closes the whole menu, and so does a press outside it.
- Long menus. A menu taller than the room scrolls with the wheel and shows scroll buttons at its ends.
- Opening in place. A menu opens at its final size on its first frame. Before the layout has solved it, the panel's height is worked out from the room above and below the trigger, and a check or radio mark found after some rows were laid out moves those rows over in the same frame. Nothing slides or grows on the second frame.
- Fade. Each menu panel, submenus included, fades in with its items over 100 ms, easing out, through
style::opacity. It still opens at its final size and place, only the alpha rises. In a menubar, moving to the next title or walking the row with Left and Right opens the next menu at full strength with no fade. The lists of a combo and a combobox fade in the same way. A close is instant. - Shadow. Every menu panel sits on the theme's
elev_md, see shadows and elevation.
Flat tables
menu_entries(u, list, count) declares a menu_entry table inside an open menu and returns the index activated, or minus one. A menu_kind_sub entry owns the entries after it that sit one depth deeper. check is the bool a check entry flips, and radio with option is the value a radio entry writes. disabled greys an entry out.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
static bool g_grid = true;
static uint32_t g_theme = 0u;
// a flat table, a sub entry owns the deeper entries after it
static const ui::menu_entry k_bar[] = {
{ "File", nullptr, ui::menu_kind_sub, 0 },
{ "New", "Ctrl+N", ui::menu_kind_item, 1 },
{ "Export", nullptr, ui::menu_kind_sub, 1 },
{ "PNG", nullptr, ui::menu_kind_item, 2 },
{ "PDF", nullptr, ui::menu_kind_item, 2, true },
{ "View", nullptr, ui::menu_kind_sub, 0 },
{ "Grid", nullptr, ui::menu_kind_check, 1, false, &g_grid },
{ nullptr, nullptr, ui::menu_kind_separator, 1 },
{ "Light", nullptr, ui::menu_kind_radio, 1, false, nullptr, &g_theme, 0u },
{ "Dark", nullptr, ui::menu_kind_radio, 1, false, nullptr, &g_theme, 1u },
};
static const ui::menu_entry k_edit[] = {
{ "Cut", "Ctrl+X", ui::menu_kind_item, 0 },
{ "Copy", "Ctrl+C", ui::menu_kind_item, 0 },
{ "Paste", "Ctrl+V", ui::menu_kind_item, 0 },
};
static void new_file() {}
static void edit(int32_t) {}
static void bar(ui::ctx* u)
{
// depth zero entries are the menus, the index into k_bar comes back
if (ui::menubar(u, "main", k_bar, 10u) == 1) {
new_file();
}
// the same kind of table under a button and under a right click
edit(ui::dropdown_menu(u, "Edit", k_edit, 3u));
ui::text(u, "canvas");
edit(ui::context_menu(u, k_edit, 3u));
}dropdown_menu, context_menu and menubar wrap a table in one call and return its index. For menubar the depth zero entries are the menus and the index is into the whole list.
dropdown
dropdown_begin(u, label) declares a button and returns true while its menu is open below it. A press opens it, and so do Enter, Space or Down with the button focused. Up opens it on the last item. The trigger carries state_open while the menu is up, see states.
context menu
context_menu_begin(u) hangs a menu on the element declared just before it. A right click over that element opens it at the pointer. With the element focused, the Apps key or Shift+F10 opens it at its bottom left corner. A second right click while it is open closes it.
menubar
menubar_begin(u, label) opens a row, menubar_menu(u, title) declares one title and returns true while its menu is open, and menubar_end closes the row. Every true menubar_menu needs its menu_end.
- Once a menu is open, moving the pointer onto another title opens that one.
- Left and Right on a title walk the row. Inside an open menu, Right on an item without a submenu opens the next menu, and Left in the top level opens the one before.
- Only one title is in the tab order, the one last focused.
- A bar holds 16 menus. More are left out with a warning.
select
select(u, label, items, count, &index) is a listbox over the engine and returns true when index changed. Its list opens scrolled so the chosen row sits in view. For your own rows, select_begin(u, label, shown) draws the trigger with shown on it and returns true while the list is open. Declare select_item(u, label, option, &value) for each row, then select_end.
- The trigger wears
role_combowith a bars mark. The list is at least as wide as the trigger and opens on the current item. - A closed, focused select jumps to the next item starting with the letters typed, with the same one second reset.
navigation menu
A row of links and triggers whose panels hold richer links, as on a site header. It keeps its own state and does not use the menu engine.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
enum page : uint32_t { page_home, page_docs, page_kit, page_blog };
static void site_nav(ui::ctx* u, uint32_t* at)
{
if (!ui::navigation_menu_begin(u, "site")) {
return;
}
if (ui::navigation_link(u, "Home", *at == page_home)) {
*at = page_home;
}
// a trigger whose panel opens on hover, a click or enter
if (ui::navigation_item_begin(u, "Learn")) {
if (ui::navigation_panel_link(u, "Docs", "guides and reference")) {
*at = page_docs;
}
if (ui::navigation_panel_link(u, "Kit", "every component")) {
*at = page_kit;
}
ui::navigation_item_end(u);
}
if (ui::navigation_link(u, "Blog", *at == page_blog)) {
*at = page_blog;
}
ui::navigation_menu_end(u);
}navigation_menu_begin(u, label)opens the row andnavigation_menu_endcloses it. A press outside the row and the open panel shuts the panel.navigation_link(u, title, active)is a top level link, checked whileactive, true when followed by a click, Enter or Space.navigation_item_begin(u, title)is a trigger with a chevron, true while its panel is open. Pair it withnavigation_item_end. The panel opens after a 0.2 second rest, on a press, or on Enter, Space or Down, which also focuses its first link. Moving to another trigger switches at once, and the panel closes 0.3 seconds after the pointer leaves it. The panel and its links fade in over 100 ms.navigation_panel_link(u, title, description)is a titled row inside a panel with an optional two line description. Following it closes the panel.- Up on an open trigger or Escape closes the panel. Escape inside a panel also sends focus back to its trigger.
- The row is one tab stop and Left and Right walk it, wrapping round. It holds 16 entries, more are left out with a warning.
Right to left
In a right to left box every menu reads Left and Right along the reading direction, so the arrow toward the start always walks back. A submenu opens toward the end of its row, which is on the left, and the physical Left key opens it. Menubars, the navigation menu and a message box's buttons walk the same way. See direction and bidi.
kit.conf line. An app that never calls one links none of its code.