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

State of a navigation bar: the bottom strip of three to five destinations that switches between the top-level views of an app. More...

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

Inheritance diagram for guillaume::components::NavigationBar:
Collaboration diagram for guillaume::components::NavigationBar:

Classes

struct  Destination
 Description of one destination, as given by the user. More...

Public Types

enum class  Variant { WithLabels , WithoutLabels }
 Whether every destination shows its label (WithLabels) or only the selected one does (WithoutLabels). More...
using IndexHandler = std::function<void(std::size_t)>
 Callback that receives the index of a destination, starting at 0.

Public Member Functions

 NavigationBar (void)=default
 Create the configuration of a bar with labels and no destination.
 ~NavigationBar (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the label visibility rule.
NavigationBar & setVariant (Variant variant)
 Choose whether every destination shows its label.
const std::vector< Destination > & getDestinations (void) const noexcept
 Get the description of every destination.
NavigationBar & setDestinations (const std::vector< Destination > &destinations)
 Replace the description of every destination.
NavigationBar & addDestination (const Destination &destination)
 Append the description of one destination.
NavigationBar & setDestinationBadge (std::size_t index, const std::string &badge)
 Change the badge text recorded for one destination.
const std::vector< ecs::Entity::Identifier > & getDestinationEntities (void) const noexcept
 Get the destination children.
NavigationBar & setDestinationEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the destination children.
const IndexHandler & getOnIndexChange (void) const noexcept
 Get the callback run when a press changes the selected destination.
NavigationBar & setOnIndexChange (IndexHandler handler)
 Set the callback run when a press changes the selected destination.
const IndexHandler & getOnTabPress (void) const noexcept
 Get the callback run on every destination press.
NavigationBar & setOnTabPress (IndexHandler handler)
 Set the callback run on every destination press.
bool isUpdatingSelection (void) const noexcept
 Tell whether systems::NavigationBar is changing the selection at this moment.
NavigationBar & setUpdatingSelection (bool updating)
 Raise or lower the guard that stops a selection change from triggering another one.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float Height = 80.0f
 Height of the bar, in dp.

Detailed Description

State of a navigation bar: the bottom strip of three to five destinations that switches between the top-level views of an app.

The entities::NavigationBar widget writes it: the destination data, the callbacks, and the identifier of the destination child it builds for each entry. systems::NavigationBar reads it every frame in the Layout phase and turns it into the bar color, the width of each destination, their placement in a row and the visibility of each label.

Which destination is selected is not stored here: it is the components::Selectable of each destination child. Read it with systems::NavigationBar::selectedIndex and change it with systems::NavigationBar::select.

See also
systems::NavigationBar, components::NavigationBarDestination, entities::NavigationBar

Definition at line 55 of file navigation_bar.hpp.

Member Typedef Documentation

◆ IndexHandler

using guillaume::components::NavigationBar::IndexHandler = std::function<void(std::size_t)>

Callback that receives the index of a destination, starting at 0.

Definition at line 83 of file navigation_bar.hpp.

Member Enumeration Documentation

◆ Variant

Whether every destination shows its label (WithLabels) or only the selected one does (WithoutLabels).

Definition at line 62 of file navigation_bar.hpp.

Member Function Documentation

◆ addDestination()

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

Append the description of one destination.

Always marks the component changed.

Parameters
destinationThe destination to add after the existing ones.
Returns
This component, for chaining.

Definition at line 59 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ getDestinationEntities()

const std::vector< ecs::Entity::Identifier > & guillaume::components::NavigationBar::getDestinationEntities ( void ) const
noexcept

Get the destination children.

Returns
One identifier per destination, in the same order as getDestinations(). Empty until the widget has built them.

Definition at line 78 of file navigation_bar.cpp.

Here is the caller graph for this function:

◆ getDestinations()

const std::vector< NavigationBar::Destination > & guillaume::components::NavigationBar::getDestinations ( void ) const
noexcept

Get the description of every destination.

Returns
The destinations, in display order.

Definition at line 44 of file navigation_bar.cpp.

◆ getOnIndexChange()

const NavigationBar::IndexHandler & guillaume::components::NavigationBar::getOnIndexChange ( void ) const
noexcept

Get the callback run when a press changes the selected destination.

Returns
The callback; empty when none is set.

Definition at line 94 of file navigation_bar.cpp.

◆ getOnTabPress()

const NavigationBar::IndexHandler & guillaume::components::NavigationBar::getOnTabPress ( void ) const
noexcept

Get the callback run on every destination press.

Returns
The callback; empty when none is set.

Definition at line 106 of file navigation_bar.cpp.

◆ getVariant()

NavigationBar::Variant guillaume::components::NavigationBar::getVariant ( void ) const
noexcept

Get the label visibility rule.

Returns
The variant, Variant::WithLabels by default.

Definition at line 29 of file navigation_bar.cpp.

◆ isUpdatingSelection()

bool guillaume::components::NavigationBar::isUpdatingSelection ( void ) const
noexcept

Tell whether systems::NavigationBar is changing the selection at this moment.

Returns
True during systems::NavigationBar::select.

Definition at line 117 of file navigation_bar.cpp.

◆ setDestinationBadge()

NavigationBar & guillaume::components::NavigationBar::setDestinationBadge ( std::size_t index,
const std::string & badge )

Change the badge text recorded for one destination.

This only updates the description. To update the badge on screen too, call systems::NavigationBar::setBadge. Marks the component changed only when the text differs.

Parameters
indexThe destination index, starting at 0. An index out of range is ignored.
badgeThe new badge text.
Returns
This component, for chaining.

Definition at line 66 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setDestinationEntities()

NavigationBar & guillaume::components::NavigationBar::setDestinationEntities ( const std::vector< ecs::Entity::Identifier > & identifiers)

Record the destination children.

Called by the widget after it creates them. Marks the component changed only when the list differs.

Parameters
identifiersOne identifier per destination, in the same order as getDestinations().
Returns
This component, for chaining.

Definition at line 83 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setDestinations()

NavigationBar & guillaume::components::NavigationBar::setDestinations ( const std::vector< Destination > & destinations)

Replace the description of every destination.

This does not build the destination children; the widget does. Marks the component changed only when the list differs.

Parameters
destinationsThe new destinations, in display order.
Returns
This component, for chaining.

Definition at line 49 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setOnIndexChange()

NavigationBar & guillaume::components::NavigationBar::setOnIndexChange ( IndexHandler handler)

Set the callback run when a press changes the selected destination.

It receives the index of the newly selected destination. It is not called when the user presses the destination that is already selected. Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 99 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setOnTabPress()

NavigationBar & guillaume::components::NavigationBar::setOnTabPress ( IndexHandler handler)

Set the callback run on every destination press.

It receives the index of the pressed destination and runs before the selection changes, even when that destination is already selected. Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 111 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setUpdatingSelection()

NavigationBar & guillaume::components::NavigationBar::setUpdatingSelection ( bool updating)

Raise or lower the guard that stops a selection change from triggering another one.

systems::NavigationBar raises it while it selects a destination, so the selection change the destination reports back is ignored. Marks the component changed when the flag differs.

Parameters
updatingTrue while the system changes the selection.
Returns
This component, for chaining.

Definition at line 122 of file navigation_bar.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Choose whether every destination shows its label.

Marks the component changed only when the variant differs.

Parameters
variantThe new variant.
Returns
This component, for chaining.

Definition at line 34 of file navigation_bar.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ Height

float guillaume::components::NavigationBar::Height = 80.0f
staticconstexpr

Height of the bar, in dp.

Definition at line 86 of file navigation_bar.hpp.


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