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

Marks an entity as something shown temporarily above the rest of the interface (a dialog, a menu, a drawer, a snackbar, a tooltip) and holds how it is dismissed. More...

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

Inheritance diagram for guillaume::components::Overlay:
Collaboration diagram for guillaume::components::Overlay:

Public Types

using DismissHandler
 Callback run on dismissal.

Public Member Functions

 Overlay (void)=default
 Create a hidden, modal overlay that is dismissed on Escape and on an outside click, and never by itself.
 ~Overlay (void)=default
 Default destructor.
bool isVisible (void) const
 Tell whether the overlay is shown.
Overlay & setVisible (bool visible)
 Show or hide the overlay.
bool isModal (void) const
 Tell whether the overlay is modal.
Overlay & setModal (bool modal)
 Declare the overlay modal (it must be answered before the rest of the interface is used) or not.
bool dismissesOnOutsideClick (void) const
 Tell whether a click outside the overlay dismisses it.
Overlay & setDismissOnOutsideClick (bool dismiss)
 Choose whether a click outside the overlay dismisses it.
bool dismissesOnEscape (void) const
 Tell whether the Escape key dismisses the overlay.
Overlay & setDismissOnEscape (bool dismiss)
 Choose whether the Escape key dismisses the overlay.
float getAutoDismiss (void) const
 Get how long the overlay stays shown before it is dismissed by itself.
Overlay & setAutoDismiss (float delay)
 Set how long the overlay stays shown before it is dismissed by itself.
bool hasAutoDismiss (void) const
 Tell whether the overlay is dismissed by itself after a delay.
float getElapsed (void) const
 Get how long the overlay has been counting towards its auto-dismissal.
Overlay & setElapsed (float elapsed)
 Store the time counted towards auto-dismissal.
Overlay & setOnDismissHandler (const DismissHandler &handler)
 Set the callback run when systems::Overlay dismisses the overlay.
DismissHandler getOnDismissHandler (void) const
 Get the callback run when the overlay is dismissed.
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.

Detailed Description

Marks an entity as something shown temporarily above the rest of the interface (a dialog, a menu, a drawer, a snackbar, a tooltip) and holds how it is dismissed.

The widget systems (systems::Dialog, systems::Menu, ...) write the flags, and their show and hide functions write the visibility. systems::Overlay reads the component in the Event phase: it keeps the visible overlays in a stack and dismisses the top one on Escape or when its auto-dismiss delay has elapsed. A click outside the top overlay dismisses it only when the application reports the click with systems::Overlay::handleOutsideClick; no system calls it.

Dismissing sets the overlay invisible, resets its elapsed time and calls the dismiss handler. Setting a shown overlay invisible by hand has the same effect on the next frame, handler included.

The component holds no drawing state: it is up to the widget system to draw a hidden overlay transparent.

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

Definition at line 54 of file overlay.hpp.

Member Typedef Documentation

◆ DismissHandler

Initial value:
std::function<void(void)>

Callback run on dismissal.

Definition at line 57 of file overlay.hpp.

Member Function Documentation

◆ dismissesOnEscape()

bool guillaume::components::Overlay::dismissesOnEscape ( void ) const

Tell whether the Escape key dismisses the overlay.

Returns
True when it does, which is the default.

Definition at line 75 of file overlay.cpp.

◆ dismissesOnOutsideClick()

bool guillaume::components::Overlay::dismissesOnOutsideClick ( void ) const

Tell whether a click outside the overlay dismisses it.

Returns
True when it does, which is the default.

Definition at line 60 of file overlay.cpp.

◆ getAutoDismiss()

float guillaume::components::Overlay::getAutoDismiss ( void ) const

Get how long the overlay stays shown before it is dismissed by itself.

Returns
The delay, in seconds; 0 means it never is.

Definition at line 90 of file overlay.cpp.

◆ getElapsed()

float guillaume::components::Overlay::getElapsed ( void ) const

Get how long the overlay has been counting towards its auto-dismissal.

Returns
The time, in seconds; 0 for an overlay without an auto-dismiss delay.

Definition at line 110 of file overlay.cpp.

◆ getOnDismissHandler()

Overlay::DismissHandler guillaume::components::Overlay::getOnDismissHandler ( void ) const

Get the callback run when the overlay is dismissed.

Returns
A copy of the callback; empty when none is set.

Definition at line 127 of file overlay.cpp.

◆ hasAutoDismiss()

bool guillaume::components::Overlay::hasAutoDismiss ( void ) const

Tell whether the overlay is dismissed by itself after a delay.

Returns
True when the auto-dismiss delay is greater than 0.

Definition at line 105 of file overlay.cpp.

◆ isModal()

bool guillaume::components::Overlay::isModal ( void ) const

Tell whether the overlay is modal.

Returns
True when modal, which is the default.

Definition at line 45 of file overlay.cpp.

◆ isVisible()

bool guillaume::components::Overlay::isVisible ( void ) const

Tell whether the overlay is shown.

Returns
True when shown; false by default.

Definition at line 27 of file overlay.cpp.

◆ setAutoDismiss()

Overlay & guillaume::components::Overlay::setAutoDismiss ( float delay)

Set how long the overlay stays shown before it is dismissed by itself.

The countdown only runs while the overlay is the top one. Marks the component changed only when the value differs.

Parameters
delayThe delay, in seconds; 0 or less disables auto-dismissal.
Returns
This component, for chaining.

Definition at line 95 of file overlay.cpp.

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

◆ setDismissOnEscape()

Overlay & guillaume::components::Overlay::setDismissOnEscape ( bool dismiss)

Choose whether the Escape key dismisses the overlay.

Escape only acts on the top overlay. Marks the component changed only when the flag differs.

Parameters
dismissTrue to dismiss on Escape.
Returns
This component, for chaining.

Definition at line 80 of file overlay.cpp.

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

◆ setDismissOnOutsideClick()

Overlay & guillaume::components::Overlay::setDismissOnOutsideClick ( bool dismiss)

Choose whether a click outside the overlay dismisses it.

Read by systems::Overlay::handleOutsideClick, for the top overlay only. Marks the component changed only when the flag differs.

Parameters
dismissTrue to dismiss on an outside click.
Returns
This component, for chaining.

Definition at line 65 of file overlay.cpp.

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

◆ setElapsed()

Overlay & guillaume::components::Overlay::setElapsed ( float elapsed)

Store the time counted towards auto-dismissal.

systems::Overlay adds the frame time to it; write 0 to restart the countdown. Does not mark the component changed.

Parameters
elapsedThe new elapsed time, in seconds.
Returns
This component, for chaining.

Definition at line 115 of file overlay.cpp.

Here is the call graph for this function:

◆ setModal()

Overlay & guillaume::components::Overlay::setModal ( bool modal)

Declare the overlay modal (it must be answered before the rest of the interface is used) or not.

The flag is a declaration made by the widget system: a dialog is modal, a snackbar or a tooltip is not. Marks the component changed only when the flag differs.

Parameters
modalTrue for a modal overlay.
Returns
This component, for chaining.

Definition at line 50 of file overlay.cpp.

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

◆ setOnDismissHandler()

Overlay & guillaume::components::Overlay::setOnDismissHandler ( const DismissHandler & handler)

Set the callback run when systems::Overlay dismisses the overlay.

Widget systems install their own here (for example to hide the widget and call the user's callback), so replacing it on a widget disconnects that. Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 121 of file overlay.cpp.

Here is the call graph for this function:

◆ setVisible()

Overlay & guillaume::components::Overlay::setVisible ( bool visible)

Show or hide the overlay.

Hiding also resets the elapsed time to 0. On its next pass, systems::Overlay puts a newly shown overlay on top of its stack, and dismisses (handler included) one that was hidden this way. Marks the component changed only when the flag differs.

Parameters
visibleTrue to show the overlay.
Returns
This component, for chaining.

Definition at line 32 of file overlay.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: