guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
text_field.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#include <vector>
26
27#include "guillaume/entities/text_field.hpp"
28
29#include "guillaume/entities/builder_base.hpp"
30#include "guillaume/entities/content_helpers.hpp"
32#include "guillaume/systems/text_field.hpp"
33#include "guillaume/theme.hpp"
34
35namespace guillaume::entities
36{
38 ecs::EntityRegistry &entityRegistry)
39 : EntityBuilderBase<TextField>(componentRegistry, entityRegistry)
40 {
41 reset();
42 }
43
44 std::shared_ptr<TextField> TextField::Builder::buildEntity(void)
45 {
46 auto entity = TextField::create(
47 this->getComponentRegistry(), _config, _variant, _placeholder,
48 _leadingIcon, _trailingIcon, _supportingText, _error, _text);
49 return entity;
50 }
51
53 {
54 _config = SurfaceConfig();
55 _variant = Variant::Filled;
56 _placeholder.clear();
57 _leadingIcon.clear();
58 _trailingIcon.clear();
59 _supportingText.clear();
60 _error = false;
61 _text.clear();
62
64 _config.mainAxisAlignment =
66 _config.crossAxisAlignment =
68 _config.spacing = systems::TextField::Spacing;
69 _config.padding = systems::TextField::Padding;
70 _config.setFixedWidth(MinWidth);
71 _config.setFixedHeight(systems::TextField::Height);
72 }
73
75 TextField::Builder::withPose(const utility::graphic::PoseF &pose)
76 {
77 _config.pose = pose;
78 return *this;
79 }
80
82 {
83 _variant = variant;
84 return *this;
85 }
86
88 TextField::Builder::withPlaceholder(const std::string &placeholder)
89 {
90 _placeholder = placeholder;
91 return *this;
92 }
93
95 TextField::Builder::withLeadingIcon(const std::string &iconGlyph)
96 {
97 _leadingIcon = iconGlyph;
98 return *this;
99 }
100
102 TextField::Builder::withTrailingIcon(const std::string &iconGlyph)
103 {
104 _trailingIcon = iconGlyph;
105 return *this;
106 }
107
109 const std::string &supportingText)
110 {
111 _supportingText = supportingText;
112 return *this;
113 }
114
116 {
117 _error = error;
118 return *this;
119 }
120
122 {
123 _text = text;
124 return *this;
125 }
126
127 std::shared_ptr<TextField> TextField::Builder::makeTextField(
128 std::shared_ptr<ecs::Entity> parent, Variant variant,
129 const std::string &placeholder, const std::string &leadingIcon,
130 const std::string &trailingIcon, const std::string &supportingText,
131 bool error, const std::string &text)
132 {
133 return withVariant(variant)
134 .withPlaceholder(placeholder)
135 .withLeadingIcon(leadingIcon)
136 .withTrailingIcon(trailingIcon)
137 .withSupportingText(supportingText)
138 .withError(error)
139 .withText(text)
140 .registerEntity(parent);
141 }
142
143 TextField::TextField(ecs::ComponentRegistry &registry,
144 const SurfaceConfig &config, Variant variant,
145 const std::string &placeholder,
146 const std::string &leadingIcon,
147 const std::string &trailingIcon,
148 const std::string &supportingText, bool error,
149 const std::string &text)
150 : SurfaceBase<components::TextField, components::Line,
151 components::TextFieldConfiguration>(registry, config)
152 {
153 configuration()
154 .setVariant(variant)
155 .setLeadingIcon(leadingIcon)
156 .setTrailingIcon(trailingIcon)
157 .setText(text);
158 field()
159 .setPlaceholder(placeholder)
160 .setSupportingText(supportingText)
161 .setError(error);
164 }
165
167 {
168 }
169
170 components::TextFieldConfiguration &TextField::configuration(void)
171 {
172 return getComponentRegistry()
174 }
175
177 TextField::configuration(void) const
178 {
179 return getComponentRegistry()
181 }
182
183 components::TextField &TextField::field(void)
184 {
186 getIdentifier());
187 }
188
189 void TextField::refresh(void)
190 {
191 buildContent();
193 }
194
200
206
212
213 TextField &TextField::setVariant(Variant variant)
214 {
215 configuration().setVariant(variant);
216 refresh();
217 return *this;
218 }
219
221 {
222 return configuration().getVariant();
223 }
224
225 TextField &TextField::setPlaceholder(const std::string &placeholder)
226 {
227 field().setPlaceholder(placeholder);
228 refresh();
229 return *this;
230 }
231
232 TextField &TextField::setText(const std::string &text)
233 {
235 text);
236 return *this;
237 }
238
239 std::string TextField::getText(void) const
240 {
242 getIdentifier());
243 }
244
245 TextField &TextField::setError(bool error)
246 {
247 field().setError(error);
248 refresh();
249 return *this;
250 }
251
252 bool TextField::isError(void) const
253 {
254 return getComponentRegistry()
256 .isError();
257 }
258
259 TextField &TextField::setErrorText(const std::string &errorText)
260 {
261 field().setErrorText(errorText);
262 refresh();
263 return *this;
264 }
265
266 TextField &TextField::setSupportingText(const std::string &supportingText)
267 {
268 field().setSupportingText(supportingText);
269 refresh();
270 return *this;
271 }
272
273 TextField &TextField::setPrefix(const std::string &prefix)
274 {
275 field().setPrefix(prefix);
276 refresh();
277 return *this;
278 }
279
280 TextField &TextField::setSuffix(const std::string &suffix)
281 {
282 field().setSuffix(suffix);
283 refresh();
284 return *this;
285 }
286
287 TextField &TextField::setDisabled(bool disabled)
288 {
290 disabled);
291 return *this;
292 }
293
294 TextField &TextField::setEditable(bool editable)
295 {
296 configuration().setEditable(editable);
298 return *this;
299 }
300
301 bool TextField::isEditable(void) const
302 {
303 return configuration().isEditable();
304 }
305
306 TextField &TextField::setDense(bool dense)
307 {
308 configuration().setDense(dense);
310 return *this;
311 }
312
313 bool TextField::isDense(void) const
314 {
315 return configuration().isDense();
316 }
317
318 TextField &TextField::setMultiline(bool multiline)
319 {
320 configuration().setMultiline(multiline);
322 return *this;
323 }
324
325 bool TextField::isMultiline(void) const
326 {
327 return configuration().isMultiline();
328 }
329
330 TextField &TextField::setWidth(float width)
331 {
332 // The component clamps the width to MinWidth.
333 configuration().setWidth(width);
335 return *this;
336 }
337
339 std::function<void(const std::string &)> onChange)
340 {
341 configuration().setOnChange(std::move(onChange));
342 return *this;
343 }
344
345 TextField &TextField::setOnFocus(std::function<void(void)> onFocus)
346 {
347 configuration().setOnFocus(std::move(onFocus));
348 return *this;
349 }
350
351 TextField &TextField::setOnBlur(std::function<void(void)> onBlur)
352 {
353 configuration().setOnBlur(std::move(onBlur));
354 return *this;
355 }
356
358 {
359 return configuration().getLabelEntity();
360 }
361
363 {
364 return configuration().getInputEntity();
365 }
366
368 {
369 return configuration().getSupportingEntity();
370 }
371
373 {
374 return configuration().getPrefixEntity();
375 }
376
378 {
379 return configuration().getSuffixEntity();
380 }
381
383 {
384 return configuration().getErrorIconEntity();
385 }
386
387 void TextField::build(void)
388 {
389 refresh();
390 }
391
392 void TextField::buildContent(void)
393 {
394 // Children need the owning handle as their parent.
395 if (weak_from_this().expired()) {
396 return;
397 }
398
399 auto &registry = getComponentRegistry();
400 auto &config = configuration();
401 const auto &state = field();
402 const auto self = shared_from_this();
403 const auto invalid = ecs::Entity::InvalidIdentifier;
404 const float iconSize = systems::TextField::IconSize;
405 // Starting colors only: systems::TextField owns the state colors.
406 const auto content = schemeColor(SchemeColorRole::OnSurface);
407 const auto variantColor =
408 schemeColor(SchemeColorRole::OnSurfaceVariant);
409 bool rowChanged = false;
410
411 if (config.getLeadingIconEntity() == invalid) {
412 const auto icon =
413 buildIcon(registry, *this, self, config.getLeadingIcon(),
414 iconSize, variantColor);
415 if (icon != nullptr) {
416 config.setLeadingIconEntity(icon->getIdentifier());
417 rowChanged = true;
418 }
419 }
420
421 if (config.getTrailingIconEntity() == invalid) {
422 const auto icon =
423 buildIcon(registry, *this, self, config.getTrailingIcon(),
424 iconSize, variantColor);
425 if (icon != nullptr) {
426 config.setTrailingIconEntity(icon->getIdentifier());
427 rowChanged = true;
428 }
429 }
430
431 if (config.getErrorIconEntity() == invalid) {
432 const auto icon =
433 buildIcon(registry, *this, self, "error", iconSize,
434 schemeColor(SchemeColorRole::Error));
435 if (icon != nullptr) {
436 config.setErrorIconEntity(icon->getIdentifier());
437 rowChanged = true;
438 }
439 }
440
441 auto column = getEntity<View>(config.getInputColumn());
442 if (column == nullptr) {
443 View::Builder builder(registry, *this);
444 column =
445 builder.makeDefaultView(self, utility::graphic::PoseF(), {});
446 column->setColor(transparentColor());
447 column->setAxis(components::Layout::Axis::Vertical);
448 column->setMainAxisAlignment(
450 column->setCrossAxisAlignment(
452 column->setPadding(0.0f);
453 column->setSpacing(0.0f);
454 config.setInputColumn(column->getIdentifier());
455 rowChanged = true;
456 }
457
458 if (config.getInputEntity() == invalid) {
459 // Built even when empty so the text-input systems can edit it.
460 Text::Builder builder(registry, *column);
461 const auto input = builder.makeText(
462 column, config.getText(), theme::TypeRole::BodyLarge, content);
463 input->setContent(config.getText());
464 config.setInputEntity(input->getIdentifier());
465 }
466
467 if (config.getLabelEntity() == invalid
468 && !state.getPlaceholder().empty()) {
469 Text::Builder builder(registry, *column);
470 const auto label =
471 builder.makeText(column, state.getPlaceholder(),
472 theme::TypeRole::BodyLarge, variantColor);
473 label->setContent(state.getPlaceholder());
474 config.setLabelEntity(label->getIdentifier());
475 }
476
477 if (config.getPrefixEntity() == invalid) {
478 const auto prefix =
479 buildText(registry, *this, self, state.getPrefix(),
480 theme::TypeRole::BodyLarge, variantColor);
481 if (prefix != nullptr) {
482 config.setPrefixEntity(prefix->getIdentifier());
483 rowChanged = true;
484 }
485 }
486
487 if (config.getSuffixEntity() == invalid) {
488 const auto suffix =
489 buildText(registry, *this, self, state.getSuffix(),
490 theme::TypeRole::BodyLarge, variantColor);
491 if (suffix != nullptr) {
492 config.setSuffixEntity(suffix->getIdentifier());
493 rowChanged = true;
494 }
495 }
496
497 // The supporting text is placed by systems::TextField, outside the
498 // row.
499 if (config.getSupportingEntity() == invalid) {
500 const auto supporting = buildText(
501 registry, *this, self,
503 theme::TypeRole::BodySmall, variantColor);
504 if (supporting != nullptr) {
505 config.setSupportingEntity(supporting->getIdentifier());
506 }
507 }
508
509 if (!rowChanged) {
510 return;
511 }
512
513 // Every row child is attached; systems::TextField then narrows the
514 // layout children to the ones currently shown.
515 std::vector<std::shared_ptr<ecs::Entity>> children;
516 if (auto icon = getEntity<Icon>(config.getLeadingIconEntity())) {
517 children.push_back(std::move(icon));
518 }
519 if (auto prefix = getEntity<Text>(config.getPrefixEntity())) {
520 children.push_back(std::move(prefix));
521 }
522 children.push_back(column);
523 if (auto suffix = getEntity<Text>(config.getSuffixEntity())) {
524 children.push_back(std::move(suffix));
525 }
526 if (auto icon = getEntity<Icon>(config.getErrorIconEntity())) {
527 children.push_back(std::move(icon));
528 }
529 if (auto icon = getEntity<Icon>(config.getTrailingIconEntity())) {
530 children.push_back(std::move(icon));
531 }
532 setChildren(children);
533 }
534
535} // namespace guillaume::entities
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
State of a text field widget that is not text around the input: its variant, icons,...
The texts around the input of a text field, and its error state: placeholder, label,...
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
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
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures a TextField, then builds it and registers it in the entity registry given at construction.
Builder & withText(const std::string &text)
Set the text the field holds when created.
Builder & withLeadingIcon(const std::string &iconGlyph)
Set the icon shown at the start of the box.
Builder & withError(bool error)
Choose whether the field starts in the error state.
void reset(void) override
Restore the defaults: Filled variant, no label, no icon, no supporting text, no error,...
Builder & withTrailingIcon(const std::string &iconGlyph)
Set the icon shown at the end of the box.
Builder & withPose(const utility::graphic::PoseF &pose)
Set the pose the field is created with.
std::shared_ptr< TextField > makeTextField(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::string &placeholder, const std::string &leadingIcon, const std::string &trailingIcon, const std::string &supportingText, bool error, const std::string &text="")
Build a text field, register it under parent and reset the builder.
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Builder & withPlaceholder(const std::string &placeholder)
Set the label.
Builder & withVariant(Variant variant)
Set the field variant.
std::shared_ptr< TextField > buildEntity(void) override
Build a text field and its children from the current configuration, without registering it or setting...
Builder & withSupportingText(const std::string &supportingText)
Set the helper text shown under the box.
static std::shared_ptr< TextField > create(Arguments &&...arguments)
Create a text field and its children, without registering it in an entity registry.
ecs::Entity::Identifier getSupportingIdentifier(void) const
Get the identifier of the child that shows the supporting or error text under the box.
TextField & setSupportingText(const std::string &supportingText)
Set the helper text shown under the box.
TextField & setSuffix(const std::string &suffix)
Set the text shown just after the typed text, such as a unit.
TextField & setErrorText(const std::string &errorText)
Set the text shown under the box in the error state.
~TextField(void) override
Default destructor.
bool isError(void) const
Check whether the field is in the error state.
TextField & setText(const std::string &text)
Replace the typed text. Restyles at once.
TextField & setDisabled(bool disabled)
Enable or disable the field.
bool isMultiline(void) const
Check whether the height follows the content.
TextField & setOnFocus(std::function< void(void)> onFocus)
Set the handler called when the field gains the focus.
bool isFocused(void) const
Check whether the field has the keyboard focus.
bool isEditable(void) const
Check whether the user may edit the text.
TextField & setOnChange(std::function< void(const std::string &)> onChange)
Set the handler called when the user edits the text (Paper onChangeText).
ecs::Entity::Identifier getPrefixIdentifier(void) const
Get the identifier of the prefix child.
ecs::Entity::Identifier getInputIdentifier(void) const
Get the identifier of the child that holds the typed text.
TextField & setError(bool error)
Put the field in or out of the error state.
std::string getText(void) const
Get the typed text.
TextField & setOnBlur(std::function< void(void)> onBlur)
Set the handler called when the field loses the focus.
bool isDisabled(void) const
Check whether the field is disabled.
Variant getVariant(void) const
Get the field variant.
static constexpr float MinWidth
Smallest width of the box, in dp (100).
TextField & setDense(bool dense)
Use the smaller, dense height (Paper dense).
TextField & setVariant(Variant variant)
Change the field variant. Restyles at once.
components::TextFieldConfiguration::Variant Variant
Look of the field: Filled or Outlined.
TextField & setPlaceholder(const std::string &placeholder)
Change the label text.
TextField & setWidth(float width)
Fix the width of the box instead of letting it follow the content. Restyles at once.
ecs::Entity::Identifier getErrorIconIdentifier(void) const
Get the identifier of the "error" icon shown in the error state.
TextField & setPrefix(const std::string &prefix)
Set the text shown just before the typed text, such as a currency sign.
bool isLabelFloating(void) const
Check whether the label floats above the typed text.
ecs::Entity::Identifier getLabelIdentifier(void) const
Get the identifier of the label child.
ecs::Entity::Identifier getSuffixIdentifier(void) const
Get the identifier of the suffix child.
TextField & setEditable(bool editable)
Allow or forbid typing in the field (Paper editable).
TextField & setMultiline(bool multiline)
Let the height of the box follow its content instead of being fixed (Paper multiline)....
bool isDense(void) const
Check whether the field uses the dense height.
static constexpr float Height
Height of a single-line field that is not dense, in dp.
static bool isFocused(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the field has the input focus.
static constexpr float Padding
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make an entity focusable and hoverable as a text field.
static std::string text(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the text the field holds.
static void setDisabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool disabled)
Enable or disable the field and restyle it.
static constexpr float IconSize
static bool isDisabled(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the field ignores input.
static void setText(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const std::string &text)
Replace the text from code and restyle the field.
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Report an edit, then style one text field and arrange its children.
static constexpr float Spacing
Gap between the icons, the affixes and the input: 12 dp.
static bool isLabelFloating(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the label is in its floating position.
static std::string supportingText(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the text shown below the field.
Makes the color helpers callable from guillaume::entities without qualification.
State. Every class here is plain data attached to an entity.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
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.
std::shared_ptr< Icon > buildIcon(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &glyphName, float fontSize, const utility::graphic::Color32Bit &color, components::Glyph::Style style=components::Glyph::Style::Outlined)
Create an Icon as a child of a widget, or nothing when there is no glyph to show.
@ BodyLarge
16 / 24, regular.
Definition typescale.hpp:60
@ BodySmall
12 / 16, regular.
Definition typescale.hpp:62
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