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

Colors, sizes and lays out a common button: the elevated, filled, tonal, outlined and text buttons, and the segments of a segmented button. More...

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

Inheritance diagram for guillaume::systems::CommonButton:
Collaboration diagram for guillaume::systems::CommonButton:

Public Member Functions

 CommonButton (void)
 Create the system for the Layout phase, matching entities that have both a components::CommonButton and a components::Button.
 ~CommonButton (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one button.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::CommonButton, components::Button >
 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 &registry, const ecs::Entity::Identifier &identifier)
 Make an entity behave as a common button.
static float iconFontSize (const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Get the font size of the icon for the configured size.
static utility::graphic::Color32Bit contentColor (const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Get the color of the icon and label of the button when it is enabled.
static void styleState (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 First half of apply: write the colors and the elevation.
static void geometry (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Second half of apply: write the corner radius, the size of the button and the position of its icon and label.
static void apply (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Style and lay out one button at once: styleState, then geometry.

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

Colors, sizes and lays out a common button: the elevated, filled, tonal, outlined and text buttons, and the segments of a segmented button.

This is the variant half of a button; systems::Button owns the input half (press, toggle, callbacks) and calls back into apply through the restyle function of components::Button.

The button sets its own size from its content: any width or height written to its components::Bound elsewhere is overwritten each frame. Use components::CommonButton::setMinWidth to make it wider.

See also
guillaume::components::CommonButton, guillaume::systems::Button, guillaume::systems::button_style, guillaume::entities::Button

Definition at line 62 of file common_button.hpp.

Constructor & Destructor Documentation

◆ CommonButton()

guillaume::systems::CommonButton::CommonButton ( void )

Create the system for the Layout phase, matching entities that have both a components::CommonButton and a components::Button.

Definition at line 53 of file common_button.cpp.

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

Member Function Documentation

◆ apply()

void guillaume::systems::CommonButton::apply ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Style and lay out one button at once: styleState, then geometry.

The frame calls it through update. Call it yourself after changing components::CommonButton or components::Button when the result must be visible before the next Layout phase; the setters of entities::Button do, and systems::Button does on every hover, press and release.

Parameters
registryThe registry holding the components.
identifierThe button entity. It must have the components listed in the class description.
Exceptions
std::runtime_errorIf the configured size or color style is not a valid enumerator.

Definition at line 299 of file common_button.cpp.

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

◆ contentColor()

utility::graphic::Color32Bit guillaume::systems::CommonButton::contentColor ( const ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Get the color of the icon and label of the button when it is enabled.

It depends on the color style and, for a toggle, on the selection. The disabled color and the content color override of components::Button are not taken into account: styleState applies them.

Parameters
registryThe registry holding the components.
identifierThe button entity.
Returns
The themed content color.
Exceptions
std::runtime_errorIf the configured color style is not a valid enumerator.

Definition at line 80 of file common_button.cpp.

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

◆ geometry()

void guillaume::systems::CommonButton::geometry ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Second half of apply: write the corner radius, the size of the button and the position of its icon and label.

  • Corners: the per-corner override of components::CommonButton when set, else one radius from the shape, the size and the press (a pressed button, or a selected toggle that morphs, changes shape).
  • Content: the icon gets the icon font size of the button size; the label gets the LabelLarge type role and its text, upper-cased when asked.
  • Size: the content plus the paddings of the size, at least components::CommonButton::MinWidth wide and the configured minimum width, and at least components::CommonButton::MinHeight high except for the ExtraSmall size.
  • Placement: icon and label are centered as a group, the icon first unless components::Button asks for a trailing icon.

A button with neither an icon nor a label only gets its corners: its components::Bound is left untouched. The child bounds read here are those of the last Measure phase, so a label changed in the same call is sized from its previous text until the next frame.

Parameters
registryThe registry holding the components.
identifierThe button entity.

Definition at line 159 of file common_button.cpp.

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

◆ iconFontSize()

float guillaume::systems::CommonButton::iconFontSize ( const ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Get the font size of the icon for the configured size.

The widget class uses it to create the icon child at the right size.

Parameters
registryThe registry holding the components.
identifierThe button entity.
Returns
The font size, in dp (see button_style::getIconFontSize).
Exceptions
std::runtime_errorIf the configured size is not a valid enumerator.

Definition at line 71 of file common_button.cpp.

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

◆ install()

void guillaume::systems::CommonButton::install ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Make an entity behave as a common button.

Adds a components::Elevation at level 0 when the entity has none, wires input through systems::Button::install, and stores apply in components::Button as the restyle function, so a hover, a press or a toggle redraws the button without waiting for the Layout phase. Call it once when the entity is built; entities::Button does it for you.

Parameters
registryThe registry holding the components. It must outlive the entity.
identifierThe button entity. It must already have its components::Button and the hand and mouse hover and button interaction components.

Definition at line 59 of file common_button.cpp.

Here is the call graph for this function:

◆ styleState()

void guillaume::systems::CommonButton::styleState ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

First half of apply: write the colors and the elevation.

  • Elevation: level 1 for an enabled Elevated button, level 2 while it is hovered and not pressed; level 0 for every other style and for any disabled button.
  • Disabled: container and outline take the disabled container color, icon and label the disabled content color.
  • Enabled: container, outline and content colors come from button_style for the current hover, press and selection; the color overrides of components::Button replace the container and content colors.

The outline width is always written as 1 dp; a style without an outline gets a transparent outline color.

Parameters
registryThe registry holding the components.
identifierThe button entity.

Definition at line 91 of file common_button.cpp.

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

◆ update()

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

Frame entry point: call apply on one button.

Parameters
entityIdentifierThe button entity. An entity missing components::CommonButton or components::Button is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 306 of file common_button.cpp.

Here is the call graph for this function:

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