|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
A box the user types text into, with a label, optional icons, prefix and suffix, and a helper or error text under it (Paper TextInput and HelperText). More...
#include <headers/guillaume/entities/text_field.hpp>


Classes | |
| class | Builder |
| Configures a TextField, then builds it and registers it in the entity registry given at construction. More... | |
Public Types | |
| using | Variant = components::TextFieldConfiguration::Variant |
| Look of the field: Filled or Outlined. | |
| Public Types inherited from guillaume::entities::SurfaceBase< components::TextField, components::Line, components::TextFieldConfiguration > | |
| using | Children |
| Public Types inherited from guillaume::ecs::Entity | |
| using | Identifier = std::size_t |
| The key under which an entity's components are stored. Systems and components refer to entities by this value. | |
| using | Signature = std::bitset<128> |
| A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits). | |
Public Member Functions | |
| ~TextField (void) override | |
| Default destructor. | |
| TextField & | setVariant (Variant variant) |
| Change the field variant. Restyles at once. | |
| Variant | getVariant (void) const |
| Get the field variant. | |
| TextField & | setPlaceholder (const std::string &placeholder) |
| Change the label text. | |
| TextField & | setText (const std::string &text) |
| Replace the typed text. Restyles at once. | |
| std::string | getText (void) const |
| Get the typed text. | |
| TextField & | setError (bool error) |
| Put the field in or out of the error state. | |
| bool | isError (void) const |
| Check whether the field is in the error state. | |
| TextField & | setErrorText (const std::string &errorText) |
| Set the text shown under the box in the error state. | |
| TextField & | setSupportingText (const std::string &supportingText) |
| Set the helper text shown under the box. | |
| TextField & | setPrefix (const std::string &prefix) |
| Set the text shown just before the typed text, such as a currency sign. | |
| TextField & | setSuffix (const std::string &suffix) |
| Set the text shown just after the typed text, such as a unit. | |
| TextField & | setDisabled (bool disabled) |
| Enable or disable the field. | |
| bool | isDisabled (void) const |
| Check whether the field is disabled. | |
| TextField & | setEditable (bool editable) |
| Allow or forbid typing in the field (Paper editable). | |
| bool | isEditable (void) const |
| Check whether the user may edit the text. | |
| TextField & | setDense (bool dense) |
| Use the smaller, dense height (Paper dense). | |
| bool | isDense (void) const |
| Check whether the field uses the dense height. | |
| TextField & | setMultiline (bool multiline) |
| Let the height of the box follow its content instead of being fixed (Paper multiline). Restyles at once. | |
| bool | isMultiline (void) const |
| Check whether the height follows the content. | |
| TextField & | setWidth (float width) |
| Fix the width of the box instead of letting it follow the content. Restyles at once. | |
| bool | isLabelFloating (void) const |
| Check whether the label floats above the typed text. | |
| bool | isFocused (void) const |
| Check whether the field has the keyboard focus. | |
| TextField & | setOnChange (std::function< void(const std::string &)> onChange) |
| Set the handler called when the user edits the text (Paper onChangeText). | |
| TextField & | setOnFocus (std::function< void(void)> onFocus) |
| Set the handler called when the field gains the focus. | |
| TextField & | setOnBlur (std::function< void(void)> onBlur) |
| Set the handler called when the field loses the focus. | |
| ecs::Entity::Identifier | getLabelIdentifier (void) const |
| Get the identifier of the label child. | |
| ecs::Entity::Identifier | getInputIdentifier (void) const |
| Get the identifier of the child that holds the typed text. | |
| ecs::Entity::Identifier | getSupportingIdentifier (void) const |
| Get the identifier of the child that shows the supporting or error text under the box. | |
| ecs::Entity::Identifier | getPrefixIdentifier (void) const |
| Get the identifier of the prefix child. | |
| ecs::Entity::Identifier | getSuffixIdentifier (void) const |
| Get the identifier of the suffix child. | |
| ecs::Entity::Identifier | getErrorIconIdentifier (void) const |
| Get the identifier of the "error" icon shown in the error state. | |
| Public Member Functions inherited from guillaume::entities::SurfaceBase< components::TextField, components::Line, components::TextFieldConfiguration > | |
| ~SurfaceBase (void) override=default | |
| Default destructor. | |
| SurfaceBase & | setPose (const utility::graphic::PoseF &pose) |
| Move the surface. | |
| SurfaceBase & | setColor (const utility::graphic::Color32Bit &color) |
| Set the fill color (Color component). | |
| 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. | |
| SurfaceConfig | getSurfaceConfig (void) const |
| Read the current configuration back from the components. | |
| 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. | |
| Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... > | |
| ParentEntityFiller (ComponentRegistry &componentRegistry) | |
| Create the entity, its listed components and its components::Hierarchy. It owns no child yet. | |
| virtual | ~ParentEntityFiller (void)=default |
| Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity). | |
| Public Member Functions inherited from guillaume::ecs::Entity | |
| Entity (void) | |
| Create an entity with a fresh identifier, an empty signature, no parent and no component. | |
| virtual | ~Entity (void)=default |
| Destroy the entity object. | |
| Entity::Identifier | getIdentifier (void) const noexcept |
| Get the identifier of the entity. | |
| Entity::Signature | getSignature (void) const noexcept |
| Get the set of component types the entity declares. | |
| void | setSignature (const Signature &signature) |
| Replace the signature of the entity. | |
| std::int32_t | getLayer (void) const noexcept |
| Get the depth of the entity in the tree. | |
| Entity & | setParent (std::shared_ptr< Entity > parent) |
| Attach the entity under another one, or detach it. | |
| std::vector< Identifier > | releaseComponents (void) |
| Drop the entity's place in the tree and all its components. | |
| std::shared_ptr< Entity > | getParent (void) const noexcept |
| Get the parent entity. | |
| Public Member Functions inherited from guillaume::ecs::EntityRegistry | |
| EntityRegistry (void)=default | |
| Create a registry. | |
| virtual | ~EntityRegistry (void)=default |
| Virtual destructor. | |
| void | addEntity (std::shared_ptr< Entity > entity) |
| Make this registry own an entity, so that it stays alive and systems visit it. | |
| bool | removeEntity (Entity::Identifier identifier) |
| Remove an entity, with its children and all their components. | |
| void | clearEntities (void) |
| Remove every entity owned by this registry, with everything they own and all their components. | |
| const std::vector< std::shared_ptr< Entity > > & | getEntities (void) const |
| Get the entities this registry owns directly. | |
| std::vector< std::shared_ptr< Entity > > | getEntitiesBreadthFirst (void) |
| List every entity of this registry and of the registries nested in it, level by level. | |
| std::vector< std::shared_ptr< Entity > > | getEntitiesBreadthFirst (void) const |
| List every entity of this registry and of the registries nested in it, level by level (const overload). | |
| template<InheritFromEntity EntityType> | |
| std::shared_ptr< EntityType > | getEntity (Entity::Identifier identifier) |
| Find an entity owned directly by this registry, by identifier. | |
| template<InheritFromEntity EntityType> | |
| std::shared_ptr< const EntityType > | getEntity (Entity::Identifier identifier) const |
| Find an entity owned directly by this registry, by identifier (const overload). | |
| std::vector< Entity::Identifier > | getEntityWithSignature (Entity::Signature systemSignature) const |
| List the entities that have every component type of a signature, from the root down. | |
| std::vector< Entity::Identifier > | getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const |
| List the entities that have every component type of a signature, in the order chosen by a traveler. | |
Static Public Member Functions | |
| template<typename... Arguments> | |
| static std::shared_ptr< TextField > | create (Arguments &&...arguments) |
| Create a text field and its children, without registering it in an entity registry. | |
| Static Public Member Functions inherited from guillaume::ecs::Entity | |
| template<InheritFromComponent... ComponentTypes> | |
| static Signature | getSignatureFromTypes (void) |
| Build the signature that has exactly the bits of the given component types. | |
Static Public Attributes | |
| static constexpr float | MinWidth |
| Smallest width of the box, in dp (100). | |
| Static Public Attributes inherited from guillaume::ecs::Entity | |
| static constexpr Identifier | InvalidIdentifier |
| "No entity": never the identifier of a real entity | |
Additional Inherited Members | |
| Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::TextField, components::Line, components::TextFieldConfiguration > | |
| SurfaceBase (ecs::ComponentRegistry ®istry, const SurfaceConfig &config) | |
| Create the entity with its components and apply a configuration. | |
| void | applyGeometry (void) |
| Arrange the layout children now with systems::Layout::apply. | |
| Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... > | |
| ComponentRegistry & | getComponentRegistry (void) |
| Get the registry that stores this entity's components. | |
| Protected Member Functions inherited from guillaume::ecs::ParentEntity | |
| std::vector< std::shared_ptr< Entity > > & | accessDirectEntities (void) override |
| Give access to the list of entities this entity owns directly. | |
| const std::vector< std::shared_ptr< Entity > > & | accessDirectEntities (void) const override |
| Give read access to the list of entities this entity owns directly. | |
| Protected Member Functions inherited from guillaume::ecs::Entity | |
| void | attachHierarchy (ComponentRegistry &componentRegistry) |
| Give the entity a components::Hierarchy in a registry and add that component to its signature. | |
| template<InheritFromComponent... ComponentTypes> | |
| void | setSignature (void) |
| Replace the signature by the one made of the given component types. | |
A box the user types text into, with a label, optional icons, prefix and suffix, and a helper or error text under it (Paper TextInput and HelperText).
Its state lives in two components: components::TextField holds the label, prefix, suffix, supporting text, error text and error state; components::TextFieldConfiguration holds the variant, the flags, the callbacks and the identifiers of the children. systems::TextField styles the box, arranges its children and reports edits each frame, in the Layout phase. The class itself holds no field: its setters write the components and restyle at once.
TextField::create(registry, config, variant, placeholder, leadingIcon, trailingIcon, supportingText, error, text) builds the same widget without registering it in an entity registry.
On screen, from start to end: the leading icon, the prefix, the input column (label and typed text), the suffix, then the trailing icon, which the "error" icon replaces in the error state. The supporting text, or the error text in the error state when there is one, is drawn under the box.
The label sits in the place of the typed text while the field is empty and unfocused. While the field is focused or holds text the label floats: it becomes smaller and moves above the text (Filled) or onto the top border (Outlined). The prefix and suffix only show while the label floats.
The variants are:
The bottom line or the border is 2 dp thick and in the primary color while the field is focused, 1 dp otherwise, and in the error color in the error state.
Things to know:
Definition at line 116 of file text_field.hpp.
Look of the field: Filled or Outlined.
Definition at line 122 of file text_field.hpp.
|
override |
Default destructor.
Definition at line 166 of file text_field.cpp.
|
inlinestatic |
Create a text field and its children, without registering it in an entity registry.
The arguments are forwarded to the private constructor: (registry, config, variant, placeholder, leadingIcon, trailingIcon, supportingText, error, text). The children are built here, by build(), because a child needs its parent to be owned by a shared pointer.
| Arguments | The constructor argument types. |
| arguments | The constructor arguments, as listed above. |
Definition at line 274 of file text_field.hpp.

| ecs::Entity::Identifier guillaume::entities::TextField::getErrorIconIdentifier | ( | void | ) | const |
Get the identifier of the "error" icon shown in the error state.
The icon exists outside the error state too, painted transparent.
Definition at line 382 of file text_field.cpp.
| ecs::Entity::Identifier guillaume::entities::TextField::getInputIdentifier | ( | void | ) | const |
Get the identifier of the child that holds the typed text.
Definition at line 362 of file text_field.cpp.
| ecs::Entity::Identifier guillaume::entities::TextField::getLabelIdentifier | ( | void | ) | const |
Get the identifier of the label child.
Definition at line 357 of file text_field.cpp.
| ecs::Entity::Identifier guillaume::entities::TextField::getPrefixIdentifier | ( | void | ) | const |
Get the identifier of the prefix child.
Definition at line 372 of file text_field.cpp.
| ecs::Entity::Identifier guillaume::entities::TextField::getSuffixIdentifier | ( | void | ) | const |
Get the identifier of the suffix child.
Definition at line 377 of file text_field.cpp.
| ecs::Entity::Identifier guillaume::entities::TextField::getSupportingIdentifier | ( | void | ) | const |
Get the identifier of the child that shows the supporting or error text under the box.
Definition at line 367 of file text_field.cpp.
| std::string guillaume::entities::TextField::getText | ( | void | ) | const |
Get the typed text.
Definition at line 239 of file text_field.cpp.

| TextField::Variant guillaume::entities::TextField::getVariant | ( | void | ) | const |
Get the field variant.
Definition at line 220 of file text_field.cpp.
| bool guillaume::entities::TextField::isDense | ( | void | ) | const |
Check whether the field uses the dense height.
Definition at line 313 of file text_field.cpp.
| bool guillaume::entities::TextField::isDisabled | ( | void | ) | const |
Check whether the field is disabled.
Definition at line 207 of file text_field.cpp.

| bool guillaume::entities::TextField::isEditable | ( | void | ) | const |
Check whether the user may edit the text.
Definition at line 301 of file text_field.cpp.
| bool guillaume::entities::TextField::isError | ( | void | ) | const |
Check whether the field is in the error state.
Definition at line 252 of file text_field.cpp.


| bool guillaume::entities::TextField::isFocused | ( | void | ) | const |
Check whether the field has the keyboard focus.
Definition at line 195 of file text_field.cpp.

| bool guillaume::entities::TextField::isLabelFloating | ( | void | ) | const |
Check whether the label floats above the typed text.
Definition at line 201 of file text_field.cpp.

| bool guillaume::entities::TextField::isMultiline | ( | void | ) | const |
Check whether the height follows the content.
Definition at line 325 of file text_field.cpp.
| TextField & guillaume::entities::TextField::setDense | ( | bool | dense | ) |
Use the smaller, dense height (Paper dense).
A dense box is 52 dp high with a label and 40 dp without, instead of 56 dp. Ignored while the field is multiline. Restyles at once.
| dense | True for the dense height. |
Definition at line 306 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setDisabled | ( | bool | disabled | ) |
Enable or disable the field.
A disabled field is drawn with the disabled colors and cannot be edited. Restyles at once.
| disabled | True to disable the field. |
Definition at line 287 of file text_field.cpp.

| TextField & guillaume::entities::TextField::setEditable | ( | bool | editable | ) |
Allow or forbid typing in the field (Paper editable).
A field that is not editable keeps its normal look and can still take the focus. Restyles at once.
| editable | True to let the user edit the text. Default: true. |
Definition at line 294 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setError | ( | bool | error | ) |
Put the field in or out of the error state.
In the error state the line or border and the text under the box take the error color, the "error" icon replaces the trailing icon, and the error text, when there is one, replaces the supporting text. Restyles at once.
| error | True for the error state. |
Definition at line 245 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setErrorText | ( | const std::string & | errorText | ) |
Set the text shown under the box in the error state.
Builds the child that shows it when missing, then restyles at once.
| errorText | The error text. When empty, the supporting text stays shown in the error state. |
Definition at line 259 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setMultiline | ( | bool | multiline | ) |
Let the height of the box follow its content instead of being fixed (Paper multiline). Restyles at once.
| multiline | True to let the height follow the content. |
Definition at line 318 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setOnBlur | ( | std::function< void(void)> | onBlur | ) |
Set the handler called when the field loses the focus.
| onBlur | The handler; an empty one removes it. |
Definition at line 351 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setOnChange | ( | std::function< void(const std::string &)> | onChange | ) |
Set the handler called when the user edits the text (Paper onChangeText).
systems::TextField calls it with the new text when it sees that the typed text differs from the one it knew. setText() does not call it.
| onChange | The handler, given the new text; an empty one removes it. |
Definition at line 338 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setOnFocus | ( | std::function< void(void)> | onFocus | ) |
Set the handler called when the field gains the focus.
| onFocus | The handler; an empty one removes it. |
Definition at line 345 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setPlaceholder | ( | const std::string & | placeholder | ) |
Change the label text.
Builds the label child when the field had none and placeholder is not empty, then restyles at once.
| placeholder | The new label text. |
Definition at line 225 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setPrefix | ( | const std::string & | prefix | ) |
Set the text shown just before the typed text, such as a currency sign.
It is visible only while the label floats. Builds the prefix child when missing, then restyles at once.
| prefix | The prefix text; empty shows none. |
Definition at line 273 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setSuffix | ( | const std::string & | suffix | ) |
Set the text shown just after the typed text, such as a unit.
It is visible only while the label floats. Builds the suffix child when missing, then restyles at once.
| suffix | The suffix text; empty shows none. |
Definition at line 280 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setSupportingText | ( | const std::string & | supportingText | ) |
Set the helper text shown under the box.
Builds the child that shows it when missing, then restyles at once.
| supportingText | The helper text; empty shows none. |
Definition at line 266 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setText | ( | const std::string & | text | ) |
Replace the typed text. Restyles at once.
Does not call the change handler: only an edit by the user does.
| text | The new text. |
Definition at line 232 of file text_field.cpp.

| TextField & guillaume::entities::TextField::setVariant | ( | Variant | variant | ) |
Change the field variant. Restyles at once.
| variant | The new variant, Filled or Outlined. |
Definition at line 213 of file text_field.cpp.


| TextField & guillaume::entities::TextField::setWidth | ( | float | width | ) |
Fix the width of the box instead of letting it follow the content. Restyles at once.
| width | The width, in dp. A value under MinWidth (100 dp) is raised to MinWidth. |
Definition at line 330 of file text_field.cpp.


|
staticconstexpr |
Smallest width of the box, in dp (100).
Definition at line 127 of file text_field.hpp.