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

A bottom bar of destinations (icon, label, optional badge) of which exactly one is selected. More...

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

Inheritance diagram for guillaume::entities::NavigationBar:
Collaboration diagram for guillaume::entities::NavigationBar:

Classes

class  Builder
 Configures a NavigationBar, creates it and registers it in an entity registry. More...

Public Types

using Variant = components::NavigationBar::Variant
using Destination = components::NavigationBar::Destination
Public Types inherited from guillaume::entities::SurfaceBase< components::SelectionGroup, components::NavigationBar >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~NavigationBar (void) override
 Default destructor.
NavigationBar & setVariant (Variant variant)
 Change the variant. Restyles at once.
Variant getVariant (void) const
 Get the variant.
NavigationBar & addDestination (const std::string &iconGlyph, const std::string &label)
 Append a destination without focused icon or badge.
NavigationBar & addDestination (const Destination &destination)
 Append a destination.
NavigationBar & setBadge (std::size_t index, const std::string &badge)
 Change the badge label of a destination.
NavigationBar & setOnIndexChange (std::function< void(std::size_t)> onIndexChange)
 Set the handler called when the user selects another destination (Paper onIndexChange).
NavigationBar & setOnTabPress (std::function< void(std::size_t)> onTabPress)
 Set the handler called on every destination press, even on the selected one (Paper onTabPress).
ecs::Entity::Identifier getIndicatorIdentifier (std::size_t index) const
 Get the active-indicator pill of a destination: the rounded shape behind the icon.
ecs::Entity::Identifier getIconIdentifier (std::size_t index) const
 Get the icon entity of a destination.
ecs::Entity::Identifier getLabelIdentifier (std::size_t index) const
 Get the label entity of a destination.
ecs::Entity::Identifier getBadgeIdentifier (std::size_t index) const
 Get the badge entity of a destination.
NavigationBar & select (std::size_t index)
 Select a destination and deselect the others.
std::size_t getSelectedIndex (void) const
 Get the index of the selected destination.
std::size_t getDestinationCount (void) const
 Get the number of destinations.
ecs::Entity::Identifier getDestinationIdentifier (std::size_t index) const
 Get the child entity of a destination: the pressable area holding its indicator, icon and label.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::SelectionGroup, components::NavigationBar >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< NavigationBar > create (Arguments &&...arguments)
 Create a navigation bar and its destination children, without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::SelectionGroup, components::NavigationBar >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A bottom bar of destinations (icon, label, optional badge) of which exactly one is selected.

Its state lives in components::NavigationBar (variant, destination data, destination child identifiers, callbacks); systems::NavigationBar colors the bar, sizes the destinations and places them in a row each frame, in the Layout phase. Which destination is selected is stored in the components::Selectable of each destination child; the bar's components::SelectionGroup keeps the selection single and never empty. The class itself holds no field.

getEntityRegistry());
auto bar = builder
.withOnIndexChange([](std::size_t index) {
// called when the user selects another destination
})
.makeNavigationBar(parent, NavigationBar::Variant::WithLabels,
{ { "home", "Home" }, { "settings", "Settings" } });
bar->setBadge(1, "3");
Configures a NavigationBar, creates it and registers it in an entity registry.

NavigationBar::create(registry, config, variant, destinations, onIndexChange) builds the same widget without registering it in an entity registry.

Things to know:

  • Indexes are positions in the order the destinations were added, starting at 0. The first destination is selected at creation.
  • select() does not call the index-change handler; only a press by the user on another destination does.
  • addDestination() selects the first destination again.
  • The bar is the entity registry that owns its destination children (detail::BarDestination). Destinations are only appended: the identifiers returned by the getters stay valid.
  • The Builder gives the bar 360 dp by components::NavigationBar::Height (80 dp). The destinations share the width equally; their size and the bar's color and layout children are overwritten each frame.
  • With Variant::WithoutLabels, only the selected destination shows its label.
See also
components::NavigationBar, systems::NavigationBar, NavigationDrawer

Definition at line 94 of file navigation_bar.hpp.

Member Typedef Documentation

◆ Destination

One destination: icon glyph name, label, glyph name of the icon shown while selected, badge label.

Definition at line 105 of file navigation_bar.hpp.

◆ Variant

Variant: WithLabels shows every label, WithoutLabels only the label of the selected destination.

Definition at line 101 of file navigation_bar.hpp.

Constructor & Destructor Documentation

◆ ~NavigationBar()

guillaume::entities::NavigationBar::~NavigationBar ( void )
override

Default destructor.

Definition at line 192 of file navigation_bar.cpp.

Member Function Documentation

◆ addDestination() [1/2]

NavigationBar & guillaume::entities::NavigationBar::addDestination ( const Destination & destination)

Append a destination.

Builds the child entity of the new destination, selects the first destination of the bar again and restyles at once. The children of the existing destinations are kept.

Parameters
destinationThe icon, label, focused icon and badge of the new destination.
Returns
This bar, for chaining.

Definition at line 260 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ addDestination() [2/2]

NavigationBar & guillaume::entities::NavigationBar::addDestination ( const std::string & iconGlyph,
const std::string & label )

Append a destination without focused icon or badge.

Same effects as the overload taking a Destination.

Parameters
iconGlyphThe glyph name of the icon.
labelThe text shown under the icon.
Returns
This bar, for chaining.

Definition at line 254 of file navigation_bar.cpp.

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

◆ create()

template<typename... Arguments>
std::shared_ptr< NavigationBar > guillaume::entities::NavigationBar::create ( Arguments &&... arguments)
inlinestatic

Create a navigation bar and its destination children, without registering it in an entity registry.

The constructors are private because the children need the bar to be owned by a shared pointer before they can take it as parent; create() constructs the bar, builds one child per destination and selects the first one.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsForwarded to a private constructor: either (registry, config, variant, destinations, onIndexChange) with Destination values, or (registry, config, variant, destinations) with (icon glyph name, label) pairs.
Returns
The new navigation bar.

Definition at line 237 of file navigation_bar.hpp.

Here is the caller graph for this function:

◆ getBadgeIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationBar::getBadgeIdentifier ( std::size_t index) const

Get the badge entity of a destination.

Parameters
indexThe index of the destination.
Returns
The identifier of the badge, or ecs::Entity::InvalidIdentifier when index is out of range or the destination never had a badge label.

Definition at line 374 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getDestinationCount()

std::size_t guillaume::entities::NavigationBar::getDestinationCount ( void ) const

Get the number of destinations.

Returns
How many destinations the bar has.

Definition at line 329 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getDestinationIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationBar::getDestinationIdentifier ( std::size_t index) const

Get the child entity of a destination: the pressable area holding its indicator, icon and label.

Parameters
indexThe index of the destination.
Returns
The identifier of the destination entity, or ecs::Entity::InvalidIdentifier when index is out of range.

Definition at line 338 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getIconIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationBar::getIconIdentifier ( std::size_t index) const

Get the icon entity of a destination.

Parameters
indexThe index of the destination.
Returns
The identifier of the icon, or ecs::Entity::InvalidIdentifier when index is out of range or the destination has no icon.

Definition at line 358 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getIndicatorIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationBar::getIndicatorIdentifier ( std::size_t index) const

Get the active-indicator pill of a destination: the rounded shape behind the icon.

Parameters
indexThe index of the destination.
Returns
The identifier of the pill, or ecs::Entity::InvalidIdentifier when index is out of range.

Definition at line 350 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getLabelIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationBar::getLabelIdentifier ( std::size_t index) const

Get the label entity of a destination.

Parameters
indexThe index of the destination.
Returns
The identifier of the label text, or ecs::Entity::InvalidIdentifier when index is out of range or the destination has no label.

Definition at line 366 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getSelectedIndex()

std::size_t guillaume::entities::NavigationBar::getSelectedIndex ( void ) const

Get the index of the selected destination.

Returns
The index of the selected destination, or 0 when the bar has no destination.

Definition at line 323 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getVariant()

NavigationBar::Variant guillaume::entities::NavigationBar::getVariant ( void ) const

Get the variant.

Returns
The variant stored in components::NavigationBar.

Definition at line 247 of file navigation_bar.cpp.

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

◆ select()

NavigationBar & guillaume::entities::NavigationBar::select ( std::size_t index)

Select a destination and deselect the others.

Restyles at once. Does not call the index-change handler.

Parameters
indexThe index of the destination to select; nothing happens when it is out of range.
Returns
This bar, for chaining.

Definition at line 316 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setBadge()

NavigationBar & guillaume::entities::NavigationBar::setBadge ( std::size_t index,
const std::string & badge )

Change the badge label of a destination.

Builds the badge child the first time the label is not empty, then restyles the destination at once. An empty label turns an existing badge into a dot; it does not remove it.

Parameters
indexThe index of the destination; nothing happens when it is out of range.
badgeThe badge label.
Returns
This bar, for chaining.

Definition at line 273 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setOnIndexChange()

NavigationBar & guillaume::entities::NavigationBar::setOnIndexChange ( std::function< void(std::size_t)> onIndexChange)

Set the handler called when the user selects another destination (Paper onIndexChange).

Parameters
onIndexChangeCalled with the index of the newly selected destination, after the selection changed. Not called by select() nor when the user presses the selected destination.
Returns
This bar, for chaining.

Definition at line 298 of file navigation_bar.cpp.

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

◆ setOnTabPress()

NavigationBar & guillaume::entities::NavigationBar::setOnTabPress ( std::function< void(std::size_t)> onTabPress)

Set the handler called on every destination press, even on the selected one (Paper onTabPress).

Parameters
onTabPressCalled with the index of the pressed destination, before the selection changes.
Returns
This bar, for chaining.

Definition at line 307 of file navigation_bar.cpp.

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

◆ setVariant()

NavigationBar & guillaume::entities::NavigationBar::setVariant ( Variant variant)

Change the variant. Restyles at once.

Parameters
variantWithLabels to show every label, WithoutLabels to show only the label of the selected destination.
Returns
This bar, for chaining.

Definition at line 238 of file navigation_bar.cpp.

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

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