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

Decides which single entity has the keyboard focus. More...

#include <headers/guillaume/systems/focus.hpp>

Inheritance diagram for guillaume::systems::Focus:
Collaboration diagram for guillaume::systems::Focus:

Public Member Functions

 Focus (event::EventBus &eventBus, utility::Engine &engine)
 Create the system, in the Event phase, and subscribe it to keyboard events (for Tab traversal).
void setFocus (const ecs::Entity::Identifier &entityIdentifier)
 Give the focus to an entity.
void clearFocus (void)
 Take the focus away from the focused entity.
std::optional< ecs::Entity::Identifier > getFocusedEntity (void) const
 The entity holding the focus.
std::optional< ecs::Entity::Identifier > getLastFocusedEntity (void) const
 The entity that held the focus before the current one, or before the focus was cleared.
void traverse (const std::vector< std::pair< ecs::Entity::Identifier, int > > &candidates, bool backward)
 Move the focus to the next or previous candidate.
void prepare (void) override
 Empty the list of focusable entities and take the next pending keyboard event, once per frame.
void cleanup (void) override
 Run Tab traversal once every entity has been visited.
virtual void update (const ecs::Entity::Identifier &entityIdentifier) override
 Focus one entity if it is being pressed, and record it as a Tab candidate if it is focusable.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Focus, components::Transform, components::Bound, components::MouseButtonInteraction, components::HandButtonInteraction, components::HandPinchInteraction, components::HandPokeInteraction >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
Public Member Functions inherited from guillaume::event::EventManager< utility::event::KeyboardEvent >
 EventManager (EventBus &eventBus)
 Subscribe to a bus; events of type EventType published after this call are queued.
virtual ~EventManager (void)=default
 Virtual destructor.
bool hasPendingEvents (void) const
 Tell whether at least one event is queued, waiting for consumeNextEvent().

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
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 does not.
Protected Member Functions inherited from guillaume::event::EventManager< utility::event::KeyboardEvent >
void consumeNextEvent (void)
 Take the oldest queued event and make it the last event.
std::shared_ptr< EventType > getLastEvent (void)
 Get the event taken by the most recent consumeNextEvent() that found one.

Detailed Description

Decides which single entity has the keyboard focus.

Runs in the Event phase on entities that have a components::Focus, Transform, Bound, MouseButtonInteraction, HandButtonInteraction, HandPinchInteraction and HandPokeInteraction (all seven are required; interaction::makeInteractive alone does not add the pinch and poke ones).

Focus moves in two ways:

  • Press: an entity takes the focus while its left mouse button, one of its hand buttons A, B, X or Y, a pinch or a poke is active on it. This reads the interaction components written earlier in the phase by systems::MouseButton and the hand systems.
  • Tab / Shift+Tab: after all entities have been visited, a Tab key-down event moves the focus to the next (or previous) focusable entity. See traverse() for the order.

It writes the focused flag of components::Focus and of components::StyleState (when present), calls the focus-gained and focus-lost handlers of components::Focus, and tells the engine whether the viewport may capture input: not while a press gives the focus to an entity, again once no entity is focused. A disabled entity cannot take the focus and loses it when visited.

Note
The system remembers one focused entity across frames and scenes; it is not reset when the active scene changes.
setFocus(), clearFocus() and traverse() read components through the registry bound to the system. Outside the frame loop, call ecs::System::bindComponentRegistry first; without it the flags and handlers are skipped and only the remembered identifier changes.
See also
components::Focus
components::Accessibility
systems::FocusRingRender

Definition at line 84 of file focus.hpp.

Constructor & Destructor Documentation

◆ Focus()

guillaume::systems::Focus::Focus ( event::EventBus & eventBus,
utility::Engine & engine )

Create the system, in the Event phase, and subscribe it to keyboard events (for Tab traversal).

Parameters
eventBusThe event bus delivering the keyboard events.
engineThe engine told whether the viewport may capture input. It must outlive the system.

Definition at line 35 of file focus.cpp.

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

Member Function Documentation

◆ cleanup()

void guillaume::systems::Focus::cleanup ( void )
overridevirtual

Run Tab traversal once every entity has been visited.

When the current keyboard event is a Tab key-down, calls traverse() on the focusable entities collected by update(), backward when a Shift modifier is set.

Reimplemented from guillaume::ecs::System.

Definition at line 308 of file focus.cpp.

Here is the call graph for this function:

◆ clearFocus()

void guillaume::systems::Focus::clearFocus ( void )

Take the focus away from the focused entity.

The entity becomes the last focused entity, its focus-lost handler is called and its focused flags are cleared. Does nothing when no entity is focused.

Definition at line 101 of file focus.cpp.

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

◆ getFocusedEntity()

std::optional< ecs::Entity::Identifier > guillaume::systems::Focus::getFocusedEntity ( void ) const

The entity holding the focus.

Returns
Its identifier, or std::nullopt when no entity is focused.

Definition at line 128 of file focus.cpp.

◆ getLastFocusedEntity()

std::optional< ecs::Entity::Identifier > guillaume::systems::Focus::getLastFocusedEntity ( void ) const

The entity that held the focus before the current one, or before the focus was cleared.

Returns
Its identifier, or std::nullopt when the focus has never left an entity.

Definition at line 134 of file focus.cpp.

◆ prepare()

void guillaume::systems::Focus::prepare ( void )
overridevirtual

Empty the list of focusable entities and take the next pending keyboard event, once per frame.

Reimplemented from guillaume::ecs::System.

Definition at line 302 of file focus.cpp.

Here is the call graph for this function:

◆ setFocus()

void guillaume::systems::Focus::setFocus ( const ecs::Entity::Identifier & entityIdentifier)

Give the focus to an entity.

When another entity held the focus, it becomes the last focused entity, its focus-lost handler is called and its focused flags are cleared. The focused flags of the new entity are then set and its focus-gained handler is called; that handler is called on every call, also when the entity already held the focus.

Parameters
entityIdentifierThe entity to focus. It is not checked for being focusable or enabled.

Definition at line 50 of file focus.cpp.

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

◆ traverse()

void guillaume::systems::Focus::traverse ( const std::vector< std::pair< ecs::Entity::Identifier, int > > & candidates,
bool backward )

Move the focus to the next or previous candidate.

Candidates with a positive focus order come first, in ascending order; the others follow in the order they are given. From the focused entity the focus moves one step and wraps at the ends. When no entity is focused, or the focused one is not a candidate, the first candidate is focused (the last one when going backward). Does nothing when candidates is empty.

Parameters
candidatesThe focusable entities, each paired with the focus order of its components::Accessibility (0 or less: no explicit order).
backwardTrue to go to the previous one (Shift+Tab).

Definition at line 266 of file focus.cpp.

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

◆ update()

void guillaume::systems::Focus::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Focus one entity if it is being pressed, and record it as a Tab candidate if it is focusable.

A disabled entity is skipped, after losing the focus if it held it. A pressed entity gets the focus and viewport input capture is turned off; otherwise capture is turned back on when no entity is focused.

Parameters
entityIdentifierThe entity to examine.

Implements guillaume::ecs::System.

Definition at line 139 of file focus.cpp.

Here is the call graph for this function:

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