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

A modal panel shown above the rest of the interface, with an optional icon, a title, a message and a row of text buttons. More...

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

Inheritance diagram for guillaume::entities::Dialog:
Collaboration diagram for guillaume::entities::Dialog:

Classes

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

Public Types

using Variant = components::Dialog::Variant
 Look of the dialog: Alert, Simple, Confirmation or FullScreen.
using Action = components::Dialog::Action
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Dialog >
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

 Dialog (ecs::ComponentRegistry &registry, const SurfaceConfig &config, Variant variant, const std::string &title, const std::string &message, const std::vector< Action > &actions, const std::string &icon, std::function< void(void)> onDismiss={})
 Construct a dialog with pressable actions and an icon.
 ~Dialog (void) override=default
 Default destructor.
Dialog & setVariant (Variant variant)
 Change the dialog variant.
Variant getVariant (void) const
 Get the dialog variant.
Dialog & setTitle (const std::string &title)
 Change the title text.
Dialog & setMessage (const std::string &message)
 Change the message text.
Dialog & show (void)
 Show the dialog and, except for the FullScreen variant, its backdrop.
Dialog & hide (void)
 Hide the dialog and its backdrop.
bool isVisible (void) const
 Check whether the dialog is shown.
Dialog & open (void)
 Show the dialog; same as show().
Dialog & close (void)
 Hide the dialog; same as hide().
bool isOpen (void) const
 Check whether the dialog is shown; same as isVisible().
Dialog & dismiss (void)
 Dismiss the dialog as the user would: hide it, then call the dismiss handler.
Dialog & setOnDismiss (std::function< void(void)> onDismiss)
 Set the handler called when the dialog is dismissed (Paper onDismiss).
std::size_t getActionCount (void) const
 Get the number of action buttons.
ecs::Entity::Identifier getActionIdentifier (std::size_t index) const
 Get the identifier of an action button.
ecs::Entity::Identifier getActionRowIdentifier (void) const
 Get the identifier of the row that holds the action buttons.
ecs::Entity::Identifier getBackdropIdentifier (void) const
 Get the identifier of the backdrop drawn behind the panel.
ecs::Entity::Identifier getIconIdentifier (void) const
 Get the identifier of the icon shown above the title.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Dialog >
 ~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< Dialog > create (Arguments &&...arguments)
 Create a dialog 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::Elevation, components::Accessibility, components::Dialog >
 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 modal panel shown above the rest of the interface, with an optional icon, a title, a message and a row of text buttons.

Its configuration lives in components::Dialog (variant, title, message, actions, icon, identifiers of the children) and its visibility and dismiss handler in components::Overlay. systems::Dialog styles the panel, arranges its children and shows or hides its backdrop each frame, in the Layout phase. The class itself holds no field: its setters write the components and restyle at once.

Dialog::Builder builder(getComponentRegistry(), getEntityRegistry());
auto dialog = builder.withOnDismiss([]() {
// called when the user dismisses the dialog
})
.addAction("Cancel")
.addAction("Delete", []() {
// called when the button is pressed
})
.makeDialog(parent, Dialog::Variant::Alert, "Delete the file?",
"This cannot be undone.");
dialog->show();
Configures a Dialog, then builds it and registers it in the entity registry given at construction.
Definition dialog.hpp:126

Dialog::create(registry, config, variant, title, message, actions, icon, onDismiss) builds the same widget without registering it in an entity registry.

Showing and hiding: a dialog is created hidden. show() and hide() switch it; dismiss() hides it and calls the dismiss handler. systems::Overlay dismisses the topmost visible overlay when the user presses Escape. Pressing an action button only calls the action's handler: the dialog stays open until the handler (or other code) hides it.

The variants differ as follows:

  • Alert, Simple: the default look, a 320 dp wide panel with rounded corners.
  • Confirmation: same look; shows the "info" icon when no icon is set.
  • FullScreen: a 640 dp high panel without rounded corners and without backdrop.

Things to know:

  • The dialog is the entity registry of its children (backdrop, icon, title, message, action row); they are built by this class and destroyed with it.
  • systems::Dialog overwrites the panel's layout settings, width, color, corner radius and elevation every frame: values set through the SurfaceBase setters do not last.
  • The actions are fixed at creation.
See also
components::Dialog, components::Overlay, systems::Dialog

Definition at line 109 of file dialog.hpp.

Member Typedef Documentation

◆ Action

One dialog action: a label and a press handler, shown as a text button in the action row.

Definition at line 119 of file dialog.hpp.

◆ Variant

Look of the dialog: Alert, Simple, Confirmation or FullScreen.

Definition at line 115 of file dialog.hpp.

Constructor & Destructor Documentation

◆ Dialog()

guillaume::entities::Dialog::Dialog ( ecs::ComponentRegistry & registry,
const SurfaceConfig & config,
Variant variant,
const std::string & title,
const std::string & message,
const std::vector< Action > & actions,
const std::string & icon,
std::function< void(void)> onDismiss = {} )

Construct a dialog with pressable actions and an icon.

Writes the components and styles the panel, but builds no child: use create() or the Builder, which also build the children.

Parameters
registryThe registry the dialog's components are created in.
configPose and layout of the panel. systems::Dialog overwrites the layout settings.
variantThe dialog variant.
titleThe title text, in the HeadlineSmall type role.
messageThe message text, in the BodyMedium type role.
actionsThe actions, shown as a row of text buttons aligned to the end of the panel.
iconThe glyph name of the icon above the title. When empty, a Confirmation dialog shows "info" and the other variants show no icon.
onDismissCalled when the dialog is dismissed; stored in components::Overlay.

Definition at line 173 of file dialog.cpp.

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

Member Function Documentation

◆ close()

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

Hide the dialog; same as hide().

Returns
This dialog, for chaining.

Definition at line 258 of file dialog.cpp.

Here is the call graph for this function:

◆ create()

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

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

The arguments are forwarded to a constructor: (registry, config, variant, title, message, actions, icon, onDismiss) with a vector of Action, or (registry, config, variant, title, message, labels) with a vector of labels. 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 dialog, hidden, with no parent.

Definition at line 283 of file dialog.hpp.

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

◆ dismiss()

Dialog & guillaume::entities::Dialog::dismiss ( void )

Dismiss the dialog as the user would: hide it, then call the dismiss handler.

Does nothing while the dialog is hidden.

Returns
This dialog, for chaining.

Definition at line 268 of file dialog.cpp.

Here is the call graph for this function:

◆ getActionCount()

std::size_t guillaume::entities::Dialog::getActionCount ( void ) const

Get the number of action buttons.

Returns
The number of buttons built; an action with an empty label has none.

Definition at line 282 of file dialog.cpp.

Here is the call graph for this function:

◆ getActionIdentifier()

ecs::Entity::Identifier guillaume::entities::Dialog::getActionIdentifier ( std::size_t index) const

Get the identifier of an action button.

Parameters
indexIndex of the button in the action row, from 0.
Returns
The identifier, or ecs::Entity::InvalidIdentifier when index is out of range.

Definition at line 290 of file dialog.cpp.

Here is the call graph for this function:

◆ getActionRowIdentifier()

ecs::Entity::Identifier guillaume::entities::Dialog::getActionRowIdentifier ( void ) const

Get the identifier of the row that holds the action buttons.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the dialog has no action.

Definition at line 301 of file dialog.cpp.

Here is the call graph for this function:

◆ getBackdropIdentifier()

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

Get the identifier of the backdrop drawn behind the panel.

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

Definition at line 308 of file dialog.cpp.

Here is the call graph for this function:

◆ getIconIdentifier()

ecs::Entity::Identifier guillaume::entities::Dialog::getIconIdentifier ( void ) const

Get the identifier of the icon shown above the title.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the dialog has no icon.

Definition at line 315 of file dialog.cpp.

Here is the call graph for this function:

◆ getVariant()

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

Get the dialog variant.

Returns
The variant stored in components::Dialog.

Definition at line 207 of file dialog.cpp.

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

◆ hide()

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

Hide the dialog and its backdrop.

Sets components::Overlay hidden and restyles at once. Does not itself call the dismiss handler; use dismiss() for that.

Returns
This dialog, for chaining.

Definition at line 240 of file dialog.cpp.

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

◆ isOpen()

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

Check whether the dialog is shown; same as isVisible().

Returns
True when the dialog is shown.

Definition at line 263 of file dialog.cpp.

Here is the call graph for this function:

◆ isVisible()

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

Check whether the dialog is shown.

Returns
True when components::Overlay is visible. False for a dialog that was never shown.

Definition at line 246 of file dialog.cpp.

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

◆ open()

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

Show the dialog; same as show().

Returns
This dialog, for chaining.

Definition at line 253 of file dialog.cpp.

Here is the call graph for this function:

◆ setMessage()

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

Change the message text.

Builds the message child when the dialog had none and message is not empty, then restyles at once. An empty message leaves an existing message child in place, with no text.

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

Definition at line 224 of file dialog.cpp.

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

◆ setOnDismiss()

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

Set the handler called when the dialog is dismissed (Paper onDismiss).

The handler is stored in components::Overlay. It is called by dismiss() and by systems::Overlay when it dismisses the dialog, for example on Escape.

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

Definition at line 274 of file dialog.cpp.

Here is the call graph for this function:

◆ setTitle()

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

Change the title text.

Builds the title child when the dialog had none and title is not empty, then restyles at once. An empty title leaves an existing title child in place, with no text.

Parameters
titleThe new title text.
Returns
This dialog, for chaining.

Definition at line 214 of file dialog.cpp.

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

◆ setVariant()

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

Change the dialog variant.

Builds the default "info" icon when the new variant is Confirmation and the dialog has no icon yet, then restyles at once.

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

Definition at line 196 of file dialog.cpp.

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

◆ show()

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

Show the dialog and, except for the FullScreen variant, its backdrop.

Sets components::Overlay visible and restyles at once.

Returns
This dialog, for chaining.

Definition at line 234 of file dialog.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: