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

Keeps the stack of open overlays (dialogs, menus, snackbars) and closes the top one on Escape or when its delay runs out. More...

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

Inheritance diagram for guillaume::systems::Overlay:
Collaboration diagram for guillaume::systems::Overlay:

Public Member Functions

 Overlay (event::EventBus &eventBus, utility::Engine &engine)
 Create the system, in the Event phase, and subscribe it to keyboard events (for Escape).
 ~Overlay (void) override=default
 Default destructor.
void prepare (void) override
 Once per frame: take the next pending keyboard event, count down the top overlay, and handle Escape.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Make the stack agree with the visibility of one overlay.
void show (const ecs::Entity::Identifier &entityIdentifier)
 Open an overlay at once: push it on top of the stack, make its component visible and turn viewport input capture off.
void dismiss (void)
 Close the top overlay.
void dismiss (const ecs::Entity::Identifier &entityIdentifier)
 Close one overlay, wherever it is in the stack.
bool isOpen (const ecs::Entity::Identifier &entityIdentifier) const
 Whether an overlay is open, that is, in the stack.
ecs::Entity::Identifier getTop (void) const
 The overlay opened last, the one Escape and the countdown apply to.
std::size_t getDepth (void) const
 The number of open overlays.
void handleEscape (void)
 Close the top overlay if its component says it dismisses on Escape. Called by prepare() on an Escape key-down.
void handleOutsideClick (const utility::math::Vector2F &point)
 Close the top overlay if a click landed outside it and its component says it dismisses on outside clicks.
void advance (float deltaTime)
 Count down the top overlay and close it when its time is up.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Overlay, components::Transform, components::Bound >
 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 cleanup (void)
 Called once per pass, after the last update().
Public Member Functions inherited from guillaume::event::EventManager< utility::event::KeyboardEvent >
 EventManager (EventBus &eventBus)
 Subscribe to a bus; events of type EventType published after this call are queued.
virtual ~EventManager (void)=default
 Virtual destructor.
bool hasPendingEvents (void) const
 Tell whether at least one event is queued, waiting for consumeNextEvent().

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.
Protected Member Functions inherited from guillaume::event::EventManager< utility::event::KeyboardEvent >
void consumeNextEvent (void)
 Take the oldest queued event and make it the last event.
std::shared_ptr< EventType > getLastEvent (void)
 Get the event taken by the most recent consumeNextEvent() that found one.

Detailed Description

Keeps the stack of open overlays (dialogs, menus, snackbars) and closes the top one on Escape or when its delay runs out.

Runs in the Event phase on entities that have a components::Overlay, a Transform and a Bound. An overlay is open while it is in the stack; the last one opened is the top. Each frame the system:

  • pushes an overlay whose component became visible, and dismisses one whose component became hidden, so writing components::Overlay::setVisible is enough to open or close one;
  • adds the frame time to the elapsed time of the top overlay and dismisses it once its auto-dismiss delay is reached (only the top overlay counts down);
  • dismisses the top overlay on an Escape key-down event, if it dismisses on Escape.

Dismissing writes visible = false and elapsed = 0 on the component and calls its dismiss handler; widget systems such as systems::Snackbar rely on that handler to learn about a timeout. While at least one overlay is open, the engine is told not to capture viewport input; capture is given back when the stack empties.

Note
Outside clicks are not detected by the system itself: the code that owns the pointer position calls handleOutsideClick().
The modal flag of components::Overlay is not read here.
show(), dismiss(), handleEscape(), handleOutsideClick() and advance() read components through the registry bound to the system. Outside the frame loop, call ecs::System::bindComponentRegistry first; without it only the stack changes (the component is not written and the dismiss handler is not called).
See also
components::Overlay
systems::Snackbar

Definition at line 78 of file overlay.hpp.

Constructor & Destructor Documentation

◆ Overlay()

guillaume::systems::Overlay::Overlay ( event::EventBus & eventBus,
utility::Engine & engine )

Create the system, in the Event phase, and subscribe it to keyboard events (for Escape).

Parameters
eventBusThe event bus delivering the keyboard events.
engineThe engine told whether the viewport may capture input. It must outlive the system.

Definition at line 29 of file overlay.cpp.

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

Member Function Documentation

◆ advance()

void guillaume::systems::Overlay::advance ( float deltaTime)

Count down the top overlay and close it when its time is up.

Adds deltaTime to the elapsed time of the top overlay when it has an auto-dismiss delay, and dismisses it once the elapsed time reaches the delay. Called by prepare() each frame.

Parameters
deltaTimeThe time to add, in seconds.

Definition at line 199 of file overlay.cpp.

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

◆ dismiss() [1/2]

void guillaume::systems::Overlay::dismiss ( const ecs::Entity::Identifier & entityIdentifier)

Close one overlay, wherever it is in the stack.

Same effects as dismiss(void), on that overlay. Does nothing when it is not open.

Parameters
entityIdentifierThe overlay entity to close.

Definition at line 111 of file overlay.cpp.

Here is the call graph for this function:

◆ dismiss() [2/2]

void guillaume::systems::Overlay::dismiss ( void )

Close the top overlay.

Removes it from the stack, hides its component, resets its elapsed time to 0 and calls its dismiss handler. Viewport input capture is turned back on when the stack becomes empty. Does nothing when no overlay is open.

Definition at line 88 of file overlay.cpp.

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

◆ getDepth()

std::size_t guillaume::systems::Overlay::getDepth ( void ) const

The number of open overlays.

Returns
The size of the stack, 0 when none is open.

Definition at line 145 of file overlay.cpp.

◆ getTop()

ecs::Entity::Identifier guillaume::systems::Overlay::getTop ( void ) const

The overlay opened last, the one Escape and the countdown apply to.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when no overlay is open.

Definition at line 140 of file overlay.cpp.

◆ handleEscape()

void guillaume::systems::Overlay::handleEscape ( void )

Close the top overlay if its component says it dismisses on Escape. Called by prepare() on an Escape key-down.

Definition at line 150 of file overlay.cpp.

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

◆ handleOutsideClick()

void guillaume::systems::Overlay::handleOutsideClick ( const utility::math::Vector2F & point)

Close the top overlay if a click landed outside it and its component says it dismisses on outside clicks.

"Inside" is the axis-aligned rectangle starting at the x and y of the overlay's Transform position, with the size of its Bound. The system does not call this itself.

Parameters
pointThe click position, in the coordinate space of the overlay's Transform position.

Definition at line 163 of file overlay.cpp.

Here is the call graph for this function:

◆ isOpen()

bool guillaume::systems::Overlay::isOpen ( const ecs::Entity::Identifier & entityIdentifier) const

Whether an overlay is open, that is, in the stack.

Parameters
entityIdentifierThe overlay entity to look for.
Returns
True when the overlay is in the stack.

Definition at line 134 of file overlay.cpp.

Here is the caller graph for this function:

◆ prepare()

void guillaume::systems::Overlay::prepare ( void )
overridevirtual

Once per frame: take the next pending keyboard event, count down the top overlay, and handle Escape.

The time passed to advance() is measured on a steady clock since the previous call. Escape is recognized by its scan code, on a key-down event.

Reimplemented from guillaume::ecs::System.

Definition at line 39 of file overlay.cpp.

Here is the call graph for this function:

◆ show()

void guillaume::systems::Overlay::show ( const ecs::Entity::Identifier & entityIdentifier)

Open an overlay at once: push it on top of the stack, make its component visible and turn viewport input capture off.

Does nothing when the overlay is already open.

Parameters
entityIdentifierThe overlay entity to open.

Definition at line 72 of file overlay.cpp.

Here is the call graph for this function:

◆ update()

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

Make the stack agree with the visibility of one overlay.

A visible overlay that is not open is pushed on top and viewport input capture is turned off; a hidden overlay that is open is dismissed (its dismiss handler is called).

Parameters
entityIdentifierThe entity holding the components::Overlay.

Implements guillaume::ecs::System.

Definition at line 56 of file overlay.cpp.

Here is the call graph for this function:

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