guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
text_field.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 <functional>
27#include <memory>
28#include <string>
29
30#include <utility/graphic/color.hpp>
31#include <utility/graphic/pose.hpp>
32
33#include "guillaume/ecs/component_registry.hpp"
34#include "guillaume/ecs/entity_builder.hpp"
35
36#include "guillaume/components/line.hpp"
37#include "guillaume/components/text_field.hpp"
38#include "guillaume/components/text_field_configuration.hpp"
39
40#include "guillaume/entities/builder_base.hpp"
41#include "guillaume/entities/icon.hpp"
42#include "guillaume/entities/surface.hpp"
43#include "guillaume/entities/text.hpp"
44#include "guillaume/entities/view.hpp"
45
46namespace guillaume::entities
47{
48
116 class TextField:
117 public SurfaceBase<components::TextField, components::Line,
118 components::TextFieldConfiguration>
119 {
120 public:
123
127 static constexpr float MinWidth =
129
134 class Builder: public EntityBuilderBase<TextField>
135 {
136 private:
137 SurfaceConfig _config;
138 Variant _variant { Variant::Filled };
139 std::string _placeholder {};
140 std::string _leadingIcon {};
141 std::string _trailingIcon {};
142 std::string _supportingText {};
143 bool _error { false };
144 std::string _text {};
145
146 public:
154 Builder(ecs::ComponentRegistry &componentRegistry,
155 ecs::EntityRegistry &entityRegistry);
156
162 std::shared_ptr<TextField> buildEntity(void) override;
163
169 void reset(void) override;
170
177 Builder &withPose(const utility::graphic::PoseF &pose);
178
184 Builder &withVariant(Variant variant);
185
195 Builder &withPlaceholder(const std::string &placeholder);
196
202 Builder &withLeadingIcon(const std::string &iconGlyph);
203
210 Builder &withTrailingIcon(const std::string &iconGlyph);
211
217 Builder &withSupportingText(const std::string &supportingText);
218
224 Builder &withError(bool error);
225
231 Builder &withText(const std::string &text);
232
251 std::shared_ptr<TextField>
252 makeTextField(std::shared_ptr<ecs::Entity> parent,
253 Variant variant, const std::string &placeholder,
254 const std::string &leadingIcon,
255 const std::string &trailingIcon,
256 const std::string &supportingText, bool error,
257 const std::string &text = "");
258 };
259
273 template<typename... Arguments>
274 static std::shared_ptr<TextField> create(Arguments &&...arguments)
275 {
276 std::shared_ptr<TextField> entity(
277 new TextField(std::forward<Arguments>(arguments)...));
278 entity->build();
279 return entity;
280 }
281
285 ~TextField(void) override;
286
292 TextField &setVariant(Variant variant);
293
298 Variant getVariant(void) const;
299
308 TextField &setPlaceholder(const std::string &placeholder);
309
317 TextField &setText(const std::string &text);
318
324 std::string getText(void) const;
325
336 TextField &setError(bool error);
337
342 bool isError(void) const;
343
353 TextField &setErrorText(const std::string &errorText);
354
363 TextField &setSupportingText(const std::string &supportingText);
364
374 TextField &setPrefix(const std::string &prefix);
375
385 TextField &setSuffix(const std::string &suffix);
386
395 TextField &setDisabled(bool disabled);
396
401 bool isDisabled(void) const;
402
412 TextField &setEditable(bool editable);
413
418 bool isEditable(void) const;
419
428 TextField &setDense(bool dense);
429
434 bool isDense(void) const;
435
442 TextField &setMultiline(bool multiline);
443
448 bool isMultiline(void) const;
449
457 TextField &setWidth(float width);
458
463 bool isLabelFloating(void) const;
464
469 bool isFocused(void) const;
470
482 TextField &
483 setOnChange(std::function<void(const std::string &)> onChange);
484
490 TextField &setOnFocus(std::function<void(void)> onFocus);
491
497 TextField &setOnBlur(std::function<void(void)> onBlur);
498
505
513
521
528
535
546
547 private:
553 void buildContent(void);
554
559 components::TextFieldConfiguration &configuration(void);
560
565 const components::TextFieldConfiguration &configuration(void) const;
566
571 components::TextField &field(void);
572
577 void refresh(void);
578
579 private:
592 TextField(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
593 Variant variant, const std::string &placeholder,
594 const std::string &leadingIcon,
595 const std::string &trailingIcon,
596 const std::string &supportingText, bool error,
597 const std::string &text);
598
605 void build(void);
606 };
607
608} // namespace guillaume::entities
State of a text field widget that is not text around the input: its variant, icons,...
static constexpr float MinWidth
Smallest width of a text field, in dp.
Variant
Look of the field: Filled has a tinted background and a line under it; Outlined has a border the labe...
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...
Owns entities and gives the systems the list of entities to visit.
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
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
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.
A box the user types text into, with a label, optional icons, prefix and suffix, and a helper or erro...
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.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
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