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

A small label that appears next to another entity while the pointer or a hand hovers that entity. More...

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

Inheritance diagram for guillaume::entities::Tooltip:
Collaboration diagram for guillaume::entities::Tooltip:

Classes

class  Builder
 Configures a Tooltip, then builds it and registers it in the entity registry given at construction. More...

Public Types

using Variant = components::Tooltip::Variant
 Look of the tooltip: Plain (one text) or Rich (title and text).
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Animation, components::Accessibility, components::Tooltip >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~Tooltip (void) override=default
 Default destructor.
Tooltip & setVariant (Variant variant)
 Change the tooltip variant.
Variant getVariant (void) const
 Get the tooltip variant.
Tooltip & setText (const std::string &text)
 Change the body text.
Tooltip & setAnchor (std::shared_ptr< ecs::Entity > anchor)
 Choose the entity whose hover shows the tooltip.
Tooltip & setEnterDelay (float seconds)
 Set how long the anchor must be hovered before the tooltip shows (Paper enterTouchDelay).
Tooltip & setLeaveDelay (float seconds)
 Set how long the tooltip stays shown after the anchor is left (Paper leaveTouchDelay).
float getEnterDelay (void) const
 Get how long the anchor must be hovered before the tooltip shows.
float getLeaveDelay (void) const
 Get how long the tooltip stays shown after the anchor is left.
Tooltip & setViewport (float width, float height)
 Set the area the tooltip must stay inside, usually the window.
Tooltip & show (void)
 Show the tooltip at once, without waiting for the enter delay.
Tooltip & hide (void)
 Hide the tooltip at once, without waiting for the leave delay. Restyles at once.
bool isVisible (void) const
 Check whether the tooltip is shown.
void advance (float deltaTime)
 Advance the hover delays by hand.
void place (void)
 Move the tooltip next to its anchor.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Animation, components::Accessibility, components::Tooltip >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Tooltip > create (Arguments &&...arguments)
 Create a tooltip and its children, without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Static Public Attributes

static constexpr float DefaultEnterDelay
 Default time the anchor must be hovered before the tooltip shows: 0.5 second (Paper enterTouchDelay).
static constexpr float DefaultLeaveDelay
 Default time after the anchor is left before the tooltip hides: 1.5 seconds (Paper leaveTouchDelay).
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Additional Inherited Members

Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Animation, components::Accessibility, components::Tooltip >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A small label that appears next to another entity while the pointer or a hand hovers that entity.

Its state lives in components::Tooltip (variant, text, title, anchor, hover delays and their timers, visibility). systems::Tooltip styles the tooltip and arranges its children each frame, in the Layout phase; it also holds the rules that run the hover delays and place the tooltip. The class itself holds no field: its setters write the component.

Tooltip::Builder builder(getComponentRegistry(), getEntityRegistry());
auto tooltip = builder.makeTooltip(parent, Tooltip::Variant::Plain,
"Save the document");
tooltip->setAnchor(saveButton);
Configures a Tooltip, then builds it and registers it in the entity registry given at construction.
Definition tooltip.hpp:133

Tooltip::create(registry, config, variant, text, title) builds the same widget without registering it in an entity registry.

Showing and hiding: a tooltip is created hidden and does nothing until setAnchor() gives it an anchor. From then on it shows itself once the anchor has been hovered for the enter delay (0.5 second by default) and hides itself once the anchor has been left for the leave delay (1.5 seconds by default). show() and hide() switch it by hand, and systems::Overlay hides it when the user presses Escape while it is the topmost visible overlay. There is no dismiss callback.

The delays are counted by the tooltip's own components::Animation, a looping one-second animation that systems::Animation samples every frame, in the Event phase, and that setAnchor() starts.

The variants are:

  • Plain: one text, in a 32 dp high label on the inverse surface color.
  • Rich: a title (TitleSmall type role) above the text, in a 64 dp high, elevated label on a surface container color.

Things to know:

  • The anchor needs a components::MouseHoverInteraction or a components::HandHoverInteraction, and must be enabled, for its hover to be seen.
  • The tooltip stores the identifier of its anchor, not the entity: it does not keep the anchor alive.
  • The tooltip is placed when it is shown, not every frame: it does not follow an anchor that moves while it is visible.
  • It is only kept inside the screen when setViewport() gave it an area.
  • A hidden tooltip is painted transparent.
  • systems::Tooltip overwrites the layout settings, height, color, corner radius and elevation every frame.
  • The title is fixed at creation.
See also
components::Tooltip, systems::Tooltip, systems::Overlay

Definition at line 105 of file tooltip.hpp.

Member Typedef Documentation

◆ Variant

Look of the tooltip: Plain (one text) or Rich (title and text).

Definition at line 112 of file tooltip.hpp.

Member Function Documentation

◆ advance()

void guillaume::entities::Tooltip::advance ( float deltaTime)

Advance the hover delays by hand.

The tooltip's own looping animation calls this every frame once an anchor is set; call it yourself only in tests or when you drive time some other way. Shows the tooltip once the anchor has been hovered for the enter delay and hides it once the anchor has been left for the leave delay. Does nothing without a live anchor.

Parameters
deltaTimeThe time elapsed since the last call, in seconds.

Definition at line 191 of file tooltip.cpp.

Here is the call graph for this function:

◆ create()

template<typename... Arguments>
std::shared_ptr< Tooltip > guillaume::entities::Tooltip::create ( Arguments &&... arguments)
inlinestatic

Create a tooltip and its children, without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant, text, title). The children are built here, by build(), because a child needs its parent to be owned by a shared pointer.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new tooltip, hidden, with no parent and no anchor.

Definition at line 237 of file tooltip.hpp.

Here is the caller graph for this function:

◆ getEnterDelay()

float guillaume::entities::Tooltip::getEnterDelay ( void ) const

Get how long the anchor must be hovered before the tooltip shows.

Returns
The delay, in seconds.

Definition at line 151 of file tooltip.cpp.

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

◆ getLeaveDelay()

float guillaume::entities::Tooltip::getLeaveDelay ( void ) const

Get how long the tooltip stays shown after the anchor is left.

Returns
The delay, in seconds.

Definition at line 158 of file tooltip.cpp.

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

◆ getVariant()

Tooltip::Variant guillaume::entities::Tooltip::getVariant ( void ) const

Get the tooltip variant.

Returns
The variant stored in components::Tooltip.

Definition at line 212 of file tooltip.cpp.

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

◆ hide()

Tooltip & guillaume::entities::Tooltip::hide ( void )

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

Returns
This tooltip, for chaining.

Definition at line 178 of file tooltip.cpp.

Here is the call graph for this function:

◆ isVisible()

bool guillaume::entities::Tooltip::isVisible ( void ) const

Check whether the tooltip is shown.

Returns
True when shown. False for a tooltip that was never shown.

Definition at line 184 of file tooltip.cpp.

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

◆ place()

void guillaume::entities::Tooltip::place ( void )

Move the tooltip next to its anchor.

The tooltip is centered horizontally on the anchor and placed just under it. When setViewport() gave an area, it goes above the anchor if it would overflow the bottom of the area, and is clamped to the area. Called by show(); call it again after moving the anchor. Does nothing when the anchor is missing or has no Transform and Bound.

Definition at line 197 of file tooltip.cpp.

Here is the call graph for this function:

◆ setAnchor()

Tooltip & guillaume::entities::Tooltip::setAnchor ( std::shared_ptr< ecs::Entity > anchor)

Choose the entity whose hover shows the tooltip.

Resets the hover timers and starts the animation that counts the delays. From then on, hovering the anchor for the enter delay shows the tooltip next to it, and leaving it for the leave delay hides it. The anchor needs a components::MouseHoverInteraction or a components::HandHoverInteraction. Only its identifier is stored.

Parameters
anchorThe entity to watch. nullptr detaches the tooltip and stops the animation; a tooltip that is shown stays shown until hide() is called.
Returns
This tooltip, for chaining.

Definition at line 126 of file tooltip.cpp.

Here is the call graph for this function:

◆ setEnterDelay()

Tooltip & guillaume::entities::Tooltip::setEnterDelay ( float seconds)

Set how long the anchor must be hovered before the tooltip shows (Paper enterTouchDelay).

Parameters
secondsThe delay, in seconds, 0 or more. Default: DefaultEnterDelay.
Returns
This tooltip, for chaining.
Exceptions
std::invalid_argumentIf seconds is negative.

Definition at line 135 of file tooltip.cpp.

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

◆ setLeaveDelay()

Tooltip & guillaume::entities::Tooltip::setLeaveDelay ( float seconds)

Set how long the tooltip stays shown after the anchor is left (Paper leaveTouchDelay).

Parameters
secondsThe delay, in seconds, 0 or more. Default: DefaultLeaveDelay.
Returns
This tooltip, for chaining.
Exceptions
std::invalid_argumentIf seconds is negative.

Definition at line 143 of file tooltip.cpp.

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

◆ setText()

Tooltip & guillaume::entities::Tooltip::setText ( const std::string & text)

Change the body text.

Builds the text child when the tooltip had none and text is not empty, then restyles at once.

Parameters
textThe new body text.
Returns
This tooltip, for chaining.

Definition at line 219 of file tooltip.cpp.

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

◆ setVariant()

Tooltip & guillaume::entities::Tooltip::setVariant ( Variant variant)

Change the tooltip variant.

Builds the title child when the new variant is Rich, the title is not empty and the child does not exist yet, then restyles at once. Switching back to Plain takes the title out of the layout.

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

Definition at line 202 of file tooltip.cpp.

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

◆ setViewport()

Tooltip & guillaume::entities::Tooltip::setViewport ( float width,
float height )

Set the area the tooltip must stay inside, usually the window.

The area starts at (0, 0), in the coordinates of the anchor's pose. Places the tooltip again when it is shown. Without an area, the tooltip is always placed under its anchor, unclamped.

Parameters
widthThe width of the area, in dp.
heightThe height of the area, in dp.
Returns
This tooltip, for chaining.

Definition at line 165 of file tooltip.cpp.

Here is the call graph for this function:

◆ show()

Tooltip & guillaume::entities::Tooltip::show ( void )

Show the tooltip at once, without waiting for the enter delay.

Places it next to its anchor (see place()) and restyles at once. Without an anchor it is shown where it is. While the anchor is not hovered, the leave delay hides it again.

Returns
This tooltip, for chaining.

Definition at line 172 of file tooltip.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ DefaultEnterDelay

float guillaume::entities::Tooltip::DefaultEnterDelay
staticconstexpr
Initial value:

Default time the anchor must be hovered before the tooltip shows: 0.5 second (Paper enterTouchDelay).

Definition at line 118 of file tooltip.hpp.

◆ DefaultLeaveDelay

float guillaume::entities::Tooltip::DefaultLeaveDelay
staticconstexpr
Initial value:

Default time after the anchor is left before the tooltip hides: 1.5 seconds (Paper leaveTouchDelay).

Definition at line 125 of file tooltip.hpp.


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