guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
tooltip.cpp
1/*
2 Copyright (c) 2026 ETIB Corporation
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy of
5 this software and associated documentation files (the "Software"), to deal in
6 the Software without restriction, including without limitation the rights to
7 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
8 of the Software, and to permit persons to whom the Software is furnished to do
9 so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in all
12 copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 SOFTWARE.
21 */
22
23#include "guillaume/systems/tooltip.hpp"
24
25#include <algorithm>
26#include <utility>
27#include <vector>
28
29#include "guillaume/components/accessibility.hpp"
30#include "guillaume/components/animation.hpp"
31#include "guillaume/components/borders.hpp"
32#include "guillaume/components/bound.hpp"
33#include "guillaume/components/color.hpp"
34#include "guillaume/components/elevation.hpp"
35#include "guillaume/components/layout.hpp"
36#include "guillaume/components/overlay.hpp"
37#include "guillaume/components/text.hpp"
38#include "guillaume/components/transform.hpp"
41#include "guillaume/motion/easing.hpp"
42#include "guillaume/systems/layout.hpp"
43#include "guillaume/theme.hpp"
44
45namespace guillaume::systems
46{
47 namespace
48 {
49 using Variant = components::Tooltip::Variant;
52
54 constexpr float PlainHeight = 32.0f;
55
57 constexpr float RichHeight = 64.0f;
58
65 void colorChild(ecs::ComponentRegistry &registry,
67 const utility::graphic::Color32Bit &color)
68 {
69 if (registry.hasComponent<components::Color>(child)) {
70 registry.getComponent<components::Color>(child).setColor(color);
71 }
72 }
73
79 void arrange(ecs::ComponentRegistry &registry,
80 const ecs::Entity::Identifier &identifier)
81 {
82 Layout::apply(registry, identifier,
83 registry.getComponent<components::Layout>(identifier)
84 .getChildren(),
85 Layout::layerOf(registry, identifier));
86 }
87 } // namespace
88
91 {
92 }
93
95 const ecs::Entity::Identifier &entityIdentifier)
96 {
97 ecs::ComponentRegistry *registry = &componentRegistry;
98 const ecs::Entity::Identifier identifier = entityIdentifier;
99
100 componentRegistry.getComponent<components::Accessibility>(identifier)
103
104 // The animation is a one-second looping ticker: the progress it
105 // reports is turned back into the elapsed time.
106 componentRegistry.getComponent<components::Animation>(identifier)
107 .setDuration(1.0f)
108 .setEasing(motion::Easing::Linear)
109 .setLooping(true)
110 .setOnSampleHandler([registry, identifier](float progress) {
111 auto &tooltip =
112 registry->getComponent<components::Tooltip>(identifier);
113 float delta = progress - tooltip.getLastProgress();
114 if (delta < 0.0f) {
115 delta += 1.0f;
116 }
117 tooltip.setLastProgress(progress);
118 advance(*registry, identifier, delta);
119 });
120
121 componentRegistry.getComponent<components::Overlay>(identifier)
122 .setOnDismissHandler([registry, identifier]() {
123 hide(*registry, identifier);
124 });
125 }
126
127 bool Tooltip::hasAnchor(const ecs::ComponentRegistry &componentRegistry,
128 const ecs::Entity::Identifier &entityIdentifier)
129 {
130 const auto anchor =
131 componentRegistry
132 .getComponent<components::Tooltip>(entityIdentifier)
133 .getAnchor();
134
135 return anchor != ecs::Entity::InvalidIdentifier
136 && componentRegistry.hasComponent<components::Transform>(anchor);
137 }
138
140 const ecs::Entity::Identifier &entityIdentifier,
141 ecs::Entity::Identifier anchorIdentifier)
142 {
143 componentRegistry.getComponent<components::Tooltip>(entityIdentifier)
144 .setAnchor(anchorIdentifier)
145 .setHoverTime(0.0f)
146 .setLeaveTime(0.0f)
147 .setLastProgress(0.0f);
148
149 auto &ticker = componentRegistry.getComponent<components::Animation>(
150 entityIdentifier);
151 if (anchorIdentifier != ecs::Entity::InvalidIdentifier) {
152 ticker.play();
153 } else {
154 ticker.stop();
155 }
156 }
157
159 const ecs::Entity::Identifier &entityIdentifier,
160 float width, float height)
161 {
162 auto &tooltip = componentRegistry.getComponent<components::Tooltip>(
163 entityIdentifier);
164
165 tooltip.setViewport(std::make_pair(width, height));
166 if (tooltip.isVisible()) {
167 place(componentRegistry, entityIdentifier);
168 }
169 }
170
171 void Tooltip::show(ecs::ComponentRegistry &componentRegistry,
172 const ecs::Entity::Identifier &entityIdentifier)
173 {
174 componentRegistry.getComponent<components::Tooltip>(entityIdentifier)
175 .setVisible(true);
176 place(componentRegistry, entityIdentifier);
177 apply(componentRegistry, entityIdentifier);
178 }
179
180 void Tooltip::hide(ecs::ComponentRegistry &componentRegistry,
181 const ecs::Entity::Identifier &entityIdentifier)
182 {
183 componentRegistry.getComponent<components::Tooltip>(entityIdentifier)
184 .setVisible(false);
185 apply(componentRegistry, entityIdentifier);
186 }
187
189 const ecs::Entity::Identifier &entityIdentifier,
190 float deltaTime)
191 {
192 if (!hasAnchor(componentRegistry, entityIdentifier)) {
193 return;
194 }
195
196 auto &tooltip = componentRegistry.getComponent<components::Tooltip>(
197 entityIdentifier);
198
199 if (interaction::isHovered(componentRegistry, tooltip.getAnchor())) {
200 tooltip.setLeaveTime(0.0f);
201 tooltip.setHoverTime(tooltip.getHoverTime() + deltaTime);
202 if (!tooltip.isVisible()
203 && tooltip.getHoverTime() >= tooltip.getEnterDelay()) {
204 show(componentRegistry, entityIdentifier);
205 }
206 return;
207 }
208
209 tooltip.setHoverTime(0.0f);
210 if (tooltip.isVisible()) {
211 tooltip.setLeaveTime(tooltip.getLeaveTime() + deltaTime);
212 if (tooltip.getLeaveTime() >= tooltip.getLeaveDelay()) {
213 tooltip.setLeaveTime(0.0f);
214 hide(componentRegistry, entityIdentifier);
215 }
216 }
217 }
218
219 void Tooltip::place(ecs::ComponentRegistry &componentRegistry,
220 const ecs::Entity::Identifier &entityIdentifier)
221 {
222 if (!hasAnchor(componentRegistry, entityIdentifier)) {
223 return;
224 }
225
226 const auto &tooltip =
227 componentRegistry.getComponent<components::Tooltip>(
228 entityIdentifier);
229 const auto anchor = tooltip.getAnchor();
230 if (!componentRegistry.hasComponent<components::Bound>(anchor)) {
231 return;
232 }
233
234 const auto anchorPose =
235 componentRegistry.getComponent<components::Transform>(anchor)
236 .getPose();
237 const auto &anchorBound =
238 componentRegistry.getComponent<components::Bound>(anchor);
239 const auto &bound =
240 componentRegistry.getComponent<components::Bound>(entityIdentifier);
241
242 const float width = bound.getWidth();
243 const float height = bound.getHeight();
244 float x = anchorPose.getPosition().getX()
245 + (anchorBound.getWidth() - width) / 2.0f;
246 // Positions are top-left corners and y points up: below the anchor
247 // is its top minus its height.
248 float y = anchorPose.getPosition().getY() - anchorBound.getHeight();
249
250 if (tooltip.getViewport().has_value()) {
251 // The viewport is measured downward from y = 0.
252 const float viewportWidth = tooltip.getViewport()->first;
253 const float viewportHeight = tooltip.getViewport()->second;
254 float down = -y;
255 if (down + height > viewportHeight) {
256 down = -anchorPose.getPosition().getY() - height;
257 }
258 x = std::clamp(x, 0.0f, std::max(0.0f, viewportWidth - width));
259 down =
260 std::clamp(down, 0.0f, std::max(0.0f, viewportHeight - height));
261 y = -down;
262 }
263
264 componentRegistry.getComponent<components::Transform>(entityIdentifier)
265 .setPose(utility::graphic::PoseF(
266 utility::graphic::PositionF(x, y,
267 anchorPose.getPosition().getZ()),
268 anchorPose.getOrientation()));
269 arrange(componentRegistry, entityIdentifier);
270 }
271
272 void Tooltip::apply(ecs::ComponentRegistry &componentRegistry,
273 const ecs::Entity::Identifier &entityIdentifier)
274 {
275 const auto &tooltip =
276 componentRegistry.getComponent<components::Tooltip>(
277 entityIdentifier);
278 const bool rich = (tooltip.getVariant() == Variant::Rich);
279 const bool visible = tooltip.isVisible();
280 const auto title = tooltip.getTitleEntity();
281 const auto text = tooltip.getTextEntity();
282
283 // The title only takes part in the layout of a rich tooltip.
284 std::vector<ecs::Entity::Identifier> children;
285 if (rich && title != ecs::Entity::InvalidIdentifier) {
286 children.push_back(title);
287 }
288 if (text != ecs::Entity::InvalidIdentifier) {
289 children.push_back(text);
290 }
291
292 componentRegistry.getComponent<components::Layout>(entityIdentifier)
297 .setPadding(8.0f)
298 .setSpacing(2.0f)
299 .setFixedHeight(rich ? RichHeight : PlainHeight)
300 .setChildren(children);
301
302 componentRegistry.getComponent<components::Elevation>(entityIdentifier)
303 .setElevationLevel(rich && visible ? theme::ElevationLevel::Level2
305 componentRegistry.getComponent<components::Borders>(entityIdentifier)
306 .setBorderRadius(
309 componentRegistry.getComponent<components::Color>(entityIdentifier)
310 .setColor(visible
311 ? schemeColor(rich ? SchemeColorRole::SurfaceContainer
312 : SchemeColorRole::InverseSurface)
313 : transparentColor());
314
315 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
316 .setModal(false)
318 .setDismissOnEscape(true)
319 .setVisible(visible);
320
321 componentRegistry
322 .getComponent<components::Accessibility>(entityIdentifier)
323 .setLabel(tooltip.getText());
324
325 if (componentRegistry.hasComponent<components::Text>(text)) {
326 componentRegistry.getComponent<components::Text>(text).setContent(
327 tooltip.getText());
328 }
329 colorChild(componentRegistry, title,
330 visible ? schemeColor(SchemeColorRole::OnSurface)
331 : transparentColor());
332 colorChild(componentRegistry, text,
333 visible
334 ? schemeColor(rich ? SchemeColorRole::OnSurfaceVariant
335 : SchemeColorRole::InverseOnSurface)
336 : transparentColor());
337
338 arrange(componentRegistry, entityIdentifier);
339 }
340
341 void Tooltip::update(const ecs::Entity::Identifier &entityIdentifier)
342 {
343 if (!requireComponent<components::Tooltip>(entityIdentifier)) {
344 return;
345 }
346
347 apply(getComponentRegistry(), entityIdentifier);
348 }
349} // namespace guillaume::systems
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
Accessibility & setLiveRegion(LiveRegion liveRegion)
Set how urgently a change of the entity is announced.
A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1,...
Definition animation.hpp:61
Animation & setEasing(motion::Easing easing)
Set the curve that turns the linear progress into the value passed to the sample handler.
Animation & setOnSampleHandler(const SampleHandler &handler)
Store the callback that applies the animation.
Animation & setLooping(bool looping)
Set whether the animation starts again when it completes.
Corner radii and outline stroke of a rectangular entity.
Definition borders.hpp:67
Size of an entity: the width and height, in dp, of the rectangle that starts at the position of its c...
Definition bound.hpp:62
Main color of an entity: the fill of a shape, or the ink of a text or an icon.
Definition color.hpp:58
Soft shadow drawn around an elevated surface.
Definition elevation.hpp:63
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
Layout & setChildren(const std::vector< ecs::Entity::Identifier > &children)
Replace the list of children to arrange.
Definition layout.cpp:171
Layout & setPadding(float padding)
Set the inset between the container's edges and its children.
Definition layout.cpp:92
Layout & setMainAxisAlignment(MainAxisAlignment alignment)
Set where the children go along the main axis.
Definition layout.cpp:47
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
Layout & setFixedHeight(float height)
Force the container height instead of wrapping the children.
Definition layout.cpp:144
Layout & setCrossAxisAlignment(CrossAxisAlignment alignment)
Set where each child goes along the cross axis.
Definition layout.cpp:62
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
Layout & setSpacing(float spacing)
Set the gap between two consecutive children.
Definition layout.cpp:77
Marks an entity as something shown temporarily above the rest of the interface (a dialog,...
Definition overlay.hpp:55
Overlay & setDismissOnOutsideClick(bool dismiss)
Choose whether a click outside the overlay dismisses it.
Definition overlay.cpp:65
Overlay & setDismissOnEscape(bool dismiss)
Choose whether the Escape key dismisses the overlay.
Definition overlay.cpp:80
Overlay & setVisible(bool visible)
Show or hide the overlay.
Definition overlay.cpp:32
A run of text: its content, its font metrics and the position of the editing cursor.
Definition text.hpp:66
State of a tooltip: a small label that appears under an entity (its anchor) after the pointer has res...
Definition tooltip.hpp:55
Tooltip & setLeaveTime(float seconds)
Store how long ago the pointer left the anchor.
Definition tooltip.cpp:166
Tooltip & setHoverTime(float seconds)
Store how long the anchor has been hovered.
Definition tooltip.cpp:152
bool isVisible(void) const noexcept
Tell whether the tooltip is shown.
Definition tooltip.cpp:189
float getLastProgress(void) const noexcept
Get the progress the timer animation reported last.
Definition tooltip.cpp:175
Tooltip & setLastProgress(float progress)
Store the progress the timer animation reported last.
Definition tooltip.cpp:180
Tooltip & setViewport(std::optional< Viewport > viewport)
Set the area the tooltip must stay inside.
Definition tooltip.cpp:209
ecs::Entity::Identifier getAnchor(void) const noexcept
Get the entity whose hover shows the tooltip.
Definition tooltip.cpp:99
Where an entity is in space: its pose (position and orientation) and its scale.
Definition transform.hpp:64
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
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...
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one tooltip; called by the frame loop.
Definition tooltip.cpp:341
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 apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one tooltip and arrange its children.
Definition tooltip.cpp:272
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.
Definition tooltip.cpp:171
static void advance(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float deltaTime)
Advance the hover timers by some elapsed time.
Definition tooltip.cpp:188
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
Tooltip(void)
Create the system in the Layout phase.
Definition tooltip.cpp:89
static void place(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Move the tooltip next to its anchor.
Definition tooltip.cpp:219
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
static void hide(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Hide the tooltip at once, without waiting for the leave delay.
Definition tooltip.cpp:180
static bool hasAnchor(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the tooltip is attached to an entity that still exists.
Definition tooltip.cpp:127
State. Every class here is plain data attached to an entity.
@ Polite
Announced once the current speech is over.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
@ Level2
Second raised level.
Definition tokens.hpp:133
@ Level0
Flat: no shadow, no tint.
Definition tokens.hpp:131
@ Medium
12 dp (cards).
Definition tokens.hpp:46
@ ExtraSmall
4 dp (text fields, menus, snackbars).
Definition tokens.hpp:44
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
Helpers of the namespace systems::interaction: what "pressable" means for a widget,...
bool isHovered(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether the mouse pointer or a hand is over an entity.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.