guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::systems::TextField Class Reference

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>

Inheritance diagram for guillaume::systems::TextField:
Collaboration diagram for guillaume::systems::TextField:

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.

Detailed Description

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.

See also
components::TextField, components::TextFieldConfiguration, entities::TextField, systems::TextInput

Definition at line 83 of file text_field.hpp.

Constructor & Destructor Documentation

◆ TextField()

guillaume::systems::TextField::TextField ( void )

Create the system in the Layout phase.

Definition at line 352 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::TextField::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::TextFieldConfiguration, TextField, Layout, Color, Borders, Line or Bound.

Definition at line 562 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ applyContainer()

void guillaume::systems::TextField::applyContainer ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.

Definition at line 467 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ applyEditing()

void guillaume::systems::TextField::applyEditing ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.

Definition at line 538 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ install()

void guillaume::systems::TextField::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
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.

Parameters
componentRegistryThe registry holding the components. It is captured by the handlers and must outlive the entity.
entityIdentifierThe text field entity.

Definition at line 357 of file text_field.cpp.

Here is the call graph for this function:

◆ isDisabled()

bool guillaume::systems::TextField::isDisabled ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the field ignores input.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Returns
True when the entity has been disabled, see setDisabled().

Definition at line 405 of file text_field.cpp.

Here is the caller graph for this function:

◆ isFocused()

bool guillaume::systems::TextField::isFocused ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the field has the input focus.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Returns
True when its components::Focus or its components::StyleState reports the focused state; false when it has neither component.

Definition at line 389 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isLabelFloating()

bool guillaume::systems::TextField::isLabelFloating ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the label is in its floating position.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Returns
True while the field is focused or its text is not empty.

Definition at line 411 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reconcile()

bool guillaume::systems::TextField::reconcile ( components::TextField & textField,
bool hasContent )
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.

Parameters
textFieldThe component to update.
hasContentTrue when the field currently holds text.
Returns
The floating state that was stored.

Definition at line 612 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setDisabled()

void guillaume::systems::TextField::setDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool disabled )
static

Enable or disable the field and restyle it.

A disabled field is drawn dimmed and its input child cannot receive typed text.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
disabledTrue to disable the field, false to enable it.

Definition at line 446 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setText()

void guillaume::systems::TextField::setText ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
const std::string & text )
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.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
textThe 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.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ supportingText()

std::string guillaume::systems::TextField::supportingText ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the text shown below the field.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Returns
The error text of components::TextField when the field is in the error state and has one, its supporting text otherwise. Empty when there is nothing to show.

Definition at line 454 of file text_field.cpp.

Here is the call graph for this function:

◆ text()

std::string guillaume::systems::TextField::text ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the text the field holds.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe text field entity.
Returns
The content of the input child when it has a components::Text, otherwise the last text recorded in components::TextFieldConfiguration. Empty when nothing is typed.

Definition at line 419 of file text_field.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::TextField::update ( const ecs::Entity::Identifier & entityIdentifier)
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.

Parameters
entityIdentifierThe entity to update.

Implements guillaume::ecs::System.

Definition at line 589 of file text_field.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ DenseHeight

float guillaume::systems::TextField::DenseHeight = 40.0f
staticconstexpr

Height of a dense single-line field without a label, in dp.

Definition at line 93 of file text_field.hpp.

◆ DenseLabelHeight

float guillaume::systems::TextField::DenseLabelHeight = 52.0f
staticconstexpr

Height of a dense single-line field that has a label, in dp.

Definition at line 90 of file text_field.hpp.

◆ Height

float guillaume::systems::TextField::Height = 56.0f
staticconstexpr

Height of a single-line field that is not dense, in dp.

Definition at line 87 of file text_field.hpp.

◆ IconSize

float guillaume::systems::TextField::IconSize = 24.0f
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.

◆ Padding

float guillaume::systems::TextField::Padding = theme::SpacingScale::get(4)
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.

◆ Spacing

float guillaume::systems::TextField::Spacing = theme::SpacingScale::get(3)
staticconstexpr

Gap between the icons, the affixes and the input: 12 dp.

Definition at line 100 of file text_field.hpp.

◆ SupportingGap

float guillaume::systems::TextField::SupportingGap = theme::SpacingScale::get(1)
staticconstexpr

Gap between the bottom of the field and the supporting text: 4 dp.

Definition at line 104 of file text_field.hpp.


The documentation for this class was generated from the following files: