guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
focus.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/focus.hpp"
24
25#include <algorithm>
26#include <climits>
27
28#include "guillaume/components/accessibility.hpp"
29#include "guillaume/components/style_state.hpp"
31
32namespace guillaume::systems
33{
34
35 Focus::Focus(event::EventBus &eventBus, utility::Engine &engine)
37 components::Bound,
38 components::MouseButtonInteraction,
39 components::HandButtonInteraction,
40 components::HandPinchInteraction,
41 components::HandPokeInteraction>(ecs::Phase::Event)
42 , event::EventManager<utility::event::KeyboardEvent>(eventBus)
43 , _engine(engine)
44 , _focusedEntity(std::nullopt)
45
46 {
47 this->getLogger().info() << "Focus system initialized";
48 }
49
50 void Focus::setFocus(const ecs::Entity::Identifier &entityIdentifier)
51 {
52 // Save the current focused entity as last focused before changing
53 if (_focusedEntity.has_value()
54 && _focusedEntity.value() != entityIdentifier) {
55 _lastFocusedEntity = _focusedEntity.value();
56 }
57
58 // Clear focus from previous entity
59 if (_focusedEntity.has_value()
60 && _focusedEntity.value() != entityIdentifier) {
61 auto previousEntity = _focusedEntity.value();
62 if (this->template hasComponent<components::Focus>(
63 previousEntity)) {
64 auto &previousFocus =
66 previousEntity);
67 auto handler = previousFocus.getOnFocusLostHandler();
68 if (handler) {
69 this->getLogger().debug()
70 << "Triggering focus lost handler for entity "
71 << previousEntity;
72 handler();
73 }
74 }
75 }
76
77 if (_focusedEntity.has_value()
78 && _focusedEntity.value() != entityIdentifier) {
79 markFocused(_focusedEntity.value(), false);
80 }
81
82 // Set focus to new entity
83 _focusedEntity = entityIdentifier;
84 markFocused(entityIdentifier, true);
85 this->getLogger().info() << "Focus set to entity " << entityIdentifier;
86
87 // Trigger focus handler for new entity
88 if (this->template hasComponent<components::Focus>(entityIdentifier)) {
89 auto &focus = this->template getComponent<components::Focus>(
90 entityIdentifier);
91 auto handler = focus.getOnFocusGainedHandler();
92 if (handler) {
93 this->getLogger().debug()
94 << "Triggering focus gained handler for entity "
95 << entityIdentifier;
96 handler();
97 }
98 }
99 }
100
102 {
103 if (_focusedEntity.has_value()) {
104 // Save the current focused entity as last focused before clearing
105 _lastFocusedEntity = _focusedEntity.value();
106
107 auto previousEntity = _focusedEntity.value();
108 if (this->template hasComponent<components::Focus>(
109 previousEntity)) {
110 auto &previousFocus =
111 this->template getComponent<components::Focus>(
112 previousEntity);
113 auto handler = previousFocus.getOnFocusLostHandler();
114 if (handler) {
115 this->getLogger().debug()
116 << "Triggering focus lost handler for entity "
117 << previousEntity;
118 handler();
119 }
120 }
121 markFocused(previousEntity, false);
122 this->getLogger().info()
123 << "Focus cleared from entity " << previousEntity;
124 _focusedEntity = std::nullopt;
125 }
126 }
127
128 std::optional<ecs::Entity::Identifier> Focus::getFocusedEntity(void) const
129 {
130 return _focusedEntity;
131 }
132
133 std::optional<ecs::Entity::Identifier>
135 {
136 return _lastFocusedEntity;
137 }
138
139 void Focus::update(const ecs::Entity::Identifier &entityIdentifier)
140 {
141 this->getLogger().debug()
142 << "Updating Focus system for entity " << entityIdentifier;
143
144 // A disabled entity cannot take or keep the focus.
145 if (!isInteractive(this->getComponentRegistry(), entityIdentifier)) {
146 if (_focusedEntity.has_value()
147 && _focusedEntity.value() == entityIdentifier) {
148 clearFocus();
149 }
150 return;
151 }
152
153 if (isFocusable(entityIdentifier)) {
154 int order = 0;
156 entityIdentifier)) {
157 order = this->template getComponent<components::Accessibility>(
158 entityIdentifier)
159 .getFocusOrder();
160 }
161 _focusables.emplace_back(entityIdentifier, order);
162 }
163
164 bool entityClicked = false;
165
166 // Check if entity was clicked with mouse
168 entityIdentifier)) {
169 auto &mouseInteraction =
171 entityIdentifier);
172 if (mouseInteraction.isButtonPressed(
173 utility::event::MouseButtonEvent::Button::Left)) {
174 entityClicked = true;
175 }
176 }
177
178 // Check if entity was clicked with hand button
179 if (!entityClicked
181 entityIdentifier)) {
182 auto &handInteraction =
184 entityIdentifier);
185 // Check common hand buttons (A, B, X, Y)
186 if (handInteraction.isButtonPressed(
187 utility::event::HandButtonEvent::Button::A)
188 || handInteraction.isButtonPressed(
189 utility::event::HandButtonEvent::Button::B)
190 || handInteraction.isButtonPressed(
191 utility::event::HandButtonEvent::Button::X)
192 || handInteraction.isButtonPressed(
193 utility::event::HandButtonEvent::Button::Y)) {
194 entityClicked = true;
195 }
196 }
197
198 // Check if entity was clicked with hand pinch
199 if (!entityClicked
201 entityIdentifier)) {
202 auto &pinchInteraction =
204 entityIdentifier);
205 if (pinchInteraction.isPinch()) {
206 entityClicked = true;
207 }
208 }
209
210 // Check if entity was clicked with hand poke
211 if (!entityClicked
213 entityIdentifier)) {
214 auto &pokeInteraction =
216 entityIdentifier);
217 if (pokeInteraction.isPoke()) {
218 entityClicked = true;
219 }
220 }
221
222 // If entity was clicked, set focus and disable viewport input
223 if (entityClicked) {
224 setFocus(entityIdentifier);
225 _engine.setShouldCaptureViewportInput(false);
226 return;
227 }
228
229 // If focus was cleared, re-enable viewport input
230 if (!_focusedEntity.has_value()) {
231 _engine.setShouldCaptureViewportInput(true);
232 }
233 }
234
235 bool Focus::isFocusable(const ecs::Entity::Identifier &entityIdentifier)
236 {
237 if (!this->template hasComponent<components::Focus>(entityIdentifier)
238 || !isInteractive(this->getComponentRegistry(), entityIdentifier)) {
239 return false;
240 }
242 entityIdentifier)) {
243 return this
245 entityIdentifier)
246 .isFocusable();
247 }
248 return true;
249 }
250
251 void Focus::markFocused(const ecs::Entity::Identifier &entityIdentifier,
252 bool focused)
253 {
254 if (this->template hasComponent<components::Focus>(entityIdentifier)) {
255 this->template getComponent<components::Focus>(entityIdentifier)
256 .setFocused(focused);
257 }
258 if (this->template hasComponent<components::StyleState>(
259 entityIdentifier)) {
261 entityIdentifier)
262 .setFocused(focused);
263 }
264 }
265
267 const std::vector<std::pair<ecs::Entity::Identifier, int>> &candidates,
268 bool backward)
269 {
270 if (candidates.empty()) {
271 return;
272 }
273
274 auto ordered = candidates;
275 std::stable_sort(ordered.begin(), ordered.end(),
276 [](const auto &lhs, const auto &rhs) {
277 const int left =
278 lhs.second > 0 ? lhs.second : INT_MAX;
279 const int right =
280 rhs.second > 0 ? rhs.second : INT_MAX;
281 return left < right;
282 });
283
284 const auto count = static_cast<std::ptrdiff_t>(ordered.size());
285 std::ptrdiff_t next = backward ? count - 1 : 0;
286
287 if (_focusedEntity.has_value()) {
288 const auto current = std::find_if(
289 ordered.begin(), ordered.end(), [this](const auto &candidate) {
290 return candidate.first == _focusedEntity.value();
291 });
292 if (current != ordered.end()) {
293 const auto index = std::distance(ordered.begin(), current);
294 next = backward ? (index - 1 + count) % count
295 : (index + 1) % count;
296 }
297 }
298
299 setFocus(ordered[static_cast<std::size_t>(next)].first);
300 }
301
302 void Focus::prepare(void)
303 {
304 _focusables.clear();
306 }
307
308 void Focus::cleanup(void)
309 {
310 const auto keyboardEvent = getLastEvent();
311 if (!keyboardEvent || !keyboardEvent->getIsDownEvent()
312 || keyboardEvent->getKeycode()
313 != utility::event::KeyboardEvent::KeyCode::Tab) {
314 return;
315 }
316
317 const bool backward =
318 keyboardEvent->isModifierSet(
319 utility::event::KeyboardEvent::KeyModifiers::LeftShift)
320 || keyboardEvent->isModifierSet(
321 utility::event::KeyboardEvent::KeyModifiers::RightShift);
322
323 traverse(_focusables, backward);
324 }
325
326} // namespace guillaume::systems
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
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
bool hasComponent(const ecs::Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component, in the bound registry.
ComponentType & getComponent(const ecs::Entity::Identifier &entityIdentifier)
Get a component of an entity from the bound registry, to read or modify it.
Hands each engine event to the listeners subscribed to its type.
Definition event_bus.hpp:67
Focus(event::EventBus &eventBus, utility::Engine &engine)
Create the system, in the Event phase, and subscribe it to keyboard events (for Tab traversal).
Definition focus.cpp:35
std::optional< ecs::Entity::Identifier > getFocusedEntity(void) const
The entity holding the focus.
Definition focus.cpp:128
void clearFocus(void)
Take the focus away from the focused entity.
Definition focus.cpp:101
void setFocus(const ecs::Entity::Identifier &entityIdentifier)
Give the focus to an entity.
Definition focus.cpp:50
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.
Definition focus.cpp:139
void traverse(const std::vector< std::pair< ecs::Entity::Identifier, int > > &candidates, bool backward)
Move the focus to the next or previous candidate.
Definition focus.cpp:266
void cleanup(void) override
Run Tab traversal once every entity has been visited.
Definition focus.cpp:308
std::optional< ecs::Entity::Identifier > getLastFocusedEntity(void) const
The entity that held the focus before the current one, or before the focus was cleared.
Definition focus.cpp:134
void prepare(void) override
Empty the list of focusable entities and take the next pending keyboard event, once per frame.
Definition focus.cpp:302
Free functions the input systems share to decide whether a pointer or hand ray hits an entity.
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
Delivery of engine events to the systems that subscribed to them.
Definition event_bus.hpp:34
Rules. Every class here runs each frame on the entities that have the components it declares.
bool isInteractive(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity accepts input.
Definition hit_test.hpp:61