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

State of a tooltip: a small label that appears under an entity (its anchor) after the pointer has rested on it. More...

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

Inheritance diagram for guillaume::components::Tooltip:
Collaboration diagram for guillaume::components::Tooltip:

Public Types

enum class  Variant { Plain , Rich }
 Kind of tooltip. More...
using Viewport = std::pair<float, float>

Public Member Functions

 Tooltip (void)=default
 Create the configuration of a hidden, empty plain tooltip with no anchor and the default delays.
 ~Tooltip (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the kind of tooltip.
Tooltip & setVariant (Variant variant)
 Set the kind of tooltip.
const std::string & getText (void) const noexcept
 Get the body text.
Tooltip & setText (const std::string &text)
 Set the body text.
const std::string & getTitle (void) const noexcept
 Get the title of a rich tooltip.
Tooltip & setTitle (const std::string &title)
 Set the title of a rich tooltip.
ecs::Entity::Identifier getTitleEntity (void) const noexcept
 Get the child that draws the title.
Tooltip & setTitleEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the title.
ecs::Entity::Identifier getTextEntity (void) const noexcept
 Get the child that draws the body text.
Tooltip & setTextEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the body text.
ecs::Entity::Identifier getAnchor (void) const noexcept
 Get the entity whose hover shows the tooltip.
Tooltip & setAnchor (ecs::Entity::Identifier identifier)
 Record the entity whose hover shows the tooltip.
float getEnterDelay (void) const noexcept
 Get how long the anchor must be hovered before the tooltip shows.
Tooltip & setEnterDelay (float seconds)
 Set how long the anchor must be hovered before the tooltip shows.
float getLeaveDelay (void) const noexcept
 Get how long the tooltip stays after the pointer leaves the anchor.
Tooltip & setLeaveDelay (float seconds)
 Set how long the tooltip stays after the pointer leaves the anchor.
float getHoverTime (void) const noexcept
 Get how long the anchor has been hovered without a break.
Tooltip & setHoverTime (float seconds)
 Store how long the anchor has been hovered.
float getLeaveTime (void) const noexcept
 Get how long ago the pointer left the anchor while the tooltip was shown.
Tooltip & setLeaveTime (float seconds)
 Store how long ago the pointer left the anchor.
float getLastProgress (void) const noexcept
 Get the progress the timer animation reported last.
Tooltip & setLastProgress (float progress)
 Store the progress the timer animation reported last.
bool isVisible (void) const noexcept
 Tell whether the tooltip is shown.
Tooltip & setVisible (bool visible)
 Record whether the tooltip is shown.
const std::optional< Viewport > & getViewport (void) const noexcept
 Get the area the tooltip must stay inside.
Tooltip & setViewport (std::optional< Viewport > viewport)
 Set the area the tooltip must stay inside.
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.

Static Public Attributes

static constexpr float DefaultEnterDelay = 0.5f
static constexpr float DefaultLeaveDelay = 1.5f

Detailed Description

State of a tooltip: a small label that appears under an entity (its anchor) after the pointer has rested on it.

It holds two kinds of state. The configuration (variant, texts, anchor, delays, viewport) is written by the entities::Tooltip widget. The running state (hover timers, visibility) is written by systems::Tooltip, which a looping components::Animation on the same entity calls each frame to advance the timers. In the Layout phase, systems::Tooltip turns all of it into the tooltip's Layout, Color, Borders, Elevation, Overlay and Accessibility, and into the text and color of its children.

The tooltip shows once its anchor has been hovered for the enter delay, and hides once the anchor has been left for the leave delay. A hidden tooltip is drawn transparent.

See also
systems::Tooltip, components::Overlay, entities::Tooltip

Definition at line 54 of file tooltip.hpp.

Member Typedef Documentation

◆ Viewport

using guillaume::components::Tooltip::Viewport = std::pair<float, float>

Area the tooltip must stay inside, as (width, height) in dp, with its origin at (0, 0).

Definition at line 67 of file tooltip.hpp.

Member Enumeration Documentation

◆ Variant

Kind of tooltip.

Plain is a 32 dp high dark label with one text. Rich is a 64 dp high elevated card with a title above the text.

Definition at line 63 of file tooltip.hpp.

Member Function Documentation

◆ getAnchor()

ecs::Entity::Identifier guillaume::components::Tooltip::getAnchor ( void ) const
noexcept

Get the entity whose hover shows the tooltip.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the tooltip has no anchor.

Definition at line 99 of file tooltip.cpp.

Here is the caller graph for this function:

◆ getEnterDelay()

float guillaume::components::Tooltip::getEnterDelay ( void ) const
noexcept

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

Returns
The delay, in seconds.

Definition at line 113 of file tooltip.cpp.

◆ getHoverTime()

float guillaume::components::Tooltip::getHoverTime ( void ) const
noexcept

Get how long the anchor has been hovered without a break.

Returns
The time, in seconds; 0 while the anchor is not hovered.

Definition at line 147 of file tooltip.cpp.

◆ getLastProgress()

float guillaume::components::Tooltip::getLastProgress ( void ) const
noexcept

Get the progress the timer animation reported last.

Returns
The progress, 0 to 1.

Definition at line 175 of file tooltip.cpp.

Here is the caller graph for this function:

◆ getLeaveDelay()

float guillaume::components::Tooltip::getLeaveDelay ( void ) const
noexcept

Get how long the tooltip stays after the pointer leaves the anchor.

Returns
The delay, in seconds.

Definition at line 130 of file tooltip.cpp.

◆ getLeaveTime()

float guillaume::components::Tooltip::getLeaveTime ( void ) const
noexcept

Get how long ago the pointer left the anchor while the tooltip was shown.

Returns
The time, in seconds; 0 while the anchor is hovered or the tooltip is hidden.

Definition at line 161 of file tooltip.cpp.

◆ getText()

const std::string & guillaume::components::Tooltip::getText ( void ) const
noexcept

Get the body text.

Returns
The text; it is also the tooltip's accessible name.

Definition at line 43 of file tooltip.cpp.

◆ getTextEntity()

ecs::Entity::Identifier guillaume::components::Tooltip::getTextEntity ( void ) const
noexcept

Get the child that draws the body text.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 85 of file tooltip.cpp.

◆ getTitle()

const std::string & guillaume::components::Tooltip::getTitle ( void ) const
noexcept

Get the title of a rich tooltip.

Returns
The title; empty when there is none.

Definition at line 57 of file tooltip.cpp.

◆ getTitleEntity()

ecs::Entity::Identifier guillaume::components::Tooltip::getTitleEntity ( void ) const
noexcept

Get the child that draws the title.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 71 of file tooltip.cpp.

◆ getVariant()

Tooltip::Variant guillaume::components::Tooltip::getVariant ( void ) const
noexcept

Get the kind of tooltip.

Returns
The variant, Variant::Plain by default.

Definition at line 29 of file tooltip.cpp.

◆ getViewport()

const std::optional< Tooltip::Viewport > & guillaume::components::Tooltip::getViewport ( void ) const
noexcept

Get the area the tooltip must stay inside.

Returns
The area as (width, height) in dp, or std::nullopt when the tooltip is not kept inside any area.

Definition at line 204 of file tooltip.cpp.

◆ isVisible()

bool guillaume::components::Tooltip::isVisible ( void ) const
noexcept

Tell whether the tooltip is shown.

Returns
True when shown; false by default.

Definition at line 189 of file tooltip.cpp.

Here is the caller graph for this function:

◆ setAnchor()

Tooltip & guillaume::components::Tooltip::setAnchor ( ecs::Entity::Identifier identifier)

Record the entity whose hover shows the tooltip.

This only stores the identifier. Use systems::Tooltip::setAnchor instead: it also resets the timers and starts or stops the animation that advances them. Marks the component changed only when the identifier differs.

Parameters
identifierThe anchor's identifier, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 104 of file tooltip.cpp.

Here is the call graph for this function:

◆ setEnterDelay()

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

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

Marks the component changed only when the value differs.

Parameters
secondsThe delay, in seconds; 0 shows the tooltip at once.
Returns
This component, for chaining.
Exceptions
std::invalid_argumentIf seconds is negative.

Definition at line 118 of file tooltip.cpp.

Here is the call graph for this function:

◆ setHoverTime()

Tooltip & guillaume::components::Tooltip::setHoverTime ( float seconds)

Store how long the anchor has been hovered.

Running state written by systems::Tooltip::advance. Marks the component changed only when the value differs.

Parameters
secondsThe time, in seconds.
Returns
This component, for chaining.

Definition at line 152 of file tooltip.cpp.

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

◆ setLastProgress()

Tooltip & guillaume::components::Tooltip::setLastProgress ( float progress)

Store the progress the timer animation reported last.

The timers are driven by a one-second looping animation; the difference between two reported progresses is the time elapsed, in seconds. Marks the component changed only when the value differs.

Parameters
progressThe progress, 0 to 1.
Returns
This component, for chaining.

Definition at line 180 of file tooltip.cpp.

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

◆ setLeaveDelay()

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

Set how long the tooltip stays after the pointer leaves the anchor.

Marks the component changed only when the value differs.

Parameters
secondsThe delay, in seconds; 0 hides the tooltip at once.
Returns
This component, 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:

◆ setLeaveTime()

Tooltip & guillaume::components::Tooltip::setLeaveTime ( float seconds)

Store how long ago the pointer left the anchor.

Running state written by systems::Tooltip::advance. Marks the component changed only when the value differs.

Parameters
secondsThe time, in seconds.
Returns
This component, for chaining.

Definition at line 166 of file tooltip.cpp.

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

◆ setText()

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

Set the body text.

systems::Tooltip copies it to the body child. Marks the component changed only when the text differs.

Parameters
textThe new text.
Returns
This component, for chaining.

Definition at line 48 of file tooltip.cpp.

Here is the call graph for this function:

◆ setTextEntity()

Tooltip & guillaume::components::Tooltip::setTextEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the body text.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 90 of file tooltip.cpp.

Here is the call graph for this function:

◆ setTitle()

Tooltip & guillaume::components::Tooltip::setTitle ( const std::string & title)

Set the title of a rich tooltip.

The widget uses it when it builds the title child. A plain tooltip does not show it. Marks the component changed only when the text differs.

Parameters
titleThe new title.
Returns
This component, for chaining.

Definition at line 62 of file tooltip.cpp.

Here is the call graph for this function:

◆ setTitleEntity()

Tooltip & guillaume::components::Tooltip::setTitleEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the title.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 76 of file tooltip.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Set the kind of tooltip.

Marks the component changed only when the variant differs.

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

Definition at line 34 of file tooltip.cpp.

Here is the call graph for this function:

◆ setViewport()

Tooltip & guillaume::components::Tooltip::setViewport ( std::optional< Viewport > viewport)

Set the area the tooltip must stay inside.

With a viewport, a tooltip that would go past the bottom edge is placed above its anchor, and its position is clamped to the area. Marks the component changed only when the value differs.

Parameters
viewportThe area as (width, height) in dp, or std::nullopt to lift the constraint.
Returns
This component, for chaining.

Definition at line 209 of file tooltip.cpp.

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

◆ setVisible()

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

Record whether the tooltip is shown.

This only stores the flag; the screen follows on the next pass of systems::Tooltip. Prefer systems::Tooltip::show and systems::Tooltip::hide, which also place and restyle the tooltip at once. Marks the component changed only when the flag differs.

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

Definition at line 194 of file tooltip.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ DefaultEnterDelay

float guillaume::components::Tooltip::DefaultEnterDelay = 0.5f
staticconstexpr

Default time the anchor must be hovered before the tooltip shows, in seconds.

Definition at line 71 of file tooltip.hpp.

◆ DefaultLeaveDelay

float guillaume::components::Tooltip::DefaultLeaveDelay = 1.5f
staticconstexpr

Default time the tooltip stays after the anchor is left, in seconds.

Definition at line 75 of file tooltip.hpp.


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