guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
button_base.cpp
1/*
2 Copyright (c) 2026 ETIB Corporation
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy of
5 this software and associated documentation files (the "Software"), to deal in
6 the Software without restriction, including without limitation the rights to
7 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
8 of the Software, and to permit persons to whom the Software is furnished to do
9 so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in all
12 copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 SOFTWARE.
21 */
22
23#include <cmath>
24#include <utility>
25
26#include "guillaume/entities/button_base.hpp"
28#include "guillaume/systems/layout.hpp"
29#include "guillaume/theme.hpp"
30
31namespace guillaume::entities
32{
34 const std::string &iconGlyphName,
35 const components::Glyph::Style &iconStyle,
36 const std::string &labelContent, bool isToggle,
37 bool isMorph, bool isDisabled, bool isTrailingIcon,
38 const std::string &accessibilityLabel,
39 std::function<void(void)> onClick)
41 components::Transform, components::Bound, components::Color,
42 components::Borders, components::Focus,
43 components::HandButtonInteraction,
44 components::HandHoverInteraction,
45 components::MouseHoverInteraction,
46 components::MouseButtonInteraction, components::StyleState,
47 components::Accessibility, components::Button>(registry)
48 {
49 state()
50 .setIconGlyphName(iconGlyphName)
51 .setIconStyle(iconStyle)
52 .setLabelContent(labelContent)
53 .setToggle(isToggle)
54 .setMorph(isMorph)
55 .setTrailingIcon(isTrailingIcon)
56 .setOnClick(std::move(onClick));
63 .setLabel(accessibilityLabel.empty() ? labelContent
64 : accessibilityLabel);
65 }
66
72
78
83
84 ButtonBase &ButtonBase::setIconGlyphName(const std::string &iconGlyphName)
85 {
86 state().setIconGlyphName(iconGlyphName);
88 return *this;
89 }
90
98
99 ButtonBase &ButtonBase::setLabelContent(const std::string &labelContent)
100 {
101 state().setLabelContent(labelContent);
103 .setContent(labelContent);
104 return *this;
105 }
106
111
112 ButtonBase &ButtonBase::setIsToggle(const bool &isToggle)
113 {
114 state().setToggle(isToggle);
115 if (!isToggle) {
116 state().setSelected(false);
117 }
118 return *this;
119 }
120
121 bool ButtonBase::isSelected(void) const
122 {
123 return state().isSelected();
124 }
125
126 ButtonBase &ButtonBase::setSelected(const bool &selected)
127 {
129 selected);
130 return *this;
131 }
132
134 const std::string &selectedIconGlyphName)
135 {
136 state().setSelectedIconGlyphName(selectedIconGlyphName);
138 return *this;
139 }
140
141 ButtonBase &ButtonBase::setMorph(const bool &isMorph)
142 {
143 state().setMorph(isMorph);
144 restyle();
145 return *this;
146 }
147
148 ButtonBase &ButtonBase::setTrailingIcon(const bool &isTrailingIcon)
149 {
150 state().setTrailingIcon(isTrailingIcon);
151 restyle();
152 return *this;
153 }
154
163
170
171 ButtonBase &
172 ButtonBase::setAccessibilityLabel(const std::string &accessibilityLabel)
173 {
176 .setLabel(accessibilityLabel);
177 return *this;
178 }
179
180 const std::string &ButtonBase::getAccessibilityLabel(void) const
181 {
182 return getComponentRegistry()
184 .getLabel();
185 }
186
187 ButtonBase &
188 ButtonBase::setAccessibilityHint(const std::string &accessibilityHint)
189 {
192 .setHint(accessibilityHint);
193 return *this;
194 }
195
196 const std::string &ButtonBase::getAccessibilityHint(void) const
197 {
198 return getComponentRegistry()
200 .getHint();
201 }
202
203 ButtonBase &
211
212 const utility::graphic::PoseF ButtonBase::applyLayerToPosition(
213 const utility::graphic::PositionF &position,
214 const utility::graphic::OrientationF &orientation,
215 const std::uint32_t &layer)
216 {
217 return systems::Layout::contentLayerPose(position, orientation, layer);
218 }
219
220 utility::graphic::Color32Bit
221 ButtonBase::applyStateAlpha(const utility::graphic::Color32Bit &color,
222 std::uint8_t alpha)
223 {
224 return withAlpha(color, alpha);
225 }
226
227 utility::graphic::Color32Bit
228 ButtonBase::applyStateLayer(const utility::graphic::Color32Bit &base,
229 const utility::graphic::Color32Bit &overlay,
230 std::uint8_t alpha)
231 {
232 return stateLayer(base, overlay, alpha);
233 }
234
235 utility::graphic::Color32Bit ButtonBase::getDisabledContainerColor(void)
236 {
237 const auto &scheme = guillaume::getActiveScheme();
238
239 return applyStateAlpha(
240 scheme.getColor(SchemeColorRole::OnSurface).getColor(),
242 }
243
244 utility::graphic::Color32Bit ButtonBase::getDisabledContentColor(void)
245 {
246 const auto &scheme = guillaume::getActiveScheme();
247
248 return applyStateAlpha(
249 scheme.getColor(SchemeColorRole::OnSurface).getColor(),
251 }
252
253 utility::graphic::Color32Bit ButtonBase::getDisabledBorderColor(void)
254 {
255 const auto &scheme = guillaume::getActiveScheme();
256
257 return applyStateAlpha(
258 scheme.getColor(SchemeColorRole::OnSurface).getColor(),
260 }
261
262 ButtonBase &
263 ButtonBase::setOnLongPress(std::function<void(void)> onLongPress)
264 {
265 state().setOnLongPress(std::move(onLongPress));
266 return *this;
267 }
268
269 ButtonBase &ButtonBase::setOnClick(std::function<void(void)> onClick)
270 {
271 state().setOnClick(std::move(onClick));
272 return *this;
273 }
274
276 {
277 state().setLoading(loading);
279 return *this;
280 }
281
282 bool ButtonBase::isLoading(void) const
283 {
284 return state().isLoading();
285 }
286
288 {
289 state().setVisible(visible);
292 .setFocusable(visible);
293 restyle();
294 return *this;
295 }
296
297 bool ButtonBase::isVisible(void) const
298 {
299 return state().isVisible();
300 }
301
303 std::optional<utility::graphic::Color32Bit> color)
304 {
306 restyle();
307 return *this;
308 }
309
311 std::optional<utility::graphic::Color32Bit> color)
312 {
314 restyle();
315 return *this;
316 }
317
318 utility::graphic::Color32Bit ButtonBase::resolveContainerColor(
319 const utility::graphic::Color32Bit &color) const
320 {
322 }
323
324 utility::graphic::Color32Bit ButtonBase::resolveContentColor(
325 const utility::graphic::Color32Bit &color) const
326 {
328 }
329
334
339
345
351
352 const std::string &ButtonBase::getActiveIconGlyphName(void) const
353 {
355 }
356
357 void ButtonBase::applyTouchTarget(float width, float height)
358 {
360 getIdentifier(), width, height);
361 }
362
367
372
377
382
384 {
385 if (usesIcon()) {
386 Icon::Builder iconBuilder(getComponentRegistry(), *this);
387 const auto icon = iconBuilder.makeIcon(
388 shared_from_this(), state().getIconGlyphName(),
390 state().getIconStyle());
391 if (icon != nullptr) {
392 state().setIcon(icon->getIdentifier());
393 }
394 }
395
396 if (usesLabel()) {
397 Text::Builder labelBuilder(getComponentRegistry(), *this);
398 const auto label = labelBuilder.makeText(
399 shared_from_this(), state().getLabelContent(),
401 if (label != nullptr) {
402 state().setLabel(label->getIdentifier());
403 }
404 }
405
407 restyle();
408 }
409
410} // namespace guillaume::entities
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
Accessibility & setLabel(const std::string &label)
Set the name announced for the entity, such as "Close".
State shared by every pressable button, whatever its look.
Definition button.hpp:77
Button & setLabelContent(const std::string &content)
Set the text of the label.
Definition button.cpp:76
Button & setIconGlyphName(const std::string &name)
Set the name of the icon glyph shown at rest.
Definition button.cpp:34
Button & setToggle(bool toggle)
Make the button a toggle or a plain button.
Definition button.cpp:118
bool isLoading(void) const noexcept
Check whether the button shows a progress glyph.
Definition button.cpp:169
Button & setContentColorOverride(const OptionalColor &color)
Replace the themed content (icon and label) color.
Definition button.cpp:254
Button & setVisible(bool visible)
Show or hide the button.
Definition button.cpp:188
bool isVisible(void) const noexcept
Check whether the button is shown.
Definition button.cpp:183
Button & setOnLongPress(Handler handler)
Set the callback run when the button is released after a long press.
Definition button.cpp:213
ecs::Entity::Identifier getIcon(void) const noexcept
Get the child entity that draws the icon.
Definition button.cpp:85
Button & setContainerColorOverride(const OptionalColor &color)
Replace the themed container (background) color.
Definition button.cpp:239
Button & setMorph(bool morph)
Choose whether the corner shape changes when selected.
Definition button.cpp:146
Button & setSelected(bool selected)
Store the selection.
Definition button.cpp:132
bool isSelected(void) const noexcept
Check whether the button is selected.
Definition button.cpp:127
Button & setSelectedIconGlyphName(const std::string &name)
Set the name of the icon glyph shown while selected.
Definition button.cpp:62
Button & setLabel(ecs::Entity::Identifier identifier)
Record which child entity draws the label.
Definition button.cpp:104
Button & setOnClick(Handler handler)
Set the callback run when the button is released.
Definition button.cpp:202
Button & setLoading(bool loading)
Show a progress glyph in place of the icon, or the icon again.
Definition button.cpp:174
Button & setIconStyle(Glyph::Style style)
Set the style the icon glyph is drawn in.
Definition button.cpp:48
Button & setIcon(ecs::Entity::Identifier identifier)
Record which child entity draws the icon.
Definition button.cpp:90
ecs::Entity::Identifier getLabel(void) const noexcept
Get the child entity that draws the label.
Definition button.cpp:99
Button & setTrailingIcon(bool trailing)
Choose on which side of the label the icon sits.
Definition button.cpp:160
Style
Family of the Material Symbols font the icon belongs to.
Definition glyph.hpp:66
The interaction state of an entity in one place: enabled or disabled, and whether it is hovered,...
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86
What Button, IconButton, FloatingActionButton and ExtendedFloatingActionButton have in common: an ico...
bool isDisabled(void) const
Tell whether the button is disabled.
ButtonBase & setLoading(bool loading)
Show or hide the loading state.
const std::string & getAccessibilityLabel(void) const
Get the name assistive tools announce for the button.
virtual utility::graphic::Color32Bit getInitialContentColor(void) const =0
Color the icon and label children are created with.
virtual bool usesIcon(void) const
Tell build() whether to create an icon child.
ButtonBase & setContainerColorOverride(std::optional< utility::graphic::Color32Bit > color)
Replace the theme's background color with a custom one, and restyle at once.
utility::graphic::Color32Bit resolveContainerColor(const utility::graphic::Color32Bit &color) const
Pick the background color to paint.
void buttonPressHandler(void)
Press the button from code, as the user would.
bool isSelected(void) const
Tell whether a toggle button is on.
void applyTouchTarget(float width, float height)
Make a small button easier to hit.
ButtonBase & setLabelContent(const std::string &labelContent)
Change the text of the label.
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 getDisabledBorderColor(void)
Get the outline color of a disabled button.
ButtonBase & setVisible(bool visible)
Show or hide the button, and restyle at once.
components::Button & state(void)
Access the shared button state, for writing.
ButtonBase & setOnLongPress(std::function< void(void)> onLongPress)
Set the function called when the user holds the button.
const std::string & getActiveIconGlyphName(void) const
Get the glyph the icon child should show right now.
utility::graphic::Color32Bit resolveContentColor(const utility::graphic::Color32Bit &color) const
Pick the icon and label color to paint.
ButtonBase & setDisabled(const bool &isDisabled)
Disable or enable the button, and restyle at once.
ButtonBase & setIconGlyphName(const std::string &iconGlyphName)
Change the icon.
ButtonBase & setSelected(const bool &selected)
Turn a toggle button on or off from code.
bool isVisible(void) const
Tell whether the button is shown.
ButtonBase(ecs::ComponentRegistry &registry, 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,...
void syncAccessibilityState(void)
Copy the current state to the icon child and to Accessibility.
ButtonBase & setAccessibilityLabel(const std::string &accessibilityLabel)
Set the name assistive tools announce for the button.
ButtonBase & setMorph(const bool &isMorph)
Choose whether the button changes shape when selected, and restyle at once.
void unHoverHandler(void)
Tell the button a pointer stopped hovering it.
static utility::graphic::Color32Bit getDisabledContentColor(void)
Get the icon and label color of a disabled button.
ButtonBase & setAccessibilityHint(const std::string &accessibilityHint)
Set the sentence that tells assistive tools what activating the button does.
ecs::Entity::Identifier getIconIdentifier(void) const
Get the icon child, to read or adjust its components.
const std::string & getAccessibilityHint(void) const
Get the sentence that tells assistive tools what activating the button does.
void hoverHandler(void)
Tell the button a pointer started hovering it.
bool isHovered(void)
Tell whether a pointer is over the button.
ButtonBase & setContentColorOverride(std::optional< utility::graphic::Color32Bit > color)
Replace the theme's icon and label color with a custom one, and restyle at once.
bool isPressed(void)
Tell whether the button is held down.
ecs::Entity::Identifier getLabelIdentifier(void) const
Get the label child, to read or adjust its components.
bool isLoading(void) const
Tell whether the button is in the loading state.
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.
ButtonBase & setTrailingIcon(const bool &isTrailingIcon)
Put the icon before or after the label, and restyle at once.
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.
ButtonBase & setIconStyle(const components::Glyph::Style &iconStyle)
Change the style the icon glyph is drawn in.
ButtonBase & setAccessibilityRole(components::AccessibilityRole role)
Change the role announced by assistive tools.
virtual float getIconFontSize(void) const =0
Size the icon child is created with.
virtual bool usesLabel(void) const
Tell build() whether to create a label child.
void restyle(void)
Recompute colors and geometry now.
void build(void)
Create the icon and label children, then style the button.
static utility::graphic::Color32Bit getDisabledContainerColor(void)
Get the background color of a disabled button.
ButtonBase & setSelectedIconGlyphName(const std::string &selectedIconGlyphName)
Set the icon shown instead of the regular one while the button is selected.
void buttonReleaseHandler(void)
Release the button from code, as the user would.
ButtonBase & setOnClick(std::function< void(void)> onClick)
Set the function called when the user clicks the button.
ButtonBase & setIsToggle(const bool &isToggle)
Make the button a toggle, or a plain push button.
A Material 3 common button: a clickable container with a text label and an optional icon (elevated,...
Definition button.hpp:76
Configures Icon widgets and registers them in the scene's entity registry.
Definition icon.hpp:87
std::shared_ptr< Icon > makeIcon(std::shared_ptr< Entity > parent, const std::string &iconName, const float &fontSize, const utility::graphic::Color32Bit &color, const components::Glyph::Style &style)
Build an icon, register it under parent and reset the builder.
Definition icon.cpp:80
Configures Text widgets and registers them in the scene's entity registry.
Definition text.hpp:98
std::shared_ptr< Text > makeText(std::shared_ptr< Entity > parent, const std::string &content, const float &fontSize, const utility::graphic::Color32Bit &color)
Build a text with an explicit font size, register it under parent and reset the builder.
Definition text.cpp:81
Short-lived handle on the icon or label child of a button, used by the variant systems to style it.
Definition button.hpp:96
const Child & setContent(const std::string &content) const
Write the string of the child's components::Text.
Definition button.cpp:92
static void press(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
React to the button being pressed: record when the press started and restyle.
Definition button.cpp:262
static void hoverChanged(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
React to a pointer or a hand entering or leaving the button: restyle it so the hover tint appears or ...
Definition button.cpp:253
static void applyTouchTarget(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier, float width, float height)
Make a small button as easy to hit as a large one, without drawing it larger.
Definition button.cpp:197
static bool isHovered(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Whether a pointer is over the button.
Definition button.cpp:146
static bool isPressed(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Whether the button is being held down.
Definition button.cpp:157
static void release(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
React to the button being released: this is the click.
Definition button.cpp:274
static utility::graphic::Color32Bit resolveContentColor(const components::Button &button, const utility::graphic::Color32Bit &color)
Let a custom content color replace the themed one.
Definition button.cpp:191
static void setSelected(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier, bool selected)
Select or unselect a toggle button from code and show it at once.
Definition button.cpp:239
static void restyle(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Recompute the colors and geometry of the button at once.
Definition button.cpp:228
static const std::string & activeIconGlyphName(const components::Button &button)
Choose the icon glyph a button shows in its current state.
Definition button.cpp:170
static void syncContent(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Copy what components::Button says onto the icon child and the accessibility state.
Definition button.cpp:213
static utility::graphic::Color32Bit resolveContainerColor(const components::Button &button, const utility::graphic::Color32Bit &color)
Let a custom container color replace the themed one.
Definition button.cpp:184
static const utility::graphic::PoseF contentLayerPose(const utility::graphic::PositionF &position, const utility::graphic::OrientationF &orientation, const std::uint32_t &containerLayer)
Compute the pose of content placed by hand on a container.
Definition layout.cpp:118
Makes the color helpers callable from guillaume::entities without qualification.
State. Every class here is plain data attached to an entity.
AccessibilityRole
What an entity is for a screen reader or another assistive technology. The values mirror react-native...
The entity-component-system core, independent of any widget.
Definition component.hpp:28
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
utility::graphic::Color32Bit stateLayer(const utility::graphic::Color32Bit &base, const utility::graphic::Color32Bit &overlay, std::uint8_t alpha)
Blend a translucent tint over a base color.
utility::graphic::Color32Bit withAlpha(const utility::graphic::Color32Bit &color, std::uint8_t alpha)
Copy a color with another alpha channel.
bool isEnabled(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity accepts input.
void setEnabled(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, bool enabled)
Enable or disable an entity.
@ LabelLarge
14 / 20, medium weight.
Definition typescale.hpp:57
@ DisabledContainer
0.12 opacity of onSurface containers.
Definition tokens.hpp:229
@ DisabledContent
0.38 opacity of onSurface content.
Definition tokens.hpp:228
std::uint8_t getStateLayerAlpha(theme::StateLayer layer)
Get the opacity the active theme gives to a state layer, as an alpha channel value.
const Scheme & getActiveScheme(void)
Get the color scheme in use: the scheme of the active theme selected by setActiveScheme().