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

A compact, 32 dp high pill with a label and optional icons, used as an action, a filter, an entered value or a suggestion. More...

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

Inheritance diagram for guillaume::entities::Chip:
Collaboration diagram for guillaume::entities::Chip:

Classes

class  Builder
 Configures, creates and registers Chip widgets. More...

Public Types

using Variant = components::Chip::Variant
using Mode = components::Chip::Mode
 Paper chip mode: Flat (tonal fill, the default) or Outlined.
Public Types inherited from guillaume::entities::SurfaceBase< components::Selectable, components::Elevation, components::Chip >
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

 ~Chip (void) override
 Destructor.
Chip & setVariant (Variant variant)
 Set the variant. Restyles at once.
Variant getVariant (void) const
 Get the variant.
Chip & setLabel (const std::string &label)
 Set the label text. Restyles at once.
Chip & setSelected (bool selected)
 Select or deselect the chip, whatever its variant. Restyles at once.
bool isSelected (void) const
 Check whether the chip is selected.
Chip & setMode (Mode mode)
 Set the mode. Restyles at once.
Mode getMode (void) const
 Get the mode.
Chip & setDisabled (bool disabled)
 Enable or disable the chip. Restyles at once.
bool isDisabled (void) const
 Check whether the chip is disabled.
Chip & setCompact (bool compact)
 Use the compact padding (Paper compact). Restyles at once.
Chip & setElevated (bool elevated)
 Paint a level 1 shadow under the chip (Paper elevated). Restyles at once.
Chip & setShowSelectedOverlay (bool show)
 Darken the chip with a pressed state layer while it is selected (Paper showSelectedOverlay). Restyles at once.
Chip & setShowSelectedCheck (bool show)
 Show the check icon while the chip is selected (Paper showSelectedCheck). Restyles at once.
Chip & setOnPress (std::function< void(void)> onPress)
 Set the handler called when the user presses the chip (Paper onPress).
Chip & setOnClose (std::function< void(void)> onClose)
 Set the handler called when the user presses the trailing close icon (Paper onClose).
ecs::Entity::Identifier getCloseIconIdentifier (void) const
 Get the identifier of the trailing close icon child.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Selectable, components::Elevation, components::Chip >
 ~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< Chip > create (Arguments &&...arguments)
 Create a chip and its icon and label 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::Selectable, components::Elevation, components::Chip >
 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 compact, 32 dp high pill with a label and optional icons, used as an action, a filter, an entered value or a suggestion.

Its state lives in components::Chip (variant, mode, label, flags, callbacks, child identifiers), its selected state in components::Selectable and its enabled state in components::StyleState; systems::Chip colors the chip and its children and arranges them in a row each frame, in the Layout phase. The class itself holds no field: its setters write the components and restyle at once.

The variant decides which children are built:

  • Assist: a leading icon (a default glyph when none is given) and the label.
  • Filter: the label, a leading icon when a glyph is given, and a check icon that takes the place of the leading icon while the chip is selected. A press toggles the selection.
  • Input: the label, a leading icon when a glyph is given, and a trailing close icon that calls the close handler.
  • Suggestion: the label, and a leading icon when a glyph is given.
Chip::Builder builder(getComponentRegistry(), getEntityRegistry());
auto chip = builder.makeChip(parent, Chip::Variant::Filter, "Vegan",
"", false);
chip->setOnPress([] {
// called when the user presses the chip
});
Configures, creates and registers Chip widgets.
Definition chip.hpp:113

Chip::create(registry, config, variant, label, iconGlyph, selected) builds the same widget without registering it in an entity registry; config is the SurfaceConfig of the pill (pose, padding, height).

The chip owns its icon and label children: it is the entity registry they are registered in. The children are built once, from the variant given at creation: setVariant() changes the behavior and the colors but adds no icon. The chip's Color, Borders, Elevation and layout padding are written each frame, so values set by hand on them are overwritten. setSelected() does not call the press handler; only a user press does. getChildren() returns the children currently laid out, read from the chip's components::Layout.

See also
components::Chip, systems::Chip, SurfaceBase

Definition at line 94 of file chip.hpp.

Member Typedef Documentation

◆ Mode

Paper chip mode: Flat (tonal fill, the default) or Outlined.

Definition at line 104 of file chip.hpp.

◆ Variant

Chip variant: Assist, Filter, Input or Suggestion (see components::Chip::Variant).

Definition at line 101 of file chip.hpp.

Constructor & Destructor Documentation

◆ ~Chip()

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

Destructor.

Definition at line 130 of file chip.cpp.

Member Function Documentation

◆ create()

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

Create a chip and its icon and label children, without registering it in an entity registry.

The constructor is private because the children need a chip already held by a std::shared_ptr as parent: create() constructs the chip then calls build(), which creates them.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsThe arguments forwarded to the constructor: (registry, config, variant, label, iconGlyph, selected).
Returns
The new chip.

Definition at line 227 of file chip.hpp.

Here is the caller graph for this function:

◆ getCloseIconIdentifier()

ecs::Entity::Identifier guillaume::entities::Chip::getCloseIconIdentifier ( void ) const

Get the identifier of the trailing close icon child.

Returns
The identifier of the close icon, or ecs::Entity::InvalidIdentifier when the chip has none.

Definition at line 215 of file chip.cpp.

Here is the call graph for this function:

◆ getMode()

Chip::Mode guillaume::entities::Chip::getMode ( void ) const

Get the mode.

Returns
Mode::Flat (the default) or Mode::Outlined.

Definition at line 143 of file chip.cpp.

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

◆ getVariant()

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

Get the variant.

Returns
The variant stored in components::Chip.

Definition at line 231 of file chip.cpp.

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

◆ isDisabled()

bool guillaume::entities::Chip::isDisabled ( void ) const

Check whether the chip is disabled.

Returns
True when the chip ignores input.

Definition at line 157 of file chip.cpp.

Here is the call graph for this function:

◆ isSelected()

bool guillaume::entities::Chip::isSelected ( void ) const

Check whether the chip is selected.

Returns
True when its components::Selectable is selected.

Definition at line 254 of file chip.cpp.

Here is the call graph for this function:

◆ setCompact()

Chip & guillaume::entities::Chip::setCompact ( bool compact)

Use the compact padding (Paper compact). Restyles at once.

Parameters
compactTrue for 8 dp of padding around the content, false for 12 dp (the default).
Returns
Reference to this chip for chaining.

Definition at line 163 of file chip.cpp.

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

◆ setDisabled()

Chip & guillaume::entities::Chip::setDisabled ( bool disabled)

Enable or disable the chip. Restyles at once.

A disabled chip is drawn with the disabled colors and calls neither the press handler nor the close handler.

Parameters
disabledTrue to disable the chip, false to enable it.
Returns
Reference to this chip for chaining.

Definition at line 150 of file chip.cpp.

Here is the call graph for this function:

◆ setElevated()

Chip & guillaume::entities::Chip::setElevated ( bool elevated)

Paint a level 1 shadow under the chip (Paper elevated). Restyles at once.

Parameters
elevatedTrue for a shadow, false for none (the default). A disabled chip has no shadow.
Returns
Reference to this chip for chaining.

Definition at line 172 of file chip.cpp.

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

◆ setLabel()

Chip & guillaume::entities::Chip::setLabel ( const std::string & label)

Set the label text. Restyles at once.

Parameters
labelThe text shown in the chip, also used as its accessibility label.
Returns
Reference to this chip for chaining.

Definition at line 238 of file chip.cpp.

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

◆ setMode()

Chip & guillaume::entities::Chip::setMode ( Mode mode)

Set the mode. Restyles at once.

Parameters
modeMode::Flat for a tonal fill, Mode::Outlined for a transparent chip with a 1 dp outline until it is selected.
Returns
Reference to this chip for chaining.

Definition at line 134 of file chip.cpp.

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

◆ setOnClose()

Chip & guillaume::entities::Chip::setOnClose ( std::function< void(void)> onClose)

Set the handler called when the user presses the trailing close icon (Paper onClose).

The handler decides what closing means; the chip does not remove itself. Only a chip created as an Input chip has a close icon: setting a handler on another chip adds none.

Parameters
onCloseThe function to call. Pass an empty function to remove the handler.
Returns
Reference to this chip for chaining.

Definition at line 207 of file chip.cpp.

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

◆ setOnPress()

Chip & guillaume::entities::Chip::setOnPress ( std::function< void(void)> onPress)

Set the handler called when the user presses the chip (Paper onPress).

For a Filter chip it is called after the selection was toggled.

Parameters
onPressThe function to call. Pass an empty function to remove the handler.
Returns
Reference to this chip for chaining.

Definition at line 199 of file chip.cpp.

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

◆ setSelected()

Chip & guillaume::entities::Chip::setSelected ( bool selected)

Select or deselect the chip, whatever its variant. Restyles at once.

The press handler is not called.

Parameters
selectedTrue to select the chip.
Returns
Reference to this chip for chaining.

Definition at line 247 of file chip.cpp.

Here is the call graph for this function:

◆ setShowSelectedCheck()

Chip & guillaume::entities::Chip::setShowSelectedCheck ( bool show)

Show the check icon while the chip is selected (Paper showSelectedCheck). Restyles at once.

Only a chip created as a Filter chip has a check icon.

Parameters
showTrue to show the check while selected (the default), false to keep the leading icon.
Returns
Reference to this chip for chaining.

Definition at line 190 of file chip.cpp.

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

◆ setShowSelectedOverlay()

Chip & guillaume::entities::Chip::setShowSelectedOverlay ( bool show)

Darken the chip with a pressed state layer while it is selected (Paper showSelectedOverlay). Restyles at once.

Parameters
showTrue to overlay the layer while selected, false not to (the default).
Returns
Reference to this chip for chaining.

Definition at line 181 of file chip.cpp.

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

◆ setVariant()

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

Set the variant. Restyles at once.

Only the behavior follows (a Filter chip toggles its selection on a press): the icon children were built for the variant given at creation and none is added or removed.

Parameters
variantThe new variant.
Returns
Reference to this chip for chaining.

Definition at line 222 of file chip.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: