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

State of a dialog: a modal panel with an optional icon, a title, a message and a row of text buttons. More...

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

Inheritance diagram for guillaume::components::Dialog:
Collaboration diagram for guillaume::components::Dialog:

Classes

struct  Action
 One action of the dialog, drawn as a text button in the action row. More...

Public Types

enum class  Variant { Alert , Simple , Confirmation , FullScreen }
 Kind of dialog. More...

Public Member Functions

 Dialog (void)=default
 Create the configuration of an empty alert dialog.
 ~Dialog (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the kind of dialog.
Dialog & setVariant (Variant variant)
 Set the kind of dialog.
const std::string & getTitle (void) const noexcept
 Get the title (headline) of the dialog.
Dialog & setTitle (const std::string &title)
 Set the title (headline) of the dialog.
const std::string & getMessage (void) const noexcept
 Get the message (supporting text) of the dialog.
Dialog & setMessage (const std::string &message)
 Set the message (supporting text) of the dialog.
const std::vector< Action > & getActions (void) const noexcept
 Get the actions of the dialog.
Dialog & setActions (std::vector< Action > actions)
 Replace the actions of the dialog.
const std::string & getIcon (void) const noexcept
 Get the icon chosen for the top of the dialog.
Dialog & setIcon (const std::string &icon)
 Choose the icon shown above the title (the hero icon).
std::string getEffectiveIcon (void) const
 Get the icon the dialog actually shows.
ecs::Entity::Identifier getIconEntity (void) const noexcept
 Get the child that draws the hero icon.
Dialog & setIconEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the hero icon.
ecs::Entity::Identifier getTitleEntity (void) const noexcept
 Get the child that draws the title.
Dialog & setTitleEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the title.
ecs::Entity::Identifier getMessageEntity (void) const noexcept
 Get the child that draws the message.
Dialog & setMessageEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the message.
const std::vector< ecs::Entity::Identifier > & getActionEntities (void) const noexcept
 Get the text buttons built for the actions.
Dialog & setActionEntities (const std::vector< ecs::Entity::Identifier > &identifiers)
 Record the text buttons built for the actions.
ecs::Entity::Identifier getActionRow (void) const noexcept
 Get the row that holds the action buttons, at the bottom of the panel.
Dialog & setActionRow (ecs::Entity::Identifier identifier)
 Record the row that holds the action buttons.
ecs::Entity::Identifier getBackdrop (void) const noexcept
 Get the child that dims the content behind the dialog.
Dialog & setBackdrop (ecs::Entity::Identifier identifier)
 Record the child that dims the content behind the dialog.
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 the dialog panel, in dp.
static constexpr float FullScreenHeight = 640.0f
 Height of a full-screen dialog, in dp.

Detailed Description

State of a dialog: a modal panel with an optional icon, a title, a message and a row of text buttons.

The entities::Dialog widget writes it: the content, and the identifiers of the children it builds (icon, title, message, action buttons, action row, backdrop). systems::Dialog reads it every frame in the Layout phase and turns it into the panel's Layout, Color, Borders, Elevation, Overlay flags and Accessibility, into the text of the title and message children, and into the state of the backdrop.

Whether the dialog is shown, and the callback run when it is dismissed, are not stored here: they are in the components::Overlay of the same entity (see systems::Dialog::show and systems::Dialog::hide).

See also
systems::Dialog, components::Overlay, entities::Dialog

Definition at line 53 of file dialog.hpp.

Member Enumeration Documentation

◆ Variant

Kind of dialog.

systems::Dialog treats two of them specially. A Confirmation dialog shows an "info" icon when no icon is set. A FullScreen dialog has a fixed height, square corners and no backdrop, and a click outside does not dismiss it. Alert and Simple are styled alike.

Definition at line 65 of file dialog.hpp.

Member Function Documentation

◆ getActionEntities()

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

Get the text buttons built for the actions.

Returns
Their identifiers, in action order.

Definition at line 158 of file dialog.cpp.

◆ getActionRow()

ecs::Entity::Identifier guillaume::components::Dialog::getActionRow ( void ) const
noexcept

Get the row that holds the action buttons, at the bottom of the panel.

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

Definition at line 173 of file dialog.cpp.

◆ getActions()

const std::vector< Dialog::Action > & guillaume::components::Dialog::getActions ( void ) const
noexcept

Get the actions of the dialog.

Returns
The actions, in the order of their buttons.

Definition at line 72 of file dialog.cpp.

◆ getBackdrop()

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

Get the child that dims the content behind the dialog.

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

Definition at line 187 of file dialog.cpp.

◆ getEffectiveIcon()

std::string guillaume::components::Dialog::getEffectiveIcon ( void ) const

Get the icon the dialog actually shows.

Returns
The icon set with setIcon(), "info" for a Confirmation dialog without one, or an empty string when there is no hero icon.

Definition at line 106 of file dialog.cpp.

◆ getIcon()

const std::string & guillaume::components::Dialog::getIcon ( void ) const
noexcept

Get the icon chosen for the top of the dialog.

Returns
The glyph name; empty when none was set. See getEffectiveIcon() for the icon actually shown.

Definition at line 92 of file dialog.cpp.

◆ getIconEntity()

ecs::Entity::Identifier guillaume::components::Dialog::getIconEntity ( void ) const
noexcept

Get the child that draws the hero icon.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the dialog has none.

Definition at line 115 of file dialog.cpp.

◆ getMessage()

const std::string & guillaume::components::Dialog::getMessage ( void ) const
noexcept

Get the message (supporting text) of the dialog.

Returns
The message.

Definition at line 58 of file dialog.cpp.

◆ getMessageEntity()

ecs::Entity::Identifier guillaume::components::Dialog::getMessageEntity ( void ) const
noexcept

Get the child that draws the message.

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

Definition at line 143 of file dialog.cpp.

◆ getTitle()

const std::string & guillaume::components::Dialog::getTitle ( void ) const
noexcept

Get the title (headline) of the dialog.

Returns
The title; it is also the dialog's accessible name.

Definition at line 44 of file dialog.cpp.

◆ getTitleEntity()

ecs::Entity::Identifier guillaume::components::Dialog::getTitleEntity ( void ) const
noexcept

Get the child that draws the title.

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

Definition at line 129 of file dialog.cpp.

Here is the caller graph for this function:

◆ getVariant()

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

Get the kind of dialog.

Returns
The variant, Variant::Alert by default.

Definition at line 30 of file dialog.cpp.

Here is the caller graph for this function:

◆ setActionEntities()

Dialog & guillaume::components::Dialog::setActionEntities ( const std::vector< ecs::Entity::Identifier > & identifiers)

Record the text buttons built for the actions.

Marks the component changed only when the list differs.

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

Definition at line 163 of file dialog.cpp.

Here is the call graph for this function:

◆ setActionRow()

Dialog & guillaume::components::Dialog::setActionRow ( ecs::Entity::Identifier identifier)

Record the row that holds the action buttons.

Marks the component changed only when the identifier differs.

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

Definition at line 178 of file dialog.cpp.

Here is the call graph for this function:

◆ setActions()

Dialog & guillaume::components::Dialog::setActions ( std::vector< Action > actions)

Replace the actions of the dialog.

The press handlers are always replaced. The component is marked changed only when the labels differ, because handlers cannot be compared. This does not build the buttons; the widget does.

Parameters
actionsThe new actions, in the order of their buttons.
Returns
This component, for chaining.

Definition at line 77 of file dialog.cpp.

Here is the call graph for this function:

◆ setBackdrop()

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

Record the child that dims the content behind the dialog.

Marks the component changed only when the identifier differs.

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

Definition at line 192 of file dialog.cpp.

Here is the call graph for this function:

◆ setIcon()

Dialog & guillaume::components::Dialog::setIcon ( const std::string & icon)

Choose the icon shown above the title (the hero icon).

With a hero icon, the icon and the title are centered. Marks the component changed only when the name differs.

Parameters
iconThe glyph name; empty for the variant's default.
Returns
This component, for chaining.

Definition at line 97 of file dialog.cpp.

Here is the call graph for this function:

◆ setIconEntity()

Dialog & guillaume::components::Dialog::setIconEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the hero icon.

Marks the component changed only when the identifier differs.

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

Definition at line 120 of file dialog.cpp.

Here is the call graph for this function:

◆ setMessage()

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

Set the message (supporting text) of the dialog.

systems::Dialog copies it to the message child. Marks the component changed only when the text differs.

Parameters
messageThe new message.
Returns
This component, for chaining.

Definition at line 63 of file dialog.cpp.

Here is the call graph for this function:

◆ setMessageEntity()

Dialog & guillaume::components::Dialog::setMessageEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the message.

Marks the component changed only when the identifier differs.

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

Definition at line 148 of file dialog.cpp.

Here is the call graph for this function:

◆ setTitle()

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

Set the title (headline) of the dialog.

systems::Dialog copies it to the title child. Marks the component changed only when the text differs.

Parameters
titleThe new title.
Returns
This component, for chaining.

Definition at line 49 of file dialog.cpp.

Here is the call graph for this function:

◆ setTitleEntity()

Dialog & guillaume::components::Dialog::setTitleEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the title.

Marks the component changed only when the identifier differs.

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

Definition at line 134 of file dialog.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Set the kind of dialog.

Marks the component changed only when the variant differs.

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

Definition at line 35 of file dialog.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ FullScreenHeight

float guillaume::components::Dialog::FullScreenHeight = 640.0f
staticconstexpr

Height of a full-screen dialog, in dp.

Definition at line 81 of file dialog.hpp.

◆ Width

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

Width of the dialog panel, in dp.

Definition at line 78 of file dialog.hpp.


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