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

A horizontal bar with a leading navigation icon button, a title and trailing action icon buttons. More...

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

Inheritance diagram for guillaume::entities::AppBar:
Collaboration diagram for guillaume::entities::AppBar:

Classes

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

Public Types

using Variant = components::AppBar::Variant
using Action = components::AppBar::Action
Public Types inherited from guillaume::entities::SurfaceBase< components::Elevation, components::AppBar >
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

 ~AppBar (void) override
 Default destructor.
AppBar & setVariant (Variant variant)
 Change the variant.
Variant getVariant (void) const
 Get the variant.
AppBar & setTitle (const std::string &title)
 Change the title text.
AppBar & setElevated (bool elevated)
 Choose the elevated look (Paper elevated). Restyles at once.
bool isElevated (void) const
 Whether the app bar uses the elevated look.
std::shared_ptr< IconButton > getNavigationButton (void) const
 Get the leading navigation button.
std::shared_ptr< IconButton > getActionButton (std::size_t index) const
 Get a trailing action button.
std::shared_ptr< Text > getTitle (void) const
 Get the title child.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::AppBar >
 ~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< AppBar > create (Arguments &&...arguments)
 Create an app bar 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.

Static Public Attributes

static constexpr float HorizontalPadding
 Padding around the children and spacing between them, in dp (Paper: 4 dp).
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Additional Inherited Members

Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::AppBar >
 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 horizontal bar with a leading navigation icon button, a title and trailing action icon buttons.

Its state lives in components::AppBar (variant, title, navigation action, trailing actions, elevated flag, child identifiers); systems::AppBar styles the bar and arranges its children each frame, in the Layout phase. The class itself holds no field: its setters write the component and restyle at once.

AppBar::Builder builder(getComponentRegistry(), getEntityRegistry());
auto appBar = builder.withTitle("Inbox")
.withNavigationIcon("menu")
.withOnNavigation([] {
// called when the user presses the navigation icon
})
.addAction("search", [] {}, "Search")
.makeAppBar(parent, AppBar::Variant::Small);
appBar->setTitle("Archive");
Configures an AppBar, creates it and registers it in an entity registry.
Definition app_bar.hpp:107

AppBar::create(registry, config, variant, title, navigation, actions, elevated) builds the same widget without registering it in an entity registry.

Things to know:

  • The variant fixes the height: 64 dp (Small, CenterAligned), 112 dp (Medium), 152 dp (Large) or 80 dp (Bottom). The width is the fixed width of the surface configuration (360 dp with the Builder defaults).
  • systems::AppBar overwrites each frame the bar's layout (axis, alignments, padding, spacing, fixed height, children), its fill color and its elevation, as well as the title's content and typescale role and the navigation button's content color.
  • The app bar is the entity registry that owns its children: the navigation button, the title and the action buttons.
  • The navigation action and the trailing actions are chosen at creation; the class has no setter for them. The navigation button exists only when a navigation icon is set.
See also
components::AppBar, systems::AppBar, IconButton

Definition at line 91 of file app_bar.hpp.

Member Typedef Documentation

◆ Action

A pressable app bar icon (navigation or action): glyph name, press handler, accessible name and disabled flag.

Definition at line 100 of file app_bar.hpp.

◆ Variant

Variant: it sets the height, the title typescale role and how the children are spread.

Definition at line 96 of file app_bar.hpp.

Constructor & Destructor Documentation

◆ ~AppBar()

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

Default destructor.

Definition at line 185 of file app_bar.cpp.

Member Function Documentation

◆ create()

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

Create an app bar and its children, without registering it in an entity registry.

The constructors are private because the children need the app bar to be owned by a shared pointer before they can take it as parent; create() constructs the app bar, then builds the navigation button, the title and the action buttons.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsForwarded to a private constructor: either (registry, config, variant, title, navigation, actions, elevated) with Action values, or (registry, config, variant, title, navigationIcon, actions) with glyph names only (no press handler, not elevated).
Returns
The new app bar.

Definition at line 262 of file app_bar.hpp.

Here is the caller graph for this function:

◆ getActionButton()

std::shared_ptr< IconButton > guillaume::entities::AppBar::getActionButton ( std::size_t index) const

Get a trailing action button.

Parameters
indexThe position of the action, 0 being the first one added.
Returns
The button, or nullptr when index is out of range.

Definition at line 295 of file app_bar.cpp.

Here is the call graph for this function:

◆ getNavigationButton()

std::shared_ptr< IconButton > guillaume::entities::AppBar::getNavigationButton ( void ) const

Get the leading navigation button.

Returns
The button, or nullptr when the app bar has no navigation icon.

Definition at line 285 of file app_bar.cpp.

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

◆ getTitle()

std::shared_ptr< Text > guillaume::entities::AppBar::getTitle ( void ) const

Get the title child.

Returns
The text entity showing the title, or nullptr when no title child was built (the title has always been empty).

Definition at line 309 of file app_bar.cpp.

Here is the call graph for this function:

◆ getVariant()

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

Get the variant.

Returns
The variant stored in components::AppBar.

Definition at line 317 of file app_bar.cpp.

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

◆ isElevated()

bool guillaume::entities::AppBar::isElevated ( void ) const

Whether the app bar uses the elevated look.

Returns
True when elevated.

Definition at line 278 of file app_bar.cpp.

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

◆ setElevated()

AppBar & guillaume::entities::AppBar::setElevated ( bool elevated)

Choose the elevated look (Paper elevated). Restyles at once.

Parameters
elevatedTrue for the level-2 elevation and its tinted surface color, false for a flat bar.
Returns
This app bar, for chaining.

Definition at line 269 of file app_bar.cpp.

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

◆ setTitle()

AppBar & guillaume::entities::AppBar::setTitle ( const std::string & title)

Change the title text.

Builds the title child when the app bar has none and title is not empty, then restyles at once. An empty title keeps an existing child, with an empty content.

Parameters
titleThe new title.
Returns
This app bar, for chaining.

Definition at line 324 of file app_bar.cpp.

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

◆ setVariant()

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

Change the variant.

Restyles at once: the height, the title typescale role and the main-axis alignment follow the variant.

Parameters
variantThe new variant.
Returns
This app bar, for chaining.

Definition at line 260 of file app_bar.cpp.

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

Member Data Documentation

◆ HorizontalPadding

float guillaume::entities::AppBar::HorizontalPadding
staticconstexpr
Initial value:
=
static constexpr float HorizontalPadding
Padding on each side of the bar and gap between its children, in dp.
Definition app_bar.hpp:85

Padding around the children and spacing between them, in dp (Paper: 4 dp).

Definition at line 343 of file app_bar.hpp.


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