guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
search.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/search.hpp"
24
25#include <functional>
26#include <utility>
27#include <vector>
28
29#include "guillaume/components/accessibility.hpp"
30#include "guillaume/components/borders.hpp"
31#include "guillaume/components/color.hpp"
32#include "guillaume/components/elevation.hpp"
33#include "guillaume/components/glyph.hpp"
34#include "guillaume/components/layout.hpp"
35#include "guillaume/components/line.hpp"
36#include "guillaume/components/overlay.hpp"
37#include "guillaume/components/text.hpp"
38#include "guillaume/components/text_field.hpp"
41#include "guillaume/systems/layout.hpp"
42#include "guillaume/systems/text_field.hpp"
43#include "guillaume/theme.hpp"
44
45namespace guillaume::systems
46{
47 namespace
48 {
49 using Variant = components::Search::Variant;
52
58 bool isValid(ecs::Entity::Identifier identifier)
59 {
60 return identifier != ecs::Entity::InvalidIdentifier;
61 }
62
69 void colorChild(ecs::ComponentRegistry &registry,
71 const utility::graphic::Color32Bit &color)
72 {
73 if (isValid(child)
74 && registry.hasComponent<components::Color>(child)) {
75 registry.getComponent<components::Color>(child).setColor(color);
76 }
77 }
78
85 void glyphChild(ecs::ComponentRegistry &registry,
86 ecs::Entity::Identifier child, const std::string &glyph)
87 {
88 if (isValid(child)
89 && registry.hasComponent<components::Glyph>(child)) {
90 registry.getComponent<components::Glyph>(child).setName(glyph);
91 }
92 }
93
101 void makeIconButton(ecs::ComponentRegistry &registry,
103 const std::string &label,
104 std::function<void(void)> onPress)
105 {
106 if (!isValid(icon)) {
107 return;
108 }
109 interaction::makeInteractive(registry, icon,
111 std::move(onPress));
112 registry.getComponent<components::Accessibility>(icon).setLabel(
113 label);
114 }
115
122 void applyVariant(ecs::ComponentRegistry &registry,
123 const ecs::Entity::Identifier &identifier,
124 const components::Search &search)
125 {
126 const bool fullScreen = search.getVariant() == Variant::FullScreen;
127
128 auto &layout =
129 registry.getComponent<components::Layout>(identifier);
131 .setMainAxisAlignment(
133 .setCrossAxisAlignment(
135 .setSpacing(theme::SpacingScale::get(4))
136 .setPadding(theme::SpacingScale::get(4))
137 .setFixedHeight(fullScreen ? components::Search::ViewHeight
139 if (!layout.hasFixedWidth() || layout.getFixedWidth() <= 0.0f) {
140 layout.setFixedWidth(components::Search::DefaultWidth);
141 }
142
143 auto &line = registry.getComponent<components::Line>(identifier);
144 if (fullScreen) {
145 line.setThickness(1.0f)
147 .setColor(schemeColor(SchemeColorRole::OutlineVariant));
148 } else {
149 line.setThickness(0.0f).clearColor();
150 }
151
152 registry.getComponent<components::Borders>(identifier)
153 .setBorderRadius(
156
157 const auto level =
158 registry.getComponent<components::Elevation>(identifier)
159 .getElevationLevel();
160 registry.getComponent<components::Color>(identifier)
161 .setColor(
163 ? schemeColor(SchemeColorRole::SurfaceContainerHigh)
164 : getElevatedSurfaceColor(level));
165 }
166 } // namespace
167
170 {
171 }
172
174 const ecs::Entity::Identifier &entityIdentifier)
175 {
176 componentRegistry
177 .getComponent<components::Accessibility>(entityIdentifier)
179
180 // Paper's Searchbar defaults to elevation 0.
181 componentRegistry.getComponent<components::Elevation>(entityIdentifier)
182 .setElevationLevel(theme::ElevationLevel::Level0);
183
184 installIcon(componentRegistry, entityIdentifier);
185 installClearIcon(componentRegistry, entityIdentifier);
186 installTrailingIcon(componentRegistry, entityIdentifier);
187 }
188
190 const ecs::Entity::Identifier &entityIdentifier)
191 {
192 ecs::ComponentRegistry *registry = &componentRegistry;
193 const ecs::Entity::Identifier identifier = entityIdentifier;
194
195 makeIconButton(
196 componentRegistry,
197 componentRegistry.getComponent<components::Search>(identifier)
198 .getSearchIcon(),
199 "search", [registry, identifier]() {
200 pressIcon(*registry, identifier);
201 });
202 }
203
205 ecs::ComponentRegistry &componentRegistry,
206 const ecs::Entity::Identifier &entityIdentifier)
207 {
208 ecs::ComponentRegistry *registry = &componentRegistry;
209 const ecs::Entity::Identifier identifier = entityIdentifier;
210
211 makeIconButton(
212 componentRegistry,
213 componentRegistry.getComponent<components::Search>(identifier)
214 .getClearIcon(),
215 "clear search", [registry, identifier]() {
216 clear(*registry, identifier);
217 });
218 }
219
221 ecs::ComponentRegistry &componentRegistry,
222 const ecs::Entity::Identifier &entityIdentifier)
223 {
224 ecs::ComponentRegistry *registry = &componentRegistry;
225 const ecs::Entity::Identifier identifier = entityIdentifier;
226 const auto &search =
227 componentRegistry.getComponent<components::Search>(identifier);
228 // Copy: making the icon interactive adds components.
229 const std::string label = search.getTrailingGlyph();
230
231 makeIconButton(componentRegistry, search.getTrailingIcon(), label,
232 [registry, identifier]() {
233 pressTrailingIcon(*registry, identifier);
234 });
235 }
236
237 std::string Search::text(const ecs::ComponentRegistry &componentRegistry,
238 const ecs::Entity::Identifier &entityIdentifier)
239 {
240 const auto &search = componentRegistry.getComponent<components::Search>(
241 entityIdentifier);
242 const auto textEntity = search.getTextEntity();
243
244 if (isValid(textEntity)
245 && componentRegistry.hasComponent<components::Text>(textEntity)) {
246 return componentRegistry.getComponent<components::Text>(textEntity)
247 .getContent();
248 }
249 return search.getText();
250 }
251
253 const ecs::Entity::Identifier &entityIdentifier,
254 const std::string &text)
255 {
256 auto &search = componentRegistry.getComponent<components::Search>(
257 entityIdentifier);
258 const auto textEntity = search.getTextEntity();
259
260 search.setText(text);
261 if (isValid(textEntity)
262 && componentRegistry.hasComponent<components::Text>(textEntity)) {
263 componentRegistry.getComponent<components::Text>(textEntity)
264 .setContent(text);
265 }
266 apply(componentRegistry, entityIdentifier);
267 }
268
269 void Search::clear(ecs::ComponentRegistry &componentRegistry,
270 const ecs::Entity::Identifier &entityIdentifier)
271 {
272 setText(componentRegistry, entityIdentifier, "");
273
274 // Copy: the handler may replace itself.
275 const auto onClear =
276 componentRegistry.getComponent<components::Search>(entityIdentifier)
277 .getOnClearIconPress();
278 if (onClear) {
279 onClear();
280 }
281 }
282
284 const ecs::Entity::Identifier &entityIdentifier)
285 {
286 // Copy: the handler may replace itself.
287 const auto onPress =
288 componentRegistry.getComponent<components::Search>(entityIdentifier)
289 .getOnIconPress();
290 if (onPress) {
291 onPress();
292 }
293 }
294
296 ecs::ComponentRegistry &componentRegistry,
297 const ecs::Entity::Identifier &entityIdentifier)
298 {
299 // Copy: the handler may replace itself.
300 const auto onPress =
301 componentRegistry.getComponent<components::Search>(entityIdentifier)
302 .getOnTrailingIconPress();
303 if (onPress) {
304 onPress();
305 }
306 }
307
308 void Search::show(ecs::ComponentRegistry &componentRegistry,
309 const ecs::Entity::Identifier &entityIdentifier)
310 {
311 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
312 .setVisible(true);
313 }
314
315 void Search::hide(ecs::ComponentRegistry &componentRegistry,
316 const ecs::Entity::Identifier &entityIdentifier)
317 {
318 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
319 .setVisible(false);
320 }
321
322 bool Search::isVisible(const ecs::ComponentRegistry &componentRegistry,
323 const ecs::Entity::Identifier &entityIdentifier)
324 {
325 return componentRegistry
326 .getComponent<components::Overlay>(entityIdentifier)
327 .isVisible();
328 }
329
330 void Search::apply(ecs::ComponentRegistry &componentRegistry,
331 const ecs::Entity::Identifier &entityIdentifier)
332 {
333 auto &search = componentRegistry.getComponent<components::Search>(
334 entityIdentifier);
335
336 // The query child is what the user types in: it is the source of
337 // the query as soon as it exists.
338 search.setText(text(componentRegistry, entityIdentifier));
339
340 const bool hasQuery = !search.getText().empty();
341 const bool loading = search.isLoading();
342 const bool showClear = hasQuery && !loading;
343 const bool showTrailing = !search.getTrailingGlyph().empty();
344 const auto iconColor = schemeColor(SchemeColorRole::OnSurfaceVariant);
345
346 applyVariant(componentRegistry, entityIdentifier, search);
347
348 // Both Paper modes are inline fields; neither is modal.
349 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
350 .setModal(false)
352 .setDismissOnEscape(true);
353
354 auto &textField = componentRegistry.getComponent<components::TextField>(
355 entityIdentifier);
356 textField.setPlaceholder(search.getPlaceholder())
357 .setLabel(search.getPlaceholder());
358 TextField::reconcile(textField, hasQuery);
359
360 componentRegistry
361 .getComponent<components::Accessibility>(entityIdentifier)
362 .setLabel(search.getPlaceholder());
363
364 const auto searchIcon = search.getSearchIcon();
365 const auto textEntity = search.getTextEntity();
366 const auto placeholder = search.getPlaceholderEntity();
367 const auto clearIcon = search.getClearIcon();
368 const auto loadingIcon = search.getLoadingIcon();
369 const auto trailing = search.getTrailingIcon();
370
371 glyphChild(componentRegistry, searchIcon, search.getIconGlyph());
372 colorChild(componentRegistry, searchIcon, iconColor);
373
374 if (isValid(placeholder)
375 && componentRegistry.hasComponent<components::Text>(placeholder)) {
376 componentRegistry.getComponent<components::Text>(placeholder)
377 .setContent(search.getPlaceholder());
378 }
379 colorChild(componentRegistry, placeholder,
380 hasQuery ? transparentColor() : iconColor);
381
382 colorChild(componentRegistry, clearIcon,
383 showClear ? iconColor : transparentColor());
384 if (isValid(clearIcon)) {
385 interaction::setEnabled(componentRegistry, clearIcon, showClear);
386 }
387
388 colorChild(componentRegistry, loadingIcon,
389 loading ? schemeColor(SchemeColorRole::Primary)
390 : transparentColor());
391
392 if (showTrailing) {
393 glyphChild(componentRegistry, trailing, search.getTrailingGlyph());
394 }
395 colorChild(componentRegistry, trailing,
396 showTrailing ? iconColor : transparentColor());
397 if (isValid(trailing)) {
398 interaction::setEnabled(componentRegistry, trailing, showTrailing);
399 }
400
401 // The query replaces the placeholder, the loading glyph replaces
402 // the clear button, and the trailing icon shows while it has a
403 // glyph.
404 std::vector<ecs::Entity::Identifier> children;
405 const auto push = [&children](ecs::Entity::Identifier child) {
406 if (isValid(child)) {
407 children.push_back(child);
408 }
409 };
410
411 push(searchIcon);
412 push(hasQuery || !isValid(placeholder) ? textEntity : placeholder);
413 push(loading ? loadingIcon : clearIcon);
414 if (showTrailing) {
415 push(trailing);
416 }
417
418 componentRegistry.getComponent<components::Layout>(entityIdentifier)
419 .setChildren(children);
420 Layout::apply(componentRegistry, entityIdentifier, children,
421 Layout::layerOf(componentRegistry, entityIdentifier));
422 }
423
424 void Search::update(const ecs::Entity::Identifier &entityIdentifier)
425 {
426 if (!requireComponent<components::Search>(entityIdentifier)) {
427 return;
428 }
429
430 apply(getComponentRegistry(), entityIdentifier);
431 }
432} // namespace guillaume::systems
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
Soft shadow drawn around an elevated surface.
Definition elevation.hpp:63
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
Marks an entity as something shown temporarily above the rest of the interface (a dialog,...
Definition overlay.hpp:55
Overlay & setDismissOnOutsideClick(bool dismiss)
Choose whether a click outside the overlay dismisses it.
Definition overlay.cpp:65
Overlay & setDismissOnEscape(bool dismiss)
Choose whether the Escape key dismisses the overlay.
Definition overlay.cpp:80
State of a search field: a leading icon, the query the user types (or a placeholder),...
Definition search.hpp:59
ecs::Entity::Identifier getClearIcon(void) const noexcept
Get the pressable child that draws the clear button.
Definition search.cpp:154
static constexpr float DefaultWidth
Width given to a search field that has no fixed width, in dp.
Definition search.hpp:72
Variant
Shape of the search field.
Definition search.hpp:64
const std::string & getText(void) const noexcept
Get the query.
Definition search.cpp:49
ecs::Entity::Identifier getSearchIcon(void) const noexcept
Get the pressable child that draws the leading icon.
Definition search.cpp:124
Search & setText(const std::string &text)
Store the query.
Definition search.cpp:54
static constexpr float ViewHeight
Height of the FullScreen variant, in dp.
Definition search.hpp:78
const std::string & getTrailingGlyph(void) const noexcept
Get the icon at the trailing edge of the field.
Definition search.cpp:69
ecs::Entity::Identifier getTextEntity(void) const noexcept
Get the child the user types the query in.
Definition search.cpp:134
static constexpr float BarHeight
Height of the SearchBar variant, in dp.
Definition search.hpp:75
The texts around the input of a text field, and its error state: placeholder, label,...
TextField & setPlaceholder(const std::string &placeholder)
Set the placeholder: the text that names the field, such as "Email".
TextField & setLabel(const std::string &label)
Store the label.
A run of text: its content, its font metrics and the position of the editing cursor.
Definition text.hpp:66
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
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
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
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...
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
static void clear(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Empty the query as a press on the clear icon would.
Definition search.cpp:269
static bool isVisible(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the search field is shown.
Definition search.cpp:322
static void pressIcon(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Activate the leading icon as a press on it would.
Definition search.cpp:283
static void hide(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Hide the search field.
Definition search.cpp:315
static void installClearIcon(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make the clear icon a button that calls clear().
Definition search.cpp:204
Search(void)
Create the system in the Layout phase.
Definition search.cpp:168
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one search field and lay out its children.
Definition search.cpp:330
static void installIcon(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make the leading icon a button that calls pressIcon().
Definition search.cpp:189
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one search field; called by the frame loop.
Definition search.cpp:424
static void setText(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const std::string &text)
Replace the query and restyle the field.
Definition search.cpp:252
static std::string text(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the query the field holds.
Definition search.cpp:237
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Give a search field its accessibility role and make its icons pressable.
Definition search.cpp:173
static void pressTrailingIcon(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Activate the trailing icon as a press on it would.
Definition search.cpp:295
static void show(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Show the search field.
Definition search.cpp:308
static void installTrailingIcon(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make the trailing icon a button that calls pressTrailingIcon().
Definition search.cpp:220
static bool reconcile(components::TextField &textField, bool hasContent)
Derive the label-floating flag of a field that has no configuration, and store it.
static constexpr float get(unsigned int steps)
Get a spacing as a number of grid units.
Definition tokens.hpp:441
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
@ Level0
Flat: no shadow, no tint.
Definition tokens.hpp:131
@ ExtraLarge
28 dp (dialogs, search bars, sheets).
Definition tokens.hpp:48
@ None
0 dp: square corners.
Definition tokens.hpp:43
utility::graphic::Color32Bit getElevatedSurfaceColor(theme::ElevationLevel level)
Get the background color of a surface raised to an elevation level.
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
Helpers of the namespace systems::interaction: what "pressable" means for a widget,...
void makeInteractive(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, components::AccessibilityRole role, std::function< void(void)> onPress, std::function< void(void)> onStateChange={})
Make an entity hoverable, pressable and focusable.
void setEnabled(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, bool enabled)
Enable or disable an entity.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.