guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
app_bar.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 <memory>
24#include <utility>
25
26#include "guillaume/entities/app_bar.hpp"
27
28#include "guillaume/entities/content_helpers.hpp"
29#include "guillaume/entities/builder_base.hpp"
31#include "guillaume/systems/app_bar.hpp"
32#include "guillaume/theme.hpp"
33
34namespace guillaume::entities
35{
37 ecs::EntityRegistry &entityRegistry)
38 : EntityBuilderBase<AppBar>(componentRegistry, entityRegistry)
39 {
40 reset();
41 }
42
43 std::shared_ptr<AppBar> AppBar::Builder::buildEntity(void)
44 {
45 auto entity =
46 AppBar::create(this->getComponentRegistry(), _config, _variant,
47 _title, _navigation, _actions, _elevated);
48 return entity;
49 }
50
52 {
53 _config = SurfaceConfig();
54 _variant = Variant::Small;
55 _title.clear();
56 _navigation = Action {};
57 _actions.clear();
58 _elevated = false;
59
61 _config.crossAxisAlignment =
63 _config.spacing = HorizontalPadding;
64 _config.padding = HorizontalPadding;
65 _config.setFixedWidth(360.0f);
66 }
67
69 AppBar::Builder::withPose(const utility::graphic::PoseF &pose)
70 {
71 _config.pose = pose;
72 return *this;
73 }
74
76 {
77 _variant = variant;
78 return *this;
79 }
80
82 {
83 _title = title;
84 return *this;
85 }
86
88 AppBar::Builder::withNavigationIcon(const std::string &iconGlyphName)
89 {
90 _navigation.icon = iconGlyphName;
91 if (_navigation.accessibilityLabel.empty()) {
92 _navigation.accessibilityLabel = iconGlyphName;
93 }
94 return *this;
95 }
96
98 AppBar::Builder::addAction(const std::string &iconGlyphName)
99 {
100 _actions.push_back(Action { iconGlyphName, {}, iconGlyphName, false });
101 return *this;
102 }
103
105 AppBar::Builder::addAction(const std::string &iconGlyphName,
106 std::function<void(void)> onPress,
107 const std::string &accessibilityLabel)
108 {
109 _actions.push_back(Action {
110 iconGlyphName, std::move(onPress),
111 accessibilityLabel.empty() ? iconGlyphName : accessibilityLabel,
112 false });
113 return *this;
114 }
115
117 AppBar::Builder::withOnNavigation(std::function<void(void)> onPress,
118 const std::string &accessibilityLabel)
119 {
120 _navigation.onPress = std::move(onPress);
121 _navigation.accessibilityLabel = accessibilityLabel;
122 return *this;
123 }
124
126 {
127 _elevated = elevated;
128 return *this;
129 }
130
132 {
133 _config.hasFixedWidth = true;
134 _config.fixedWidth = width;
135 return *this;
136 }
137
138 std::shared_ptr<AppBar>
139 AppBar::Builder::makeAppBar(std::shared_ptr<ecs::Entity> parent,
140 Variant variant)
141 {
142 return withVariant(variant).registerEntity(parent);
143 }
144
145 namespace
146 {
147 std::vector<AppBar::Action>
148 toActions(const std::vector<std::string> &icons)
149 {
150 std::vector<AppBar::Action> actions;
151 for (const auto &icon: icons) {
152 actions.push_back(AppBar::Action { icon, {}, icon, false });
153 }
154 return actions;
155 }
156 } // namespace
157
158 AppBar::AppBar(ecs::ComponentRegistry &registry,
159 const SurfaceConfig &config, Variant variant,
160 const std::string &title, const std::string &navigationIcon,
161 const std::vector<std::string> &actions)
162 : AppBar(registry, config, variant, title,
163 Action { navigationIcon, {}, navigationIcon, false },
164 toActions(actions), false)
165 {
166 }
167
168 AppBar::AppBar(ecs::ComponentRegistry &registry,
169 const SurfaceConfig &config, Variant variant,
170 const std::string &title, const Action &navigation,
171 const std::vector<Action> &actions, bool elevated)
172 : SurfaceBase<components::Elevation, components::AppBar>(registry,
173 config)
174 {
176 .getComponent<components::AppBar>(getIdentifier())
177 .setVariant(variant)
178 .setTitle(title)
179 .setNavigation(navigation)
180 .setActions(actions)
181 .setElevated(elevated);
183 }
184
186 {
187 }
188
189 std::shared_ptr<IconButton> AppBar::buildAction(const Action &action)
190 {
191 IconButton::Builder builder(this->getComponentRegistry(), *this);
192 return builder.withIcon(action.icon)
193 .withOnClick(action.onPress)
194 .withVariant(IconButton::Variant::Standard)
195 .withSize(IconButton::Size::Medium)
196 .withDisabled(action.disabled)
197 .withAccessibilityLabel(action.accessibilityLabel)
198 .registerEntity(this->shared_from_this());
199 }
200
201 void AppBar::buildContent(void)
202 {
203 // Children need the owning handle as their parent.
204 if (weak_from_this().expired()) {
205 return;
206 }
207
208 auto &registry = getComponentRegistry();
209 auto &appBar =
210 registry.getComponent<components::AppBar>(getIdentifier());
211
212 // Which children are missing is decided by systems::AppBar; they are
213 // only built here because that needs shared_from_this().
215 const auto navigation = buildAction(appBar.getNavigation());
216 if (navigation != nullptr) {
217 appBar.setNavigationButton(navigation->getIdentifier());
218 }
219 }
220
222 const auto title = buildText(
223 registry, *this, shared_from_this(), appBar.getTitle(),
224 systems::AppBar::titleRole(appBar.getVariant()),
225 schemeColor(SchemeColorRole::OnSurface));
226 if (title != nullptr) {
227 appBar.setTitleEntity(title->getIdentifier());
229 }
230 }
231
234 for (const auto &action: appBar.getActions()) {
235 const auto button = buildAction(action);
236 identifiers.push_back(button != nullptr
237 ? button->getIdentifier()
239 }
240 appBar.setActionButtons(identifiers);
241 }
242
243 // Hand the layout children to the surface.
244 std::vector<std::shared_ptr<ecs::Entity>> children;
245 if (auto navigation =
246 getEntity<IconButton>(appBar.getNavigationButton())) {
247 children.push_back(std::move(navigation));
248 }
249 if (auto title = getEntity<Text>(appBar.getTitleEntity())) {
250 children.push_back(std::move(title));
251 }
252 for (const auto identifier: appBar.getActionButtons()) {
253 if (auto action = getEntity<IconButton>(identifier)) {
254 children.push_back(std::move(action));
255 }
256 }
257 setChildren(children);
258 }
259
268
269 AppBar &AppBar::setElevated(bool elevated)
270 {
273 .setElevated(elevated);
275 return *this;
276 }
277
278 bool AppBar::isElevated(void) const
279 {
280 return getComponentRegistry()
282 .isElevated();
283 }
284
285 std::shared_ptr<IconButton> AppBar::getNavigationButton(void) const
286 {
287 // The lookup is const because this getter is; the child itself is
288 // shared and mutable, hence the cast.
289 return std::const_pointer_cast<IconButton>(getEntity<IconButton>(
291 .getComponent<components::AppBar>(getIdentifier())
293 }
294
295 std::shared_ptr<IconButton> AppBar::getActionButton(std::size_t index) const
296 {
297 const auto &actions =
300 .getActionButtons();
301
302 if (index >= actions.size()) {
303 return nullptr;
304 }
305 return std::const_pointer_cast<IconButton>(
306 getEntity<IconButton>(actions[index]));
307 }
308
309 std::shared_ptr<Text> AppBar::getTitle(void) const
310 {
311 return std::const_pointer_cast<Text>(getEntity<Text>(
313 .getComponent<components::AppBar>(getIdentifier())
314 .getTitleEntity()));
315 }
316
323
324 AppBar &AppBar::setTitle(const std::string &title)
325 {
328 .setTitle(title);
329 // A first title needs its text child.
330 buildContent();
332 return *this;
333 }
334
335 void AppBar::build(void)
336 {
337 buildContent();
339 }
340
341} // namespace guillaume::entities
State of an app bar: the strip that carries a screen's title, its navigation icon and its action icon...
Definition app_bar.hpp:54
std::vector< ecs::Entity::Identifier > Identifiers
Identifiers of child entities, in display order.
Definition app_bar.hpp:79
@ 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...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
ComponentRegistry & getComponentRegistry(void)
Get the registry in which the builder creates components.
Owns entities and gives the systems the list of entities to visit.
std::shared_ptr< EntityType > getEntity(Entity::Identifier identifier)
Find an entity owned directly by this registry, by identifier.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
Configures an AppBar, creates it and registers it in an entity registry.
Definition app_bar.hpp:107
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the app bar is placed.
Definition app_bar.cpp:69
Builder & withFixedWidth(float width)
Set the width of the app bar.
Definition app_bar.cpp:131
Builder & withElevated(bool elevated)
Choose the elevated look (Paper elevated).
Definition app_bar.cpp:125
Builder & addAction(const std::string &iconGlyphName)
Append a trailing action button without press handler.
Definition app_bar.cpp:98
std::shared_ptr< AppBar > makeAppBar(std::shared_ptr< ecs::Entity > parent, Variant variant)
Build an app bar, register it under parent and reset the builder.
Definition app_bar.cpp:139
Builder & withOnNavigation(std::function< void(void)> onPress, const std::string &accessibilityLabel="Navigate up")
Set the press handler of the navigation button (Paper Appbar.BackAction).
Definition app_bar.cpp:117
Builder & withNavigationIcon(const std::string &iconGlyphName)
Set the icon of the leading navigation button.
Definition app_bar.cpp:88
Builder & withTitle(const std::string &title)
Set the title text.
Definition app_bar.cpp:81
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Definition app_bar.cpp:36
Builder & withVariant(Variant variant)
Set the variant.
Definition app_bar.cpp:75
void reset(void) override
Restore the defaults.
Definition app_bar.cpp:51
std::shared_ptr< AppBar > buildEntity(void) override
Build an app bar and its children from the current configuration, without registering it or setting i...
Definition app_bar.cpp:43
A horizontal bar with a leading navigation icon button, a title and trailing action icon buttons.
Definition app_bar.hpp:92
std::shared_ptr< Text > getTitle(void) const
Get the title child.
Definition app_bar.cpp:309
AppBar & setVariant(Variant variant)
Change the variant.
Definition app_bar.cpp:260
static std::shared_ptr< AppBar > create(Arguments &&...arguments)
Create an app bar and its children, without registering it in an entity registry.
Definition app_bar.hpp:262
std::shared_ptr< IconButton > getActionButton(std::size_t index) const
Get a trailing action button.
Definition app_bar.cpp:295
static constexpr float HorizontalPadding
Padding around the children and spacing between them, in dp (Paper: 4 dp).
Definition app_bar.hpp:343
bool isElevated(void) const
Whether the app bar uses the elevated look.
Definition app_bar.cpp:278
Variant getVariant(void) const
Get the variant.
Definition app_bar.cpp:317
components::AppBar::Action Action
Definition app_bar.hpp:100
AppBar & setElevated(bool elevated)
Choose the elevated look (Paper elevated). Restyles at once.
Definition app_bar.cpp:269
~AppBar(void) override
Default destructor.
Definition app_bar.cpp:185
std::shared_ptr< IconButton > getNavigationButton(void) const
Get the leading navigation button.
Definition app_bar.cpp:285
AppBar & setTitle(const std::string &title)
Change the title text.
Definition app_bar.cpp:324
components::AppBar::Variant Variant
Definition app_bar.hpp:96
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures, creates and registers IconButton widgets.
Base of the widgets that are a rectangle containing other widgets (Card, Dialog, Checkbox,...
Definition surface.hpp:243
static bool needsNavigationButton(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the navigation button child still has to be created.
Definition app_bar.cpp:165
static theme::TypeRole titleRole(components::AppBar::Variant variant)
Get the typescale role the title of a variant is drawn with.
Definition app_bar.cpp:150
static bool needsActionButtons(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the action button children have to be created again.
Definition app_bar.cpp:186
static void installTitle(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Expose the title child to assistive technology as a header.
Definition app_bar.cpp:113
static bool needsTitle(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the title child still has to be created.
Definition app_bar.cpp:176
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one app bar and arrange its children.
Definition app_bar.cpp:196
Makes the color helpers callable from guillaume::entities without qualification.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
std::shared_ptr< Text > buildText(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &content, float fontSize, const utility::graphic::Color32Bit &color)
Create a Text of a given font size as a child of a widget, or nothing when there is no content.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
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