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

Whether an XR hand (controller) aims at an entity, what to call when the aim enters or leaves, and how far the hit area extends past the bound. More...

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

Inheritance diagram for guillaume::components::HandHoverInteraction:
Collaboration diagram for guillaume::components::HandHoverInteraction:

Public Types

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

Public Member Functions

 HandHoverInteraction (void)
 Construct a component that is not hovered, has no handler and no margin.
 ~HandHoverInteraction (void)=default
 Default destructor.
HandHoverInteraction & setOnHoverHandler (const HoverHandler &handler)
 Store the callback run when the hand ray enters the entity.
HandHoverInteraction & setOnUnhoverHandler (const UnhoverHandler &handler)
 Store the callback run when the hand ray leaves the entity.
HoverHandler getOnHoverHandler (void) const
 Get the callback run when the hand ray enters the entity.
UnhoverHandler getOnUnhoverHandler (void) const
 Get the callback run when the hand ray leaves the entity.
bool isHovered (void) const
 Check whether a hand aims at the entity.
HandHoverInteraction & setHovered (bool isHovered)
 Record whether a hand aims at the entity.
utility::graphic::SizeUI getAccessibilityMargin (void) const
 Get the hit area added around the entity's bound.
HandHoverInteraction & setAccessibilityMargin (const utility::graphic::SizeUI &margin)
 Grow the hit area past the entity's 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 an XR hand (controller) aims at an entity, what to call when the aim enters or leaves, and how far the hit area extends past the bound.

systems::HandMotion writes the hovered flag in the Event phase: on each hand motion event it tests the aim ray of the hand against the entity's Transform and Bound, grown by the hit margin. It calls the hover handler once when the ray 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::HandHoverInteraction>(identifier)
.setOnHoverHandler([] { showHint(); })
.setOnUnhoverHandler([] { hideHint(); });
Whether an XR hand (controller) aims at an entity, what to call when the aim enters or leaves,...
HandHoverInteraction & setOnUnhoverHandler(const UnhoverHandler &handler)
Store the callback run when the hand ray leaves the entity.
HandHoverInteraction & setOnHoverHandler(const HoverHandler &handler)
Store the callback run when the hand ray enters the entity.

The accessibility margin stored here is only used when the entity has no MouseHoverInteraction: the margin of that component comes first. The flag only changes in a frame that received a hand motion event.

See also
systems::HandMotion, MouseHoverInteraction, StyleState

Definition at line 58 of file hand_hover_interaction.hpp.

Member Typedef Documentation

◆ HoverHandler

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

Called on hover start.

Definition at line 61 of file hand_hover_interaction.hpp.

◆ UnhoverHandler

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

Called on hover end.

Definition at line 63 of file hand_hover_interaction.hpp.

Constructor & Destructor Documentation

◆ HandHoverInteraction()

guillaume::components::HandHoverInteraction::HandHoverInteraction ( void )

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

Definition at line 28 of file hand_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::HandHoverInteraction::getAccessibilityMargin ( void ) const

Get the hit area added around the entity's 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 hand_hover_interaction.cpp.

◆ getOnHoverHandler()

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

Get the callback run when the hand ray enters the entity.

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

Definition at line 53 of file hand_hover_interaction.cpp.

◆ getOnUnhoverHandler()

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

Get the callback run when the hand ray leaves the entity.

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

Definition at line 59 of file hand_hover_interaction.cpp.

◆ isHovered()

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

Check whether a hand aims at the entity.

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

Definition at line 64 of file hand_hover_interaction.cpp.

Here is the caller graph for this function:

◆ setAccessibilityMargin()

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

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

Ignored by the hit tests when the entity also has a MouseHoverInteraction; widget systems set the same margin on both. 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 hand_hover_interaction.cpp.

Here is the call graph for this function:

◆ setHovered()

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

Record whether a hand aims at the entity.

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

Parameters
isHoveredTrue when a hand ray hits the entity.
Returns
This component, to chain calls.

Definition at line 69 of file hand_hover_interaction.cpp.

Here is the call graph for this function:

◆ setOnHoverHandler()

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

Store the callback run when the hand ray 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 hand_hover_interaction.cpp.

Here is the call graph for this function:

◆ setOnUnhoverHandler()

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

Store the callback run when the hand ray 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 45 of file hand_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: