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

State of a search field: a leading icon, the query the user types (or a placeholder), then a clear button or a loading glyph and an optional trailing icon. More...

#include <headers/guillaume/components/search.hpp>

Inheritance diagram for guillaume::components::Search:
Collaboration diagram for guillaume::components::Search:

Public Types

enum class  Variant { SearchBar , FullScreen , View = FullScreen }
 Shape of the search field. More...

Public Member Functions

 Search (void)=default
 Create the configuration of an empty search bar with the "search" leading icon.
 ~Search (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the shape of the field.
Search & setVariant (Variant variant)
 Set the shape of the field.
const std::string & getPlaceholder (void) const noexcept
 Get the hint shown while the query is empty.
Search & setPlaceholder (const std::string &placeholder)
 Set the hint shown while the query is empty, such as "Search".
const std::string & getText (void) const noexcept
 Get the query.
Search & setText (const std::string &text)
 Store the query.
const std::string & getIconGlyph (void) const noexcept
 Get the icon at the leading edge of the field.
Search & setIconGlyph (const std::string &glyph)
 Set the icon at the leading edge of the field, such as "arrow_back".
const std::string & getTrailingGlyph (void) const noexcept
 Get the icon at the trailing edge of the field.
Search & setTrailingGlyph (const std::string &glyph)
 Set the icon at the trailing edge of the field, such as "mic".
bool isLoading (void) const noexcept
 Tell whether the field shows its loading glyph.
Search & setLoading (bool loading)
 Show or hide the loading glyph.
const std::function< void(void)> & getOnIconPress (void) const noexcept
 Get the callback run when the leading icon is pressed.
Search & setOnIconPress (std::function< void(void)> handler)
 Set the callback run when the leading icon is pressed.
const std::function< void(void)> & getOnClearIconPress (void) const noexcept
 Get the callback run when the clear button is pressed.
Search & setOnClearIconPress (std::function< void(void)> handler)
 Set the callback run when the clear button is pressed.
const std::function< void(void)> & getOnTrailingIconPress (void) const noexcept
 Get the callback run when the trailing icon is pressed.
Search & setOnTrailingIconPress (std::function< void(void)> handler)
 Set the callback run when the trailing icon is pressed.
ecs::Entity::Identifier getSearchIcon (void) const noexcept
 Get the pressable child that draws the leading icon.
Search & setSearchIcon (ecs::Entity::Identifier identifier)
 Record the pressable child that draws the leading icon.
ecs::Entity::Identifier getTextEntity (void) const noexcept
 Get the child the user types the query in.
Search & setTextEntity (ecs::Entity::Identifier identifier)
 Record the child the user types the query in.
ecs::Entity::Identifier getPlaceholderEntity (void) const noexcept
 Get the child that draws the placeholder.
Search & setPlaceholderEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the placeholder.
ecs::Entity::Identifier getClearIcon (void) const noexcept
 Get the pressable child that draws the clear button.
Search & setClearIcon (ecs::Entity::Identifier identifier)
 Record the pressable child that draws the clear button.
ecs::Entity::Identifier getLoadingIcon (void) const noexcept
 Get the child that draws the loading glyph.
Search & setLoadingIcon (ecs::Entity::Identifier identifier)
 Record the child that draws the loading glyph.
ecs::Entity::Identifier getTrailingIcon (void) const noexcept
 Get the pressable child that draws the trailing icon.
Search & setTrailingIcon (ecs::Entity::Identifier identifier)
 Record the pressable child that draws the trailing icon.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float DefaultWidth = 360.0f
 Width given to a search field that has no fixed width, in dp.
static constexpr float BarHeight = 56.0f
 Height of the SearchBar variant, in dp.
static constexpr float ViewHeight = 72.0f
 Height of the FullScreen variant, in dp.
static constexpr float IconSize = 24.0f
 Size of the icons, in dp.
static constexpr const char * SearchGlyph = "search"
 Glyph name of the default leading icon.
static constexpr const char * ClearGlyph = "close"
 Glyph name of the clear button.
static constexpr const char * LoadingGlyph = "progress_activity"
 Glyph name of the icon shown while loading.

Detailed Description

State of a search field: a leading icon, the query the user types (or a placeholder), then a clear button or a loading glyph and an optional trailing icon.

The entities::Search widget writes it: the texts, glyphs, handlers and the identifiers of the children it builds. systems::Search reads it every frame in the Layout phase and turns it into the field's Layout, Color, Borders, Line, Overlay flags, TextField and Accessibility, and into the glyph, color and enabled state of its children.

Two things are not stored here: whether the field is shown (components::Overlay of the same entity) and its elevation (components::Elevation).

Once the query child exists, the components::Text of that child is where the user types, and systems::Search copies it back into this component every frame. So change the query with systems::Search::setText, which writes both; a value written with setText() alone is overwritten on the next frame.

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

Definition at line 58 of file search.hpp.

Member Enumeration Documentation

◆ Variant

Shape of the search field.

Enumerator
SearchBar 

Pill-shaped bar, 56 dp high.

FullScreen 

Square-cornered view, 72 dp high, with a divider line under it.

View 

Another name for FullScreen.

Definition at line 64 of file search.hpp.

Member Function Documentation

◆ getClearIcon()

ecs::Entity::Identifier guillaume::components::Search::getClearIcon ( void ) const
noexcept

Get the pressable child that draws the clear button.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 154 of file search.cpp.

Here is the caller graph for this function:

◆ getIconGlyph()

const std::string & guillaume::components::Search::getIconGlyph ( void ) const
noexcept

Get the icon at the leading edge of the field.

Returns
The glyph name, "search" by default.

Definition at line 59 of file search.cpp.

◆ getLoadingIcon()

ecs::Entity::Identifier guillaume::components::Search::getLoadingIcon ( void ) const
noexcept

Get the child that draws the loading glyph.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 164 of file search.cpp.

◆ getOnClearIconPress()

const std::function< void(void)> & guillaume::components::Search::getOnClearIconPress ( void ) const
noexcept

Get the callback run when the clear button is pressed.

Returns
The callback; empty when none is set.

Definition at line 101 of file search.cpp.

◆ getOnIconPress()

const std::function< void(void)> & guillaume::components::Search::getOnIconPress ( void ) const
noexcept

Get the callback run when the leading icon is pressed.

Returns
The callback; empty when none is set.

Definition at line 89 of file search.cpp.

◆ getOnTrailingIconPress()

const std::function< void(void)> & guillaume::components::Search::getOnTrailingIconPress ( void ) const
noexcept

Get the callback run when the trailing icon is pressed.

Returns
The callback; empty when none is set.

Definition at line 113 of file search.cpp.

◆ getPlaceholder()

const std::string & guillaume::components::Search::getPlaceholder ( void ) const
noexcept

Get the hint shown while the query is empty.

Returns
The placeholder; it is also the field's accessible name.

Definition at line 39 of file search.cpp.

◆ getPlaceholderEntity()

ecs::Entity::Identifier guillaume::components::Search::getPlaceholderEntity ( void ) const
noexcept

Get the child that draws the placeholder.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 144 of file search.cpp.

◆ getSearchIcon()

ecs::Entity::Identifier guillaume::components::Search::getSearchIcon ( void ) const
noexcept

Get the pressable child that draws the leading icon.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 124 of file search.cpp.

Here is the caller graph for this function:

◆ getText()

const std::string & guillaume::components::Search::getText ( void ) const
noexcept

Get the query.

Once the query child exists, its components::Text is what the user edits; systems::Search copies it back here every frame.

Returns
The query as of the last pass of systems::Search.

Definition at line 49 of file search.cpp.

Here is the caller graph for this function:

◆ getTextEntity()

ecs::Entity::Identifier guillaume::components::Search::getTextEntity ( void ) const
noexcept

Get the child the user types the query in.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 134 of file search.cpp.

Here is the caller graph for this function:

◆ getTrailingGlyph()

const std::string & guillaume::components::Search::getTrailingGlyph ( void ) const
noexcept

Get the icon at the trailing edge of the field.

Returns
The glyph name; empty when the field has no trailing icon.

Definition at line 69 of file search.cpp.

Here is the caller graph for this function:

◆ getTrailingIcon()

ecs::Entity::Identifier guillaume::components::Search::getTrailingIcon ( void ) const
noexcept

Get the pressable child that draws the trailing icon.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 174 of file search.cpp.

◆ getVariant()

Search::Variant guillaume::components::Search::getVariant ( void ) const
noexcept

Get the shape of the field.

Returns
The variant, Variant::SearchBar by default.

Definition at line 29 of file search.cpp.

◆ isLoading()

bool guillaume::components::Search::isLoading ( void ) const
noexcept

Tell whether the field shows its loading glyph.

Returns
True while loading.

Definition at line 79 of file search.cpp.

◆ setClearIcon()

Search & guillaume::components::Search::setClearIcon ( ecs::Entity::Identifier identifier)

Record the pressable child that draws the clear button.

The button is shown and enabled only while there is a query and the field is not loading. Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 159 of file search.cpp.

Here is the call graph for this function:

◆ setIconGlyph()

Search & guillaume::components::Search::setIconGlyph ( const std::string & glyph)

Set the icon at the leading edge of the field, such as "arrow_back".

Marks the component changed only when the name differs.

Parameters
glyphThe glyph name.
Returns
This component, for chaining.

Definition at line 64 of file search.cpp.

Here is the call graph for this function:

◆ setLoading()

Search & guillaume::components::Search::setLoading ( bool loading)

Show or hide the loading glyph.

While loading, the loading glyph takes the place of the clear button. Marks the component changed only when the flag differs.

Parameters
loadingTrue while results are being fetched.
Returns
This component, for chaining.

Definition at line 84 of file search.cpp.

Here is the call graph for this function:

◆ setLoadingIcon()

Search & guillaume::components::Search::setLoadingIcon ( ecs::Entity::Identifier identifier)

Record the child that draws the loading glyph.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 169 of file search.cpp.

Here is the call graph for this function:

◆ setOnClearIconPress()

Search & guillaume::components::Search::setOnClearIconPress ( std::function< void(void)> handler)

Set the callback run when the clear button is pressed.

It runs after the query has been emptied. Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 106 of file search.cpp.

Here is the call graph for this function:

◆ setOnIconPress()

Search & guillaume::components::Search::setOnIconPress ( std::function< void(void)> handler)

Set the callback run when the leading icon is pressed.

Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 94 of file search.cpp.

Here is the call graph for this function:

◆ setOnTrailingIconPress()

Search & guillaume::components::Search::setOnTrailingIconPress ( std::function< void(void)> handler)

Set the callback run when the trailing icon is pressed.

Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 118 of file search.cpp.

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

◆ setPlaceholder()

Search & guillaume::components::Search::setPlaceholder ( const std::string & placeholder)

Set the hint shown while the query is empty, such as "Search".

Marks the component changed only when the text differs.

Parameters
placeholderThe new placeholder.
Returns
This component, for chaining.

Definition at line 44 of file search.cpp.

Here is the call graph for this function:

◆ setPlaceholderEntity()

Search & guillaume::components::Search::setPlaceholderEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the placeholder.

It takes the place of the query child while the query is empty. Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 149 of file search.cpp.

Here is the call graph for this function:

◆ setSearchIcon()

Search & guillaume::components::Search::setSearchIcon ( ecs::Entity::Identifier identifier)

Record the pressable child that draws the leading icon.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 129 of file search.cpp.

Here is the call graph for this function:

◆ setText()

Search & guillaume::components::Search::setText ( const std::string & text)

Store the query.

Once the query child exists this value is overwritten every frame from that child; use systems::Search::setText to change the query. Marks the component changed only when the text differs.

Parameters
textThe new query.
Returns
This component, for chaining.

Definition at line 54 of file search.cpp.

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

◆ setTextEntity()

Search & guillaume::components::Search::setTextEntity ( ecs::Entity::Identifier identifier)

Record the child the user types the query in.

From then on its components::Text is the source of the query. Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 139 of file search.cpp.

Here is the call graph for this function:

◆ setTrailingGlyph()

Search & guillaume::components::Search::setTrailingGlyph ( const std::string & glyph)

Set the icon at the trailing edge of the field, such as "mic".

The trailing icon is shown and pressable only while this name is not empty. Marks the component changed only when the name differs.

Parameters
glyphThe glyph name; empty for no trailing icon.
Returns
This component, for chaining.

Definition at line 74 of file search.cpp.

Here is the call graph for this function:

◆ setTrailingIcon()

Search & guillaume::components::Search::setTrailingIcon ( ecs::Entity::Identifier identifier)

Record the pressable child that draws the trailing icon.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 179 of file search.cpp.

Here is the call graph for this function:

◆ setVariant()

Search & guillaume::components::Search::setVariant ( Variant variant)

Set the shape of the field.

Marks the component changed only when the variant differs.

Parameters
variantThe new variant.
Returns
This component, for chaining.

Definition at line 34 of file search.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ BarHeight

float guillaume::components::Search::BarHeight = 56.0f
staticconstexpr

Height of the SearchBar variant, in dp.

Definition at line 75 of file search.hpp.

◆ ClearGlyph

const char* guillaume::components::Search::ClearGlyph = "close"
staticconstexpr

Glyph name of the clear button.

Definition at line 87 of file search.hpp.

◆ DefaultWidth

float guillaume::components::Search::DefaultWidth = 360.0f
staticconstexpr

Width given to a search field that has no fixed width, in dp.

Definition at line 72 of file search.hpp.

◆ IconSize

float guillaume::components::Search::IconSize = 24.0f
staticconstexpr

Size of the icons, in dp.

Definition at line 81 of file search.hpp.

◆ LoadingGlyph

const char* guillaume::components::Search::LoadingGlyph = "progress_activity"
staticconstexpr

Glyph name of the icon shown while loading.

Definition at line 90 of file search.hpp.

◆ SearchGlyph

const char* guillaume::components::Search::SearchGlyph = "search"
staticconstexpr

Glyph name of the default leading icon.

Definition at line 84 of file search.hpp.

◆ ViewHeight

float guillaume::components::Search::ViewHeight = 72.0f
staticconstexpr

Height of the FullScreen variant, in dp.

Definition at line 78 of file search.hpp.


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