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

Styles a tooltip, shows it after its anchor has been hovered for a while and places it next to that anchor. More...

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

Inheritance diagram for guillaume::systems::Tooltip:
Collaboration diagram for guillaume::systems::Tooltip:

Public Member Functions

 Tooltip (void)
 Create the system in the Layout phase.
 ~Tooltip (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one tooltip; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Tooltip >
 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 tooltip its accessibility semantics, its ticker and its dismissal.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Style one tooltip and arrange its children.
static void setAnchor (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, ecs::Entity::Identifier anchorIdentifier)
 Attach the tooltip to the entity whose hover triggers it.
static void setViewport (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float width, float height)
 Set the area the tooltip must stay inside.
static void show (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Show the tooltip next to its anchor at once, without waiting for the enter delay.
static void hide (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Hide the tooltip at once, without waiting for the leave delay.
static void advance (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float deltaTime)
 Advance the hover timers by some elapsed time.
static void place (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Move the tooltip next to its anchor.
static bool hasAnchor (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the tooltip is attached to an entity that still exists.

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 tooltip, shows it after its anchor has been hovered for a while and places it next to that anchor.

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

The visible flag of components::Tooltip is the source of truth: apply() copies it to the tooltip's components::Overlay. A hidden tooltip is not removed, it is painted transparent with no elevation.

The hover delays are counted by the tooltip's own components::Animation, which install() turns into a looping one-second ticker: each sample is converted back into elapsed seconds and passed to advance(). The ticker runs only while the tooltip has an anchor.

The tooltip is placed when it is shown and when the viewport changes. It does not follow an anchor that moves while it is visible.

systems::Tooltip::install(registry, tooltip);
systems::Tooltip::setViewport(registry, tooltip, 1280.0f, 720.0f);
systems::Tooltip::setAnchor(registry, tooltip, button);
// From here on, hovering `button` shows the tooltip.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Give a tooltip its accessibility semantics, its ticker and its dismissal.
Definition tooltip.cpp:94
static void setViewport(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float width, float height)
Set the area the tooltip must stay inside.
Definition tooltip.cpp:158
static void setAnchor(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, ecs::Entity::Identifier anchorIdentifier)
Attach the tooltip to the entity whose hover triggers it.
Definition tooltip.cpp:139
See also
components::Tooltip, components::Overlay, entities::Tooltip, systems::Animation

Definition at line 73 of file tooltip.hpp.

Constructor & Destructor Documentation

◆ Tooltip()

guillaume::systems::Tooltip::Tooltip ( void )

Create the system in the Layout phase.

Definition at line 89 of file tooltip.cpp.

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

Member Function Documentation

◆ advance()

void guillaume::systems::Tooltip::advance ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
float deltaTime )
static

Advance the hover timers by some elapsed time.

While the anchor is hovered, the hover time grows and the tooltip is shown once it reaches the enter delay. While the anchor is not hovered, the hover time is reset, and a visible tooltip is hidden once it has been left for the leave delay. Does nothing when hasAnchor() is false. The ticker calls it on every sample; a test can call it directly to simulate time passing.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.
deltaTimeTime elapsed since the previous call, in seconds.

Definition at line 188 of file tooltip.cpp.

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

◆ apply()

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

Style one tooltip and arrange its children.

This is what update() runs each frame. Call it directly after changing components::Tooltip to see the result before the next frame, which is what the setters of entities::Tooltip do. It does not move the tooltip; place() does.

A plain tooltip is 32 dp high and shows its body only. A Rich tooltip is 64 dp high, shows its title above the body and has a shadow while visible. The width follows the content.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::Tooltip, Layout, Elevation, Borders, Color, Overlay or Accessibility.

Definition at line 272 of file tooltip.cpp.

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

◆ hasAnchor()

bool guillaume::systems::Tooltip::hasAnchor ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the tooltip is attached to an entity that still exists.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.
Returns
False when the anchor is ecs::Entity::InvalidIdentifier or has no components::Transform in the registry, which is the case once the anchor entity has been destroyed.

Definition at line 127 of file tooltip.cpp.

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

◆ hide()

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

Hide the tooltip at once, without waiting for the leave delay.

Clears the visible flag of components::Tooltip and calls apply().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.

Definition at line 180 of file tooltip.cpp.

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

◆ install()

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

Give a tooltip its accessibility semantics, its ticker and its dismissal.

Sets the role of its components::Accessibility to Text with a polite live region; makes its components::Animation a linear, looping, one-second ticker whose samples call advance() with the time elapsed since the previous sample; and makes the dismiss handler of its components::Overlay (Escape) call hide(). The ticker is not started here, see setAnchor(). Call it once, after the entity has its components::Tooltip, Overlay, Elevation, Animation, Accessibility, Layout, Transform, Bound, Color and Borders.

Parameters
componentRegistryThe registry holding the components. It is captured by the handlers and must outlive the entity.
entityIdentifierThe tooltip entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::Accessibility, Animation or Overlay.

Definition at line 94 of file tooltip.cpp.

Here is the call graph for this function:

◆ place()

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

Move the tooltip next to its anchor.

The tooltip is centered horizontally on the anchor and placed right under it, with the anchor's depth and orientation. When a viewport is set, a tooltip that would cross its bottom edge is placed above the anchor instead, and the position is then clamped so the tooltip stays inside the viewport. Does nothing when hasAnchor() is false or when the anchor has no Bound.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.

Definition at line 219 of file tooltip.cpp.

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

◆ setAnchor()

void guillaume::systems::Tooltip::setAnchor ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
ecs::Entity::Identifier anchorIdentifier )
static

Attach the tooltip to the entity whose hover triggers it.

Records the anchor, resets the hover timers and starts the ticker. Passing ecs::Entity::InvalidIdentifier detaches the tooltip and stops the ticker; a tooltip that is visible at that moment stays visible until hide() is called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.
anchorIdentifierThe entity to watch, or ecs::Entity::InvalidIdentifier for none. It needs a Transform and a Bound for the tooltip to be placed, and hover interaction components for the hover to be detected.

Definition at line 139 of file tooltip.cpp.

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

◆ setViewport()

void guillaume::systems::Tooltip::setViewport ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
float width,
float height )
static

Set the area the tooltip must stay inside.

The area starts at the origin. When the tooltip is visible it is placed again at once. Without a viewport the tooltip is always placed under its anchor and never clamped.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.
widthWidth of the area, in dp.
heightHeight of the area, in dp.

Definition at line 158 of file tooltip.cpp.

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

◆ show()

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

Show the tooltip next to its anchor at once, without waiting for the enter delay.

Sets the visible flag of components::Tooltip, then calls place() and apply().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe tooltip entity.

Definition at line 171 of file tooltip.cpp.

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

◆ update()

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

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

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

Parameters
entityIdentifierThe tooltip entity.

Implements guillaume::ecs::System.

Definition at line 341 of file tooltip.cpp.

Here is the call graph for this function:

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