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

The rules of a chip: pressing it, selecting it, closing it, coloring it and arranging its icons and label. More...

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

Inheritance diagram for guillaume::systems::Chip:
Collaboration diagram for guillaume::systems::Chip:

Public Member Functions

 Chip (void)
 Create the system for the Layout phase, matching entities that have a components::Chip.
 ~Chip (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one chip.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Chip >
 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)
 Make an entity behave as a chip.
static void installCloseIcon (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Make the trailing icon of a chip a close button.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Draw one chip from its components and arrange its children.
static void press (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Press the chip as a click does.
static void close (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Press the close icon of the chip as a click does.
static void setSelected (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool selected)
 Select or deselect the chip from code and show it at once.
static bool isSelected (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the chip is selected.
static void setDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool disabled)
 Enable or disable the chip and show it at once.
static bool isDisabled (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the chip ignores input and is drawn disabled.
static std::string leadingGlyph (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the name of the glyph the leading icon of the chip should show.
static bool needsCheckIcon (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the widget class should build a selected check child for this chip.
static bool needsCloseIcon (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the widget class should build a trailing close icon child for this chip.

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

The rules of a chip: pressing it, selecting it, closing it, coloring it and arranging its icons and label.

The chip entity is the rounded container, a horizontal layout. Its leading icon, selected check, label and trailing close icon are optional child entities, recorded by identifier in components::Chip. Whether it is selected is the flag of components::Selectable; whether it is disabled is the enabled flag of components::StyleState.

// Select a filter chip from code; the press callback is not called.
systems::Chip::setSelected(registry, identifier, true);
static void setSelected(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool selected)
Select or deselect the chip from code and show it at once.
Definition chip.cpp:203

This system never creates a child: leadingGlyph, needsCheckIcon and needsCloseIcon tell the widget class (entities::Chip) which children to build. While the selected check is shown, it takes the place of the leading icon in the layout.

See also
guillaume::components::Chip, guillaume::entities::Chip, guillaume::systems::interaction

Definition at line 69 of file chip.hpp.

Constructor & Destructor Documentation

◆ Chip()

guillaume::systems::Chip::Chip ( void )

Create the system for the Layout phase, matching entities that have a components::Chip.

Definition at line 107 of file chip.cpp.

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

Member Function Documentation

◆ apply()

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

Draw one chip from its components and arrange its children.

  • Container: SecondaryContainer for a Flat chip and for any selected chip; transparent with a 1 dp Outline border for an unselected Outlined chip. A selected chip gets an extra tint when the component asks for the selected overlay, and the hover or press tint comes on top.
  • Content: the label and trailing icon use the content color of that container; the leading icon and the check are Primary, or the content color when selected.
  • Disabled: disabled container and content colors, no tint.
  • Elevation: level 1 for an elevated, enabled chip, else level 0.
  • Layout: padding of components::Chip::Padding, or CompactPadding for a compact chip; children in the order check or leading icon, label, trailing icon.

A chip whose component records no child at all keeps the layout children it was given.

The frame calls it through update. Call it yourself after writing components::Chip when the result must be visible before the next Layout phase; the setters of entities::Chip do.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity. It must have components::Chip, components::Selectable, components::Color, components::Borders, components::Elevation, components::Layout and components::Accessibility.

Definition at line 256 of file chip.cpp.

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

◆ close()

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

Press the close icon of the chip as a click does.

Calls the close callback of the component, and nothing else: the chip is not removed or hidden, the callback decides what closing means. Nothing is called when the chip is disabled or has no close callback.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.

Definition at line 240 of file chip.cpp.

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

◆ install()

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

Make an entity behave as a chip.

Calls systems::interaction::makeInteractive with the Button accessibility role, so a click or a hand press calls press and any hover or press change calls apply, and sets the selection handler of components::Selectable so a selection written from outside is drawn at once.

Call it once when the entity is built; entities::Chip does it for you. It does not style anything: call apply after it.

Parameters
componentRegistryThe registry holding the components. The handlers keep its address, so it must outlive the entity.
entityIdentifierThe chip entity. It must already have a components::Selectable.

Definition at line 112 of file chip.cpp.

Here is the call graph for this function:

◆ installCloseIcon()

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

Make the trailing icon of a chip a close button.

Makes the trailing icon recorded in components::Chip interactive on its own (Button role, accessibility label "Close") so that pressing it calls close on the chip instead of pressing the chip. Call it after the trailing icon child has been created and recorded. Does nothing when the chip has no trailing icon.

Parameters
componentRegistryThe registry holding the components. The handler keeps its address, so it must outlive the entity.
entityIdentifierThe chip entity, not the icon.

Definition at line 134 of file chip.cpp.

Here is the call graph for this function:

◆ isDisabled()

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

Whether the chip ignores input and is drawn disabled.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
Returns
True when the entity has a components::StyleState that is not enabled.

Definition at line 164 of file chip.cpp.

Here is the caller graph for this function:

◆ isSelected()

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

Whether the chip is selected.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity. It must have a components::Selectable.
Returns
The selected flag of its components::Selectable.

Definition at line 156 of file chip.cpp.

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

◆ leadingGlyph()

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

Get the name of the glyph the leading icon of the chip should show.

The widget class calls it to decide whether to build a leading icon child and with which glyph.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
Returns
The glyph configured in components::Chip; components::Chip::DefaultAssistGlyph for an Assist chip without one; an empty string when the chip should have no leading icon.

Definition at line 171 of file chip.cpp.

Here is the call graph for this function:

◆ needsCheckIcon()

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

Whether the widget class should build a selected check child for this chip.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
Returns
True for the Filter variant, false for the others.

Definition at line 184 of file chip.cpp.

Here is the call graph for this function:

◆ needsCloseIcon()

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

Whether the widget class should build a trailing close icon child for this chip.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
Returns
True for the Input variant, or for any variant with a close callback set.

Definition at line 193 of file chip.cpp.

Here is the call graph for this function:

◆ press()

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

Press the chip as a click does.

A Filter chip flips its selection and is redrawn; the other variants keep theirs. Then the press callback of the component is called. Nothing happens, and nothing is called, when the chip is disabled.

The handlers set by install call it; call it directly to simulate a click, for example in a test on a bare identifier.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.

Definition at line 220 of file chip.cpp.

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

◆ setDisabled()

void guillaume::systems::Chip::setDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool disabled )
static

Enable or disable the chip and show it at once.

Writes the enabled flag of components::StyleState (through systems::interaction::setEnabled), then calls apply. A disabled chip ignores press and close and is drawn with the disabled colors.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
disabledTrue to disable the chip, false to enable it.

Definition at line 212 of file chip.cpp.

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

◆ setSelected()

void guillaume::systems::Chip::setSelected ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool selected )
static

Select or deselect the chip from code and show it at once.

Writes the selected flag of components::Selectable, then calls apply. The press callback is not called, and the call works on any variant and on a disabled chip.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe chip entity.
selectedTrue to select the chip, false to deselect it.

Definition at line 203 of file chip.cpp.

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

◆ update()

void guillaume::systems::Chip::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Frame entry point: call apply on one chip.

Parameters
entityIdentifierThe chip entity. An entity without a components::Chip is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 340 of file chip.cpp.

Here is the call graph for this function:

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