mini_arcade_core.ui.menu ======================== .. py:module:: mini_arcade_core.ui.menu .. autoapi-nested-parse:: Menu system for mini arcade core. Classes ------- .. autoapisummary:: mini_arcade_core.ui.menu.MenuItem mini_arcade_core.ui.menu.MenuStyle mini_arcade_core.ui.menu.Menu mini_arcade_core.ui.menu.MenuWorld mini_arcade_core.ui.menu.MenuIntent mini_arcade_core.ui.menu.MenuTickContext mini_arcade_core.ui.menu.MenuInputSystem mini_arcade_core.ui.menu.MenuNavigationSystem mini_arcade_core.ui.menu.MenuActionSystem mini_arcade_core.ui.menu.MenuRenderSystem mini_arcade_core.ui.menu.BaseMenuScene Module Contents --------------- .. py:class:: MenuItem Represents a single item in a menu. :ivar label (str): The text label of the menu item. :ivar on_select (BaseCommand): The action to perform when the item is selected. .. py:attribute:: id :type: str .. py:attribute:: label :type: str .. py:attribute:: command_factory :type: Callable[[], mini_arcade_core.engine.commands.Command] .. py:attribute:: label_fn :type: Optional[Callable[[object], str]] :value: None .. py:method:: resolved_label(ctx: object) -> str Get the resolved label for this menu item. :param ctx: The current ctx instance. :type ctx: object :return: The resolved label string. :rtype: str .. py:class:: MenuStyle Styling options for the Menu. :ivar normal (Color): Color for unselected items. :ivar selected (Color): Color for the selected item. :ivar line_height (int): Vertical spacing between items. :ivar title_color (Color): Color for the title text. :ivar title_spacing (int): Vertical space between title and first item. :ivar title_margin_bottom (int): Additional margin below the title. :ivar background_color (Color | None): Solid background color for the menu. :ivar overlay_color (Color | None): Full-screen overlay color. :ivar panel_color (Color | None): Color for the panel behind content. :ivar panel_padding_x (int): Horizontal padding inside the panel. :ivar panel_padding_y (int): Vertical padding inside the panel. :ivar button_enabled (bool): Whether to render items as buttons. :ivar button_fill (Color): Fill color for buttons. :ivar button_border (Color): Border color for buttons. :ivar button_selected_border (Color): Border color for the selected button. :ivar button_width (int | None): Fixed width for buttons, or None for auto-fit. :ivar button_height (int): Fixed height for buttons. :ivar button_gap (int): Vertical gap between buttons. :ivar button_padding_x (int): Horizontal padding inside buttons. :ivar hint (str | None): Optional hint text to display at the bottom. :ivar hint_color (Color): Color for the hint text. :ivar hint_margin_bottom (int): Additional margin below the hint text. :ivar title_font_size (int): Font size for the title text. :ivar hint_font_size (int): Font size for the hint text. :ivar item_font_size (int): Font size for the menu items. .. py:attribute:: normal :type: mini_arcade_core.backend.types.Color :value: (220, 220, 220) .. py:attribute:: selected :type: mini_arcade_core.backend.types.Color :value: (255, 255, 0) .. py:attribute:: line_height :type: int :value: 28 .. py:attribute:: title_color :type: mini_arcade_core.backend.types.Color :value: (255, 255, 255) .. py:attribute:: title_spacing :type: int :value: 18 .. py:attribute:: title_margin_bottom :type: int :value: 20 .. py:attribute:: background_color :type: mini_arcade_core.backend.types.Color | None :value: None .. py:attribute:: overlay_color :type: mini_arcade_core.backend.types.Color | None :value: None .. py:attribute:: panel_color :type: mini_arcade_core.backend.types.Color | None :value: None .. py:attribute:: panel_padding_x :type: int :value: 24 .. py:attribute:: panel_padding_y :type: int :value: 18 .. py:attribute:: button_enabled :type: bool :value: False .. py:attribute:: button_fill :type: mini_arcade_core.backend.types.Color :value: (30, 30, 30, 1.0) .. py:attribute:: button_border :type: mini_arcade_core.backend.types.Color :value: (120, 120, 120, 1.0) .. py:attribute:: button_selected_border :type: mini_arcade_core.backend.types.Color :value: (255, 255, 0, 1.0) .. py:attribute:: button_width :type: int | None :value: None .. py:attribute:: button_height :type: int :value: 40 .. py:attribute:: button_gap :type: int :value: 20 .. py:attribute:: button_padding_x :type: int :value: 20 .. py:attribute:: hint :type: str | None :value: None .. py:attribute:: hint_color :type: mini_arcade_core.backend.types.Color :value: (200, 200, 200) .. py:attribute:: hint_margin_bottom :type: int :value: 50 .. py:attribute:: title_font_size :value: 44 .. py:attribute:: hint_font_size :value: 14 .. py:attribute:: item_font_size :value: 24 .. py:class:: Menu(items: Sequence[MenuItem], *, viewport: tuple[int, int] | None = None, title: str | None = None, style: MenuStyle | None = None, on_select: Optional[Callable[[MenuItem], None]] = None) A simple text-based menu system. .. py:attribute:: items .. py:attribute:: viewport :value: None .. py:attribute:: title :value: None .. py:attribute:: style .. py:attribute:: selected_index :value: 0 .. py:attribute:: stable_width :value: True .. py:method:: set_items(items: Sequence[MenuItem]) Set the menu items. :param items: Sequence of new MenuItem instances. :type items: Sequence[MenuItem] .. py:method:: set_selected_index(index: int) Set the selected index of the menu. :param index: New selected index. :type index: int .. py:method:: set_labels(labels: Sequence[str]) Set the labels of the menu items. :param labels: Sequence of new labels for the menu items. :type labels: Sequence[str] .. py:method:: move_up() Move the selection up by one item, wrapping around if necessary. .. py:method:: move_down() Move the selection down by one item, wrapping around if necessary. .. py:method:: select() Select the currently highlighted item, invoking its action. .. py:method:: handle_event(event: mini_arcade_core.backend.events.Event, *, up_key: int, down_key: int, select_key: int) -> bool Handle an input event to navigate the menu. :param event: The input event to handle. :type event: Event :param up_key: Key code for moving selection up. type up_key: int :param down_key: Key code for moving selection down. :type down_key: int :param select_key: Key code for selecting the current item. :type select_key: int .. py:method:: draw(surface: mini_arcade_core.backend.Backend) Draw the menu onto the given backend surface. :param surface: The backend surface to draw on. :type surface: Backend .. py:method:: set_viewport(viewport: tuple[int, int]) Set the viewport size for the menu. :param viewport: New viewport size. :type viewport: tuple[int, int] .. py:class:: MenuWorld Bases: :py:obj:`mini_arcade_core.scenes.sim_scene.BaseWorld` Data model for menu scenes. :ivar selected (int): Currently selected menu item index. :ivar move_cooldown (float): Cooldown time between menu moves. :ivar _cooldown_timer (float): Internal timer for move cooldown. .. py:attribute:: entities :type: list :value: [] .. py:attribute:: selected :type: int :value: 0 .. py:attribute:: move_cooldown :type: float :value: 0.12 .. py:method:: step_timer(dt: float) Step the internal cooldown timer. :param dt: Delta time since last update. :type dt: float .. py:method:: can_move() -> bool Check if the menu can move selection (cooldown elapsed). :return: True if movement is allowed, False otherwise. :rtype: bool .. py:method:: consume_move() Consume a move action and reset the cooldown timer. .. py:class:: MenuIntent Bases: :py:obj:`mini_arcade_core.scenes.sim_scene.BaseIntent` Represents the user's intent in the menu for the current tick. :ivar move_up (bool): Whether the user intends to move up. :ivar move_down (bool): Whether the user intends to move down. :ivar select (bool): Whether the user intends to select the current item. :ivar quit (bool): Whether the user intends to quit the menu. .. py:attribute:: move_up :type: bool :value: False .. py:attribute:: move_down :type: bool :value: False .. py:attribute:: select :type: bool :value: False .. py:attribute:: quit :type: bool :value: False .. py:class:: MenuTickContext Bases: :py:obj:`mini_arcade_core.scenes.sim_scene.BaseTickContext`\ [\ :py:obj:`MenuWorld`\ , :py:obj:`MenuIntent`\ ] Context for a single tick of the menu scene. :ivar input_frame (InputFrame): The current input frame. :ivar dt (float): Delta time since last tick. :ivar menu (Menu): The Menu instance. :ivar model (MenuWorld): The MenuWorld instance. :ivar commands (CommandQueue): The command queue for pushing commands. :ivar intent (MenuIntent | None): The current menu intent. :ivar quit_cmd_factory (callable | None): Factory for quit command. :ivar packet (RenderPacket | None): The resulting render packet. .. py:attribute:: menu :type: Menu | None :value: None .. py:attribute:: quit_cmd_factory :type: callable | None :value: None .. py:class:: MenuInputSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.builtins.InputIntentSystem` Converts InputFrame -> MenuIntent. .. py:attribute:: name :type: str :value: 'menu_input' .. py:method:: build_intent(ctx: MenuTickContext) Build the intent .. py:class:: MenuNavigationSystem Menu navigation system. .. py:attribute:: name :type: str :value: 'menu_nav' .. py:attribute:: order :type: int :value: 20 .. py:method:: step(ctx: MenuTickContext) Update menu selection based on intent. .. py:class:: MenuActionSystem Menu action execution system. .. py:attribute:: name :type: str :value: 'menu_actions' .. py:attribute:: order :type: int :value: 30 .. py:method:: step(ctx: MenuTickContext) Execute actions based on menu intent. .. py:class:: MenuRenderSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.builtins.BaseQueuedRenderSystem`\ [\ :py:obj:`MenuTickContext`\ ] Menu rendering system. .. py:attribute:: name :type: str :value: 'menu_render' .. py:attribute:: merge_existing_draw_ops :type: bool :value: False .. py:method:: emit(ctx: MenuTickContext, rq) Emit draw calls into the render queue. :param ctx: The tick context containing world state and other info. :type ctx: BaseTickContext :param rq: The render queue to emit draw calls into. :type rq: RenderQueue .. py:class:: BaseMenuScene(ctx: mini_arcade_core.runtime.context.RuntimeContext) Bases: :py:obj:`mini_arcade_core.scenes.sim_scene.SimScene`\ [\ :py:obj:`MenuTickContext`\ , :py:obj:`MenuWorld`\ ] Base scene class for menu-based scenes. :ivar world (MenuWorld): The data model for the menu scene. .. py:attribute:: menu :type: Menu .. py:method:: on_enter() Called when the scene becomes active (safe place to create world & add systems). .. py:property:: menu_title :type: str | None Get the title of the menu. :return: The menu title string, or None for no title. :rtype: str | None .. py:method:: menu_style() -> MenuStyle Get the style configuration for the menu. :return: The MenuStyle instance for styling the menu. :rtype: MenuStyle .. py:method:: menu_items() -> list[MenuItem] :abstractmethod: Get the list of menu items for the menu. :return: List of MenuItem instances for the menu. :rtype: list[MenuItem] .. py:method:: quit_command() Get the command to execute when quitting the menu. :return: The command to execute on quit. :rtype: Command .. py:method:: menu_viewport() -> tuple[int, int] Get the viewport size for the menu. :return: The viewport size tuple (width, height). :rtype: tuple[int, int]