guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::systems::Search Class Reference

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>

Inheritance diagram for guillaume::systems::Search:
Collaboration diagram for guillaume::systems::Search:

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.

Detailed Description

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.

See also
components::Search, components::TextField, entities::Search, systems::TextField

Definition at line 71 of file search.hpp.

Constructor & Destructor Documentation

◆ Search()

guillaume::systems::Search::Search ( void )

Create the system in the Layout phase.

Definition at line 168 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::Search::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks one of the components listed in install().

Definition at line 330 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ clear()

void guillaume::systems::Search::clear ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.

Definition at line 269 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ hide()

void guillaume::systems::Search::hide ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Hide the search field.

Clears the visible flag of its components::Overlay. The query is kept and no handler is called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.

Definition at line 315 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ install()

void guillaume::systems::Search::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components. It is captured by the icon handlers and must outlive the entity.
entityIdentifierThe search entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::Accessibility, Elevation or Search.

Definition at line 173 of file search.cpp.

Here is the call graph for this function:

◆ installClearIcon()

void guillaume::systems::Search::installClearIcon ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components. It is captured by the press handler and must outlive the entity.
entityIdentifierThe search entity.

Definition at line 204 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ installIcon()

void guillaume::systems::Search::installIcon ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components. It is captured by the press handler and must outlive the entity.
entityIdentifierThe search entity.

Definition at line 189 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ installTrailingIcon()

void guillaume::systems::Search::installTrailingIcon ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components. It is captured by the press handler and must outlive the entity.
entityIdentifierThe search entity.

Definition at line 220 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isVisible()

bool guillaume::systems::Search::isVisible ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the search field is shown.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.
Returns
The visible flag of its components::Overlay.

Definition at line 322 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ pressIcon()

void guillaume::systems::Search::pressIcon ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Activate the leading icon as a press on it would.

Calls the icon press handler of components::Search when there is one.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.

Definition at line 283 of file search.cpp.

Here is the call graph for this function:

◆ pressTrailingIcon()

void guillaume::systems::Search::pressTrailingIcon ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Activate the trailing icon as a press on it would.

Calls the trailing icon press handler of components::Search when there is one.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.

Definition at line 295 of file search.cpp.

Here is the call graph for this function:

◆ setText()

void guillaume::systems::Search::setText ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
const std::string & text )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.
textThe new query; an empty string shows the placeholder again.

Definition at line 252 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ show()

void guillaume::systems::Search::show ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.

Definition at line 308 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ text()

std::string guillaume::systems::Search::text ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the query the field holds.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe search entity.
Returns
The content of the query child when it exists and has a components::Text, otherwise the query recorded in components::Search. Empty when nothing is typed.

Definition at line 237 of file search.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::Search::update ( const ecs::Entity::Identifier & entityIdentifier)
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.

Parameters
entityIdentifierThe search entity.

Implements guillaume::ecs::System.

Definition at line 424 of file search.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: