|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
Styles a text field, arranges its label, input, affixes, icons and supporting text, and reports what the user typed. More...
#include <headers/guillaume/systems/text_field.hpp>


Public Member Functions | |
| TextField (void) | |
| Create the system in the Layout phase. | |
| ~TextField (void) override=default | |
| Default destructor. | |
| void | update (const ecs::Entity::Identifier &entityIdentifier) override |
| Update one entity that has a components::TextField; called by the frame loop. | |
| Public Member Functions inherited from guillaume::ecs::SystemFiller< components::TextField > | |
| SystemFiller (Phase phase) | |
| Create the system and set its signature from ComponentTypes. | |
| virtual | ~SystemFiller (void)=default |
| Virtual destructor. | |
| Public Member Functions inherited from guillaume::ecs::System | |
| System (Phase phase) | |
| Create a system that runs in a given phase, with an empty signature. | |
| virtual | ~System (void)=default |
| Virtual destructor. | |
| Phase | getPhase (void) const noexcept |
| Get the phase of the frame in which the system runs. | |
| Entity::Signature | getSignature (void) const noexcept |
| Get the component types an entity must declare to be visited by this system. | |
| void | routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler) |
| Run the system once over a scene: prepare(), update() on each matching entity, cleanup(). | |
| void | bindComponentRegistry (ecs::ComponentRegistry &componentRegistry) |
| Bind a component registry so update() can be called directly, without routine(). | |
| void | unbindComponentRegistry (void) |
| Drop the binding made by bindComponentRegistry(). | |
| virtual void | prepare (void) |
| Called once per pass, before the first update(). | |
| virtual void | cleanup (void) |
| Called once per pass, after the last update(). | |
Static Public Member Functions | |
| static void | install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Make an entity focusable and hoverable as a text 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 void | applyContainer (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Style the container only, leaving the children alone. | |
| static void | applyEditing (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Let the input child receive typed text only while the field is being edited. | |
| static bool | isFocused (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Whether the field has the input focus. | |
| static bool | isDisabled (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Whether the field ignores input. | |
| static bool | isLabelFloating (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Whether the label is in its floating position. | |
| static std::string | text (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Get the text the field holds. | |
| 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 | setDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool disabled) |
| Enable or disable the field and restyle it. | |
| static std::string | supportingText (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier) |
| Get the text shown below the field. | |
| static bool | reconcile (components::TextField &textField, bool hasContent) |
| Derive the label-floating flag of a field that has no configuration, and store it. | |
Static Public Attributes | |
| static constexpr float | Height = 56.0f |
| Height of a single-line field that is not dense, in dp. | |
| static constexpr float | DenseLabelHeight = 52.0f |
| Height of a dense single-line field that has a label, in dp. | |
| static constexpr float | DenseHeight = 40.0f |
| Height of a dense single-line field without a label, in dp. | |
| static constexpr float | Padding = theme::SpacingScale::get(4) |
| static constexpr float | Spacing = theme::SpacingScale::get(3) |
| Gap between the icons, the affixes and the input: 12 dp. | |
| static constexpr float | SupportingGap = theme::SpacingScale::get(1) |
| static constexpr float | IconSize = 24.0f |
Additional Inherited Members | |
| Protected Member Functions inherited from guillaume::ecs::System | |
| template<InheritFromComponent... ComponentTypes> | |
| void | setSignature (void) |
| Replace the signature by the one made of the given component types. | |
| ecs::EntityRegistry & | getEntityRegistry (void) |
| Get the entity registry of the scene being processed. | |
| const ecs::EntityRegistry & | getEntityRegistry (void) const |
| Get the entity registry of the scene being processed, read-only. | |
| ecs::ComponentRegistry & | getComponentRegistry (void) |
| Get the component registry of the scene being processed. | |
| const ecs::ComponentRegistry & | getComponentRegistry (void) const |
| Get the component registry of the scene being processed, read-only. | |
| template<InheritFromComponent ComponentType> | |
| bool | hasComponent (const ecs::Entity::Identifier &entityIdentifier) const |
| Tell whether an entity has a component, in the bound registry. | |
| template<InheritFromComponent ComponentType> | |
| ComponentType & | getComponent (const ecs::Entity::Identifier &entityIdentifier) |
| Get a component of an entity from the bound registry, to read or modify it. | |
| template<InheritFromComponent ComponentType> | |
| const ComponentType & | getComponent (const ecs::Entity::Identifier &entityIdentifier) const |
| Get a component of an entity from the bound registry, read-only. | |
| template<InheritFromComponent ComponentType> | |
| bool | requireComponent (const ecs::Entity::Identifier &entityIdentifier) |
| Tell whether an entity has a component, and log a warning naming the entity and the component when it does not. | |
Styles a text field, arranges its label, input, affixes, icons and supporting text, and reports what the user typed.
Runs in the Layout phase on every entity that has a components::TextField. It is registered after systems::Layout and after systems::Search, so the children are already measured and a search field has already written its components::TextField.
What it does depends on the other components of the entity:
With a components::TextFieldConfiguration (the text field widget), it runs apply():
With only its own components::Text, it keeps the label-floating flag of components::TextField in step with the content, through reconcile(). An entity with neither is left alone.
The label "floats" (moves up and shrinks) while the field is focused or holds text; it rests in place of the input otherwise. The prefix and suffix show only while it floats. In the error state the error icon replaces the trailing icon and the error text replaces the supporting text.
The text typed by the user lives in the components::Text of the input child. The change callback is called from apply() when that text differs from the last one recorded, so an edit is reported on the frame after it was typed.
Definition at line 83 of file text_field.hpp.
| guillaume::systems::TextField::TextField | ( | void | ) |
Create the system in the Layout phase.
Definition at line 352 of file text_field.cpp.


|
static |
Report an edit, then style one text field and arrange its children.
This is what update() runs each frame on a text field widget. Call it directly after changing components::TextField or components::TextFieldConfiguration to see the result before the next frame, which is what the setters of entities::TextField do.
In order: calls the change callback when the input text differs from the last one recorded; styles the container (applyContainer()); writes the content, type role and color of the children; records and places the layout children; places the supporting text under the field and, for the outlined variant, the floating label on the outline; updates the editing focus (applyEditing()).
The field is as wide as its content plus padding, or as the width forced in the configuration, and never narrower than components::TextFieldConfiguration::MinWidth.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
| ecs::EntityComponentNotFoundException | When the entity lacks components::TextFieldConfiguration, TextField, Layout, Color, Borders, Line or Bound. |
Definition at line 562 of file text_field.cpp.


|
static |
Style the container only, leaving the children alone.
Writes the row configuration and height of components::Layout and the look of the variant: an outlined field has a transparent fill and a stroke around it; a filled field has a tinted fill and an active indicator line at the bottom. The stroke or indicator is 2 dp thick while the field is focused and enabled, 1 dp otherwise, and takes the error, primary or disabled color of its state. A multiline field has no fixed height. This is the cheap restyle run on a hover or press change.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 467 of file text_field.cpp.


|
static |
Let the input child receive typed text only while the field is being edited.
Adds a components::Focus to the input child while the field is editable, enabled and focused, and removes it otherwise. The text input system only writes to entities that have that component. Does nothing when no input child is recorded.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 538 of file text_field.cpp.


|
static |
Make an entity focusable and hoverable as a text field.
Adds the interaction components (hover and press state, focus, style state, the TextField accessibility role), restyles the container with applyContainer() on a hover or press change, and makes gaining and losing the focus call the focus and blur callbacks of components::TextFieldConfiguration. Call it once, after the entity has its components::TextField, TextFieldConfiguration, Line, Layout, Transform, Bound, Color and Borders.
| componentRegistry | The registry holding the components. It is captured by the handlers and must outlive the entity. |
| entityIdentifier | The text field entity. |
Definition at line 357 of file text_field.cpp.

|
static |
Whether the field ignores input.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 405 of file text_field.cpp.

|
static |
Whether the field has the input focus.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 389 of file text_field.cpp.


|
static |
Whether the label is in its floating position.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 411 of file text_field.cpp.


|
static |
Derive the label-floating flag of a field that has no configuration, and store it.
The label floats when the field has content or is in the error state. Focus is not taken into account here, unlike isLabelFloating(). systems::Search uses it for the field it drives.
| textField | The component to update. |
| hasContent | True when the field currently holds text. |
Definition at line 612 of file text_field.cpp.


|
static |
Enable or disable the field and restyle it.
A disabled field is drawn dimmed and its input child cannot receive typed text.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
| disabled | True to disable the field, false to enable it. |
Definition at line 446 of file text_field.cpp.


|
static |
Replace the text from code and restyle the field.
The change callback is not called: it is reserved for edits made by the user.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
| text | The new text; an empty string lets the label rest again when the field is not focused. |
Definition at line 433 of file text_field.cpp.


|
static |
Get the text shown below the field.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 454 of file text_field.cpp.

|
static |
Get the text the field holds.
| componentRegistry | The registry holding the components. |
| entityIdentifier | The text field entity. |
Definition at line 419 of file text_field.cpp.


|
overridevirtual |
Update one entity that has a components::TextField; called by the frame loop.
Runs apply() when the entity also has a components::TextFieldConfiguration. Otherwise, when it has its own components::Text, calls reconcile() with whether that text is empty. Logs a warning and does nothing when the entity has no components::TextField.
| entityIdentifier | The entity to update. |
Implements guillaume::ecs::System.
Definition at line 589 of file text_field.cpp.

|
staticconstexpr |
Height of a dense single-line field without a label, in dp.
Definition at line 93 of file text_field.hpp.
|
staticconstexpr |
Height of a dense single-line field that has a label, in dp.
Definition at line 90 of file text_field.hpp.
|
staticconstexpr |
Height of a single-line field that is not dense, in dp.
Definition at line 87 of file text_field.hpp.
|
staticconstexpr |
Width assumed for the leading icon when the outlined floating label is placed after it, in dp.
Definition at line 108 of file text_field.hpp.
|
staticconstexpr |
Space between the left and right edges of the field and its content: 16 dp.
Definition at line 97 of file text_field.hpp.
|
staticconstexpr |
Gap between the icons, the affixes and the input: 12 dp.
Definition at line 100 of file text_field.hpp.
|
staticconstexpr |
Gap between the bottom of the field and the supporting text: 4 dp.
Definition at line 104 of file text_field.hpp.