|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
Decides which single entity has the keyboard focus. More...
#include <headers/guillaume/systems/focus.hpp>


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. | |
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:
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.
| 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).
| eventBus | The event bus delivering the keyboard events. |
| engine | The engine told whether the viewport may capture input. It must outlive the system. |
Definition at line 35 of file focus.cpp.


|
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.

| 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.


| std::optional< ecs::Entity::Identifier > guillaume::systems::Focus::getFocusedEntity | ( | void | ) | const |
| std::optional< ecs::Entity::Identifier > guillaume::systems::Focus::getLastFocusedEntity | ( | void | ) | const |
|
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.

| 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.
| entityIdentifier | The entity to focus. It is not checked for being focusable or enabled. |
Definition at line 50 of file focus.cpp.


| 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.
| candidates | The focusable entities, each paired with the focus order of its components::Accessibility (0 or less: no explicit order). |
| backward | True to go to the previous one (Shift+Tab). |
Definition at line 266 of file focus.cpp.


|
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.
| entityIdentifier | The entity to examine. |
Implements guillaume::ecs::System.
Definition at line 139 of file focus.cpp.
