Skip to main content

UI Stacks 101 — How Menus Work (Common UI)

This project uses Common UI’s Activatable Widgets and Stacks.
You never destroy menus while navigating — you push them onto a stack and deactivate (or pop) them when leaving. This preserves input, back navigation, and animations.

This project centralizes UI navigation in CUI_BaseStack, which has three Common UI stacks:​

  • BaseStack — primary “screen” navigation (Main, Options, Pause, etc.)
  • OverlayStack — lightweight overlays (rarely used in this template)
  • ModalStack — confirm dialogs (Yes/No)

Menus are pushed to stacks and deactivated (or popped) when leaving. Do not call RemoveFromParent on stack-managed screens.

When to use each stack​

  • BaseStack (Main)

    • Full-screen screens and flows.
    • Example: Main Menu → Options → Controls.

  • OverlayStack

    • Short-lived HUD overlays, toasts, tips.
    • Not used in any provided content.

  • ModalStack

    • Blocking confirmations.
    • Example: “Apply changes?” [Yes/No].

Function Library: PushToMainStack​

Purpose: Ensure the BaseStack exists (create if missing), re-activate it (if inactive), then push the given widget onto it.

Behavior

  1. If CUI_BaseStack is not present, create/spawn it and add to screen.
  2. If BaseStack exists but is inactive, Activate it.
  3. Push the provided widget onto BaseStack (it becomes the active screen).

Inputs

  • Widget — an instance of your CommonActivatableWidget screen.

Outputs

  • OutWidget — Common Activatable Widget object the pushed widget instance.
  • Success — bool true if pushed.