guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
surface.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 <utility>
26#include <memory>
27#include <vector>
28
29#include <utility/graphic/color.hpp>
30#include <utility/graphic/pose.hpp>
31
32#include "guillaume/ecs/component.hpp"
33#include "guillaume/ecs/component_registry.hpp"
34#include "guillaume/ecs/entity.hpp"
35#include "guillaume/ecs/parent_entity_filler.hpp"
36
37#include "guillaume/components/borders.hpp"
38#include "guillaume/components/bound.hpp"
39#include "guillaume/components/color.hpp"
40#include "guillaume/components/layout.hpp"
41#include "guillaume/components/transform.hpp"
42
43namespace guillaume::entities
44{
45
72 utility::graphic::PoseF
73 pose {};
74 utility::graphic::Color32Bit color {
75 0, 0, 0, 0
76 };
77 float borderRadius { 0.0f };
87 float spacing { 0.0f };
88 float padding {
89 0.0f
90 };
92 false
93 };
94 float fixedWidth {
95 0.0f
96 };
98 false
99 };
101 0.0f
102 };
103
109 SurfaceConfig &setPose(const utility::graphic::PoseF &value);
110
116 SurfaceConfig &setColor(const utility::graphic::Color32Bit &value);
117
123 SurfaceConfig &setBorderRadius(float value);
124
132
140
148
154 SurfaceConfig &setSpacing(float value);
155
162 SurfaceConfig &setPadding(float value);
163
172 SurfaceConfig &setFixedWidth(float value);
173
182 SurfaceConfig &setFixedHeight(float value);
183
198 float spacing);
199 };
200
238 template<ecs::InheritFromComponent... ExtraComponents> class SurfaceBase:
239 public std::enable_shared_from_this<SurfaceBase<ExtraComponents...>>,
241 components::Layout, components::Transform, components::Bound,
242 components::Color, components::Borders, ExtraComponents...>
243 {
244 public:
245 using Children =
246 std::vector<std::shared_ptr<ecs::Entity>>;
248
252 ~SurfaceBase(void) override = default;
253
262 SurfaceBase &setPose(const utility::graphic::PoseF &pose);
263
272 SurfaceBase &setColor(const utility::graphic::Color32Bit &color);
273
280
292
303
319
326 std::vector<ecs::Entity::Identifier> getChildren(void) const;
327
328 protected:
337 const SurfaceConfig &config);
338
346 void applyGeometry(void);
347 };
348
349} // namespace guillaume::entities
350
351#include "guillaume/entities/surface.tpp"
352
353#include "guillaume/components/elevation.hpp"
354#include "guillaume/components/surface_tone.hpp"
355#include "guillaume/entities/builder_base.hpp"
356#include "guillaume/theme/tokens.hpp"
357
358namespace guillaume::entities
359{
360
387 class Surface:
388 public SurfaceBase<components::Elevation, components::SurfaceTone>
389 {
390 public:
394 enum class Mode {
397 };
398
402 class Builder: public EntityBuilderBase<Surface>
403 {
404 private:
405 SurfaceConfig _config;
406 theme::ElevationLevel _elevation {
408 };
409 Mode _mode {
411 };
412
413 public:
421 Builder(ecs::ComponentRegistry &componentRegistry,
422 ecs::EntityRegistry &entityRegistry);
423
429 std::shared_ptr<Surface> buildEntity(void) override;
430
437 void reset(void) override;
438
445 Builder &withPose(const utility::graphic::PoseF &pose);
446
455
462 Builder &withMode(Mode mode);
463
471
483 Builder &withConfig(const SurfaceConfig &config);
484
497 std::shared_ptr<Surface>
498 makeSurface(std::shared_ptr<ecs::Entity> parent,
499 theme::ElevationLevel elevation,
500 Mode mode = Mode::Elevated);
501 };
502
515 template<typename... Arguments>
516 static std::shared_ptr<Surface> create(Arguments &&...arguments)
517 {
518 std::shared_ptr<Surface> entity(
519 new Surface(std::forward<Arguments>(arguments)...));
520 return entity;
521 }
522
526 ~Surface(void) override = default;
527
536 Surface &setElevation(theme::ElevationLevel elevation);
537
544
550 Surface &setMode(Mode mode);
551
556 Mode getMode(void) const;
557
558 private:
567 Surface(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
568 theme::ElevationLevel elevation, Mode mode);
569 };
570
571} // namespace guillaume::entities
CrossAxisAlignment
Where each child goes along the cross axis, inside the padding. In a container that wraps its childre...
Definition layout.hpp:99
MainAxisAlignment
Where the children go along the main axis when the container is larger than them.
Definition layout.hpp:86
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
Axis
Direction along which children are arranged.
Definition layout.hpp:74
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
Owns entities and gives the systems the list of entities to visit.
The base class of a widget with children: an EntityFiller that is also a ParentEntity.
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
SurfaceConfig getSurfaceConfig(void) const
Read the current configuration back from the components.
std::vector< std::shared_ptr< ecs::Entity > > Children
Definition surface.hpp:245
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
Create the entity with its components and apply a configuration.
SurfaceBase & setChildren(const Children &children)
Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren(void) const
Get the children this surface arranges.
SurfaceBase & setPose(const utility::graphic::PoseF &pose)
Move the surface.
SurfaceBase & setColor(const utility::graphic::Color32Bit &color)
Set the fill color (Color component).
~SurfaceBase(void) override=default
Default destructor.
SurfaceBase & setBorderRadius(float radius)
Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig(const SurfaceConfig &config)
Apply every field of a configuration at once.
void applyGeometry(void)
Arrange the layout children now with systems::Layout::apply.
Builder & withMode(Mode mode)
Choose whether the surface casts a shadow.
Definition surface.cpp:154
std::shared_ptr< Surface > makeSurface(std::shared_ptr< ecs::Entity > parent, theme::ElevationLevel elevation, Mode mode=Mode::Elevated)
Build a surface with the given elevation and register it under a parent.
Definition surface.cpp:175
Builder & withShape(theme::ShapeRole role)
Set the corner radius from a shape role of the theme.
Definition surface.cpp:160
Builder & withElevation(theme::ElevationLevel elevation)
Set the elevation level, which tints the background and sizes the shadow.
Definition surface.cpp:148
std::shared_ptr< Surface > buildEntity(void) override
Create a surface from the current configuration, without attaching nor registering it.
Definition surface.cpp:125
Builder & withConfig(const SurfaceConfig &config)
Replace the layout configuration: axis, alignment, spacing, padding, fixed size and corner radius.
Definition surface.cpp:166
void reset(void) override
Restore the defaults: elevation level 1, a shadow (Mode::Elevated), square corners,...
Definition surface.cpp:131
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the surface is.
Definition surface.cpp:141
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Construct a builder set to the defaults of reset().
Definition surface.cpp:118
Mode getMode(void) const
Tell whether the surface casts a shadow.
Definition surface.cpp:220
theme::ElevationLevel getElevation(void) const
Get the elevation level.
Definition surface.cpp:204
~Surface(void) override=default
Destructor.
Surface & setMode(Mode mode)
Turn the shadow on or off, and restyle at once.
Definition surface.cpp:211
static std::shared_ptr< Surface > create(Arguments &&...arguments)
Create a surface without registering it.
Definition surface.hpp:516
Surface & setElevation(theme::ElevationLevel elevation)
Change the elevation level.
Definition surface.cpp:195
Mode
Whether the surface casts a shadow.
Definition surface.hpp:394
@ Elevated
Tinted background and the shadow of the level.
Definition surface.hpp:396
@ Flat
Tinted background, no shadow.
Definition surface.hpp:395
Constrains a template parameter to a type derived from Component (or Component itself).
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
ElevationLevel
How far a surface is raised above the background, in six steps.
Definition tokens.hpp:130
@ Level1
Lowest raised level.
Definition tokens.hpp:132
ShapeRole
The corner radii a widget can ask for, by name.
Definition tokens.hpp:42
Everything needed to set up a surface in one value: where it is, how it looks and how it arranges its...
Definition surface.hpp:71
SurfaceConfig & setMainAxisAlignment(components::Layout::MainAxisAlignment value)
Set where the children go along the axis.
Definition surface.cpp:54
float padding
Gap between the edges and the children, in dp.
Definition surface.hpp:88
SurfaceConfig & setFixedHeight(float value)
Give the surface a height that does not depend on its children.
Definition surface.cpp:87
SurfaceConfig & setBorderRadius(float value)
Set the radius of the four corners.
Definition surface.cpp:42
utility::graphic::PoseF pose
Position and orientation of the surface.
Definition surface.hpp:73
SurfaceConfig & setAxis(components::Layout::Axis value)
Choose between a row and a column.
Definition surface.cpp:48
SurfaceConfig & setCrossAxisAlignment(components::Layout::CrossAxisAlignment value)
Set where the children go across the axis.
Definition surface.cpp:61
float spacing
Gap between two children, in dp.
Definition surface.hpp:87
SurfaceConfig & setPose(const utility::graphic::PoseF &value)
Set where the surface is.
Definition surface.cpp:29
bool hasFixedWidth
True when fixedWidth replaces the content width.
Definition surface.hpp:91
float fixedWidth
Width in dp, used only when hasFixedWidth.
Definition surface.hpp:94
SurfaceConfig & setPadding(float value)
Set the gap between the edges of the surface and its children.
Definition surface.cpp:74
components::Layout::MainAxisAlignment mainAxisAlignment
Where the children go along the axis.
Definition surface.hpp:81
utility::graphic::Color32Bit color
Fill color (transparent by default).
Definition surface.hpp:74
SurfaceConfig & setColor(const utility::graphic::Color32Bit &value)
Set the fill color.
Definition surface.cpp:36
components::Layout::Axis axis
Direction the children are arranged in.
Definition surface.hpp:78
static SurfaceConfig panel(float width, components::Layout::Axis axis, float spacing)
Get the configuration shared by dialog and picker panels.
Definition surface.cpp:94
bool hasFixedHeight
True when fixedHeight replaces the content height.
Definition surface.hpp:97
float fixedHeight
Height in dp, used only when hasFixedHeight.
Definition surface.hpp:100
components::Layout::CrossAxisAlignment crossAxisAlignment
Where the children go across the axis.
Definition surface.hpp:84
SurfaceConfig & setFixedWidth(float value)
Give the surface a width that does not depend on its children.
Definition surface.cpp:80
SurfaceConfig & setSpacing(float value)
Set the gap between two consecutive children.
Definition surface.cpp:68
float borderRadius
Radius of the four corners, in dp.
Definition surface.hpp:77