Guide API
Skip to main content

Module menu_session

Module menu_session 

Source
Expand description

The interactive menu layer — opening, navigating, and selecting menus — driven by one MenuSession capture handler on the single event loop.

§The architecture

Opening a submenu would normally nest one modal loop per open box. Here there is a single event loop, so one MenuSession capture handler owns the WHOLE open stack (bar + every open box) and runs the interaction as one flat loop rather than recursion. While the session is on the capture stack it consumes every menu-directed event: the bar and boxes only draw and report item geometry — they are never focused and carry no event logic of their own.

§State

The session holds a stack of levels (MenuLevel), one per open bar/box, each carrying its view_id, a clone of its menu, its current highlight index, its bounds (cached at open — a box never moves), and an is_bar flag (a bar is one row, a box a vertical column). Cloning the menu at open freezes its disabled flags for the menu’s lifetime — the session swallows command-set-changed broadcasts while active, so regray does not reach an open menu. The top of the stack is the active level; a parent level is suspended. Cross-level mouse hit-testing gates against the cached per-level bounds.

Behavioral note (a consequence of cloning at open): writing the chosen item back as the level’s default lands on the level’s clone, which is discarded when the session closes — so the bar’s permanent Menu::default is NOT updated, and a later re-activation restarts on the original default rather than the last-selected item. This is inert within a session (a closed box is only reopened by re-cloning through the bar), the same trade-off as the disabled-freezing above. Persisting the default would write the chosen index back to the bar’s real menu on close, via a deferred request mirroring the existing highlight write.

§Keyboard

The keyboard arms cover Up/Down/Left/Right/Home/End/Enter/Esc plus a character / hotkey arm. Choosing a submenu pushes a level; choosing a command ends the session and posts the command; Esc or Left close levels.

§Mouse

The mouse arms cover press/release/move plus item tracking and the parent-level hit gates, with per-level transient flags for the “last opened title”, “mouse has landed on an item”, and “first event of this level”. Keyboard and mouse share one re-apply run loop tail (set highlight → reset the last-opened marker → open gate → command result → pop / re-apply). The open gate re-applies the triggering mouse event into the freshly-opened child; the child-pop records the parent’s last-opened title and default (the “click an open title to close it” mechanism). The bar’s mouse-down activation lives in menu_view::handle_event (activate_mouse). The per-session put_click_event_on_exit flag (true for a bar/box, false for a context popup) gates the bottom-level exit-click re-post.

§Context popups

A context popup is a menu box with two observable differences: no default highlight on open (the level starts with nothing highlighted and clears its clone’s Menu::default) and no exit-click re-post (the popup_menu constructor sets put_click_event_on_exit to false). The popup_menu free function builds and runs it (placement via auto_place_popup). A popup needs no extra accelerator handling of its own: it is run modally the instant it opens, so the session already owns the event loop and the flat loop’s hotkey handling covers it (see popup_menu).

Mouse auto-repeat / press-and-hold does not apply to menus.

§Turbo Vision heritage

Flattens TMenuView::execute() and TMenuPopup (tmnuview.cpp, tmenupop.cpp, popupmnu.cpp/menus.h). The nested modal loops (one per open box) become one capture handler on the single event loop (deviation D9).

Structs§

MenuSession
The modal menu interaction, run as one capture handler on the single event loop.

Functions§

activate
Open a menu session from the bar.
activate_mouse
Open a menu session from the bar on a mouse press: push the session, then re-post the click so the session’s press arm processes it.
popup_menu
Open a standalone context popup MenuBox near where_, run as a single-box MenuSession on the capture stack.