guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
button_base.hpp
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#pragma once
24
25#include <chrono>
26#include <optional>
27#include <cstdint>
28#include <functional>
29#include <memory>
30#include <string>
31
32#include "guillaume/ecs/component_registry.hpp"
33#include "guillaume/ecs/parent_entity_filler.hpp"
34
35#include "guillaume/components/borders.hpp"
36#include "guillaume/components/button.hpp"
37#include "guillaume/components/transform.hpp"
38#include "guillaume/components/bound.hpp"
39#include "guillaume/components/accessibility.hpp"
40#include "guillaume/components/color.hpp"
41#include "guillaume/components/focus.hpp"
42#include "guillaume/components/hand_button_interaction.hpp"
43#include "guillaume/components/hand_hover_interaction.hpp"
44#include "guillaume/components/mouse_hover_interaction.hpp"
45#include "guillaume/components/mouse_button_interaction.hpp"
46#include "guillaume/components/style_state.hpp"
47
48#include "guillaume/entities/icon.hpp"
49#include "guillaume/entities/text.hpp"
50#include "guillaume/systems/button.hpp"
51
52namespace guillaume::entities
53{
54
98 public std::enable_shared_from_this<ButtonBase>,
100 components::Transform, components::Bound, components::Color,
101 components::Borders, components::Focus,
102 components::HandButtonInteraction, components::HandHoverInteraction,
103 components::MouseHoverInteraction,
104 components::MouseButtonInteraction, components::StyleState,
105 components::Accessibility, components::Button>
106 {
107 public:
111 ~ButtonBase(void) override = default;
112
121 ButtonBase &setIconGlyphName(const std::string &iconGlyphName);
122
130
139 ButtonBase &setLabelContent(const std::string &labelContent);
140
149 ButtonBase &setIsToggle(const bool &isToggle);
150
156 bool isSelected(void) const;
157
166 ButtonBase &setSelected(const bool &selected);
167
175 ButtonBase &
176 setSelectedIconGlyphName(const std::string &selectedIconGlyphName);
177
186 ButtonBase &setMorph(const bool &isMorph);
187
194 ButtonBase &setTrailingIcon(const bool &isTrailingIcon);
195
204 ButtonBase &setDisabled(const bool &isDisabled);
205
210 bool isDisabled(void) const;
211
218 ButtonBase &
219 setAccessibilityLabel(const std::string &accessibilityLabel);
220
225 const std::string &getAccessibilityLabel(void) const;
226
233 ButtonBase &setAccessibilityHint(const std::string &accessibilityHint);
234
242
254 ButtonBase &setOnLongPress(std::function<void(void)> onLongPress);
255
265 ButtonBase &setLoading(bool loading);
266
281 ButtonBase &setVisible(bool visible);
282
287 bool isVisible(void) const;
288
293 bool isLoading(void) const;
294
303 std::optional<utility::graphic::Color32Bit> color);
304
313 std::optional<utility::graphic::Color32Bit> color);
314
318 static constexpr const char *LoadingGlyph =
320
325 static constexpr std::chrono::milliseconds LongPressDuration {
327 };
328
335 const std::string &getAccessibilityHint(void) const;
336
346 ButtonBase &setOnClick(std::function<void(void)> onClick);
347
354
361
362 protected:
373 void build(void);
374
391 const std::string &iconGlyphName,
392 const components::Glyph::Style &iconStyle,
393 const std::string &labelContent, bool isToggle, bool isMorph,
394 bool isDisabled, bool isTrailingIcon,
395 const std::string &accessibilityLabel,
396 std::function<void(void)> onClick);
397
403
408 const components::Button &state(void) const;
409
417 void restyle(void);
418
423 virtual float getIconFontSize(void) const = 0;
424
429 virtual bool usesLabel(void) const
430 {
431 return false;
432 }
433
438 virtual bool usesIcon(void) const
439 {
440 return true;
441 }
442
448 virtual utility::graphic::Color32Bit
449 getInitialContentColor(void) const = 0;
450
455 bool isHovered(void);
456
462 bool isPressed(void);
463
470 const std::string &getActiveIconGlyphName(void) const;
471
472 public:
485 static const utility::graphic::PoseF applyLayerToPosition(
486 const utility::graphic::PositionF &position,
487 const utility::graphic::OrientationF &orientation,
488 const std::uint32_t &layer);
489
497 static utility::graphic::Color32Bit
498 applyStateAlpha(const utility::graphic::Color32Bit &color,
499 std::uint8_t alpha);
500
510 static utility::graphic::Color32Bit
511 applyStateLayer(const utility::graphic::Color32Bit &base,
512 const utility::graphic::Color32Bit &overlay,
513 std::uint8_t alpha);
514
520 static utility::graphic::Color32Bit getDisabledContainerColor(void);
521
527 static utility::graphic::Color32Bit getDisabledContentColor(void);
528
535 static utility::graphic::Color32Bit getDisabledBorderColor(void);
536
544 void hoverHandler(void);
545
551 void unHoverHandler(void);
552
559 void buttonPressHandler(void);
560
568 void buttonReleaseHandler(void);
569
570 protected:
582 void applyTouchTarget(float width, float height);
583
592 void syncAccessibilityState(void);
593
600 utility::graphic::Color32Bit resolveContainerColor(
601 const utility::graphic::Color32Bit &color) const;
602
609 utility::graphic::Color32Bit resolveContentColor(
610 const utility::graphic::Color32Bit &color) const;
611 static constexpr float _layerDepthStep {
612 1.0f
613 };
614 };
615
616} // namespace guillaume::entities
State shared by every pressable button, whatever its look.
Definition button.hpp:77
Style
Family of the Material Symbols font the icon belongs to.
Definition glyph.hpp:66
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
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
The base class of a widget with children: an EntityFiller that is also a ParentEntity.
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.
~ButtonBase(void) override=default
Default destructor.
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.
static constexpr const char * LoadingGlyph
Name of the glyph the icon child shows while loading.
static constexpr float _layerDepthStep
Depth between two layers, toward the viewer.
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.
static constexpr std::chrono::milliseconds LongPressDuration
How long a press must last to count as a long press (500 ms).
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.
static constexpr std::chrono::milliseconds LongPressDuration
Definition button.hpp:176
static constexpr const char * LoadingGlyph
Definition button.hpp:172
AccessibilityRole
What an entity is for a screen reader or another assistive technology. The values mirror react-native...
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46