guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
search.hpp
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#pragma once
24
25#include <utility>
26#include <functional>
27#include <memory>
28#include <string>
29
30#include <utility/graphic/color.hpp>
31#include <utility/graphic/pose.hpp>
32
33#include "guillaume/ecs/component_registry.hpp"
34#include "guillaume/ecs/entity_builder.hpp"
35
36#include "guillaume/components/accessibility.hpp"
37#include "guillaume/components/elevation.hpp"
38#include "guillaume/components/focus.hpp"
39#include "guillaume/components/line.hpp"
40#include "guillaume/components/overlay.hpp"
41#include "guillaume/components/search.hpp"
42#include "guillaume/components/text_field.hpp"
43
44#include "guillaume/entities/builder_base.hpp"
45#include "guillaume/entities/icon.hpp"
46#include "guillaume/entities/surface.hpp"
47#include "guillaume/entities/text.hpp"
48
49namespace guillaume::entities
50{
51
98 class Search:
99 public SurfaceBase<components::Overlay, components::TextField,
100 components::Elevation, components::Line,
101 components::Focus, components::Accessibility,
102 components::Search>
103 {
104 public:
106
111 class Builder: public EntityBuilderBase<Search>
112 {
113 private:
114 SurfaceConfig _config;
115 Variant _variant { Variant::SearchBar };
116 std::string _placeholder {};
117 std::string _text {};
118
119 public:
127 Builder(ecs::ComponentRegistry &componentRegistry,
128 ecs::EntityRegistry &entityRegistry);
129
135 std::shared_ptr<Search> buildEntity(void) override;
136
145 void reset(void) override;
146
153 Builder &withPose(const utility::graphic::PoseF &pose);
154
161 Builder &withVariant(Variant variant);
162
170 Builder &withPlaceholder(const std::string &placeholder);
171
177 Builder &withText(const std::string &text);
178
189 std::shared_ptr<Search>
190 makeSearch(std::shared_ptr<ecs::Entity> parent, Variant variant,
191 const std::string &placeholder,
192 const std::string &text = "");
193 };
194
208 template<typename... Arguments>
209 static std::shared_ptr<Search> create(Arguments &&...arguments)
210 {
211 std::shared_ptr<Search> entity(
212 new Search(std::forward<Arguments>(arguments)...));
213 entity->build();
214 return entity;
215 }
216
220 ~Search(void) override;
221
228 Search &setVariant(Variant variant);
229
234 Variant getVariant(void) const;
235
246 Search &setPlaceholder(const std::string &placeholder);
247
255 Search &setText(const std::string &text);
256
262 std::string getText(void) const;
263
269 Search &clear(void);
270
278 Search &setIcon(const std::string &iconGlyph);
279
286 Search &setOnIconPress(std::function<void(void)> onIconPress);
287
294 Search &setOnClearIconPress(std::function<void(void)> onClearIconPress);
295
308 Search &setTrailingIcon(const std::string &iconGlyph,
309 std::function<void(void)> onPress = {});
310
317 Search &setLoading(bool loading);
318
323 bool isLoading(void) const;
324
335 Search &setElevation(theme::ElevationLevel level);
336
344
351
359
366
372 Search &show(void);
373
379 Search &hide(void);
380
386 bool isVisible(void) const;
387
392 Search &open(void);
393
398 Search &close(void);
399
404 bool isOpen(void) const;
405
406 private:
416 void buildChildren(void);
417
418 private:
431 Search(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
432 Variant variant, const std::string &placeholder,
433 const std::string &text);
434
441 void build(void);
442 };
443
444} // namespace guillaume::entities
Variant
Shape of the search field.
Definition search.hpp:64
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
Owns entities and gives the systems the list of entities to visit.
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
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Definition search.cpp:37
std::shared_ptr< Search > makeSearch(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::string &placeholder, const std::string &text="")
Build a search field, register it under parent and reset the builder.
Definition search.cpp:96
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the search field is placed.
Definition search.cpp:71
std::shared_ptr< Search > buildEntity(void) override
Build a search field and its children from the current configuration, without registering it or setti...
Definition search.cpp:44
Builder & withText(const std::string &text)
Set the initial query.
Definition search.cpp:90
void reset(void) override
Restore the defaults.
Definition search.cpp:51
Builder & withVariant(Variant variant)
Set the variant.
Definition search.cpp:77
Builder & withPlaceholder(const std::string &placeholder)
Set the placeholder: the hint shown while the query is empty.
Definition search.cpp:84
A search field: a leading icon, an editable query with a placeholder, a clear button and an optional ...
Definition search.hpp:103
Search & setLoading(bool loading)
Show the loading glyph in place of the clear button, or the reverse. Restyles at once.
Definition search.cpp:209
Search & setOnIconPress(std::function< void(void)> onIconPress)
Set the handler called when the user presses the leading icon (Paper onIconPress).
Definition search.cpp:180
Search & setPlaceholder(const std::string &placeholder)
Change the placeholder: the hint shown while the query is empty.
Definition search.cpp:143
components::Search::Variant Variant
Search variant.
Definition search.hpp:105
static std::shared_ptr< Search > create(Arguments &&...arguments)
Create a search field and its children, without registering it in an entity registry.
Definition search.hpp:209
Search & hide(void)
Hide the search field: set its components::Overlay not visible.
Definition search.cpp:268
Search & setElevation(theme::ElevationLevel level)
Set the elevation level (Paper elevation). Restyles at once.
Definition search.cpp:225
Search & setIcon(const std::string &iconGlyph)
Change the glyph of the leading icon (Paper icon). Restyles at once.
Definition search.cpp:170
~Search(void) override
Default destructor.
Definition search.cpp:123
ecs::Entity::Identifier getTextIdentifier(void) const
Get the query text entity: the text the user edits.
Definition search.cpp:255
ecs::Entity::Identifier getPlaceholderIdentifier(void) const
Get the placeholder text entity.
Definition search.cpp:248
ecs::Entity::Identifier getIconIdentifier(void) const
Get the leading icon: a pressable icon entity.
Definition search.cpp:234
Search & setOnClearIconPress(std::function< void(void)> onClearIconPress)
Set the handler called after the query was cleared, by the clear button or by clear() (Paper onClearI...
Definition search.cpp:189
Search & open(void)
Open the search field. Same as show().
Definition search.cpp:280
bool isVisible(void) const
Whether the search field is shown.
Definition search.cpp:274
bool isLoading(void) const
Whether the loading glyph replaces the clear button.
Definition search.cpp:218
ecs::Entity::Identifier getClearIdentifier(void) const
Get the clear button: a pressable icon entity.
Definition search.cpp:241
Search & clear(void)
Empty the query, as the clear button does, then call the clear handler.
Definition search.cpp:164
Search & show(void)
Show the search field: set its components::Overlay visible.
Definition search.cpp:262
Search & close(void)
Close the search field. Same as hide().
Definition search.cpp:285
Search & setText(const std::string &text)
Replace the query. Restyles at once.
Definition search.cpp:153
Search & setTrailingIcon(const std::string &iconGlyph, std::function< void(void)> onPress={})
Set or hide the trailing icon (Paper right and traileringIcon).
Definition search.cpp:197
Search & setVariant(Variant variant)
Change the variant. Restyles at once.
Definition search.cpp:127
bool isOpen(void) const
Whether the search field is open. Same as isVisible().
Definition search.cpp:290
Variant getVariant(void) const
Get the variant.
Definition search.cpp:136
std::string getText(void) const
Get the query, including what the user typed.
Definition search.cpp:159
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
ElevationLevel
How far a surface is raised above the background, in six steps.
Definition tokens.hpp:130
Everything needed to set up a surface in one value: where it is, how it looks and how it arranges its...
Definition surface.hpp:71