TextInput

textInput · Elements · interactive

A single-line input, and a type that says what it accepts.

Import

#include "gbui/widgets/textInput.hpp"

Example

Nothing is downloaded until you press it.

TextInputResult textInput(Ui& ui, const Interaction& input, std::string_view id, TextEditState& state, const TextInputOptions& options = {});

Edits state in place when it has focus and returns what happened, so a caller can react to a submit without diffing the text. The pointer places the caret: a press puts it at the character it landed on, and holding and moving drags a selection out from there. Both measure the run the same way the caret is drawn, so what is clicked is where it lands.

API

TextInputOptions

Option	Type	Default	What it does
type	InputType Text · Password · Number	InputType::Text	What the box accepts. Everything below marked for one type is ignored by the others.
name	std::string_view		What this is called, for a reader who cannot see the caption beside it. Unnecessary when a label or a field names it — those attach the relation, and a name given twice is a name read out twice. Necessary the rest of the time, and the placeholder is not a substitute: a box named by its placeholder loses its name the moment somebody types in it.
placeholder	std::string_view		Shown while the text is empty. It steps aside once the box has the keyboard: a hint you are being asked to type over is noise the moment you start.
disabled	bool	false
readOnly	bool	false
invalid	bool	false	Draws the box in the error colour. The control's half of the state field owns the message for. A component does not reach into another component's options, so a field with an error on it does not restyle its control by remote control — the caller says so twice, once in each place, and both are readable on their own.
leading optional	std::optional<Icon>		A glyph at the leading edge, inside the box.
revealToggle	bool	true	The eye at the trailing edge that shows the text while it is held. On by default, because a field you cannot read back is a field people mistype into; turn it off where a shoulder-surfer is the threat being designed against.
revealed	bool	false	Whether the text is currently shown. The caller owns it, like every other piece of state here, and flips it when the result says so.
minimum	double	-1e18
maximum	double	1e18
step	double	1.0	What one arrow, one wheel notch or one step button is worth.
decimals	int	0	Digits after the point. Zero also stops a point being typed at all.
suffix	std::string_view		Drawn after the value, and never part of it: " min", "px", "%". A suffix inside the editable text would be a suffix the caret can be put in the middle of.
steppers	StepperPlacement Sides · Stacked · None	StepperPlacement::Sides	Where the step buttons go, and whether there are any at all.
stackedBelow	float	110.0f	Below this width the steppers drop to Stacked automatically, so a box in a narrow column shows its value rather than two buttons.
height	float	0.0f	Zero takes the active design's control height.
width	float	kAuto	kAuto fits the content — except on a number, which takes 120 px: a box sized to its digits changes width as they are typed, and the steppers walk out from under the pointer clicking them.
grow	float	0.0f