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

State of a text field widget that is not text around the input: its variant, icons, flags, width, callbacks and the identifiers of its children. More...

#include <headers/guillaume/components/text_field_configuration.hpp>

Inheritance diagram for guillaume::components::TextFieldConfiguration:
Collaboration diagram for guillaume::components::TextFieldConfiguration:

Public Types

enum class  Variant { Filled , Outlined }
 Look of the field: Filled has a tinted background and a line under it; Outlined has a border the label sits on. More...
using ChangeHandler = std::function<void(const std::string &)>
using Handler = std::function<void(void)>

Public Member Functions

 TextFieldConfiguration (void)=default
 Create the configuration of an editable, single-line filled field with no icon and no forced width.
 ~TextFieldConfiguration (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the look of the field.
TextFieldConfiguration & setVariant (Variant variant)
 Choose between the filled and the outlined look.
const std::string & getLeadingIcon (void) const noexcept
 Get the icon shown before the input.
TextFieldConfiguration & setLeadingIcon (const std::string &glyph)
 Set the icon shown before the input.
const std::string & getTrailingIcon (void) const noexcept
 Get the icon shown after the input.
TextFieldConfiguration & setTrailingIcon (const std::string &glyph)
 Set the icon shown after the input.
const std::string & getText (void) const noexcept
 Get the last known input text.
TextFieldConfiguration & setText (const std::string &text)
 Store the last known input text.
bool isEditable (void) const noexcept
 Tell whether the user can edit the text.
TextFieldConfiguration & setEditable (bool editable)
 Allow or forbid editing by the user.
bool isDense (void) const noexcept
 Tell whether the field uses the compact height.
TextFieldConfiguration & setDense (bool dense)
 Choose between the regular and the compact height.
bool isMultiline (void) const noexcept
 Tell whether the field grows with its content.
TextFieldConfiguration & setMultiline (bool multiline)
 Choose between a fixed height and a height that follows the content.
const std::optional< float > & getWidth (void) const noexcept
 Get the forced width of the field.
TextFieldConfiguration & setWidth (std::optional< float > width)
 Force the width of the field, or let it follow its content.
const ChangeHandler & getOnChange (void) const noexcept
 Get the callback run when the user edits the text.
TextFieldConfiguration & setOnChange (ChangeHandler handler)
 Set the callback run when the user edits the text.
const Handler & getOnFocus (void) const noexcept
 Get the callback run when the field gains the focus.
TextFieldConfiguration & setOnFocus (Handler handler)
 Set the callback run when the field gains the focus.
const Handler & getOnBlur (void) const noexcept
 Get the callback run when the field loses the focus.
TextFieldConfiguration & setOnBlur (Handler handler)
 Set the callback run when the field loses the focus.
ecs::Entity::Identifier getLeadingIconEntity (void) const noexcept
 Get the child that draws the leading icon.
TextFieldConfiguration & setLeadingIconEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the leading icon.
ecs::Entity::Identifier getTrailingIconEntity (void) const noexcept
 Get the child that draws the trailing icon.
TextFieldConfiguration & setTrailingIconEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the trailing icon.
ecs::Entity::Identifier getErrorIconEntity (void) const noexcept
 Get the child that draws the icon shown while the field is in error.
TextFieldConfiguration & setErrorIconEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the icon shown while the field is in error.
ecs::Entity::Identifier getInputColumn (void) const noexcept
 Get the column that stacks the label above the input.
TextFieldConfiguration & setInputColumn (ecs::Entity::Identifier identifier)
 Record the column that stacks the label above the input.
ecs::Entity::Identifier getLabelEntity (void) const noexcept
 Get the child that draws the label (the placeholder text).
TextFieldConfiguration & setLabelEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the label.
ecs::Entity::Identifier getInputEntity (void) const noexcept
 Get the child the user types in.
TextFieldConfiguration & setInputEntity (ecs::Entity::Identifier identifier)
 Record the child the user types in.
ecs::Entity::Identifier getPrefixEntity (void) const noexcept
 Get the child that draws the prefix.
TextFieldConfiguration & setPrefixEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the prefix.
ecs::Entity::Identifier getSuffixEntity (void) const noexcept
 Get the child that draws the suffix.
TextFieldConfiguration & setSuffixEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the suffix.
ecs::Entity::Identifier getSupportingEntity (void) const noexcept
 Get the child that draws the supporting or error text under the field.
TextFieldConfiguration & setSupportingEntity (ecs::Entity::Identifier identifier)
 Record the child that draws the supporting or error text under the field.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float MinWidth = 100.0f
 Smallest width of a text field, in dp.

Detailed Description

State of a text field widget that is not text around the input: its variant, icons, flags, width, callbacks and the identifiers of its children.

A text field has two components. components::TextField holds the placeholder, supporting text, affixes and error state. This one holds the rest. The entities::TextField widget writes both. systems::TextField reads both every frame in the Layout phase and turns them into the field's Layout, Color, Borders and Line, and into the content, color and placement of the children.

The text the user types is the components::Text of the input child. getText() is only the copy systems::TextField compares it with to detect an edit. To change the text from code, call systems::TextField::setText.

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

Definition at line 54 of file text_field_configuration.hpp.

Member Typedef Documentation

◆ ChangeHandler

using guillaume::components::TextFieldConfiguration::ChangeHandler = std::function<void(const std::string &)>

Callback that receives the new text after the user edits the input.

Definition at line 65 of file text_field_configuration.hpp.

◆ Handler

using guillaume::components::TextFieldConfiguration::Handler = std::function<void(void)>

Callback that takes no argument, used when the field gains or loses the focus.

Definition at line 69 of file text_field_configuration.hpp.

Member Enumeration Documentation

◆ Variant

Look of the field: Filled has a tinted background and a line under it; Outlined has a border the label sits on.

Definition at line 61 of file text_field_configuration.hpp.

Member Function Documentation

◆ getErrorIconEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getErrorIconEntity ( void ) const
noexcept

Get the child that draws the icon shown while the field is in error.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 233 of file text_field_configuration.cpp.

◆ getInputColumn()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getInputColumn ( void ) const
noexcept

Get the column that stacks the label above the input.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 250 of file text_field_configuration.cpp.

◆ getInputEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getInputEntity ( void ) const
noexcept

Get the child the user types in.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 284 of file text_field_configuration.cpp.

◆ getLabelEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getLabelEntity ( void ) const
noexcept

Get the child that draws the label (the placeholder text).

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 267 of file text_field_configuration.cpp.

◆ getLeadingIcon()

const std::string & guillaume::components::TextFieldConfiguration::getLeadingIcon ( void ) const
noexcept

Get the icon shown before the input.

Returns
The glyph name; empty for none.

Definition at line 47 of file text_field_configuration.cpp.

◆ getLeadingIconEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getLeadingIconEntity ( void ) const
noexcept

Get the child that draws the leading icon.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the field has none.

Definition at line 199 of file text_field_configuration.cpp.

◆ getOnBlur()

const TextFieldConfiguration::Handler & guillaume::components::TextFieldConfiguration::getOnBlur ( void ) const
noexcept

Get the callback run when the field loses the focus.

Returns
The callback; empty when none is set.

Definition at line 187 of file text_field_configuration.cpp.

◆ getOnChange()

const TextFieldConfiguration::ChangeHandler & guillaume::components::TextFieldConfiguration::getOnChange ( void ) const
noexcept

Get the callback run when the user edits the text.

Returns
The callback; empty when none is set.

Definition at line 162 of file text_field_configuration.cpp.

◆ getOnFocus()

const TextFieldConfiguration::Handler & guillaume::components::TextFieldConfiguration::getOnFocus ( void ) const
noexcept

Get the callback run when the field gains the focus.

Returns
The callback; empty when none is set.

Definition at line 175 of file text_field_configuration.cpp.

◆ getPrefixEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getPrefixEntity ( void ) const
noexcept

Get the child that draws the prefix.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 301 of file text_field_configuration.cpp.

◆ getSuffixEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getSuffixEntity ( void ) const
noexcept

Get the child that draws the suffix.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 318 of file text_field_configuration.cpp.

◆ getSupportingEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getSupportingEntity ( void ) const
noexcept

Get the child that draws the supporting or error text under the field.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 335 of file text_field_configuration.cpp.

◆ getText()

const std::string & guillaume::components::TextFieldConfiguration::getText ( void ) const
noexcept

Get the last known input text.

The live text is the content of the input child; this copy is what systems::TextField compares it with to report edits, and the text of a field whose input child does not exist yet.

Returns
The text as of the last pass of systems::TextField.

Definition at line 80 of file text_field_configuration.cpp.

◆ getTrailingIcon()

const std::string & guillaume::components::TextFieldConfiguration::getTrailingIcon ( void ) const
noexcept

Get the icon shown after the input.

Returns
The glyph name; empty for none.

Definition at line 64 of file text_field_configuration.cpp.

◆ getTrailingIconEntity()

ecs::Entity::Identifier guillaume::components::TextFieldConfiguration::getTrailingIconEntity ( void ) const
noexcept

Get the child that draws the trailing icon.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the field has none.

Definition at line 216 of file text_field_configuration.cpp.

◆ getVariant()

TextFieldConfiguration::Variant guillaume::components::TextFieldConfiguration::getVariant ( void ) const
noexcept

Get the look of the field.

Returns
The variant, Variant::Filled by default.

Definition at line 31 of file text_field_configuration.cpp.

◆ getWidth()

const std::optional< float > & guillaume::components::TextFieldConfiguration::getWidth ( void ) const
noexcept

Get the forced width of the field.

Returns
The width in dp, or std::nullopt when the width follows the content.

Definition at line 142 of file text_field_configuration.cpp.

◆ isDense()

bool guillaume::components::TextFieldConfiguration::isDense ( void ) const
noexcept

Tell whether the field uses the compact height.

Returns
True when dense.

Definition at line 111 of file text_field_configuration.cpp.

◆ isEditable()

bool guillaume::components::TextFieldConfiguration::isEditable ( void ) const
noexcept

Tell whether the user can edit the text.

Returns
True when editable, which is the default.

Definition at line 96 of file text_field_configuration.cpp.

◆ isMultiline()

bool guillaume::components::TextFieldConfiguration::isMultiline ( void ) const
noexcept

Tell whether the field grows with its content.

Returns
True when multiline.

Definition at line 126 of file text_field_configuration.cpp.

◆ setDense()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setDense ( bool dense)

Choose between the regular and the compact height.

A regular field is 56 dp high. A dense one is 52 dp high with a placeholder and 40 dp without. Ignored by a multiline field. Marks the component changed only when the flag differs.

Parameters
denseTrue for the compact height.
Returns
This component, for chaining.

Definition at line 116 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setEditable()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setEditable ( bool editable)

Allow or forbid editing by the user.

The input child receives the keyboard only while the field is editable, enabled and focused. A read-only field can still be focused. Marks the component changed only when the flag differs.

Parameters
editableTrue to let the user edit the text.
Returns
This component, for chaining.

Definition at line 101 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setErrorIconEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setErrorIconEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the icon shown while the field is in error.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 238 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setInputColumn()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setInputColumn ( ecs::Entity::Identifier identifier)

Record the column that stacks the label above the input.

Marks the component changed only when the identifier differs.

Parameters
identifierThe column's identifier.
Returns
This component, for chaining.

Definition at line 255 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setInputEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setInputEntity ( ecs::Entity::Identifier identifier)

Record the child the user types in.

From then on its components::Text is the text of the field. Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 289 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setLabelEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setLabelEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the label.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 272 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setLeadingIcon()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setLeadingIcon ( const std::string & glyph)

Set the icon shown before the input.

The widget uses it when it builds the leading icon child. Marks the component changed only when the name differs.

Parameters
glyphThe glyph name; empty for none.
Returns
This component, for chaining.

Definition at line 53 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setLeadingIconEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setLeadingIconEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the leading icon.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 204 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setMultiline()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setMultiline ( bool multiline)

Choose between a fixed height and a height that follows the content.

Marks the component changed only when the flag differs.

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

Definition at line 131 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setOnBlur()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setOnBlur ( Handler handler)

Set the callback run when the field loses the focus.

Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 192 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setOnChange()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setOnChange ( ChangeHandler handler)

Set the callback run when the user edits the text.

systems::TextField calls it with the new text, on the frame it sees the input differ from the last known text. It is not called for a text set with systems::TextField::setText. Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 168 of file text_field_configuration.cpp.

◆ setOnFocus()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setOnFocus ( Handler handler)

Set the callback run when the field gains the focus.

Does not mark the component changed.

Parameters
handlerThe callback; an empty one removes it.
Returns
This component, for chaining.

Definition at line 180 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setPrefixEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setPrefixEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the prefix.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 306 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setSuffixEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setSuffixEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the suffix.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 323 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setSupportingEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setSupportingEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the supporting or error text under the field.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 340 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setText()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setText ( const std::string & text)

Store the last known input text.

This does not change what the field shows; use systems::TextField::setText for that. Marks the component changed only when the text differs.

Parameters
textThe text of the input child.
Returns
This component, for chaining.

Definition at line 86 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setTrailingIcon()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setTrailingIcon ( const std::string & glyph)

Set the icon shown after the input.

The widget uses it when it builds the trailing icon child. While the field is in error, the error icon is shown in its place. Marks the component changed only when the name differs.

Parameters
glyphThe glyph name; empty for none.
Returns
This component, for chaining.

Definition at line 70 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setTrailingIconEntity()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setTrailingIconEntity ( ecs::Entity::Identifier identifier)

Record the child that draws the trailing icon.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 221 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setVariant()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setVariant ( Variant variant)

Choose between the filled and the outlined look.

Marks the component changed only when the variant differs.

Parameters
variantThe new variant.
Returns
This component, for chaining.

Definition at line 36 of file text_field_configuration.cpp.

Here is the call graph for this function:

◆ setWidth()

TextFieldConfiguration & guillaume::components::TextFieldConfiguration::setWidth ( std::optional< float > width)

Force the width of the field, or let it follow its content.

Marks the component changed only when the stored value differs.

Parameters
widthThe width in dp, raised to MinWidth when smaller; std::nullopt to follow the content (never below MinWidth).
Returns
This component, for chaining.

Definition at line 148 of file text_field_configuration.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ MinWidth

float guillaume::components::TextFieldConfiguration::MinWidth = 100.0f
staticconstexpr

Smallest width of a text field, in dp.

Definition at line 72 of file text_field_configuration.hpp.


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