|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
Styles a search field and lays out the children that its query, loading state and trailing icon call for. More...
#include <headers/guillaume/systems/search.hpp>


Public Member Functions | |
| Search (void) | |
| Create the system in the Layout phase. | |
| ~Search (void) override=default | |
| Default destructor. | |
| void | update (const ecs::Entity::Identifier &entityIdentifier) override |
| Run apply() on one search field; called by the frame loop. | |
| Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Search > | |
| 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(). | |
| virtual void | prepare (void) |
| Called once per pass, before the first update(). | |
| virtual void | cleanup (void) |
| Called once per pass, after the last update(). | |
Static Public Member Functions | |
| static void | install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Give a search field its accessibility role and make its icons pressable. | |
| static void | installIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Make the leading icon a button that calls pressIcon(). | |
| static void | installClearIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Make the clear icon a button that calls clear(). | |
| static void | installTrailingIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Make the trailing icon a button that calls pressTrailingIcon(). | |
| static void | apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Style one search field and lay out its children. | |
| static std::string | text (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Get the query the field holds. | |
| static void | setText (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const std::string &text) |
| Replace the query and restyle the field. | |
| static void | clear (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Empty the query as a press on the clear icon would. | |
| static void | pressIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Activate the leading icon as a press on it would. | |
| static void | pressTrailingIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Activate the trailing icon as a press on it would. | |
| static void | show (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Show the search field. | |
| static void | hide (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Hide the search field. | |
| static bool | isVisible (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Whether the search field is shown. | |
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. | |
Styles a search field and lays out the children that its query, loading state and trailing icon call for.
Runs in the Layout phase on every entity that has a components::Search. It is registered after systems::Layout, so the texts and icons are already measured when it arranges them.
The row holds, in order: the leading icon; the query child once something is typed, otherwise the placeholder; the loading icon while loading, otherwise the clear icon; and the trailing icon while it has a glyph. The clear icon keeps its place in an empty field: it is painted transparent and disabled.
The query child is what the user types in. As soon as it exists, its components::Text is the source of the query, and the copy in components::Search is overwritten from it on every apply().
Whether the field is shown is the visible flag of its components::Overlay. A search field is never modal; it closes on Escape but not on a click outside.
Definition at line 71 of file search.hpp.
| guillaume::systems::Search::Search | ( | void | ) |
Create the system in the Layout phase.
Definition at line 168 of file search.cpp.


|
static |
Style one search field and lay out its children.
This is what update() runs each frame. Call it directly after changing components::Search to see the result before the next frame, which is what the setters of entities::Search do.
The SearchBar variant is a pill of components::Search::BarHeight; the FullScreen variant is a square-cornered header of components::Search::ViewHeight with a divider under it. The container color follows the elevation level of the field.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
| ecs::EntityComponentNotFoundException | When the entity lacks one of the components listed in install(). |
Definition at line 330 of file search.cpp.


|
static |
Empty the query as a press on the clear icon would.
Calls setText() with an empty string, then the clear handler of components::Search when there is one.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 269 of file search.cpp.


|
static |
Hide the search field.
Clears the visible flag of its components::Overlay. The query is kept and no handler is called.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 315 of file search.cpp.


|
static |
Give a search field its accessibility role and make its icons pressable.
Sets the role of its components::Accessibility to Search, resets its components::Elevation to level 0, then calls installIcon(), installClearIcon() and installTrailingIcon(). Call it once, after the entity has its components::Search, Overlay, TextField, Elevation, Line, Accessibility, Layout, Transform, Bound, Color and Borders. Set another elevation level after this call, not before.
| componentRegistry | The registry holding the components. It is captured by the icon handlers and must outlive the entity. |
| entityIdentifier | The search entity. |
| ecs::EntityComponentNotFoundException | When the entity lacks components::Accessibility, Elevation or Search. |
Definition at line 173 of file search.cpp.

|
static |
Make the clear icon a button that calls clear().
Adds the interaction components to the clear icon recorded in components::Search and names it "clear search" for assistive technology. Call it once the icon entity exists. Does nothing when no clear icon is recorded.
| componentRegistry | The registry holding the components. It is captured by the press handler and must outlive the entity. |
| entityIdentifier | The search entity. |
Definition at line 204 of file search.cpp.


|
static |
Make the leading icon a button that calls pressIcon().
Adds the interaction components to the leading icon recorded in components::Search and names it "search" for assistive technology. Call it once the icon entity exists. Does nothing when no leading icon is recorded.
| componentRegistry | The registry holding the components. It is captured by the press handler and must outlive the entity. |
| entityIdentifier | The search entity. |
Definition at line 189 of file search.cpp.


|
static |
Make the trailing icon a button that calls pressTrailingIcon().
Adds the interaction components to the trailing icon recorded in components::Search. Its accessible name is the name of the trailing glyph at the time of the call. Call it once the icon entity exists. Does nothing when no trailing icon is recorded.
| componentRegistry | The registry holding the components. It is captured by the press handler and must outlive the entity. |
| entityIdentifier | The search entity. |
Definition at line 220 of file search.cpp.


|
static |
Whether the search field is shown.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 322 of file search.cpp.


|
static |
Activate the leading icon as a press on it would.
Calls the icon press handler of components::Search when there is one.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 283 of file search.cpp.

|
static |
Activate the trailing icon as a press on it would.
Calls the trailing icon press handler of components::Search when there is one.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 295 of file search.cpp.

|
static |
Replace the query and restyle the field.
Writes the query to components::Search and to the query child when it exists, then calls apply() so the placeholder and the clear icon follow. No handler is called.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
| text | The new query; an empty string shows the placeholder again. |
Definition at line 252 of file search.cpp.


|
static |
Show the search field.
Sets the visible flag of its components::Overlay. The field is not restyled here; that happens on the next frame.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 308 of file search.cpp.


|
static |
Get the query the field holds.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The search entity. |
Definition at line 237 of file search.cpp.


|
overridevirtual |
Run apply() on one search field; called by the frame loop.
Logs a warning and does nothing when the entity has no components::Search.
| entityIdentifier | The search entity. |
Implements guillaume::ecs::System.
Definition at line 424 of file search.cpp.
