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

Styles a navigation drawer, stacks its entries in a column and keeps exactly one of its destinations selected. More...

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

Inheritance diagram for guillaume::systems::NavigationDrawer:
Collaboration diagram for guillaume::systems::NavigationDrawer:

Public Member Functions

 NavigationDrawer (void)
 Create the system in the Layout phase.
 ~NavigationDrawer (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one navigation drawer; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::NavigationDrawer >
 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 drawer to its destinations and section headers.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Shape and color the drawer, style its destinations, stack its entries and place its backdrop.
static float widthOf (components::NavigationDrawer::Variant variant)
 Get the drawer width of a variant, in dp.
static void select (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Select a destination from code.
static void selectFirstEnabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Select the first destination that is not disabled, then restyle.
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 drawer.
static void setDestinationDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
 Enable or disable one destination and restyle it.
static void show (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Show the drawer, and its backdrop when it is modal.
static void hide (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Hide the drawer and its backdrop.
static std::size_t selectedIndex (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the index of the selected destination.

Static Public Attributes

static constexpr float Padding = theme::SpacingScale::get(3)
 Space between the edge of the drawer and its entries: 12 dp.
static constexpr float Spacing = theme::SpacingScale::get(1)
 Gap between two stacked entries: 4 dp.

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 drawer, stacks its entries in a column and keeps exactly one of its destinations selected.

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

An entry is a destination, a section header or a divider. The index taken by the functions below counts destinations only: it is a position in components::NavigationDrawer::getDestinationEntities, starting at 0.

The variant decides the shape: Standard and Modal drawers are components::NavigationDrawer::Width wide, a Collapsed one is a rail of components::NavigationDrawer::CollapsedWidth. Only a Modal drawer is a modal overlay with a backdrop, and only it closes on a click outside; every variant closes on Escape.

systems::NavigationDrawer::press(registry, drawer, 2); // as a click
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 show(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Show the drawer, and its backdrop when it is modal.
static void selectFirstEnabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Select the first destination that is not disabled, then restyle.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Connect a navigation drawer to its destinations and section headers.
See also
components::NavigationDrawer, systems::NavigationDrawerDestination, systems::Selection, systems::Backdrop

Definition at line 78 of file navigation_drawer.hpp.

Constructor & Destructor Documentation

◆ NavigationDrawer()

guillaume::systems::NavigationDrawer::NavigationDrawer ( void )

Create the system in the Layout phase.

Definition at line 64 of file navigation_drawer.cpp.

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

Member Function Documentation

◆ apply()

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

Shape and color the drawer, style its destinations, stack its entries and place its backdrop.

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

The drawer is attached to the leading edge, so only its trailing corners are rounded (none are for a Collapsed drawer). Each destination is as wide as the drawer minus Padding on both sides. The backdrop, when the component records one, is visible only for a Modal drawer whose overlay is visible, and is given the pose and size of the drawer.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::NavigationDrawer, Layout, Borders, Color or Overlay.

Definition at line 283 of file navigation_drawer.cpp.

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

◆ destinationSelected()

void guillaume::systems::NavigationDrawer::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 drawer.

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 drawer. 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 drawer entity.
indexIndex of the destination that became selected. An index past the end is ignored.

Definition at line 204 of file navigation_drawer.cpp.

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

◆ hide()

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

Hide the drawer and its backdrop.

Clears the visible flag of the drawer's components::Overlay and calls apply(). The dismiss handler of the overlay is not called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.

Definition at line 274 of file navigation_drawer.cpp.

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

◆ install()

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

Connect a navigation drawer to its destinations and section headers.

Forbids an empty selection in the drawer's components::SelectionGroup. For every destination recorded in components::NavigationDrawer, replaces its press callback with a call to press() and its selection-changed handler with a call to destinationSelected(). Gives every section header entity the Header accessibility role and its title as label (adding a components::Accessibility when it has none). The handlers capture the index of the destination, so call install() again each time the children change.

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

Definition at line 77 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ press()

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

Activate a destination as a press on it would.

Selects the destination, then calls the index-change callback of components::NavigationDrawer when the selected index is different from the one before the press. Does nothing for a disabled destination.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.
indexIndex of the pressed destination, sections and dividers not counted. An index past the end is ignored.

Definition at line 218 of file navigation_drawer.cpp.

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

◆ select()

void guillaume::systems::NavigationDrawer::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 drawer. The index-change callback is not called, and a disabled destination is selected like any other: use press() to behave as the user would.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.
indexIndex of the destination to select, sections and dividers not counted. An index past the end is ignored.

Definition at line 160 of file navigation_drawer.cpp.

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

◆ selectedIndex()

std::size_t guillaume::systems::NavigationDrawer::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 drawer entity.
Returns
The index of the first destination whose components::Selectable is selected, sections and dividers not counted. Also 0 when no destination is selected, so 0 alone does not prove that the first one is.

Definition at line 142 of file navigation_drawer.cpp.

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

◆ selectFirstEnabled()

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

Select the first destination that is not disabled, then restyle.

Use it to give a drawer its initial selection. When every destination is disabled, the selection is left as it is and the drawer is only restyled. No callback is called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.

Definition at line 183 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setDestinationDisabled()

void guillaume::systems::NavigationDrawer::setDestinationDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
bool disabled )
static

Enable or disable one destination and restyle it.

Stores the flag in components::NavigationDrawer and forwards it to systems::NavigationDrawerDestination::setDisabled. A disabled destination that is selected stays selected.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.
indexIndex of the destination, sections and dividers not counted. An index past the end is ignored.
disabledTrue to disable the destination, false to enable it.

Definition at line 248 of file navigation_drawer.cpp.

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

◆ show()

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

Show the drawer, and its backdrop when it is modal.

Sets the visible flag of the drawer's components::Overlay and calls apply().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe navigation drawer entity.

Definition at line 266 of file navigation_drawer.cpp.

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

◆ update()

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

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

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

Parameters
entityIdentifierThe navigation drawer entity.

Implements guillaume::ecs::System.

Definition at line 367 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ widthOf()

float guillaume::systems::NavigationDrawer::widthOf ( components::NavigationDrawer::Variant variant)
static

Get the drawer width of a variant, in dp.

Parameters
variantThe drawer variant.
Returns
components::NavigationDrawer::CollapsedWidth (80) for the Collapsed variant, components::NavigationDrawer::Width (320) otherwise.

Definition at line 70 of file navigation_drawer.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ Padding

float guillaume::systems::NavigationDrawer::Padding = theme::SpacingScale::get(3)
staticconstexpr

Space between the edge of the drawer and its entries: 12 dp.

Definition at line 83 of file navigation_drawer.hpp.

◆ Spacing

float guillaume::systems::NavigationDrawer::Spacing = theme::SpacingScale::get(1)
staticconstexpr

Gap between two stacked entries: 4 dp.

Definition at line 86 of file navigation_drawer.hpp.


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