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

A side sheet listing destinations, of which exactly one is selected, with optional section titles and dividers (Paper Drawer.Section, Drawer.Item and Drawer.CollapsedItem). More...

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

Inheritance diagram for guillaume::entities::NavigationDrawer:
Collaboration diagram for guillaume::entities::NavigationDrawer:

Classes

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

Public Types

using Variant = components::NavigationDrawer::Variant
using EntryKind = components::NavigationDrawer::EntryKind
 Kind of a drawer entry: destination, section title or divider.
using Entry = components::NavigationDrawer::Entry
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::SelectionGroup, components::NavigationDrawer >
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

 ~NavigationDrawer (void) override
 Default destructor.
NavigationDrawer & setVariant (Variant variant)
 Change the variant.
Variant getVariant (void) const
 Get the variant.
NavigationDrawer & 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.
NavigationDrawer & setDestinationDisabled (std::size_t index, bool disabled)
 Enable or disable a destination. Restyles it at once.
NavigationDrawer & setOnIndexChange (std::function< void(std::size_t)> onIndexChange)
 Set the handler called when the user selects another destination.
NavigationDrawer & open (void)
 Open the drawer. Same as show().
NavigationDrawer & close (void)
 Close the drawer. Same as hide().
bool isOpen (void) const
 Whether the drawer is open. Same as isVisible().
NavigationDrawer & show (void)
 Show the drawer, and its backdrop when the variant is Modal.
NavigationDrawer & hide (void)
 Hide the drawer and its backdrop.
bool isVisible (void) const
 Whether the drawer is shown.
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: its pressable row.
ecs::Entity::Identifier getRightIdentifier (std::size_t index) const
 Get the trailing text entity of a destination.
std::size_t getSectionCount (void) const
 Get the number of section titles built.
ecs::Entity::Identifier getSectionIdentifier (std::size_t index) const
 Get the text entity of a section title.
std::size_t getDividerCount (void) const
 Get the number of dividers.
ecs::Entity::Identifier getBackdropIdentifier (void) const
 Get the backdrop: the child that dims what is behind an open Modal drawer.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::SelectionGroup, components::NavigationDrawer >
 ~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< NavigationDrawer > create (Arguments &&...arguments)
 Create a drawer and its 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::Overlay, components::SelectionGroup, components::NavigationDrawer >
 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 side sheet listing destinations, of which exactly one is selected, with optional section titles and dividers (Paper Drawer.Section, Drawer.Item and Drawer.CollapsedItem).

Its state lives in components::NavigationDrawer (variant, entries, child identifiers, index-change handler); systems::NavigationDrawer sizes and colors the sheet, places the entries in a column and drives the backdrop each frame, in the Layout phase. Which destination is selected is stored in the components::Selectable of each destination child; whether the drawer is shown is stored in its components::Overlay. The class itself holds no field.

getEntityRegistry());
auto drawer = builder.addSection("Mail")
.addDestination("inbox", "Inbox", "24")
.addDestination("send", "Sent")
.addDivider()
.withOnIndexChange([](std::size_t index) {
// called when the user selects another destination
})
.makeNavigationDrawer(parent, NavigationDrawer::Variant::Modal, {});
drawer->open();
Configures a NavigationDrawer, creates it and registers it in an entity registry.

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

Things to know:

  • A destination index counts destinations only, from 0: sections and dividers are skipped.
  • The drawer is closed at creation: isOpen() is false until open().
  • The first enabled destination is selected at creation. select() does not call the index-change handler and does not check the disabled flag; only a press by the user on another, enabled destination calls the handler.
  • The size is fixed by the variant and overwritten each frame: 320 dp wide (Standard, Modal) or 80 dp wide (Collapsed), 640 dp high. The color, corners, padding and spacing are overwritten too.
  • Modal dims what is behind the drawer with a backdrop while it is open, and sets its components::Overlay to be dismissed by a click outside. Collapsed is a narrow rail with the label under the icon, without section titles or trailing texts.
  • The drawer is the entity registry that owns its children. setVariant() removes and rebuilds every entry child when it switches between Collapsed and another variant: the identifiers returned before by getDestinationIdentifier(), getRightIdentifier() and getSectionIdentifier() are then invalid. The backdrop is kept.
See also
components::NavigationDrawer, systems::NavigationDrawer, NavigationBar

Definition at line 105 of file navigation_drawer.hpp.

Member Typedef Documentation

◆ Entry

One drawer entry: kind, icon glyph name, label, trailing text and disabled flag.

Definition at line 119 of file navigation_drawer.hpp.

◆ EntryKind

Kind of a drawer entry: destination, section title or divider.

Definition at line 115 of file navigation_drawer.hpp.

◆ Variant

Variant: Standard (docked sheet), Modal (sheet over a backdrop) or Collapsed (narrow rail).

Definition at line 112 of file navigation_drawer.hpp.

Constructor & Destructor Documentation

◆ ~NavigationDrawer()

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

Default destructor.

Definition at line 195 of file navigation_drawer.cpp.

Member Function Documentation

◆ close()

NavigationDrawer & guillaume::entities::NavigationDrawer::close ( void )

Close the drawer. Same as hide().

Returns
This drawer, for chaining.

Definition at line 396 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ create()

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

Create a drawer and its children, without registering it in an entity registry.

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

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

Definition at line 255 of file navigation_drawer.hpp.

Here is the caller graph for this function:

◆ getBackdropIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationDrawer::getBackdropIdentifier ( void ) const

Get the backdrop: the child that dims what is behind an open Modal drawer.

The backdrop exists for every variant; it is only shown for Modal.

Returns
The identifier of the backdrop, or ecs::Entity::InvalidIdentifier before the children are built.

Definition at line 468 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getDestinationCount()

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

Get the number of destinations.

Returns
How many entries are destinations.

Definition at line 406 of file navigation_drawer.cpp.

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

◆ getDestinationIdentifier()

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

Get the child entity of a destination: its pressable row.

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

Definition at line 414 of file navigation_drawer.cpp.

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

◆ getDividerCount()

std::size_t guillaume::entities::NavigationDrawer::getDividerCount ( void ) const

Get the number of dividers.

Returns
How many divider children the drawer has.

Definition at line 460 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getRightIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationDrawer::getRightIdentifier ( std::size_t index) const

Get the trailing text entity of a destination.

Parameters
indexThe index of the destination, sections and dividers not counted.
Returns
The identifier of the text, or ecs::Entity::InvalidIdentifier when index is out of range, the destination has no trailing text or the variant is Collapsed.

Definition at line 426 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getSectionCount()

std::size_t guillaume::entities::NavigationDrawer::getSectionCount ( void ) const

Get the number of section titles built.

Returns
How many section entries have a title child: sections with an empty title are not counted, and the count is 0 with the Collapsed variant.

Definition at line 440 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getSectionIdentifier()

ecs::Entity::Identifier guillaume::entities::NavigationDrawer::getSectionIdentifier ( std::size_t index) const

Get the text entity of a section title.

Parameters
indexThe position among the section titles built, from 0.
Returns
The identifier of the text, or ecs::Entity::InvalidIdentifier when index is out of range.

Definition at line 449 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getSelectedIndex()

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

Get the index of the selected destination.

Returns
The index, sections and dividers not counted, or 0 when no destination is selected.

Definition at line 346 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ getVariant()

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

Get the variant.

Returns
The variant stored in components::NavigationDrawer.

Definition at line 332 of file navigation_drawer.cpp.

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

◆ hide()

NavigationDrawer & guillaume::entities::NavigationDrawer::hide ( void )

Hide the drawer and its backdrop.

Sets the drawer's components::Overlay not visible and restyles at once.

Returns
This drawer, for chaining.

Definition at line 377 of file navigation_drawer.cpp.

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

◆ isOpen()

bool guillaume::entities::NavigationDrawer::isOpen ( void ) const

Whether the drawer is open. Same as isVisible().

Returns
True between open() and close(); false at creation.

Definition at line 401 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ isVisible()

bool guillaume::entities::NavigationDrawer::isVisible ( void ) const

Whether the drawer is shown.

Returns
True when its components::Overlay is visible; false at creation.

Definition at line 384 of file navigation_drawer.cpp.

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

◆ open()

NavigationDrawer & guillaume::entities::NavigationDrawer::open ( void )

Open the drawer. Same as show().

Returns
This drawer, for chaining.

Definition at line 391 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ select()

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

Select a destination and deselect the others.

Restyles at once. Does not call the index-change handler and does not check whether the destination is disabled.

Parameters
indexThe index of the destination, sections and dividers not counted; nothing happens when it is out of range.
Returns
This drawer, for chaining.

Definition at line 339 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setDestinationDisabled()

NavigationDrawer & guillaume::entities::NavigationDrawer::setDestinationDisabled ( std::size_t index,
bool disabled )

Enable or disable a destination. Restyles it at once.

A disabled destination ignores presses. Disabling the selected destination does not move the selection.

Parameters
indexThe index of the destination, sections and dividers not counted; nothing happens when it is out of range.
disabledTrue to disable, false to enable.
Returns
This drawer, for chaining.

Definition at line 353 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setOnIndexChange()

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

Set the handler called when the user selects another destination.

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 drawer, for chaining.

Definition at line 361 of file navigation_drawer.cpp.

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

◆ setVariant()

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

Change the variant.

Restyles at once. Switching between Collapsed and another variant removes every entry child and builds new ones (a rail and a sheet are made of different children), then selects the same destination index again; identifiers of entry children obtained before are then invalid. This rebuild is skipped when the drawer has no destination child. Switching between Standard and Modal keeps the children.

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

Definition at line 305 of file navigation_drawer.cpp.

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

◆ show()

NavigationDrawer & guillaume::entities::NavigationDrawer::show ( void )

Show the drawer, and its backdrop when the variant is Modal.

Sets the drawer's components::Overlay visible and restyles at once.

Returns
This drawer, for chaining.

Definition at line 370 of file navigation_drawer.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: