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

A short message bar that disappears by itself after a few seconds, with an optional action label the user can press. More...

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

Inheritance diagram for guillaume::entities::Snackbar:
Collaboration diagram for guillaume::entities::Snackbar:

Classes

class  Builder
 Configures a Snackbar, then builds it and registers it in the entity registry given at construction. More...

Public Types

using Variant = components::Snackbar::Variant
 Look of the snackbar: SingleLine, MultiLine or WithAction.
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Snackbar >
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

 ~Snackbar (void) override=default
 Default destructor.
Snackbar & setVariant (Variant variant)
 Change the snackbar variant.
Variant getVariant (void) const
 Get the snackbar variant.
Snackbar & setMessage (const std::string &message)
 Change the message text.
Snackbar & setVisible (bool visible)
 Show or hide the snackbar (Paper visible).
Snackbar & show (void)
 Show the snackbar; same as setVisible(true).
Snackbar & hide (void)
 Hide the snackbar without calling the dismiss handler; same as setVisible(false).
bool isVisible (void) const
 Check whether the snackbar is shown.
Snackbar & setDuration (float seconds)
 Set how long the snackbar stays shown (Paper duration).
float getDuration (void) const
 Get how long the snackbar stays shown.
Snackbar & setOnDismiss (std::function< void(void)> onDismiss)
 Set the handler called when the snackbar dismisses itself (Paper onDismiss).
Snackbar & setOnAction (std::function< void(void)> onAction)
 Set the handler called when the action is pressed (Paper action.onPress).
Snackbar & pressAction (void)
 Activate the action as a press on its label would: call the action handler, then hide the snackbar and call the dismiss handler.
std::shared_ptr< Text > getActionEntity (void) const
 Get the text entity that shows the action label.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Snackbar >
 ~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< Snackbar > create (Arguments &&...arguments)
 Create a snackbar 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 DurationShort
 Short display time: 4 seconds (Paper Snackbar.DURATION_SHORT).
static constexpr float DurationMedium
 Default display time: 7 seconds (Paper Snackbar.DURATION_MEDIUM).
static constexpr float DurationLong
 Long display time: 10 seconds (Paper Snackbar.DURATION_LONG).
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::Overlay, components::Elevation, components::Accessibility, components::Snackbar >
 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 short message bar that disappears by itself after a few seconds, with an optional action label the user can press.

Its state lives in components::Snackbar (variant, message, action label, visibility, duration, callbacks). systems::Snackbar styles the bar and arranges its children each frame, in the Layout phase, and copies the visibility and the duration to components::Overlay; systems::Overlay runs the countdown. The class itself holds no field: its setters write the component and restyle at once.

Snackbar::Builder builder(getComponentRegistry(), getEntityRegistry());
auto snackbar = builder.withDuration(Snackbar::DurationShort)
.withOnAction([]() {
// called when the user presses "Undo"
})
.makeSnackbar(parent, Snackbar::Variant::WithAction,
"Message archived", "Undo");
Configures a Snackbar, then builds it and registers it in the entity registry given at construction.
Definition snackbar.hpp:132
static constexpr float DurationShort
Short display time: 4 seconds (Paper Snackbar.DURATION_SHORT).
Definition snackbar.hpp:110

Snackbar::create(registry, config, variant, message, action) builds the same widget without registering it in an entity registry.

Showing and hiding: a snackbar is shown as soon as it is created, unless the builder was given withVisible(false). show() shows it and restarts the countdown; hide() hides it without calling the dismiss handler. The snackbar dismisses itself, and then calls the dismiss handler, when its duration has elapsed, when the user presses Escape, and after the action is pressed. The duration is in seconds; 0 keeps the snackbar until it is hidden.

The variants are:

  • SingleLine: a message, in a 48 dp high bar.
  • MultiLine: a message, in a 68 dp high bar.
  • WithAction: a message followed by the action label, in a 48 dp high bar. Only this variant builds the action label.

Things to know:

  • The builder makes the bar 344 dp wide.
  • A hidden snackbar keeps its place in its parent's layout; it is painted transparent.
  • systems::Snackbar overwrites the bar's layout settings, height, color, corner radius and elevation every frame.
  • systems::Overlay only counts down, and only applies Escape to, the topmost visible overlay: a snackbar under a dialog waits.
  • The action label is fixed at creation.
See also
components::Snackbar, systems::Snackbar, systems::Overlay

Definition at line 98 of file snackbar.hpp.

Member Typedef Documentation

◆ Variant

Look of the snackbar: SingleLine, MultiLine or WithAction.

Definition at line 104 of file snackbar.hpp.

Member Function Documentation

◆ create()

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

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

The arguments are forwarded to the private constructor: (registry, config, variant, message, action). The children are built here, by build(), because a child needs its parent to be owned by a shared pointer.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new snackbar, shown, with no parent.

Definition at line 270 of file snackbar.hpp.

Here is the caller graph for this function:

◆ getActionEntity()

std::shared_ptr< Text > guillaume::entities::Snackbar::getActionEntity ( void ) const

Get the text entity that shows the action label.

Returns
The action label, or nullptr when the snackbar has none.

Definition at line 219 of file snackbar.cpp.

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

◆ getDuration()

float guillaume::entities::Snackbar::getDuration ( void ) const

Get how long the snackbar stays shown.

Returns
The display time, in seconds; 0 means it never dismisses itself.

Definition at line 190 of file snackbar.cpp.

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

◆ getVariant()

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

Get the snackbar variant.

Returns
The variant stored in components::Snackbar.

Definition at line 239 of file snackbar.cpp.

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

◆ hide()

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

Hide the snackbar without calling the dismiss handler; same as setVisible(false).

Returns
This snackbar, for chaining.

Definition at line 169 of file snackbar.cpp.

Here is the call graph for this function:

◆ isVisible()

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

Check whether the snackbar is shown.

Returns
True when shown.

Definition at line 174 of file snackbar.cpp.

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

◆ pressAction()

Snackbar & guillaume::entities::Snackbar::pressAction ( void )

Activate the action as a press on its label would: call the action handler, then hide the snackbar and call the dismiss handler.

Does nothing while the snackbar is hidden.

Returns
This snackbar, for chaining.

Definition at line 213 of file snackbar.cpp.

Here is the call graph for this function:

◆ setDuration()

Snackbar & guillaume::entities::Snackbar::setDuration ( float seconds)

Set how long the snackbar stays shown (Paper duration).

Restyles at once, which copies the duration to components::Overlay. Does not restart a running countdown.

Parameters
secondsThe display time, in seconds; 0 never dismisses.
Returns
This snackbar, for chaining.
Exceptions
std::invalid_argumentIf seconds is negative.

Definition at line 181 of file snackbar.cpp.

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

◆ setMessage()

Snackbar & guillaume::entities::Snackbar::setMessage ( const std::string & message)

Change the message text.

Builds the message child when the snackbar had none and message is not empty, then restyles at once.

Parameters
messageThe new message text.
Returns
This snackbar, for chaining.

Definition at line 246 of file snackbar.cpp.

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

◆ setOnAction()

Snackbar & guillaume::entities::Snackbar::setOnAction ( std::function< void(void)> onAction)

Set the handler called when the action is pressed (Paper action.onPress).

Parameters
onActionThe handler; an empty one removes it.
Returns
This snackbar, for chaining.

Definition at line 205 of file snackbar.cpp.

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

◆ setOnDismiss()

Snackbar & guillaume::entities::Snackbar::setOnDismiss ( std::function< void(void)> onDismiss)

Set the handler called when the snackbar dismisses itself (Paper onDismiss).

It is called after the snackbar has been hidden by the end of its duration, by Escape or by a press on the action. hide() and setVisible(false) do not call it.

Parameters
onDismissThe handler; an empty one removes it.
Returns
This snackbar, for chaining.

Definition at line 197 of file snackbar.cpp.

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

◆ setVariant()

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

Change the snackbar variant.

Builds the action label when the new variant is WithAction, the action label is not empty and the child does not exist yet, then restyles at once.

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

Definition at line 229 of file snackbar.cpp.

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

◆ setVisible()

Snackbar & guillaume::entities::Snackbar::setVisible ( bool visible)

Show or hide the snackbar (Paper visible).

Restyles at once. Showing a hidden snackbar restarts the auto-dismiss countdown run by systems::Overlay. Hiding does not call the dismiss handler. A hidden snackbar is painted transparent.

Parameters
visibleTrue to show, false to hide.
Returns
This snackbar, for chaining.

Definition at line 154 of file snackbar.cpp.

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

◆ show()

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

Show the snackbar; same as setVisible(true).

Returns
This snackbar, for chaining.

Definition at line 164 of file snackbar.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ DurationLong

float guillaume::entities::Snackbar::DurationLong
staticconstexpr
Initial value:
=
static constexpr float DurationLong
Long display time, in seconds.
Definition snackbar.hpp:75

Long display time: 10 seconds (Paper Snackbar.DURATION_LONG).

Definition at line 124 of file snackbar.hpp.

◆ DurationMedium

float guillaume::entities::Snackbar::DurationMedium
staticconstexpr
Initial value:
=
static constexpr float DurationMedium
Medium display time, in seconds. This is the default.
Definition snackbar.hpp:72

Default display time: 7 seconds (Paper Snackbar.DURATION_MEDIUM).

Definition at line 117 of file snackbar.hpp.

◆ DurationShort

float guillaume::entities::Snackbar::DurationShort
staticconstexpr
Initial value:
=
static constexpr float DurationShort
Short display time, in seconds.
Definition snackbar.hpp:69

Short display time: 4 seconds (Paper Snackbar.DURATION_SHORT).

Definition at line 110 of file snackbar.hpp.


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