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

A search field: a leading icon, an editable query with a placeholder, a clear button and an optional trailing icon (Paper Searchbar). More...

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

Inheritance diagram for guillaume::entities::Search:
Collaboration diagram for guillaume::entities::Search:

Classes

class  Builder
 Configures a Search, creates it and registers it in an entity registry. More...

Public Types

using Variant = components::Search::Variant
 Search variant.
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::TextField, components::Elevation, components::Line, components::Focus, components::Accessibility, components::Search >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~Search (void) override
 Default destructor.
Search & setVariant (Variant variant)
 Change the variant. Restyles at once.
Variant getVariant (void) const
 Get the variant.
Search & setPlaceholder (const std::string &placeholder)
 Change the placeholder: the hint shown while the query is empty.
Search & setText (const std::string &text)
 Replace the query. Restyles at once.
std::string getText (void) const
 Get the query, including what the user typed.
Search & clear (void)
 Empty the query, as the clear button does, then call the clear handler.
Search & setIcon (const std::string &iconGlyph)
 Change the glyph of the leading icon (Paper icon). Restyles at once.
Search & setOnIconPress (std::function< void(void)> onIconPress)
 Set the handler called when the user presses the leading icon (Paper onIconPress).
Search & setOnClearIconPress (std::function< void(void)> onClearIconPress)
 Set the handler called after the query was cleared, by the clear button or by clear() (Paper onClearIconPress).
Search & setTrailingIcon (const std::string &iconGlyph, std::function< void(void)> onPress={})
 Set or hide the trailing icon (Paper right and traileringIcon).
Search & setLoading (bool loading)
 Show the loading glyph in place of the clear button, or the reverse. Restyles at once.
bool isLoading (void) const
 Whether the loading glyph replaces the clear button.
Search & setElevation (theme::ElevationLevel level)
 Set the elevation level (Paper elevation). Restyles at once.
ecs::Entity::Identifier getIconIdentifier (void) const
 Get the leading icon: a pressable icon entity.
ecs::Entity::Identifier getClearIdentifier (void) const
 Get the clear button: a pressable icon entity.
ecs::Entity::Identifier getPlaceholderIdentifier (void) const
 Get the placeholder text entity.
ecs::Entity::Identifier getTextIdentifier (void) const
 Get the query text entity: the text the user edits.
Search & show (void)
 Show the search field: set its components::Overlay visible.
Search & hide (void)
 Hide the search field: set its components::Overlay not visible.
bool isVisible (void) const
 Whether the search field is shown.
Search & open (void)
 Open the search field. Same as show().
Search & close (void)
 Close the search field. Same as hide().
bool isOpen (void) const
 Whether the search field is open. Same as isVisible().
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::TextField, components::Elevation, components::Line, components::Focus, components::Accessibility, components::Search >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Search > create (Arguments &&...arguments)
 Create a search field and its children, without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::TextField, components::Elevation, components::Line, components::Focus, components::Accessibility, components::Search >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A search field: a leading icon, an editable query with a placeholder, a clear button and an optional trailing icon (Paper Searchbar).

Its state lives in components::Search (variant, placeholder, query, glyphs, loading flag, handlers, child identifiers); whether it is shown lives in components::Overlay and its elevation in components::Elevation. systems::Search styles the field and lays out the children its state calls for each frame, in the Layout phase. The class itself holds no field: it builds the child entities, and its setters write the components and restyle at once.

Search::Builder builder(getComponentRegistry(), getEntityRegistry());
auto search = builder.makeSearch(parent, Search::Variant::SearchBar,
"Search messages");
search->setOnClearIconPress([] {
// called after the query was cleared
});
search->open();
std::string query = search->getText();
Configures a Search, creates it and registers it in an entity registry.
Definition search.hpp:112

Search::create(registry, config, variant, placeholder, text) builds the same widget without registering it in an entity registry.

Things to know:

  • Variant::SearchBar is a 56 dp high pill; Variant::FullScreen (alias View) is 72 dp high, without rounded corners, with a divider under it. The height, shape, divider, color, padding and spacing are overwritten each frame. The width is the fixed width of the surface configuration, 360 dp by default.
  • The placeholder shows while the query is empty. The clear button works while the query is not empty; the loading glyph replaces it while isLoading() is true.
  • The user edits the query child directly: read the query with getText(). The widget has no handler called when the query changes; setText() calls no handler either.
  • isOpen() is false at creation: the field's components::Overlay starts not visible until open() or show().
  • The field is the entity registry that owns its children; they are built once and kept, so their identifiers stay valid.
See also
components::Search, systems::Search, TextField

Definition at line 98 of file search.hpp.

Member Typedef Documentation

◆ Variant

Constructor & Destructor Documentation

◆ ~Search()

guillaume::entities::Search::~Search ( void )
override

Default destructor.

Definition at line 123 of file search.cpp.

Member Function Documentation

◆ clear()

Search & guillaume::entities::Search::clear ( void )

Empty the query, as the clear button does, then call the clear handler.

Returns
This search field, for chaining.

Definition at line 164 of file search.cpp.

Here is the call graph for this function:

◆ close()

Search & guillaume::entities::Search::close ( void )

Close the search field. Same as hide().

Returns
This search field, for chaining.

Definition at line 285 of file search.cpp.

Here is the call graph for this function:

◆ create()

template<typename... Arguments>
std::shared_ptr< Search > guillaume::entities::Search::create ( Arguments &&... arguments)
inlinestatic

Create a search field and its children, without registering it in an entity registry.

The constructor is private because the children need the field to be owned by a shared pointer before they can take it as parent; create() constructs the field, then builds the icons, the query text and the placeholder.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsForwarded to the private constructor: (registry, config, variant, placeholder, text).
Returns
The new search field.

Definition at line 209 of file search.hpp.

Here is the caller graph for this function:

◆ getClearIdentifier()

ecs::Entity::Identifier guillaume::entities::Search::getClearIdentifier ( void ) const

Get the clear button: a pressable icon entity.

Returns
The identifier of the icon, or ecs::Entity::InvalidIdentifier before the children are built.

Definition at line 241 of file search.cpp.

Here is the call graph for this function:

◆ getIconIdentifier()

ecs::Entity::Identifier guillaume::entities::Search::getIconIdentifier ( void ) const

Get the leading icon: a pressable icon entity.

Returns
The identifier of the icon, or ecs::Entity::InvalidIdentifier when it was not built (the leading glyph was empty).

Definition at line 234 of file search.cpp.

Here is the call graph for this function:

◆ getPlaceholderIdentifier()

ecs::Entity::Identifier guillaume::entities::Search::getPlaceholderIdentifier ( void ) const

Get the placeholder text entity.

Returns
The identifier of the text, or ecs::Entity::InvalidIdentifier when the placeholder has always been empty.

Definition at line 248 of file search.cpp.

Here is the call graph for this function:

◆ getText()

std::string guillaume::entities::Search::getText ( void ) const

Get the query, including what the user typed.

Returns
The content of the query child, or the query stored in components::Search before that child is built.

Definition at line 159 of file search.cpp.

Here is the call graph for this function:

◆ getTextIdentifier()

ecs::Entity::Identifier guillaume::entities::Search::getTextIdentifier ( void ) const

Get the query text entity: the text the user edits.

Returns
The identifier of the text, or ecs::Entity::InvalidIdentifier before the children are built.

Definition at line 255 of file search.cpp.

Here is the call graph for this function:

◆ getVariant()

Search::Variant guillaume::entities::Search::getVariant ( void ) const

Get the variant.

Returns
The variant stored in components::Search.

Definition at line 136 of file search.cpp.

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

◆ hide()

Search & guillaume::entities::Search::hide ( void )

Hide the search field: set its components::Overlay not visible.

Returns
This search field, for chaining.

Definition at line 268 of file search.cpp.

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

◆ isLoading()

bool guillaume::entities::Search::isLoading ( void ) const

Whether the loading glyph replaces the clear button.

Returns
True while loading.

Definition at line 218 of file search.cpp.

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

◆ isOpen()

bool guillaume::entities::Search::isOpen ( void ) const

Whether the search field is open. Same as isVisible().

Returns
True when shown; false at creation.

Definition at line 290 of file search.cpp.

Here is the call graph for this function:

◆ isVisible()

bool guillaume::entities::Search::isVisible ( void ) const

Whether the search field is shown.

Returns
True when its components::Overlay is visible; false at creation.

Definition at line 274 of file search.cpp.

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

◆ open()

Search & guillaume::entities::Search::open ( void )

Open the search field. Same as show().

Returns
This search field, for chaining.

Definition at line 280 of file search.cpp.

Here is the call graph for this function:

◆ setElevation()

Search & guillaume::entities::Search::setElevation ( theme::ElevationLevel level)

Set the elevation level (Paper elevation). Restyles at once.

Writes the field's components::Elevation. The fill color follows: the surface-container-high color at level 0, the tinted elevated surface color above.

Parameters
levelThe elevation level. Default: level 0.
Returns
This search field, for chaining.

Definition at line 225 of file search.cpp.

Here is the call graph for this function:

◆ setIcon()

Search & guillaume::entities::Search::setIcon ( const std::string & iconGlyph)

Change the glyph of the leading icon (Paper icon). Restyles at once.

Parameters
iconGlyphThe glyph name of the icon. The default is components::Search::SearchGlyph ("search").
Returns
This search field, for chaining.

Definition at line 170 of file search.cpp.

Here is the call graph for this function:

◆ setLoading()

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

Show the loading glyph in place of the clear button, or the reverse. Restyles at once.

Parameters
loadingTrue while a search is in progress.
Returns
This search field, for chaining.

Definition at line 209 of file search.cpp.

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

◆ setOnClearIconPress()

Search & guillaume::entities::Search::setOnClearIconPress ( std::function< void(void)> onClearIconPress)

Set the handler called after the query was cleared, by the clear button or by clear() (Paper onClearIconPress).

Parameters
onClearIconPressThe handler; an empty function for none.
Returns
This search field, for chaining.

Definition at line 189 of file search.cpp.

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

◆ setOnIconPress()

Search & guillaume::entities::Search::setOnIconPress ( std::function< void(void)> onIconPress)

Set the handler called when the user presses the leading icon (Paper onIconPress).

Parameters
onIconPressThe handler; an empty function for none.
Returns
This search field, for chaining.

Definition at line 180 of file search.cpp.

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

◆ setPlaceholder()

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

Change the placeholder: the hint shown while the query is empty.

Builds the placeholder child the first time the text is not empty, then restyles at once.

Parameters
placeholderThe new placeholder text; it is also the accessible name of the field.
Returns
This search field, for chaining.

Definition at line 143 of file search.cpp.

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

◆ setText()

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

Replace the query. Restyles at once.

Calls no handler.

Parameters
textThe new query.
Returns
This search field, for chaining.

Definition at line 153 of file search.cpp.

Here is the call graph for this function:

◆ setTrailingIcon()

Search & guillaume::entities::Search::setTrailingIcon ( const std::string & iconGlyph,
std::function< void(void)> onPress = {} )

Set or hide the trailing icon (Paper right and traileringIcon).

Builds the trailing icon child the first time the glyph is not empty, then restyles at once.

Parameters
iconGlyphThe glyph name of the icon; an empty string hides the icon and disables its presses.
onPressCalled when the user presses the trailing icon; it replaces the previous handler, even when left empty.
Returns
This search field, for chaining.

Definition at line 197 of file search.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Change the variant. Restyles at once.

Parameters
variantSearchBar for the 56 dp pill, FullScreen for the 72 dp field with a divider.
Returns
This search field, for chaining.

Definition at line 127 of file search.cpp.

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

◆ show()

Search & guillaume::entities::Search::show ( void )

Show the search field: set its components::Overlay visible.

Returns
This search field, for chaining.

Definition at line 262 of file search.cpp.

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

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