guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
theme.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 <array>
26#include <cstdint>
27#include <map>
28#include <stdexcept>
29#include <string>
30
31#include <utility/graphic/color.hpp>
32
33#include "guillaume/theme/tokens.hpp"
34#include "guillaume/theme/typescale.hpp"
35
36namespace guillaume
37{
38
58 enum class SchemeColorRole : std::size_t {
59 Primary,
60 SurfaceTint,
61 OnPrimary,
62 PrimaryContainer,
63 OnPrimaryContainer,
65 OnSecondary,
66 SecondaryContainer,
67 OnSecondaryContainer,
69 OnTertiary,
70 TertiaryContainer,
71 OnTertiaryContainer,
72 Error,
73 OnError,
74 ErrorContainer,
75 OnErrorContainer,
76 Background,
77 OnBackground,
78 Surface,
79 OnSurface,
80 SurfaceVariant,
81 OnSurfaceVariant,
82 Outline,
83 OutlineVariant,
84 Shadow,
85 Scrim,
86 InverseSurface,
87 InverseOnSurface,
88 InversePrimary,
89 PrimaryFixed,
90 OnPrimaryFixed,
91 PrimaryFixedDim,
92 OnPrimaryFixedVariant,
93 SecondaryFixed,
94 OnSecondaryFixed,
95 SecondaryFixedDim,
96 OnSecondaryFixedVariant,
97 TertiaryFixed,
98 OnTertiaryFixed,
99 TertiaryFixedDim,
100 OnTertiaryFixedVariant,
101 SurfaceDim,
102 SurfaceBright,
103 SurfaceContainerLowest,
104 SurfaceContainerLow,
105 SurfaceContainer,
106 SurfaceContainerHigh,
107 SurfaceContainerHighest,
112 };
113
132
148
158 {
159 private:
160 utility::graphic::Color32Bit
161 _color;
162 std::string _name;
163 std::string _description;
164 bool _harmonized;
167
168 public:
174
183 ExtendedColor(const utility::graphic::Color32Bit &color,
184 const std::string &name, const std::string &description,
185 bool harmonized);
186
190 ~ExtendedColor(void) = default;
191
196 const utility::graphic::Color32Bit &getColor(void) const;
197
202 const std::string &getName(void) const;
203
208 const std::string &getDescription(void) const;
209
216 bool isHarmonized(void) const;
217
223 void setColor(const utility::graphic::Color32Bit &color);
224
229 void setName(const std::string &name);
230
235 void setDescription(const std::string &description);
236
242 void setHarmonized(bool harmonized);
243 };
244
262 class Scheme
263 {
264 private:
265 std::array<ExtendedColor,
266 static_cast<std::size_t>(SchemeColorRole::Count)>
267 _colors;
268
274 static constexpr std::size_t toIndex(SchemeColorRole role);
275
276 public:
281 Scheme(void) = default;
282
288 explicit Scheme(
289 const std::array<ExtendedColor,
290 static_cast<std::size_t>(SchemeColorRole::Count)>
291 &colors);
292
296 ~Scheme(void) = default;
297
306
314
322 void setColor(SchemeColorRole role, const ExtendedColor &color);
323
338 const utility::graphic::Color32Bit &color,
339 const std::string &name = "",
340 const std::string &description = "",
341 bool harmonized = false);
342
350 const auto &getColors(void) const;
351 };
352
364 {
365 public:
370 enum class Tone : std::uint8_t {
371 T0 = 0,
372 T10 = 10,
373 T20 = 20,
374 T30 = 30,
375 T40 = 40,
376 T50 = 50,
377 T60 = 60,
378 T70 = 70,
379 T80 = 80,
380 T90 = 90,
381 T100 = 100
382 };
383
384 private:
385 std::string _name;
386 std::string _description;
387 std::map<Tone, ExtendedColor> _tones;
388
389 public:
393 Palette(void);
394
400 Palette(const std::string &name, const std::string &description);
401
405 ~Palette(void) = default;
406
411 const std::string &getName(void) const;
412
417 const std::string &getDescription(void) const;
418
424 const std::map<Tone, ExtendedColor> &getTones(void) const;
425
430 void setName(const std::string &name);
431
436 void setDescription(const std::string &description);
437
443 void setTone(Tone tone, const ExtendedColor &color);
444
455 void setTone(Tone tone, const utility::graphic::Color32Bit &color,
456 const std::string &name = "",
457 const std::string &description = "",
458 bool harmonized = false);
459
466 bool hasTone(Tone tone) const;
467
475 const ExtendedColor &getTone(Tone tone) const;
476
481 void removeTone(Tone tone);
482
486 void clearTones(void);
487 };
488
534 class Theme
535 {
536 private:
537 std::string _name;
538 std::string _description;
539 std::array<Scheme, ThemeSchemeRole::ThemeSchemeCount>
540 _schemes;
541 std::array<Palette, ThemePaletteRole::ThemePaletteCount>
542 _palettes;
543 theme::Typescale _typescale;
544 theme::ShapeScale _shapes;
546 _elevations;
548 _stateLayers;
549 theme::MotionScale _motion;
550
551 public:
556 Theme(void);
557
564 Theme(const std::string &name, const std::string &description);
565
569 virtual ~Theme(void) = default;
570
575 const std::string &getName(void) const;
576
581 const std::string &getDescription(void) const;
582
587 void setName(const std::string &name);
588
593 void setDescription(const std::string &description);
594
600 const Scheme &getScheme(ThemeSchemeRole role) const;
601
609
616
624
631 void setScheme(ThemeSchemeRole role, const Scheme &scheme);
632
639 void setPalette(ThemePaletteRole role, const Palette &palette);
640
646 const theme::Typescale &getTypescale(void) const;
647
654
659 void setTypescale(const theme::Typescale &typescale);
660
665 const theme::ShapeScale &getShapes(void) const;
666
673
680
687
694
701
706 const theme::MotionScale &getMotion(void) const;
707
714 };
715
724 extern const Theme defaultTheme;
725
734 const Theme &getActiveTheme(void);
735
750
757
767 utility::graphic::Color32Bit getActiveColor(SchemeColorRole role);
768
779
785
799
809
821
831
845 utility::graphic::Color32Bit
847
857
858} // namespace guillaume
A color with a name and a description, as stored in a Scheme or a Palette.
Definition theme.hpp:158
ExtendedColor(const utility::graphic::Color32Bit &color, const std::string &name, const std::string &description, bool harmonized)
Create a color with its documentation.
const utility::graphic::Color32Bit & getColor(void) const
Get the color to draw with.
const std::string & getDescription(void) const
Get the text describing what the color is for.
~ExtendedColor(void)=default
Default destructor.
void setColor(const utility::graphic::Color32Bit &color)
Replace the color value; the name and the description are kept.
void setHarmonized(bool harmonized)
Mark the color as harmonized or not.
void setDescription(const std::string &description)
Replace the text describing what the color is for.
bool isHarmonized(void) const
Tell whether the color was shifted toward the theme's source color.
void setName(const std::string &name)
Replace the name of the color.
ExtendedColor(void)
Create a default-constructed color with an empty name and description, not harmonized.
const std::string & getName(void) const
Get the name of the color.
The shades of one color family, from black (tone 0) to white (tone 100).
Definition theme.hpp:364
~Palette(void)=default
Default destructor.
void setTone(Tone tone, const ExtendedColor &color)
Define a tone, replacing the color it already has, if any.
const std::string & getDescription(void) const
Get the text describing what the palette is for.
bool hasTone(Tone tone) const
Tell whether a tone is defined.
void setName(const std::string &name)
Replace the name of the palette.
Palette(const std::string &name, const std::string &description)
Create a palette with a name and no tone.
Palette(void)
Create a palette with no name and no tone.
const ExtendedColor & getTone(Tone tone) const
Get the color of a tone.
const std::string & getName(void) const
Get the name of the palette.
void setTone(Tone tone, const utility::graphic::Color32Bit &color, const std::string &name="", const std::string &description="", bool harmonized=false)
Define a tone from a plain color value, replacing the color it already has, if any.
void clearTones(void)
Undefine every tone of the palette.
void removeTone(Tone tone)
Undefine a tone. Does nothing when it is not defined.
Tone
The tones a palette can hold. The number is the lightness: 0 is black, 100 is white.
Definition theme.hpp:370
@ T30
Lightness 30.
Definition theme.hpp:374
@ T40
Lightness 40.
Definition theme.hpp:375
@ T10
Lightness 10.
Definition theme.hpp:372
@ T80
Lightness 80.
Definition theme.hpp:379
@ T20
Lightness 20.
Definition theme.hpp:373
@ T60
Lightness 60.
Definition theme.hpp:377
@ T90
Lightness 90.
Definition theme.hpp:380
@ T70
Lightness 70.
Definition theme.hpp:378
@ T50
Lightness 50.
Definition theme.hpp:376
void setDescription(const std::string &description)
Replace the text describing what the palette is for.
const std::map< Tone, ExtendedColor > & getTones(void) const
Get every tone defined in the palette.
One complete set of colors: a color for every SchemeColorRole.
Definition theme.hpp:263
Scheme(void)=default
Create a scheme in which every role has a default-constructed, unnamed color.
~Scheme(void)=default
Default destructor.
const auto & getColors(void) const
Get every color of the scheme.
void setColor(SchemeColorRole role, const ExtendedColor &color)
Replace the color of a role, with its name and description.
void setColor(SchemeColorRole role, const utility::graphic::Color32Bit &color, const std::string &name="", const std::string &description="", bool harmonized=false)
Replace the color of a role from a plain color value.
ExtendedColor & getColor(SchemeColorRole role)
Get the color of a role, to modify it in place.
const ExtendedColor & getColor(SchemeColorRole role) const
Get the color of a role, with its name and description.
Scheme(const std::array< ExtendedColor, static_cast< std::size_t >(SchemeColorRole::Count)> &colors)
Create a scheme from a full set of colors.
Every design token of the UI in one object: colors, type scale, corner shapes, elevation,...
Definition theme.hpp:535
void setTypescale(const theme::Typescale &typescale)
Replace every text style of the theme at once.
const std::string & getDescription(void) const
Get the text describing the theme.
void setScheme(ThemeSchemeRole role, const Scheme &scheme)
Replace one of the six color schemes as a whole.
theme::Typescale & getTypescale(void)
Get the text styles of the theme, to change a role in place with theme::Typescale::set.
const theme::Typescale & getTypescale(void) const
Get the text styles of the theme.
const theme::ElevationScale & getElevations(void) const
Get the elevation levels of the theme (shadow and surface tint).
Theme(void)
Create an unnamed theme with the baseline scales and empty color schemes and palettes.
const Palette & getPalette(ThemePaletteRole role) const
Get one of the five tonal palettes.
Scheme & getScheme(ThemeSchemeRole role)
Get one of the six color schemes, to change its colors in place.
const theme::MotionScale & getMotion(void) const
Get the animation durations of the theme.
const theme::StateLayerScale & getStateLayers(void) const
Get the state-layer opacities of the theme (hovered, focused, pressed, ...).
const theme::ShapeScale & getShapes(void) const
Get the corner radii of the theme.
virtual ~Theme(void)=default
Virtual destructor.
Theme(const std::string &name, const std::string &description)
Create a named theme with the baseline scales and empty color schemes and palettes.
void setName(const std::string &name)
Replace the name of the theme.
theme::ShapeScale & getShapes(void)
Get the corner radii of the theme, to change the roundness in place.
const std::string & getName(void) const
Get the name of the theme.
theme::StateLayerScale & getStateLayers(void)
Get the state-layer opacities of the theme, to change one in place.
const Scheme & getScheme(ThemeSchemeRole role) const
Get one of the six color schemes.
theme::MotionScale & getMotion(void)
Get the animation durations of the theme, to change one in place.
void setPalette(ThemePaletteRole role, const Palette &palette)
Replace one of the five tonal palettes as a whole.
theme::ElevationScale & getElevations(void)
Get the elevation levels of the theme, to change a level in place.
Palette & getPalette(ThemePaletteRole role)
Get one of the five tonal palettes, to change its tones in place.
void setDescription(const std::string &description)
Replace the text describing the theme.
The six elevation levels of a theme: one ElevationToken per ElevationLevel.
Definition tokens.hpp:170
The animation timings of a theme: one length per MotionDuration, plus which easing curve to use for w...
Definition tokens.hpp:329
Turns a ShapeRole into a corner radius in dp, scaled by one "roundness" value.
Definition tokens.hpp:74
The opacity of each StateLayer, 0 to 1.
Definition tokens.hpp:243
The text styles of a theme: one TypeToken per TypeRole.
Design tokens: colors, type scale, shapes, elevation, motion and spacing. Read them through guillaume...
ElevationLevel
How far a surface is raised above the background, in six steps.
Definition tokens.hpp:130
TypeRole
The named text styles of Material Design 3: what a piece of text is, not how big it is.
Definition typescale.hpp:47
StateLayer
The interaction states that change how a widget is drawn.
Definition tokens.hpp:223
MotionDuration
The named animation lengths of Material Design 3. The values given are the defaults.
Definition tokens.hpp:290
ShapeRole
The corner radii a widget can ask for, by name.
Definition tokens.hpp:42
A C++20 UI framework for desktop and XR, built as an entity-component-system.
ThemePaletteRole
The five tonal palettes a Theme holds, one per color family.
Definition theme.hpp:140
@ NeutralVariant
Tinted greys used for outlines and variants.
Definition theme.hpp:145
@ Neutral
Greys used for surfaces and text.
Definition theme.hpp:144
@ ThemePaletteCount
Number of palettes; not a palette.
Definition theme.hpp:146
@ Secondary
Tones of the secondary accent color.
Definition theme.hpp:142
@ Tertiary
Tones of the tertiary accent color.
Definition theme.hpp:143
@ Primary
Tones of the primary accent color.
Definition theme.hpp:141
ThemeSchemeRole
The six color schemes a Theme holds: light and dark, each in standard, medium and high contrast.
Definition theme.hpp:123
@ Dark
Dark scheme, standard contrast.
Definition theme.hpp:127
@ DarkHighContrast
Dark scheme, high contrast.
Definition theme.hpp:129
@ Light
Light scheme, standard contrast.
Definition theme.hpp:124
@ LightMediumContrast
Light scheme, medium contrast.
Definition theme.hpp:125
@ LightHighContrast
Light scheme, high contrast.
Definition theme.hpp:126
@ DarkMediumContrast
Dark scheme, medium contrast.
Definition theme.hpp:128
@ ThemeSchemeCount
Number of schemes; not a scheme.
Definition theme.hpp:130
utility::graphic::Color32Bit getElevatedSurfaceColor(theme::ElevationLevel level)
Get the background color of a surface raised to an elevation level.
const theme::ElevationToken & getElevationToken(theme::ElevationLevel level)
Get the shadow and tint the active theme gives to an elevation level.
const Theme & getActiveTheme(void)
Get the theme every widget and system reads its tokens from.
std::uint8_t getStateLayerAlpha(theme::StateLayer layer)
Get the opacity the active theme gives to a state layer, as an alpha channel value.
const theme::TypeToken & getTypeToken(theme::TypeRole role)
Get the text style the active theme gives to a role: font family, weight, size, line height and lette...
SchemeColorRole
The named colors of a scheme: what a color is used for, not what it looks like.
Definition theme.hpp:58
@ SurfaceDisabled
Disabled container (onSurface at 12%).
Definition theme.hpp:108
@ OnSurfaceDisabled
Disabled content (onSurface at 38%).
Definition theme.hpp:109
@ Count
Number of roles; not a role.
Definition theme.hpp:111
@ Backdrop
Modal backdrop behind dialogs and drawers.
Definition theme.hpp:110
float getMotionDuration(theme::MotionDuration duration)
Get the length the active theme gives to a duration token.
void setActiveScheme(ThemeSchemeRole role)
Choose which of the six schemes of the active theme is in use, for instance to switch between light a...
const theme::Typescale & getActiveTypescale(void)
Get the text styles of the active theme.
const Theme defaultTheme
The theme of the library: Material Design 3 baseline colors (six schemes, five palettes) and scales.
void setActiveTheme(const Theme &theme)
Replace the active theme by a copy of another theme.
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
utility::graphic::Color32Bit getActiveColor(SchemeColorRole role)
Get the color the active scheme gives to a role.
const Scheme & getActiveScheme(void)
Get the color scheme in use: the scheme of the active theme selected by setActiveScheme().
What one elevation level looks like: how much the surface is tinted and how large and dark its shadow...
Definition tokens.hpp:144
One text style: everything needed to measure and draw a piece of text.
Definition typescale.hpp:83