Enum bevy_ui_navigation::NavMenu

#[non_exhaustive]
pub enum NavMenu {
    Bound2d,
    Wrapping2d,
    BoundScope,
    WrappingScope,
}

A menu that isolate children Focusables from other focusables and specify navigation method within itself.

Usage

A NavMenu can be used to:

• Prevent navigation from one specific submenu to another
• Specify if 2d navigation wraps around the screen, see NavMenu::Wrapping2d.
• Specify “scope menus” such that a NavRequest::ScopeMove emitted when the focused element is a Focusable nested within this NavMenu will navigate this menu. See NavMenu::BoundScope and NavMenu::WrappingScope.
• Specify submenus and specify from where those submenus are reachable.
• Add a specific component to all Focusables in this menu. You must first create a “seed” bundle with any of the NavMenu methods and then call marking on it.
• Specify which entity will be the parents of this NavMenu, see NavMenu::reachable_from or NavMenu::reachable_from_named if you don’t have access to the Entity for the parent Focusable

If you want to specify which Focusable should be focused first when entering a menu, you should mark one of the children of this menu with Focusable::dormant.

Example

See the example in this crate’s root level documentation page.

Invariants

You need to follow those rules (invariants) to avoid panics:

1. A Menu must have at least one Focusable child in the UI hierarchy.
2. There must not be a menu loop. Ie: a way to go from menu A to menu B and then from menu B to menu A while never going back.
3. Focusables in 2d menus must have a GlobalTransform.

Panics

Thankfully, programming errors are caught early and you’ll probably get a panic fairly quickly if you don’t follow the invariants.

• Invariant (1) panics as soon as you add the menu without focusable children.
• Invariant (2) panics if the focus goes into a menu loop.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Bound2d

Non-wrapping menu with 2d navigation.

It is possible to move around this menu in all cardinal directions, the focus changes according to the physical position of the Focusable in it.

If the player moves to a direction where there aren’t any focusables, nothing will happen.

Wrapping2d

Wrapping menu with 2d navigation.

It is possible to move around this menu in all cardinal directions, the focus changes according to the physical position of the Focusable in it.

If the player moves to a direction where there aren’t any focusables, the focus will “wrap” to the other direction of the screen.

BoundScope

Non-wrapping scope menu

Controlled with NavRequest::ScopeMove even when the focused element is not in this menu, but in a submenu reachable from this one.

WrappingScope

Wrapping scope menu

Controlled with NavRequest::ScopeMove even when the focused element is not in this menu, but in a submenu reachable from this one.

Implementations

impl NavMenu

pub fn with_parent(self, focus_parent: Option<Entity>) -> MenuSeed

Spawn a NavMenu seed with provided parent entity (or root if None).

Prefer Self::reachable_from and Self::root to this if you don’t already have an Option<Entity>.

pub fn root(self) -> MenuSeed

Spawn this menu with no parents.

No Focusable will “lead to” this menu. You either need to programmatically give focus to this menu tree with NavRequest::FocusOn or have only one root menu.

pub fn reachable_from(self, focusable: Entity) -> MenuSeed

Spawn this menu as reachable from a given Focusable

When requesting NavRequest::Action when focusable is focused, the focus will be changed to a focusable within this menu.

Important

You must ensure this doesn’t create a cycle. Eg: you shouldn’t be able to reach NavMenu X from Focusable Y if there is a path from NavMenu X to Focusable Y.

pub fn reachable_from_named(
    self,
    parent_label: impl Into<Cow<'static, str>>
) -> NamedMenuSeed

Spawn this menu as reachable from a Focusable with a Name component.

This is useful if, for example, you just want to spawn your UI without keeping track of entity ids of buttons that leads to submenus.

Trait Implementations

impl Clone for NavMenu

fn clone(&self) -> NavMenu

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NavMenu

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<NavMenu> for NavMenu

fn eq(&self, other: &NavMenu) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Copy for NavMenu

impl StructuralPartialEq for NavMenu