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

State of a navigation drawer: the side sheet that lists the destinations of an app, grouped by section headers and dividers. More...

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

Inheritance diagram for guillaume::components::NavigationDrawer:
Collaboration diagram for guillaume::components::NavigationDrawer:

Classes

struct  Entry
 Description of one drawer entry, as given by the user. More...

Public Types

enum class  Variant { Standard , Modal , Collapsed }
 How the drawer is presented. More...
enum class  EntryKind { Destination , Section , Divider }
 What a drawer entry is. More...
using IndexHandler = std::function<void(std::size_t)>
 Callback that receives a destination index, starting at 0.

Public Member Functions

 NavigationDrawer (void)=default
 Create the configuration of a standard drawer with no entry.
 ~NavigationDrawer (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get how the drawer is presented.
NavigationDrawer & setVariant (Variant variant)
 Choose how the drawer is presented.
const std::vector< Entry > & getEntries (void) const noexcept
 Get the description of every entry.
NavigationDrawer & setEntries (const std::vector< Entry > &entries)
 Replace the description of every entry.
NavigationDrawer & setDestinationDisabled (std::size_t index, bool disabled)
 Change the disabled flag recorded for one destination.
std::size_t getDestinationCount (void) const noexcept
 Count the entries that are destinations.
const std::vector< ecs::Entity::Identifier > & getEntryEntities (void) const noexcept
 Get the child built for each entry, whatever its kind.
NavigationDrawer & setEntryEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the child built for each entry, whatever its kind.
const std::vector< ecs::Entity::Identifier > & getDestinationEntities (void) const noexcept
 Get the destination children.
NavigationDrawer & setDestinationEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the destination children.
const std::vector< ecs::Entity::Identifier > & getSectionEntities (void) const noexcept
 Get the section header children.
NavigationDrawer & setSectionEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the section header children.
const std::vector< ecs::Entity::Identifier > & getDividerEntities (void) const noexcept
 Get the divider children.
NavigationDrawer & setDividerEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the divider children.
ecs::Entity::Identifier getBackdrop (void) const noexcept
 Get the child that dims the content behind a modal drawer.
NavigationDrawer & setBackdrop (ecs::Entity::Identifier identifier)
 Record the child that dims the content behind a modal drawer.
const IndexHandler & getOnIndexChange (void) const noexcept
 Get the callback run when a press changes the selected destination.
NavigationDrawer & setOnIndexChange (IndexHandler handler)
 Set the callback run when a press changes the selected destination.
bool isUpdatingSelection (void) const noexcept
 Tell whether systems::NavigationDrawer is changing the selection at this moment.
NavigationDrawer & 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 Width = 320.0f
 Width of a standard or modal drawer, in dp.
static constexpr float CollapsedWidth = 80.0f
 Width of a collapsed drawer (rail), in dp.
static constexpr float Height = 640.0f
 Height of the drawer, in dp.

Detailed Description

State of a navigation drawer: the side sheet that lists the destinations of an app, grouped by section headers and dividers.

The entities::NavigationDrawer widget writes it: the variant, the entries, the selection callback, and the identifiers of the children it builds for the entries and of the modal backdrop. systems::NavigationDrawer reads it every frame in the Layout phase and turns it into the sheet's size, shape and color, the column of entries, the flags of the drawer's components::Overlay and the backdrop.

Two things are not stored here. Which destination is selected is the components::Selectable of each destination child (see systems::NavigationDrawer::selectedIndex). Whether the drawer is shown is its components::Overlay (see systems::NavigationDrawer::show).

A destination index counts destinations only: sections and dividers are skipped. An entry index counts every entry.

See also
systems::NavigationDrawer, components::NavigationDrawerDestination, entities::NavigationDrawer

Definition at line 59 of file navigation_drawer.hpp.

Member Typedef Documentation

◆ IndexHandler

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

Callback that receives a destination index, starting at 0.

Definition at line 105 of file navigation_drawer.hpp.

Member Enumeration Documentation

◆ EntryKind

What a drawer entry is.

Enumerator
Destination 

Pressable destination.

Section 

Section header (titleSmall text).

Divider 

Horizontal divider line.

Definition at line 76 of file navigation_drawer.hpp.

◆ Variant

How the drawer is presented.

Enumerator
Standard 

Sheet docked beside the content, on surface.

Modal 

that dims the content and closes it on a click.

Sheet on surfaceContainerLow above a backdrop

Collapsed 

Narrow rail whose destinations stack an icon above a label.

Definition at line 65 of file navigation_drawer.hpp.

Member Function Documentation

◆ getBackdrop()

ecs::Entity::Identifier guillaume::components::NavigationDrawer::getBackdrop ( void ) const
noexcept

Get the child that dims the content behind a modal drawer.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 156 of file navigation_drawer.cpp.

◆ getDestinationCount()

std::size_t guillaume::components::NavigationDrawer::getDestinationCount ( void ) const
noexcept

Count the entries that are destinations.

Returns
The number of entries of kind EntryKind::Destination.

Definition at line 80 of file navigation_drawer.cpp.

◆ getDestinationEntities()

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

Get the destination children.

Returns
The identifiers, indexed by destination index.

Definition at line 109 of file navigation_drawer.cpp.

Here is the caller graph for this function:

◆ getDividerEntities()

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

Get the divider children.

Returns
Their identifiers, in entry order.

Definition at line 141 of file navigation_drawer.cpp.

◆ getEntries()

const std::vector< NavigationDrawer::Entry > & guillaume::components::NavigationDrawer::getEntries ( void ) const
noexcept

Get the description of every entry.

Returns
The entries, from top to bottom.

Definition at line 44 of file navigation_drawer.cpp.

◆ getEntryEntities()

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

Get the child built for each entry, whatever its kind.

Returns
The identifiers, in entry order. systems::NavigationDrawer places them in a column. Empty until the widget has built them.

Definition at line 93 of file navigation_drawer.cpp.

◆ getOnIndexChange()

const NavigationDrawer::IndexHandler & guillaume::components::NavigationDrawer::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 172 of file navigation_drawer.cpp.

◆ getSectionEntities()

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

Get the section header children.

Returns
One identifier per section entry that has a title, in entry order.

Definition at line 125 of file navigation_drawer.cpp.

◆ getVariant()

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

Get how the drawer is presented.

Returns
The variant, Variant::Standard by default.

Definition at line 29 of file navigation_drawer.cpp.

Here is the caller graph for this function:

◆ isUpdatingSelection()

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

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

Returns
True during systems::NavigationDrawer::select.

Definition at line 183 of file navigation_drawer.cpp.

◆ setBackdrop()

NavigationDrawer & guillaume::components::NavigationDrawer::setBackdrop ( ecs::Entity::Identifier identifier)

Record the child that dims the content behind a modal drawer.

Marks the component changed only when the identifier differs.

Parameters
identifierThe backdrop's identifier.
Returns
This component, for chaining.

Definition at line 162 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setDestinationDisabled()

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

Change the disabled flag recorded for one destination.

This only updates the entry. To disable the destination on screen too, call systems::NavigationDrawer::setDestinationDisabled. Marks the component changed only when the flag differs.

Parameters
indexThe destination index, starting at 0. An index out of range is ignored.
disabledTrue to disable the destination.
Returns
This component, for chaining.

Definition at line 60 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setDestinationEntities()

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

Record the destination children.

Marks the component changed only when the list differs.

Parameters
identifiersThe identifiers, indexed by destination index.
Returns
This component, for chaining.

Definition at line 114 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setDividerEntities()

NavigationDrawer & guillaume::components::NavigationDrawer::setDividerEntities ( const std::vector< ecs::Entity::Identifier > & identifiers)

Record the divider children.

Marks the component changed only when the list differs.

Parameters
identifiersTheir identifiers, in entry order.
Returns
This component, for chaining.

Definition at line 146 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setEntries()

NavigationDrawer & guillaume::components::NavigationDrawer::setEntries ( const std::vector< Entry > & entries)

Replace the description of every entry.

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

Parameters
entriesThe new entries, from top to bottom.
Returns
This component, for chaining.

Definition at line 50 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setEntryEntities()

NavigationDrawer & guillaume::components::NavigationDrawer::setEntryEntities ( const std::vector< ecs::Entity::Identifier > & identifiers)

Record the child built for each entry, whatever its kind.

Marks the component changed only when the list differs.

Parameters
identifiersThe identifiers, in entry order.
Returns
This component, for chaining.

Definition at line 98 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setOnIndexChange()

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

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

It receives the destination index of the newly selected destination. It is not called for a press on the destination that is already selected, nor on a disabled one. Does not mark the component changed.

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

Definition at line 177 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setSectionEntities()

NavigationDrawer & guillaume::components::NavigationDrawer::setSectionEntities ( const std::vector< ecs::Entity::Identifier > & identifiers)

Record the section header children.

Marks the component changed only when the list differs.

Parameters
identifiersOne identifier per section entry that has a title, in entry order.
Returns
This component, for chaining.

Definition at line 130 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setUpdatingSelection()

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

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

systems::NavigationDrawer 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 188 of file navigation_drawer.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Choose how the drawer is presented.

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_drawer.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ CollapsedWidth

float guillaume::components::NavigationDrawer::CollapsedWidth = 80.0f
staticconstexpr

Width of a collapsed drawer (rail), in dp.

Definition at line 111 of file navigation_drawer.hpp.

◆ Height

float guillaume::components::NavigationDrawer::Height = 640.0f
staticconstexpr

Height of the drawer, in dp.

Definition at line 114 of file navigation_drawer.hpp.

◆ Width

float guillaume::components::NavigationDrawer::Width = 320.0f
staticconstexpr

Width of a standard or modal drawer, in dp.

Definition at line 108 of file navigation_drawer.hpp.


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