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

Styles a dialog panel, stacks its icon, title, message and action row, and shows or hides the backdrop behind it. More...

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

Inheritance diagram for guillaume::systems::Dialog:
Collaboration diagram for guillaume::systems::Dialog:

Public Member Functions

 Dialog (void)
 Create the system in the Layout phase.
 ~Dialog (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one dialog; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Dialog >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Give a dialog panel its accessibility semantics.
static void installTitle (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Expose the title child to assistive technology as a header.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Style one dialog, arrange its children and place its backdrop.
static void show (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Show the dialog and its backdrop.
static void hide (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Hide the dialog and its backdrop without telling anyone.
static void dismiss (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Close the dialog as the user would with Escape or a click outside.
static void pressAction (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Activate an action as a press on its button would.

Static Public Attributes

static constexpr float Padding = theme::SpacingScale::get(6)
 Space between the edge of the panel and its content: 24 dp.
static constexpr float Spacing = theme::SpacingScale::get(4)
 Gap between two stacked sections of the dialog: 16 dp.

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
bool requireComponent (const ecs::Entity::Identifier &entityIdentifier)
 Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.

Detailed Description

Styles a dialog panel, stacks its icon, title, message and action row, and shows or hides the backdrop behind it.

Runs in the Layout phase on every entity that has a components::Dialog. It is registered after systems::Layout, so the children are already measured when it arranges them.

Whether the dialog is shown is the visible flag of its components::Overlay; show(), hide() and dismiss() change it. A dialog is always modal. It closes on Escape, and on a click outside unless its variant is FullScreen.

systems::Dialog::show(registry, dialog);
// ... later, from a "Cancel" action:
systems::Dialog::dismiss(registry, dialog);
static void dismiss(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Close the dialog as the user would with Escape or a click outside.
Definition dialog.cpp:131
static void show(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Show the dialog and its backdrop.
Definition dialog.cpp:115
See also
components::Dialog, components::Overlay, entities::Dialog, systems::Backdrop

Definition at line 67 of file dialog.hpp.

Constructor & Destructor Documentation

◆ Dialog()

guillaume::systems::Dialog::Dialog ( void )

Create the system in the Layout phase.

Definition at line 80 of file dialog.cpp.

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

Member Function Documentation

◆ apply()

void guillaume::systems::Dialog::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Style one dialog, arrange its children and place its backdrop.

This is what update() runs each frame. Call it directly after changing components::Dialog to see the result before the next frame, which is what the setters of entities::Dialog do.

The children are stacked in the order icon, title, message, action row, skipping the ones that do not exist; they are centered horizontally when the dialog has an icon and start-aligned otherwise. A FullScreen dialog has a fixed height of components::Dialog::FullScreenHeight, square corners and no backdrop. The backdrop is visible only while the dialog is, and is given the pose and size of the panel.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks one of the components listed in install().

Definition at line 170 of file dialog.cpp.

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

◆ dismiss()

void guillaume::systems::Dialog::dismiss ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Close the dialog as the user would with Escape or a click outside.

Hides the dialog, then calls the dismiss handler of its components::Overlay when there is one. Does nothing when the dialog is already hidden.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.

Definition at line 131 of file dialog.cpp.

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

◆ hide()

void guillaume::systems::Dialog::hide ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Hide the dialog and its backdrop without telling anyone.

Clears the visible flag of the dialog's components::Overlay and calls apply(). The dismiss handler is not called: use dismiss() when the application must be notified.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.

Definition at line 123 of file dialog.cpp.

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

◆ install()

void guillaume::systems::Dialog::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Give a dialog panel its accessibility semantics.

Sets the role of the panel's components::Accessibility to Dialog, makes the panel itself non-focusable, then calls installTitle(). Call it once, after the entity has its components::Dialog, Overlay, Elevation, Accessibility, Layout, Transform, Bound, Color and Borders.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity has no components::Accessibility or components::Dialog.

Definition at line 85 of file dialog.cpp.

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

◆ installTitle()

void guillaume::systems::Dialog::installTitle ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Expose the title child to assistive technology as a header.

Adds a components::Accessibility to the title entity recorded in components::Dialog when it has none, sets its role to Header and its label to the title text, and makes it non-focusable. Call it again when the title child is created after install(). Does nothing when no title child is recorded.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.

Definition at line 96 of file dialog.cpp.

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

◆ pressAction()

void guillaume::systems::Dialog::pressAction ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Activate an action as a press on its button would.

Calls the press handler of the action when it has one. The dialog stays open: a handler that should close it calls hide() or dismiss() itself.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.
indexPosition of the action in the action list of components::Dialog, starting at 0. An index past the end is ignored.

Definition at line 151 of file dialog.cpp.

Here is the call graph for this function:

◆ show()

void guillaume::systems::Dialog::show ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Show the dialog and its backdrop.

Sets the visible flag of the dialog's components::Overlay and calls apply().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe dialog entity.

Definition at line 115 of file dialog.cpp.

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

◆ update()

void guillaume::systems::Dialog::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Run apply() on one dialog; called by the frame loop.

Logs a warning and does nothing when the entity has no components::Dialog.

Parameters
entityIdentifierThe dialog entity.

Implements guillaume::ecs::System.

Definition at line 258 of file dialog.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ Padding

float guillaume::systems::Dialog::Padding = theme::SpacingScale::get(6)
staticconstexpr

Space between the edge of the panel and its content: 24 dp.

Definition at line 71 of file dialog.hpp.

◆ Spacing

float guillaume::systems::Dialog::Spacing = theme::SpacingScale::get(4)
staticconstexpr

Gap between two stacked sections of the dialog: 16 dp.

Definition at line 74 of file dialog.hpp.


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