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

Whether the mouse pointer is over an entity, what to call when it enters or leaves, and how far the hit area extends past the bound. More...

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

Inheritance diagram for guillaume::components::MouseHoverInteraction:
Collaboration diagram for guillaume::components::MouseHoverInteraction:

Public Types

using HoverHandler
 Called on hover start.
using UnhoverHandler
 Called on hover end.

Public Member Functions

 MouseHoverInteraction (void)
 Construct a component that is not hovered, has no handler and no margin.
 ~MouseHoverInteraction (void)=default
 Default destructor.
MouseHoverInteraction & setOnHoverHandler (const HoverHandler &handler)
 Store the callback run when the pointer enters the entity.
MouseHoverInteraction & setOnUnhoverHandler (const UnhoverHandler &handler)
 Store the callback run when the pointer leaves the entity.
HoverHandler getOnHoverHandler (void) const
 Get the callback run when the pointer enters the entity.
UnhoverHandler getOnUnhoverHandler (void) const
 Get the callback run when the pointer leaves the entity.
bool isHovered (void) const
 Check whether the pointer is over the entity.
MouseHoverInteraction & setHovered (bool isHovered)
 Record whether the pointer is over the entity.
utility::graphic::SizeUI getAccessibilityMargin (void) const
 Get the hit area added around the bound.
MouseHoverInteraction & setAccessibilityMargin (const utility::graphic::SizeUI &margin)
 Grow the hit area past the bound without growing the entity on screen.
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

Whether the mouse pointer is over an entity, what to call when it enters or leaves, and how far the hit area extends past the bound.

systems::MouseMotion writes the hovered flag in the Event phase: on each mouse motion event it casts a ray from the pointer and tests it against the entity's Transform and Bound, grown by the accessibility margin. It calls the hover handler once when the pointer enters and the unhover handler once when it leaves. An entity disabled through StyleState is never hovered. systems::StyleState copies the flag into StyleState::isHovered.

registry.addComponent<components::MouseHoverInteraction>(identifier)
.setOnHoverHandler([] { showHint(); })
.setOnUnhoverHandler([] { hideHint(); });
Whether the mouse pointer is over an entity, what to call when it enters or leaves,...
MouseHoverInteraction & setOnUnhoverHandler(const UnhoverHandler &handler)
Store the callback run when the pointer leaves the entity.
MouseHoverInteraction & setOnHoverHandler(const HoverHandler &handler)
Store the callback run when the pointer enters the entity.

The accessibility margin of this component is the hit margin of the entity for every pointer and hand test (hover, buttons, pinch, poke), not only for the mouse hover. The flag only changes in a frame that received a mouse motion event.

See also
systems::MouseMotion, HandHoverInteraction, StyleState

Definition at line 59 of file mouse_hover_interaction.hpp.

Member Typedef Documentation

◆ HoverHandler

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

Called on hover start.

Definition at line 62 of file mouse_hover_interaction.hpp.

◆ UnhoverHandler

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

Called on hover end.

Definition at line 64 of file mouse_hover_interaction.hpp.

Constructor & Destructor Documentation

◆ MouseHoverInteraction()

guillaume::components::MouseHoverInteraction::MouseHoverInteraction ( void )

Construct a component that is not hovered, has no handler and no margin.

Definition at line 28 of file mouse_hover_interaction.cpp.

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

Member Function Documentation

◆ getAccessibilityMargin()

utility::graphic::SizeUI guillaume::components::MouseHoverInteraction::getAccessibilityMargin ( void ) const

Get the hit area added around the bound.

Returns
The margin, in dp: the width is added on the left and on the right, the height above and below.

Definition at line 80 of file mouse_hover_interaction.cpp.

◆ getOnHoverHandler()

MouseHoverInteraction::HoverHandler guillaume::components::MouseHoverInteraction::getOnHoverHandler ( void ) const

Get the callback run when the pointer enters the entity.

Returns
A copy of the handler; empty (nullptr) when none was set.

Definition at line 53 of file mouse_hover_interaction.cpp.

◆ getOnUnhoverHandler()

MouseHoverInteraction::UnhoverHandler guillaume::components::MouseHoverInteraction::getOnUnhoverHandler ( void ) const

Get the callback run when the pointer leaves the entity.

Returns
A copy of the handler; empty (nullptr) when none was set.

Definition at line 59 of file mouse_hover_interaction.cpp.

◆ isHovered()

bool guillaume::components::MouseHoverInteraction::isHovered ( void ) const

Check whether the pointer is over the entity.

Returns
True from the motion event that entered the hit area until the one that left it.

Definition at line 64 of file mouse_hover_interaction.cpp.

Here is the caller graph for this function:

◆ setAccessibilityMargin()

MouseHoverInteraction & guillaume::components::MouseHoverInteraction::setAccessibilityMargin ( const utility::graphic::SizeUI & margin)

Grow the hit area past the bound without growing the entity on screen.

Widget systems use it to give a small control the 48 dp touch target: a 40 dp wide control gets a margin of 4. Marks the component changed only when the margin differs.

Parameters
marginThe margin, in dp: the width is added on the left and on the right, the height above and below.
Returns
This component, to chain calls.

Definition at line 85 of file mouse_hover_interaction.cpp.

Here is the call graph for this function:

◆ setHovered()

MouseHoverInteraction & guillaume::components::MouseHoverInteraction::setHovered ( bool isHovered)

Record whether the pointer is over the entity.

Called by systems::MouseMotion; it calls no handler. Marks the component changed only when the flag differs.

Parameters
isHoveredTrue when the pointer is over the entity.
Returns
This component, to chain calls.

Definition at line 69 of file mouse_hover_interaction.cpp.

Here is the call graph for this function:

◆ setOnHoverHandler()

MouseHoverInteraction & guillaume::components::MouseHoverInteraction::setOnHoverHandler ( const HoverHandler & handler)

Store the callback run when the pointer enters the entity.

Always marks the component changed.

Parameters
handlerThe callback, or nullptr to remove the current one.
Returns
This component, to chain calls.

Definition at line 37 of file mouse_hover_interaction.cpp.

Here is the call graph for this function:

◆ setOnUnhoverHandler()

MouseHoverInteraction & guillaume::components::MouseHoverInteraction::setOnUnhoverHandler ( const UnhoverHandler & handler)

Store the callback run when the pointer leaves the entity.

Always marks the component changed.

Parameters
handlerThe callback, or nullptr to remove the current one.
Returns
This component, to chain calls.

Definition at line 44 of file mouse_hover_interaction.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: