|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
A Material 3 common button: a clickable container with a text label and an optional icon (elevated, filled, tonal, outlined or text). More...
#include <headers/guillaume/entities/button.hpp>


Classes | |
| class | Builder |
| Configures, creates and registers Button widgets. More... | |
Public Types | |
| using | Color = components::CommonButton::Color |
| using | Shape = components::CommonButton::Shape |
| using | Size = components::CommonButton::Size |
| 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 | |
| ~Button (void) override=default | |
| Default destructor. | |
| Button & | setCompact (bool compact) |
| Use the compact horizontal padding (Paper compact). Restyles at once. | |
| Button & | setMinWidth (float minWidth) |
| Raise the minimum container width above MinWidth. Restyles at once. | |
| bool | isCompact (void) const |
| Check whether the button uses the compact horizontal padding. | |
| Button & | setUppercase (bool uppercase) |
| Render the label in upper case (Paper uppercase). Restyles at once. | |
| bool | isUppercase (void) const |
| Check whether the label is displayed in upper case. | |
| Button & | setColorStyle (const Color &colorStyle) |
| Set the color style. Restyles at once. | |
| Button & | setShape (const Shape &shape) |
| Set the corner shape. Restyles at once. | |
| Button & | setSize (const Size &size) |
| Set the size, which decides the paddings, the icon size and the corner radius. Restyles at once. | |
| Color | getColorStyle (void) const |
| Get the color style. | |
| Shape | getShape (void) const |
| Get the corner shape. | |
| Size | getSize (void) const |
| Get the size. | |
| Public Member Functions inherited from guillaume::entities::ButtonBase | |
| ~ButtonBase (void) override=default | |
| Default destructor. | |
| ButtonBase & | setIconGlyphName (const std::string &iconGlyphName) |
| Change the icon. | |
| ButtonBase & | setIconStyle (const components::Glyph::Style &iconStyle) |
| Change the style the icon glyph is drawn in. | |
| ButtonBase & | setLabelContent (const std::string &labelContent) |
| Change the text of the label. | |
| ButtonBase & | setIsToggle (const bool &isToggle) |
| Make the button a toggle, or a plain push button. | |
| bool | isSelected (void) const |
| Tell whether a toggle button is on. | |
| ButtonBase & | setSelected (const bool &selected) |
| Turn a toggle button on or off from code. | |
| ButtonBase & | setSelectedIconGlyphName (const std::string &selectedIconGlyphName) |
| Set the icon shown instead of the regular one while the button is selected. | |
| ButtonBase & | setMorph (const bool &isMorph) |
| Choose whether the button changes shape when selected, and restyle at once. | |
| ButtonBase & | setTrailingIcon (const bool &isTrailingIcon) |
| Put the icon before or after the label, and restyle at once. | |
| ButtonBase & | setDisabled (const bool &isDisabled) |
| Disable or enable the button, and restyle at once. | |
| bool | isDisabled (void) const |
| Tell whether the button is disabled. | |
| ButtonBase & | setAccessibilityLabel (const std::string &accessibilityLabel) |
| Set the name assistive tools announce for the button. | |
| const std::string & | getAccessibilityLabel (void) const |
| Get the name assistive tools announce for the button. | |
| ButtonBase & | setAccessibilityHint (const std::string &accessibilityHint) |
| Set the sentence that tells assistive tools what activating the button does. | |
| ButtonBase & | setAccessibilityRole (components::AccessibilityRole role) |
| Change the role announced by assistive tools. | |
| ButtonBase & | setOnLongPress (std::function< void(void)> onLongPress) |
| Set the function called when the user holds the button. | |
| ButtonBase & | setLoading (bool loading) |
| Show or hide the loading state. | |
| ButtonBase & | setVisible (bool visible) |
| Show or hide the button, and restyle at once. | |
| bool | isVisible (void) const |
| Tell whether the button is shown. | |
| bool | isLoading (void) const |
| Tell whether the button is in the loading state. | |
| ButtonBase & | setContainerColorOverride (std::optional< utility::graphic::Color32Bit > color) |
| Replace the theme's background color with a custom one, and restyle at once. | |
| ButtonBase & | setContentColorOverride (std::optional< utility::graphic::Color32Bit > color) |
| Replace the theme's icon and label color with a custom one, and restyle at once. | |
| const std::string & | getAccessibilityHint (void) const |
| Get the sentence that tells assistive tools what activating the button does. | |
| ButtonBase & | setOnClick (std::function< void(void)> onClick) |
| Set the function called when the user clicks the button. | |
| ecs::Entity::Identifier | getIconIdentifier (void) const |
| Get the icon child, to read or adjust its components. | |
| ecs::Entity::Identifier | getLabelIdentifier (void) const |
| Get the label child, to read or adjust its components. | |
| void | hoverHandler (void) |
| Tell the button a pointer started hovering it. | |
| void | unHoverHandler (void) |
| Tell the button a pointer stopped hovering it. | |
| void | buttonPressHandler (void) |
| Press the button from code, as the user would. | |
| void | buttonReleaseHandler (void) |
| Release the button from code, as the user would. | |
| Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Transform, components::Bound, components::Color, components::Borders, components::Focus, components::HandButtonInteraction, components::HandHoverInteraction, components::MouseHoverInteraction, components::MouseButtonInteraction, components::StyleState, components::Accessibility, components::Button > | |
| 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< Button > | create (Arguments &&...arguments) |
| Create a button and its icon and label children, without registering it in an entity registry. | |
| Static Public Member Functions inherited from guillaume::entities::ButtonBase | |
| static const utility::graphic::PoseF | applyLayerToPosition (const utility::graphic::PositionF &position, const utility::graphic::OrientationF &orientation, const std::uint32_t &layer) |
| Compute the pose of content drawn in front of a button. | |
| static utility::graphic::Color32Bit | applyStateAlpha (const utility::graphic::Color32Bit &color, std::uint8_t alpha) |
| Replace the alpha of a color and keep its red, green and blue. | |
| static utility::graphic::Color32Bit | applyStateLayer (const utility::graphic::Color32Bit &base, const utility::graphic::Color32Bit &overlay, std::uint8_t alpha) |
| Blend a translucent state layer (hover, press) over a container color. | |
| static utility::graphic::Color32Bit | getDisabledContainerColor (void) |
| Get the background color of a disabled button. | |
| static utility::graphic::Color32Bit | getDisabledContentColor (void) |
| Get the icon and label color of a disabled button. | |
| static utility::graphic::Color32Bit | getDisabledBorderColor (void) |
| Get the outline color of a disabled button. | |
| 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. | |
Static Public Attributes | |
| static constexpr float | MinWidth = components::CommonButton::MinWidth |
| Minimum container width, in dp (M3: 64 dp). | |
| static constexpr float | MinHeight = components::CommonButton::MinHeight |
| Minimum container height, in dp (M3: 40 dp). It does not apply to Size::ExtraSmall. | |
| Static Public Attributes inherited from guillaume::entities::ButtonBase | |
| static constexpr const char * | LoadingGlyph |
| Name of the glyph the icon child shows while loading. | |
| static constexpr std::chrono::milliseconds | LongPressDuration |
| How long a press must last to count as a long press (500 ms). | |
| Static Public Attributes inherited from guillaume::ecs::Entity | |
| static constexpr Identifier | InvalidIdentifier |
| "No entity": never the identifier of a real entity | |
Protected Member Functions | |
| float | getIconFontSize (void) const override |
| Get the font size of the icon child for the current size. | |
| bool | usesLabel (void) const override |
| Tell ButtonBase::build() that this variant has a label child. | |
| utility::graphic::Color32Bit | getInitialContentColor (void) const override |
| Get the color the icon and label children are created with. | |
| Protected Member Functions inherited from guillaume::entities::ButtonBase | |
| void | build (void) |
| Create the icon and label children, then style the button. | |
| ButtonBase (ecs::ComponentRegistry ®istry, const std::string &iconGlyphName, const components::Glyph::Style &iconStyle, const std::string &labelContent, bool isToggle, bool isMorph, bool isDisabled, bool isTrailingIcon, const std::string &accessibilityLabel, std::function< void(void)> onClick) | |
| Create the entity with its components and store the initial state. The children are created later, by build(). | |
| components::Button & | state (void) |
| Access the shared button state, for writing. | |
| const components::Button & | state (void) const |
| Access the shared button state, for reading. | |
| void | restyle (void) |
| Recompute colors and geometry now. | |
| virtual bool | usesIcon (void) const |
| Tell build() whether to create an icon child. | |
| bool | isHovered (void) |
| Tell whether a pointer is over the button. | |
| bool | isPressed (void) |
| Tell whether the button is held down. | |
| const std::string & | getActiveIconGlyphName (void) const |
| Get the glyph the icon child should show right now. | |
| void | applyTouchTarget (float width, float height) |
| Make a small button easier to hit. | |
| void | syncAccessibilityState (void) |
| Copy the current state to the icon child and to Accessibility. | |
| utility::graphic::Color32Bit | resolveContainerColor (const utility::graphic::Color32Bit &color) const |
| Pick the background color to paint. | |
| utility::graphic::Color32Bit | resolveContentColor (const utility::graphic::Color32Bit &color) const |
| Pick the icon and label color to paint. | |
| Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Transform, components::Bound, components::Color, components::Borders, components::Focus, components::HandButtonInteraction, components::HandHoverInteraction, components::MouseHoverInteraction, components::MouseButtonInteraction, components::StyleState, components::Accessibility, components::Button > | |
| 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. | |
Additional Inherited Members | |
| Static Protected Attributes inherited from guillaume::entities::ButtonBase | |
| static constexpr float | _layerDepthStep |
| Depth between two layers, toward the viewer. | |
A Material 3 common button: a clickable container with a text label and an optional icon (elevated, filled, tonal, outlined or text).
The state shared by every button (label, icon, toggle, callbacks) lives in components::Button, and systems::Button turns input into clicks in the Event phase. What is specific to this variant (color style, shape, size) lives in components::CommonButton; systems::CommonButton colors the container, sizes it and places the icon and the label each frame, in the Layout phase. The class itself holds no field: its setters write the component and restyle at once.
Button::create(registry, iconGlyphName, iconStyle, labelContent, isToggle, colorStyle, shape, size, isMorph, isDisabled, isTrailingIcon, accessibilityLabel, onClick) builds the same widget without registering it in an entity registry.
The button owns its icon and label children: it is the entity registry they are registered in. Its size is computed from its content and written to its Bound each frame, so a size set by hand on the Bound is overwritten. setSelected() does not call the click handler; only a user click does.
Definition at line 75 of file button.hpp.
Color style: Elevated, Filled, Tonal, Outlined, Text or Segmented (see components::CommonButton::Color).
Definition at line 80 of file button.hpp.
Corner shape: Round or Square (see components::CommonButton::Shape).
Definition at line 84 of file button.hpp.
Size, from ExtraSmall to ExtraLarge (see components::CommonButton::Size).
Definition at line 88 of file button.hpp.
|
inlinestatic |
Create a button and its icon and label children, without registering it in an entity registry.
The constructor is private because the children need a button already held by a std::shared_ptr as parent: create() constructs the button then calls build(), which creates them.
| Arguments | The types of the constructor arguments. |
| arguments | The arguments forwarded to the constructor: (registry, iconGlyphName, iconStyle, labelContent, isToggle, colorStyle, shape, size, isMorph, isDisabled, isTrailingIcon, accessibilityLabel, onClick). |
Definition at line 334 of file button.hpp.

| Button::Color guillaume::entities::Button::getColorStyle | ( | void | ) | const |
Get the color style.
Definition at line 279 of file button.cpp.


|
overrideprotectedvirtual |
Get the font size of the icon child for the current size.
Implements guillaume::entities::ButtonBase.
Definition at line 199 of file button.cpp.

|
overrideprotectedvirtual |
Get the color the icon and label children are created with.
Implements guillaume::entities::ButtonBase.
Definition at line 205 of file button.cpp.

| Button::Shape guillaume::entities::Button::getShape | ( | void | ) | const |
Get the corner shape.
Definition at line 286 of file button.cpp.


| Button::Size guillaume::entities::Button::getSize | ( | void | ) | const |
Get the size.
Definition at line 293 of file button.cpp.


| bool guillaume::entities::Button::isCompact | ( | void | ) | const |
Check whether the button uses the compact horizontal padding.
Definition at line 265 of file button.cpp.


| bool guillaume::entities::Button::isUppercase | ( | void | ) | const |
Check whether the label is displayed in upper case.
Definition at line 272 of file button.cpp.


| Button & guillaume::entities::Button::setColorStyle | ( | const Color & | colorStyle | ) |
Set the color style. Restyles at once.
| colorStyle | The new color style. |
Definition at line 238 of file button.cpp.


| Button & guillaume::entities::Button::setCompact | ( | bool | compact | ) |
Use the compact horizontal padding (Paper compact). Restyles at once.
| compact | True for the compact padding, false for the regular padding of the size. |
Definition at line 220 of file button.cpp.


| Button & guillaume::entities::Button::setMinWidth | ( | float | minWidth | ) |
Raise the minimum container width above MinWidth. Restyles at once.
systems::SegmentedButton writes the same value on the segments of a segmented button to give them one width, so a value set here on a segment is overwritten.
| minWidth | The minimum width, in dp. A value below MinWidth has no effect. |
Definition at line 211 of file button.cpp.


| Button & guillaume::entities::Button::setShape | ( | const Shape & | shape | ) |
Set the corner shape. Restyles at once.
| shape | The new corner shape. |
Definition at line 247 of file button.cpp.


| Button & guillaume::entities::Button::setSize | ( | const Size & | size | ) |
Set the size, which decides the paddings, the icon size and the corner radius. Restyles at once.
| size | The new size. |
Definition at line 256 of file button.cpp.


| Button & guillaume::entities::Button::setUppercase | ( | bool | uppercase | ) |
Render the label in upper case (Paper uppercase). Restyles at once.
Only the displayed text changes; the label content stored in components::Button keeps its case.
| uppercase | True to display the label in upper case. |
Definition at line 229 of file button.cpp.


|
inlineoverrideprotectedvirtual |
Tell ButtonBase::build() that this variant has a label child.
Reimplemented from guillaume::entities::ButtonBase.
Definition at line 306 of file button.hpp.
|
staticconstexpr |
Minimum container height, in dp (M3: 40 dp). It does not apply to Size::ExtraSmall.
Definition at line 402 of file button.hpp.
|
staticconstexpr |
Minimum container width, in dp (M3: 64 dp).
Definition at line 396 of file button.hpp.