guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::systems::NavigationBar Class Reference

Styles a navigation bar, shares its width between its destinations and keeps exactly one of them selected. More...

#include <headers/guillaume/systems/navigation_bar.hpp>

Inheritance diagram for guillaume::systems::NavigationBar:
Collaboration diagram for guillaume::systems::NavigationBar:

Public Member Functions

 NavigationBar (void)
 Create the system in the Layout phase.
 ~NavigationBar (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one navigation bar; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::NavigationBar >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Connect a navigation bar to its destinations.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Color the bar, size and style its destinations and place them in a row.
static void select (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Select a destination from code.
static void press (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Activate a destination as a press on it would.
static void destinationSelected (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 React to a destination that became selected without going through the bar.
static void setBadge (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, const std::string &badge)
 Set the badge of a destination and restyle that destination.
static std::size_t selectedIndex (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the index of the selected destination.

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
bool requireComponent (const ecs::Entity::Identifier &entityIdentifier)
 Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.

Detailed Description

Styles a navigation bar, shares its width between its destinations and keeps exactly one of them selected.

Runs in the Layout phase on every entity that has a components::NavigationBar. It is registered after systems::NavigationBarDestination, so each destination has been styled on its own before the bar sizes and places it.

Destinations are named by their index in components::NavigationBar::getDestinationEntities, starting at 0. A child without a components::NavigationBarDestination is placed in the row but otherwise ignored.

The bar is 80 dp high (components::NavigationBar::Height). With the WithLabels variant every destination shows its label; with the other variant only the selected one does.

systems::NavigationBar::select(registry, bar, 1); // no callback
systems::NavigationBar::press(registry, bar, 2); // as a click would
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Connect a navigation bar to its destinations.
static void press(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Activate a destination as a press on it would.
static void select(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Select a destination from code.
See also
components::NavigationBar, systems::NavigationBarDestination, systems::Selection, entities::NavigationBar

Definition at line 72 of file navigation_bar.hpp.

Constructor & Destructor Documentation

◆ NavigationBar()

guillaume::systems::NavigationBar::NavigationBar ( void )

Create the system in the Layout phase.

Definition at line 59 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::NavigationBar::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Color the bar, size and style its destinations and place them in a row.

This is what update() runs each frame. Call it directly after changing components::NavigationBar to see the result before the next frame, which is what the setters of entities::NavigationBar do.

The width of the bar minus its padding is divided equally between the destinations. The width used is the fixed width of the bar's components::Layout when it has one, otherwise the width of its components::Bound.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::NavigationBar, Color or Layout.

Definition at line 217 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ destinationSelected()

void guillaume::systems::NavigationBar::destinationSelected ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

React to a destination that became selected without going through the bar.

Called by the selection-changed handler wired by install(), for instance when code selects the components::Selectable of a destination directly. Deselects the other destinations and restyles the bar. Does nothing while select() is itself changing the selection, which is what keeps the two from calling each other for ever.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
indexIndex of the destination that became selected. An index past the end is ignored.

Definition at line 153 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ install()

void guillaume::systems::NavigationBar::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Connect a navigation bar to its destinations.

Forbids an empty selection in the bar's components::SelectionGroup, gives the bar the TabList accessibility role (adding a components::Accessibility when it has none), and for every destination recorded in components::NavigationBar replaces its press callback with a call to press() and its selection-changed handler with a call to destinationSelected(). The handlers capture the index of the destination, so call install() again each time the destination children change.

Parameters
componentRegistryThe registry holding the components. It is captured by the handlers and must outlive the entity.
entityIdentifierThe navigation bar entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity has no components::NavigationBar or components::SelectionGroup.

Definition at line 64 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ press()

void guillaume::systems::NavigationBar::press ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Activate a destination as a press on it would.

In this order: calls the press callback of components::NavigationBar with the index, selects the destination, then calls the index-change callback when the selected index is different from the one before the press. The press callback is therefore also called when the user presses the destination that is already selected.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
indexIndex of the pressed destination. An index past the end is ignored and no callback is called.

Definition at line 166 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ select()

void guillaume::systems::NavigationBar::select ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Select a destination from code.

Selects the destination, deselects the others and restyles the bar. Neither the press callback nor the index-change callback is called: use press() to behave as the user would.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
indexIndex of the destination to select. An index past the end is ignored.

Definition at line 131 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ selectedIndex()

std::size_t guillaume::systems::NavigationBar::selectedIndex ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the index of the selected destination.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
Returns
The index of the first destination whose components::Selectable is selected. Also 0 when no destination is selected, so 0 alone does not prove that the first one is.

Definition at line 113 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setBadge()

void guillaume::systems::NavigationBar::setBadge ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
const std::string & badge )
static

Set the badge of a destination and restyle that destination.

Stores the label in components::NavigationBar and forwards it to systems::NavigationBarDestination::setBadge.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation bar entity.
indexIndex of the destination. An index past the end is ignored.
badgeThe text shown in the badge, such as a count. An empty string shows a dot.

Definition at line 201 of file navigation_bar.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::NavigationBar::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Run apply() on one navigation bar; called by the frame loop.

Logs a warning and does nothing when the entity has no components::NavigationBar.

Parameters
entityIdentifierThe navigation bar entity.

Implements guillaume::ecs::System.

Definition at line 277 of file navigation_bar.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: