Home /Modules/gui/MENUS.md

MENUS.md

lib/gui/MENUS.md · 121 line(s) · markdown

SLeeLa GUI Menu Contract

Scope

SLGuiMenuBar, SLGuiMenu, and SLGuiMenuItem are toolkit-neutral menu state models available in version-mual, version-gual, version-thual, version-dual, and version-military.

Widget Vocabulary

The factories use existing uiBox, uiButton, and uiSeparator primitives. The menu and menu-bar tags are recognized as container surfaces; menuitem/menu-item tags are included in host activation polling and raise the ordinary CLICK event through SLGuiHostAdapter. This is the portable custom-widget fallback; native OS menu rendering still requires the Java/native host to implement the corresponding bridge behavior.

Model Responsibilities

A menu item is activatable only if enabled, not a separator, and configured with a non-empty action name. The host/runtime should consume takeActivation() once and dispatch the item’s named action/operation through the existing action system. Menu model state does not itself execute arbitrary operations.

Backend Capability

SLGuiBackend.supportsNativeMenus() returns true for JavaFX (javafx/fx) and the native backend. It is an eligibility/capability signal, not proof that a given host binary currently renders native menus. Swing and any host without native menu integration must use the custom-widget fallback.

Interaction Contract

The shared SLGuiMenuBar model in all five GUI versions exposes the same controller-level state transitions:

These methods are toolkit-neutral state transitions. They do not manufacture pointer coordinates or keyboard events; the host must call them from real input events. This keeps the model testable and avoids inventing a premature OFFCLICK event type. Existing CLICK remains the normal activation event.

Integration Checklist

  1. Mount the menu bar above the window content and preserve menu ordering.
  2. Keep exactly one active top-level popup per menu bar.
  3. Route pointer activation and Enter/Space through the same named-action latch.
  4. Send outside-click classification to the menu controller once per pointer event, using the combined bar-and-popup bounds.
  5. Support Escape dismissal, arrow-key navigation, and focus restoration.
  6. Close menus after successful ordinary activation; preserve checked state for checkable items.
  7. Render disabled entries and separators distinctly and expose accessible names/roles.
  8. If native menus are unavailable, render the same model with custom widgets.
  9. Do not execute the operation string as code; resolve it through the application's registered action table.
  10. Test the same behavior on each supported host/backend before claiming native menus are complete.

Visual Quality Baseline

The five SLGuiTheme definitions now expose shared menu depth tokens and accessors. These define the intended design language; a host renderer must consume them before the effect is visible. Native and Java hosts should be verified separately, and unsupported effects should degrade cleanly to a clear border and hover/focus state.

Host Activation Status

The factories recognize menu surfaces as containers. menuitem and menu-item are included in SLGuiWidgetFactory.interactive() and map to CLICK, so the existing SLGuiHostAdapter polls their activation latches and dispatches the same DOM event type as ordinary buttons. The military command-console example and the dedicated menu showcase both demonstrate visible, collapsible dropdown panels backed by the ui* widget bridge.

Limits

The SLeeLa library models now provide explicit toggle, outside-dismissal, Escape, activation-dismissal, and top-level navigation state transitions. These are not by themselves proof that every host wires those transitions to real native pointer/keyboard input. Native OS menu widgets, popup positioning, full keyboard event routing, outside-click dismissal, resolution of the model's named action/operation fields, and accessibility semantics remain host/runtime integration responsibilities and must be tested in each backend before being described as complete.