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

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>

Inheritance diagram for guillaume::entities::TextField:
Collaboration diagram for guillaume::entities::TextField:

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 &registry, 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.

Detailed Description

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::Builder builder(getComponentRegistry(), getEntityRegistry());
auto field = builder.makeTextField(parent, TextField::Variant::Outlined,
"Email", "mail", "", "We never share it", false);
field->setOnChange([](const std::string &text) {
// called when the user edits the text
});
Configures a TextField, then builds it and registers it in the entity registry given at construction.

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:

  • Filled: a tinted box with a line at the bottom.
  • Outlined: a transparent box with a border all around.

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:

  • The box is 56 dp high; 52 dp when dense with a label, 40 dp when dense without one. A multiline field takes the height of its content. The width follows the content, with a minimum of MinWidth (100 dp), unless setWidth() fixes it.
  • The typed text lives in the components::Text of the input child (getInputIdentifier()). systems::TextField gives that child a components::Focus while the field is focused, editable and enabled; that is what lets the text input systems edit it.
  • The change handler is called by systems::TextField when it sees that the typed text differs from the one it knew. setText() does not call it.
  • The field is the entity registry of its children; they are built by this class and destroyed with it.
  • systems::TextField overwrites the layout settings, size, colors, border and bottom line every frame.
  • The leading and trailing icons are fixed at creation.
See also
components::TextField, components::TextFieldConfiguration, systems::TextField

Definition at line 116 of file text_field.hpp.

Member Typedef Documentation

◆ Variant

Look of the field: Filled or Outlined.

Definition at line 122 of file text_field.hpp.

Constructor & Destructor Documentation

◆ ~TextField()

guillaume::entities::TextField::~TextField ( void )
override

Default destructor.

Definition at line 166 of file text_field.cpp.

Member Function Documentation

◆ create()

template<typename... Arguments>
std::shared_ptr< TextField > guillaume::entities::TextField::create ( Arguments &&... arguments)
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.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new text field, with no parent.

Definition at line 274 of file text_field.hpp.

Here is the caller graph for this function:

◆ getErrorIconIdentifier()

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.

Returns
The identifier, or ecs::Entity::InvalidIdentifier before the children are built.

Definition at line 382 of file text_field.cpp.

◆ getInputIdentifier()

ecs::Entity::Identifier guillaume::entities::TextField::getInputIdentifier ( void ) const

Get the identifier of the child that holds the typed text.

Returns
The identifier, or ecs::Entity::InvalidIdentifier before the children are built.

Definition at line 362 of file text_field.cpp.

◆ getLabelIdentifier()

ecs::Entity::Identifier guillaume::entities::TextField::getLabelIdentifier ( void ) const

Get the identifier of the label child.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the field has no label.

Definition at line 357 of file text_field.cpp.

◆ getPrefixIdentifier()

ecs::Entity::Identifier guillaume::entities::TextField::getPrefixIdentifier ( void ) const

Get the identifier of the prefix child.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the field never had a prefix.

Definition at line 372 of file text_field.cpp.

◆ getSuffixIdentifier()

ecs::Entity::Identifier guillaume::entities::TextField::getSuffixIdentifier ( void ) const

Get the identifier of the suffix child.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the field never had a suffix.

Definition at line 377 of file text_field.cpp.

◆ getSupportingIdentifier()

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.

Returns
The identifier, or ecs::Entity::InvalidIdentifier when the field never had such a text.

Definition at line 367 of file text_field.cpp.

◆ getText()

std::string guillaume::entities::TextField::getText ( void ) const

Get the typed text.

Returns
The content of the input child, including what the user typed; empty when the field holds no text.

Definition at line 239 of file text_field.cpp.

Here is the call graph for this function:

◆ getVariant()

TextField::Variant guillaume::entities::TextField::getVariant ( void ) const

Get the field variant.

Returns
The variant stored in components::TextFieldConfiguration.

Definition at line 220 of file text_field.cpp.

◆ isDense()

bool guillaume::entities::TextField::isDense ( void ) const

Check whether the field uses the dense height.

Returns
True when dense.

Definition at line 313 of file text_field.cpp.

◆ isDisabled()

bool guillaume::entities::TextField::isDisabled ( void ) const

Check whether the field is disabled.

Returns
True when disabled.

Definition at line 207 of file text_field.cpp.

Here is the call graph for this function:

◆ isEditable()

bool guillaume::entities::TextField::isEditable ( void ) const

Check whether the user may edit the text.

Returns
True when editable.

Definition at line 301 of file text_field.cpp.

◆ isError()

bool guillaume::entities::TextField::isError ( void ) const

Check whether the field is in the error state.

Returns
True in the error state.

Definition at line 252 of file text_field.cpp.

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

◆ isFocused()

bool guillaume::entities::TextField::isFocused ( void ) const

Check whether the field has the keyboard focus.

Returns
True when focused.

Definition at line 195 of file text_field.cpp.

Here is the call graph for this function:

◆ isLabelFloating()

bool guillaume::entities::TextField::isLabelFloating ( void ) const

Check whether the label floats above the typed text.

Returns
True while the field is focused or holds text.

Definition at line 201 of file text_field.cpp.

Here is the call graph for this function:

◆ isMultiline()

bool guillaume::entities::TextField::isMultiline ( void ) const

Check whether the height follows the content.

Returns
True when multiline.

Definition at line 325 of file text_field.cpp.

◆ setDense()

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.

Parameters
denseTrue for the dense height.
Returns
This field, for chaining.

Definition at line 306 of file text_field.cpp.

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

◆ setDisabled()

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.

Parameters
disabledTrue to disable the field.
Returns
This field, for chaining.

Definition at line 287 of file text_field.cpp.

Here is the call graph for this function:

◆ setEditable()

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.

Parameters
editableTrue to let the user edit the text. Default: true.
Returns
This field, for chaining.

Definition at line 294 of file text_field.cpp.

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

◆ setError()

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.

Parameters
errorTrue for the error state.
Returns
This field, for chaining.

Definition at line 245 of file text_field.cpp.

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

◆ setErrorText()

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.

Parameters
errorTextThe error text. When empty, the supporting text stays shown in the error state.
Returns
This field, for chaining.

Definition at line 259 of file text_field.cpp.

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

◆ setMultiline()

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.

Parameters
multilineTrue to let the height follow the content.
Returns
This field, for chaining.

Definition at line 318 of file text_field.cpp.

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

◆ setOnBlur()

TextField & guillaume::entities::TextField::setOnBlur ( std::function< void(void)> onBlur)

Set the handler called when the field loses the focus.

Parameters
onBlurThe handler; an empty one removes it.
Returns
This field, for chaining.

Definition at line 351 of file text_field.cpp.

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

◆ setOnChange()

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.

Parameters
onChangeThe handler, given the new text; an empty one removes it.
Returns
This field, for chaining.

Definition at line 338 of file text_field.cpp.

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

◆ setOnFocus()

TextField & guillaume::entities::TextField::setOnFocus ( std::function< void(void)> onFocus)

Set the handler called when the field gains the focus.

Parameters
onFocusThe handler; an empty one removes it.
Returns
This field, for chaining.

Definition at line 345 of file text_field.cpp.

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

◆ setPlaceholder()

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.

Parameters
placeholderThe new label text.
Returns
This field, for chaining.

Definition at line 225 of file text_field.cpp.

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

◆ setPrefix()

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.

Parameters
prefixThe prefix text; empty shows none.
Returns
This field, for chaining.

Definition at line 273 of file text_field.cpp.

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

◆ setSuffix()

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.

Parameters
suffixThe suffix text; empty shows none.
Returns
This field, for chaining.

Definition at line 280 of file text_field.cpp.

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

◆ setSupportingText()

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.

Parameters
supportingTextThe helper text; empty shows none.
Returns
This field, for chaining.

Definition at line 266 of file text_field.cpp.

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

◆ setText()

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.

Parameters
textThe new text.
Returns
This field, for chaining.

Definition at line 232 of file text_field.cpp.

Here is the call graph for this function:

◆ setVariant()

TextField & guillaume::entities::TextField::setVariant ( Variant variant)

Change the field variant. Restyles at once.

Parameters
variantThe new variant, Filled or Outlined.
Returns
This field, for chaining.

Definition at line 213 of file text_field.cpp.

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

◆ setWidth()

TextField & guillaume::entities::TextField::setWidth ( float width)

Fix the width of the box instead of letting it follow the content. Restyles at once.

Parameters
widthThe width, in dp. A value under MinWidth (100 dp) is raised to MinWidth.
Returns
This field, for chaining.

Definition at line 330 of file text_field.cpp.

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

Member Data Documentation

◆ MinWidth

float guillaume::entities::TextField::MinWidth
staticconstexpr
Initial value:

Smallest width of the box, in dp (100).

Definition at line 127 of file text_field.hpp.


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