Use the Text Box nodes to add single-line text input to your application. More...

#include <kanzi/ui/node/concept/text_box.hpp>

Inheritance diagram for kanzi::TextBoxConcept:

Classes
class	CursorPositionMessageArguments
	Message arguments for messages that contain the information about the position index of the cursor position. More...

class	DeleteSelectionMessageArguments
	Message arguments for messages that delete the portion of the text that is selected. More...

class	EditingStateChangedMessageArguments
	Message arguments for the messages about changing the editing state of a Text Box node. More...

class	EraseCharactersMessageArguments
	Message arguments for messages that erase the characters at the cursor position. More...

class	InputMethodActionMessageArguments
	Message arguments for the message about the input method action execution received on a Text Box node. More...

class	InputMethodAvailableMessageArguments
	Message arguments for the InputMethodAvailableMessage and InputMethodUnavailableMessage. More...

class	ModifyEditingStateMessageArguments
	Message arguments for the messages that modify the editing state. More...

class	ModifySelectionMessageArguments
	Message arguments for the messages that modify the cursor position for a selection. More...

class	MoveCursorMessageArguments
	Message arguments for messages that move the cursor position. More...

class	SelectedTextMessageArguments
	Message arguments that hold the information about the selected text in the buffer of a Text Box node. More...

class	TextChangedMessageArguments
	Message arguments for the messages about the content change of a Text Box node. More...

class	TextCompositionStateMessageArguments
	Message arguments for the messages about the text composition state change of a Text Box node. More...

class	TextContentMessageArguments
	Message arguments for the messages about the content of a Text Box node. More...

class	TextInsertionMessageArguments
	Message arguments that hold the information for inserting text to a Text Box node. More...

class	TextRangeMessageArguments
	Message arguments that hold the information for operations that target a text range, such as selecting or deleting text in a Text Box node. More...

Public Types
enum	EditMode { EditMode::Automatic, EditMode::Triggered }
	The edit modes. More...

Public Member Functions
	KZ_METACLASS_PROPERTY_TYPE (CompositionTextProperty)

Static Public Member Functions
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

Static Public Attributes
static MessageType< TextCompositionStateMessageArguments >	CompositionTextChangedMessage
	Text Box dispatches this message when the composition text is updated by the input methods. More...

static MessageType< TextCompositionStateMessageArguments >	CompositionTextCommittedMessage
	Text Box dispatches this message when the composition text is committed to the cached text. More...

static MessageType< CursorPositionMessageArguments >	CursorMovedMessage
	Text Box node dispatches this message when the application user moves the cursor in that Text Box node. More...

static MessageType< TextChangedMessageArguments >	EditingFinishedMessage
	Text Box node dispatches this message when it leaves the editing state after the application user modifies the text content. More...

static MessageType< TextChangedMessageArguments >	EditingStartedMessage
	Text Box node dispatches this message when the application user makes the first modification to the text in that Text Box node. More...

static MessageType< EditingStateChangedMessageArguments >	EnteredEditingStateMessage
	Text Box node dispatches this message when it enters the editing state. More...

static MessageType< InputMethodActionMessageArguments >	InputMethodActionMessage
	Text Box node dispatches this message when an input method executes the input action assigned to the text box. More...

static MessageType< InputMethodAvailableMessageArguments >	InputMethodAvailableMessage
	Text Box node dispatches this message when an input method becomes available. More...

static MessageType< InputMethodAvailableMessageArguments >	InputMethodUnavailableMessage
	Text Box node dispatches this message when the composing input method becomes unavailable. More...

static MessageType< EditingStateChangedMessageArguments >	LeftEditingStateMessage
	Text Box node dispatches this message when it leaves the editing state. More...

static MessageType< SelectedTextMessageArguments >	SelectionChangedMessage
	Text Box node dispatches this message when the application user changes the text selection in that Text Box node. More...

static MessageType< CursorPositionMessageArguments >	SelectionClearedMessage
	Text Box node dispatches this message when the application user clears or resets the text selection in that Text Box node. More...

static MessageType< SelectedTextMessageArguments >	SelectionStartedMessage
	Text Box node dispatches this message when the application user starts selecting text in that Text Box node. More...

static MessageType< TextChangedMessageArguments >	TextChangedMessage
	Text Box node dispatches this message when the application user changes the text in that Text Box node. More...

static MessageType< TextCompositionStateMessageArguments >	TextCompositionCanceledMessage
	Text Box dispatches this message when the text composition is canceled. More...

Properties
static PropertyType< string >	DisplayTextProperty
	Reports the text displayed in a Text Box. More...

static PropertyType< string >	CompositionTextProperty
	Reports the text that the user composes in a Text Box using an input method editor (IME). More...

static PropertyType< ResourceSharedPtr >	SelectionBackgroundBrushProperty
	Sets the brush that highlights selected text. More...

static PropertyType< ResourceSharedPtr >	SelectionForegroundBrushProperty
	Sets the brush for rendering the selected text. More...

static PropertyType< ResourceSharedPtr >	CompositionTextBackgroundBrushProperty
	Sets the brush that highlights the text that the user composes using an input method editor (IME). More...

static PropertyType< ResourceSharedPtr >	CompositionTextForegroundBrushProperty
	Sets the brush that fills the text that the user composes using an input method editor (IME). More...

static PropertyType< int >	CursorPositionProperty
	Sets the position of the cursor in the text buffer of a Text Box node. More...

static PropertyType< int >	SelectionStartCursorPositionProperty
	Reports the position of the cursor that marks the beginning of text selection in the text buffer of a Text Box node. More...

static PropertyType< int >	SelectionEndCursorPositionProperty
	Reports the position of the cursor that marks the end of text selection in the text buffer of a Text Box node. More...

static PropertyType< bool >	HasSelectionProperty
	Reports whether any of the text in a Text Box node is selected. More...

static PropertyType< bool >	ReadOnlyProperty
	Sets whether the Text Box node accepts user input. More...

static PropertyType< int >	MaximumTextLengthProperty
	Sets the maximum allowed text length in a Text Box node. More...

static PropertyType< ResourceSharedPtr >	CursorPrefabProperty
	Sets the prefab template that defines the appearance of the cursor, instead of using the default cursor. More...

static PropertyType< ResourceSharedPtr >	SelectionStartPrefabProperty
	Sets the prefab template that defines the appearance of the selection handle at the beginning of text selection, instead of using the default handle. More...

static PropertyType< ResourceSharedPtr >	SelectionEndPrefabProperty
	Sets the prefab template that defines the appearance of the selection handle at the end of text selection, instead of using the default handle. More...

static PropertyType< ResourceSharedPtr >	TextHintPrefabProperty
	Sets the prefab template that a Text Box node uses to show placeholder content when there is no text content in that Text Box node. More...

static PropertyType< bool >	HideTextHintWhenEditingProperty
	Sets whether Kanzi hides the placeholder content, which you set using the TextHintPrefabProperty, either: More...

static PropertyType< EchoMode >	EchoModeProperty
	Sets how a Text Box node shows text. More...

static PropertyType< InputType >	InputTypeProperty
	Sets the input type of the input methods that provide the input for a Text Box. More...

static PropertyType< EditMode >	EditModeProperty
	Sets the edit mode of a Text Box node. The default value is EditMode::Automatic. More...

static PropertyType< bool >	IsEditingProperty
	Reports the editing state of a Text Box node. More...

static PropertyType< bool >	IsComposingTextProperty
	Reports the text composition state of a Text Box node. More...

static PropertyType< int >	CharacterCountProperty
	Contains the number of characters in a Text Box node. More...

static PropertyType< int >	WordCountProperty
	Contains the number of words in a Text Box node. More...

static PropertyType< int >	PasswordEchoTimeoutProperty
	Sets the time in milliseconds that Kanzi shows an inserted character before masking it when using the EchoMode::Password echo mode. More...

static PropertyType< string >	PasswordMaskingCharacterProperty
	Sets the UTF-8 character that masks each password character when using EchoMode::Password. More...

static PropertyType< InputMethodAction >	InputMethodActionProperty
	Sets the label of the user action button on the on-screen keyboard. More...

static PropertyType< TextKeyNavigationDirection >	TextKeyNavigationDirectionProperty
	Sets the direction of key navigation for the Text Box node. More...

Actions

static MessageType< TextContentMessageArguments >	InsertTextAtCursorMessage
	Dispatch this message to insert given text at the cursor position. More...

static MessageType< EraseCharactersMessageArguments >	BackspaceAtCursorMessage
	Dispatch this message to erase at the cursor position the previous character in the text string. More...

static MessageType< EraseCharactersMessageArguments >	BackspaceWordAtCursorMessage
	Dispatch this message to erase the characters between the cursor position and the previous word boundary in the text string. More...

static MessageType< EraseCharactersMessageArguments >	DeleteAtCursorMessage
	Dispatch this message to erase at the cursor position the next character in the text string. More...

static MessageType< EraseCharactersMessageArguments >	DeleteWordAtCursorMessage
	Dispatch this message to erase the characters between the cursor position and the next word boundary in the text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorBackwardMessage
	Dispatch this message to move the cursor backward in a text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorForwardMessage
	Dispatch this message to move the cursor forward in the text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorToPreviousWordMessage
	Dispatch this message to move the cursor to the previous word boundary in the text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorToNextWordMessage
	Dispatch this message to move the cursor to the next word boundary in the text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorHomeMessage
	Dispatch this message to move the cursor to the beginning of the text string. More...

static MessageType< MoveCursorMessageArguments >	MoveCursorToEndMessage
	Dispatch this message to move the cursor to the end of the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionStartForwardMessage
	Dispatch this message to move the handle at the start of text selection forward by one character in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionStartBackwardMessage
	Dispatch this message to move the handle at the start of text selection backward by one character in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionStartToNextWordMessage
	Dispatch this message to move the handle at the start of text selection forward to the start of the next word in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionStartToPreviousWordMessage
	Dispatch this message to move the handle at the start of text selection backward to the start of the previous word in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionEndForwardMessage
	Dispatch this message to move the handle at the end of text selection forward by one character in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionEndBackwardMessage
	Dispatch this message to move the handle at the end of text selection backward by one character in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionEndToNextWordMessage
	Dispatch this message to move the handle at the end of text selection forward to the start of the next word in the text string. More...

static MessageType< ModifySelectionMessageArguments >	MoveSelectionEndToPreviousWordMessage
	Dispatch this message to move the handle at the end of text selection backward to the start of the previous word in the text string. More...

static MessageType< TextRangeMessageArguments >	SelectTextMessage
	Dispatch this message to select the text between two character indexes in the current text string. More...

static MessageType< TextRangeMessageArguments >	DeleteTextMessage
	Dispatch this message to delete the text between two character indexes in the current text string. More...

static MessageType< DeleteSelectionMessageArguments >	DeleteSelectionMessage
	Dispatch this message to erase any currently selected text. More...

static MessageType< TextInsertionMessageArguments >	InsertTextMessage
	Dispatch this message to insert given text at a given position. More...

static MessageType< ModifySelectionMessageArguments >	SelectToHomeMessage
	Dispatch this message to select the text from the beginning of the text string to the cursor position. More...

static MessageType< ModifySelectionMessageArguments >	SelectToEndMessage
	Dispatch this message to select the text from the cursor position to the end of the text string. More...

static MessageType< ModifySelectionMessageArguments >	ClearSelectionMessage
	Dispatch this message to clear the current text selection. More...

static MessageType< ModifySelectionMessageArguments >	SelectAllMessage
	Dispatch this message to select all text. More...

static MessageType< ModifySelectionMessageArguments >	SelectWordAtCursorMessage
	Dispatch this message to select the word at the current cursor position. More...

static MessageType< ModifyEditingStateMessageArguments >	EnterEditingStateMessage
	Dispatch this message to make a Text Box node enter the editing state. More...

static MessageType< ModifyEditingStateMessageArguments >	LeaveEditingStateMessage
	Dispatch this message to make a Text Box node leave the editing state. More...

static MessageType< TextCompositionStateMessageArguments >	CommitCompositionTextMessage
	Dispatch this message to make a Text Box commit the composition text. More...

static MessageType< TextCompositionStateMessageArguments >	CancelTextCompositionMessage
	Dispatch this message to make a Text Box cancel the text composition. More...

Protected Member Functions
void	drawRectangle (Renderer3D &renderer, const Matrix4x4 &transform, const Vector2 &topLeft, const Vector2 &bottomRight, float z, const Material &material)
	Draws a filled rectangle with given corner coordinates and z-plane. More...

float	getTextHeight (const TextFormat &textFormat) const
	Returns the height in pixels of the text from the given text format. More...

float	getTextTop (const TextFormat &textFormat) const
	Returns the top of the text in a line. More...

Detailed Description

Use the Text Box nodes to add single-line text input to your application.

Use TextBox3D to add text input in 3D space and TextBox2D to add text input in 2D space.

Editing state

A Text Box enters the editing state either automatically, or manually, using a trigger. To control this behavior, set the EditModeProperty to either:

EditMode::Automatic to make the Text Box node enter the editing state when the application user taps or clicks that node, or when the user sets focus to that node using the focus chain navigation. When the user sets focus to a Text Box node by tapping or clicking that node, the Text Box node places its cursor where the user tapped or clicked. A Text Box node leaves the editing state when the focus moves from that Text Box node to another node.
EditMode::Triggered to make the Text Box node enter the editing state when a trigger initiates the EnterEditingStateMessage action, or when you call the TextBoxConceptImpl::enterEditingState() method. The Text Box stays in the edit mode until a trigger initiates the LeaveEditingStateMessage action, or you call the TextBoxConceptImpl::leaveEditingState() method.

To control the content of a Text Box node that is in the EditMode::Triggered edit mode and has no focus, use Actions.

While a Text Box node is in the editing state, do not let any other Text Box node enter the editing state.

Setting the text content

The TextConcept::TextProperty holds the text content of a Text Box node. When you set the value of the TextConcept::TextProperty, the Text Box node updates the content and scrolls the text input to the end of the text.

To add text in a Text Box node, call the TextBoxConceptImpl::insertText() or TextBoxConceptImpl::insertTextAtCursor() method.

Controlling the position of the cursor

The application user can move the cursor in a Text Box node horizontally by dragging the cursor to the desired position, or by using keyboard keys. Moving the cursor towards the left or right edge of a Text Box node triggers the scrolling of the content that does not fit in the node.

The Text Box nodes report the position of the cursor using the CursorPositionProperty. To control the position of the cursor, use methods such as TextBoxConceptImpl::setCursorPosition(), TextBoxConceptImpl::moveCursorForward(), TextBoxConceptImpl::moveCursorBackward(), TextBoxConceptImpl::moveCursorHome(), TextBoxConceptImpl::moveCursorToEnd(), TextBoxConceptImpl::moveCursorToPoint(), and so on.

Selecting text

The application user can select text in a Text Box node by double-tapping or double-clicking that node. This gesture places the cursor at the position that the user double-tapped or double-clicked, and selects the word at the cursor.

The start and end points of text selection are marked with selection handles that the application user can drag to modify the text selection. When the user drags one handle over the other, Kanzi flips the dragged handle, and continues the selected text in the direction of the other handle.

To modify the text selection in a Text Box node, use methods such as TextBoxConceptImpl::selectWordAtCursor(), TextBoxConceptImpl::selectWordAt(), TextBoxConceptImpl::selectText(), TextBoxConceptImpl::selectAll(), TextBoxConceptImpl::moveSelectionStartBackward(), TextBoxConceptImpl::moveSelectionStartForward(), TextBoxConceptImpl::moveSelectionStartToPreviousWord(), TextBoxConceptImpl::moveSelectionStartToNextWord(), and so on.

Disabling a Text Box

To disable a Text Box node, set the Node::EnabledProperty to false. A disabled Text Box leaves the editing state and stays in that state while the Text Box is disabled. A disabled Text Box does not respond to input. To visually indicate the disabled state of a Text Box node, create a state manager and use the Node::EffectivelyEnabledProperty as its controller property.

Setting the appearance of the cursor and selected text

The Text Box nodes come with a preset appearance for the cursor. To set the appearance of the cursor, use the CursorPrefabProperty.

The Text Box nodes come with a preset appearance for selected text and its highlight. To set the appearance of selected text:

For a TextBox2D node use the SelectionForegroundBrushProperty and SelectionBackgroundBrushProperty.
For a TextBox3D node use the TextBox3D::SelectionFontColorProperty and TextBox3D::SelectionBackgroundColorProperty.

The Text Box nodes come with a preset appearance for composition text and its highlight. Composition text is an instance of text that the application user produces using an input method editor (IME). To set the appearance of composition text:

For a TextBox2D node use the CompositionTextForegroundBrushProperty and CompositionTextBackgroundBrushProperty.
For a TextBox3D node use the TextBox3D::CompositionFontColorProperty and TextBox3D::CompositionBackgroundColorProperty.

The beginning and end of text selection are marked with selection handles that you can configure using the SelectionStartPrefabProperty and SelectionEndPrefabProperty.

The cursor and text selection prefabs are centered around the top of the text line. To make the prefabs fit in a TextBox2D node, set the padding of the node using the TextConcept::HorizontalPaddingProperty and TextConcept::VerticalPaddingProperty.

Showing placeholder content

If a Text Box node is empty, you can use the TextHintPrefabProperty to set the prefab template that the Text Box node uses to show placeholder content. For example, you can use this placeholder content to show text that tells the user what they can enter in a Text Box node. The placeholder content, or hint, can be a prefab or a resource that shows text, a list of buttons, or any other visual element that is parented to the Text Box node and therefore rendered within the Text Box area.

To control the visibility of the placeholder content, use the HideTextHintWhenEditingProperty.

Setting the width of a Text Box node

A Text Box node by default grows to the right along with its content. When you set the value of the Node::WidthProperty in a Text Box node, Kanzi clips the content in that Text Box node to fit into the width that you set.

Truncating text

When a Text Box node is not in the editing state, it truncates text that is longer than the width of the Text Box node, and indicates the truncation with ellipsis or the characters that you define using the TextConcept::OverflowProperty. When a Text Box node is in the editing state, it positions the cursor at the point where the application user can edit the text. The node no longer truncates the content that spans beyond the area and the user can scroll the text.

Since: Kanzi 3.9.0

Member Enumeration Documentation

◆ EditMode

enum kanzi::TextBoxConcept::EditMode

strong

The edit modes.

Enumerator

Automatic

A Text Box node enters the editing state when the node gets the focus, and leaves the editing state when the node loses the focus.

Triggered

A Text Box enters the editing state on a trigger, and remains in this state until another trigger makes the node leave the editing state.

To enter the editing state use the EnterEditingStateMessage message or the TextBoxConceptImpl::enterEditingState() method. To leave the editing state use the LeaveEditingStateMessage message or the TextBoxConceptImpl::leaveEditingState() method.

Member Function Documentation

◆ KZ_METACLASS_PROPERTY_TYPE()

kanzi::TextBoxConcept::KZ_METACLASS_PROPERTY_TYPE ( CompositionTextProperty )

◆ makeEditorInfo()

static PropertyTypeEditorInfoSharedPtr kanzi::TextBoxConcept::makeEditorInfo ( )

static

◆ getTextTop()

float kanzi::TextBoxConcept::getTextTop ( const TextFormat & textFormat ) const

protected

Returns the top of the text in a line.

It is the half of the line height minus the font size in pixels.

Parameters

textFormat The text format structure that holds information about the font and line height.

Returns: The top of the text in the line.

◆ getTextHeight()

float kanzi::TextBoxConcept::getTextHeight ( const TextFormat & textFormat ) const

protected

Returns the height in pixels of the text from the given text format.

Parameters

textFormat The text format structure.

Returns: The height of the text.

◆ drawRectangle()

void kanzi::TextBoxConcept::drawRectangle	(	Renderer3D &	renderer,
		const Matrix4x4 &	transform,
		const Vector2 &	topLeft,
		const Vector2 &	bottomRight,
		float	z,
		const Material &	material
	)

protected

Draws a filled rectangle with given corner coordinates and z-plane.

Member Data Documentation

◆ DisplayTextProperty

PropertyType<string> kanzi::TextBoxConcept::DisplayTextProperty

static

Reports the text displayed in a Text Box.

This property is read-only.

See also: TextBoxConceptImpl::getDisplayText()

◆ CompositionTextProperty

PropertyType<string> kanzi::TextBoxConcept::CompositionTextProperty

static

Reports the text that the user composes in a Text Box using an input method editor (IME).

This property is read-only, and has a value when the Text Box is in the text composition state.

See also: TextBoxConcept::CompositionTextChangedMessage, TextBoxConcept::TextCompositionCanceledMessage

◆ SelectionBackgroundBrushProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::SelectionBackgroundBrushProperty

static

Sets the brush that highlights selected text.

The default value is ResourceSharedPtr();

See also: TextBoxConceptImpl::setSelectionBackgroundBrush(), TextBoxConceptImpl::getSelectionBackgroundBrush()

◆ SelectionForegroundBrushProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::SelectionForegroundBrushProperty

static

Sets the brush for rendering the selected text.

The default value is ResourceSharedPtr();

See also: TextBoxConceptImpl::setSelectionForegroundBrush(), TextBoxConceptImpl::getSelectionForegroundBrush()

◆ CompositionTextBackgroundBrushProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::CompositionTextBackgroundBrushProperty

static

Sets the brush that highlights the text that the user composes using an input method editor (IME).

The default value is ResourceSharedPtr();

See also: TextBoxConceptImpl::setCompositionBackgroundBrush(), TextBoxConceptImpl::getCompositionBackgroundBrush()

◆ CompositionTextForegroundBrushProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::CompositionTextForegroundBrushProperty

static

Sets the brush that fills the text that the user composes using an input method editor (IME).

The default value is ResourceSharedPtr();

See also: TextBoxConceptImpl::setCompositionForegroundBrush(), TextBoxConceptImpl::getCompositionForegroundBrush()

◆ CursorPositionProperty

PropertyType<int> kanzi::TextBoxConcept::CursorPositionProperty

static

Sets the position of the cursor in the text buffer of a Text Box node.

The default value is 0.

See also: TextBoxConceptImpl::setCursorPosition(), TextBoxConceptImpl::getCursorPosition()

◆ SelectionStartCursorPositionProperty

PropertyType<int> kanzi::TextBoxConcept::SelectionStartCursorPositionProperty

static

Reports the position of the cursor that marks the beginning of text selection in the text buffer of a Text Box node.

The property is read-only. The default value is 0.

See also: TextBoxConceptImpl::setSelectionStart(), TextBoxConceptImpl::getSelectionStart()

◆ SelectionEndCursorPositionProperty

PropertyType<int> kanzi::TextBoxConcept::SelectionEndCursorPositionProperty

static

Reports the position of the cursor that marks the end of text selection in the text buffer of a Text Box node.

The property is read-only and it is synchronized with the value of the CursorPositionProperty. The default value is 0.

See also: TextBoxConceptImpl::setSelectionEnd(), TextBoxConceptImpl::getSelectionEnd()

◆ HasSelectionProperty

PropertyType<bool> kanzi::TextBoxConcept::HasSelectionProperty

static

Reports whether any of the text in a Text Box node is selected.

The default value is false.

See also: TextBoxConceptImpl::hasSelection()

◆ ReadOnlyProperty

PropertyType<bool> kanzi::TextBoxConcept::ReadOnlyProperty

static

Sets whether the Text Box node accepts user input.

When the ReadOnlyProperty is set to true, you can set the text only through the TextConcept::TextProperty and using the content manipulator methods and triggers. User input originated using the keyboard and input methods is ignored. The default value is false.

See also: TextBoxConceptImpl::isReadOnly(), TextBoxConceptImpl::setReadOnly()

◆ MaximumTextLengthProperty

PropertyType<int> kanzi::TextBoxConcept::MaximumTextLengthProperty

static

Sets the maximum allowed text length in a Text Box node.

This way you can prevent user input beyond maximum text length. Length unit are UTF-8 characters and buffer byte length can be greater for multi-byte characters. The default value is 0, which sets unlimited length.

See also: TextBoxConceptImpl::setMaximumTextLength(), TextBoxConceptImpl::getMaximumTextLength()

◆ CursorPrefabProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::CursorPrefabProperty

static

Sets the prefab template that defines the appearance of the cursor, instead of using the default cursor.

◆ SelectionStartPrefabProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::SelectionStartPrefabProperty

static

Sets the prefab template that defines the appearance of the selection handle at the beginning of text selection, instead of using the default handle.

◆ SelectionEndPrefabProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::SelectionEndPrefabProperty

static

Sets the prefab template that defines the appearance of the selection handle at the end of text selection, instead of using the default handle.

◆ TextHintPrefabProperty

PropertyType<ResourceSharedPtr> kanzi::TextBoxConcept::TextHintPrefabProperty

static

Sets the prefab template that a Text Box node uses to show placeholder content when there is no text content in that Text Box node.

◆ HideTextHintWhenEditingProperty

PropertyType<bool> kanzi::TextBoxConcept::HideTextHintWhenEditingProperty

static

Sets whether Kanzi hides the placeholder content, which you set using the TextHintPrefabProperty, either:

Whenever the Text Box node is empty and in the editing state
Only when the user enters text in the Text Box node

◆ EchoModeProperty

PropertyType<EchoMode> kanzi::TextBoxConcept::EchoModeProperty

static

Sets how a Text Box node shows text.

The NoEcho mode that does not show the entered text affects only the displayed text, not the text buffer.

See also: TextBoxConceptImpl::setEchoMode(), TextBoxConceptImpl::getEchoMode()

◆ InputTypeProperty

PropertyType<InputType> kanzi::TextBoxConcept::InputTypeProperty

static

Sets the input type of the input methods that provide the input for a Text Box.

See also: TextBoxConceptImpl::setInputType(), TextBoxConceptImpl::getInputType()

◆ EditModeProperty

PropertyType<EditMode> kanzi::TextBoxConcept::EditModeProperty

static

Sets the edit mode of a Text Box node. The default value is EditMode::Automatic.

◆ IsEditingProperty

PropertyType<bool> kanzi::TextBoxConcept::IsEditingProperty

static

Reports the editing state of a Text Box node.

This read-only property is set to:

True when the Text Box enters the editing state.
False when the Text Box leaves the editing state. This is the default value.

◆ IsComposingTextProperty

PropertyType<bool> kanzi::TextBoxConcept::IsComposingTextProperty

static

Reports the text composition state of a Text Box node.

This read-only property is set to:

True when the Text Box is in the text composition state.
False when the Text Box is not in the text composition state.

◆ CharacterCountProperty

PropertyType<int> kanzi::TextBoxConcept::CharacterCountProperty

static

Contains the number of characters in a Text Box node.

The default value is 0.

◆ WordCountProperty

PropertyType<int> kanzi::TextBoxConcept::WordCountProperty

static

Contains the number of words in a Text Box node.

A Text Box node gets the number of words by counting the non-whitespace blocks in a string. It counts each ideograph as a word, regardless of whitespace. The default value is 0.

◆ PasswordEchoTimeoutProperty

PropertyType<int> kanzi::TextBoxConcept::PasswordEchoTimeoutProperty

static

Sets the time in milliseconds that Kanzi shows an inserted character before masking it when using the EchoMode::Password echo mode.

The default value is 1000.

See also: TextBoxConceptImpl::setEchoMode(), TextBoxConceptImpl::getEchoMode()

◆ PasswordMaskingCharacterProperty

PropertyType<string> kanzi::TextBoxConcept::PasswordMaskingCharacterProperty

static

Sets the UTF-8 character that masks each password character when using EchoMode::Password.

By default Kanzi masks each password character with a bullet symbol (u8"\u2022").

See also: TextBoxConceptImpl::setPasswordMaskingCharacter(), TextBoxConceptImpl::getPasswordMaskingCharacter()

◆ InputMethodActionProperty

PropertyType<InputMethodAction> kanzi::TextBoxConcept::InputMethodActionProperty

static

Sets the label of the user action button on the on-screen keyboard.

The default value is InputMethodAction::Default.

See also: InputMethodAction, InputMethod

◆ TextKeyNavigationDirectionProperty

PropertyType<TextKeyNavigationDirection> kanzi::TextBoxConcept::TextKeyNavigationDirectionProperty

static

Sets the direction of key navigation for the Text Box node.

The default value is TextInputManipulator::TextKeyNavigationDirection::LeftToRight.

See also: TextBoxConceptImpl::setTextKeyNavigationDirection(), TextBoxConceptImpl::getTextKeyNavigationDirection()

◆ InputMethodAvailableMessage

MessageType<InputMethodAvailableMessageArguments> kanzi::TextBoxConcept::InputMethodAvailableMessage

static

Text Box node dispatches this message when an input method becomes available.

◆ InputMethodUnavailableMessage

MessageType<InputMethodAvailableMessageArguments> kanzi::TextBoxConcept::InputMethodUnavailableMessage

static

Text Box node dispatches this message when the composing input method becomes unavailable.

◆ CursorMovedMessage

MessageType<CursorPositionMessageArguments> kanzi::TextBoxConcept::CursorMovedMessage

static

Text Box node dispatches this message when the application user moves the cursor in that Text Box node.

This message type contains information about the cursor position the moment a Text Box node sends the message.

◆ TextChangedMessage

MessageType<TextChangedMessageArguments> kanzi::TextBoxConcept::TextChangedMessage

static

Text Box node dispatches this message when the application user changes the text in that Text Box node.

◆ SelectionChangedMessage

MessageType<SelectedTextMessageArguments> kanzi::TextBoxConcept::SelectionChangedMessage

static

Text Box node dispatches this message when the application user changes the text selection in that Text Box node.

This message type contains the selected text and both, the begin and end indexes.

◆ SelectionStartedMessage

MessageType<SelectedTextMessageArguments> kanzi::TextBoxConcept::SelectionStartedMessage

static

Text Box node dispatches this message when the application user starts selecting text in that Text Box node.

This message type contains the selected text and both, the begin and end indexes.

◆ SelectionClearedMessage

MessageType<CursorPositionMessageArguments> kanzi::TextBoxConcept::SelectionClearedMessage

static

Text Box node dispatches this message when the application user clears or resets the text selection in that Text Box node.

This message type contains the cursor position the moment a Text Box node sends the message.

◆ EditingStartedMessage

MessageType<TextChangedMessageArguments> kanzi::TextBoxConcept::EditingStartedMessage

static

Text Box node dispatches this message when the application user makes the first modification to the text in that Text Box node.

A Text Box node sends this message only if it is in the editing state.

◆ EditingFinishedMessage

MessageType<TextChangedMessageArguments> kanzi::TextBoxConcept::EditingFinishedMessage

static

Text Box node dispatches this message when it leaves the editing state after the application user modifies the text content.

If the user does not edit the text while that Text Box node is in the editing state, that Text Box node does not send neither EditingStartedMessage nor EditingFinishedMessage.

◆ CompositionTextChangedMessage

MessageType<TextCompositionStateMessageArguments> kanzi::TextBoxConcept::CompositionTextChangedMessage

static

Text Box dispatches this message when the composition text is updated by the input methods.

See also: IsComposingTextProperty

◆ TextCompositionCanceledMessage

MessageType<TextCompositionStateMessageArguments> kanzi::TextBoxConcept::TextCompositionCanceledMessage

static

Text Box dispatches this message when the text composition is canceled.

See also: IsComposingTextProperty

◆ CompositionTextCommittedMessage

MessageType<TextCompositionStateMessageArguments> kanzi::TextBoxConcept::CompositionTextCommittedMessage

static

Text Box dispatches this message when the composition text is committed to the cached text.

See also: IsComposingTextProperty

◆ EnteredEditingStateMessage

MessageType<EditingStateChangedMessageArguments> kanzi::TextBoxConcept::EnteredEditingStateMessage

static

Text Box node dispatches this message when it enters the editing state.

◆ LeftEditingStateMessage

MessageType<EditingStateChangedMessageArguments> kanzi::TextBoxConcept::LeftEditingStateMessage

static

Text Box node dispatches this message when it leaves the editing state.

◆ InputMethodActionMessage

MessageType<InputMethodActionMessageArguments> kanzi::TextBoxConcept::InputMethodActionMessage

static

Text Box node dispatches this message when an input method executes the input action assigned to the text box.

◆ InsertTextAtCursorMessage

MessageType<TextContentMessageArguments> kanzi::TextBoxConcept::InsertTextAtCursorMessage

static

Dispatch this message to insert given text at the cursor position.

◆ BackspaceAtCursorMessage

MessageType<EraseCharactersMessageArguments> kanzi::TextBoxConcept::BackspaceAtCursorMessage

static

Dispatch this message to erase at the cursor position the previous character in the text string.

If the Text Box has selected text, dispatching this message erases that text.

This message does not have any arguments.

◆ BackspaceWordAtCursorMessage

MessageType<EraseCharactersMessageArguments> kanzi::TextBoxConcept::BackspaceWordAtCursorMessage

static

Dispatch this message to erase the characters between the cursor position and the previous word boundary in the text string.

If the Text Box has selected text, dispatching this message erases that text.

This message does not have any arguments.

◆ DeleteAtCursorMessage

MessageType<EraseCharactersMessageArguments> kanzi::TextBoxConcept::DeleteAtCursorMessage

static

Dispatch this message to erase at the cursor position the next character in the text string.

If the Text Box has selected text, dispatching this message erases that text.

This message does not have any arguments.

◆ DeleteWordAtCursorMessage

MessageType<EraseCharactersMessageArguments> kanzi::TextBoxConcept::DeleteWordAtCursorMessage

static

Dispatch this message to erase the characters between the cursor position and the next word boundary in the text string.

If the Text Box has selected text, dispatching this message erases that text.

This message does not have any arguments.

◆ MoveCursorBackwardMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorBackwardMessage

static

Dispatch this message to move the cursor backward in a text string.

For example, in text that uses a left-to-right script it moves the cursor to the left.

This message does not have any arguments.

◆ MoveCursorForwardMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorForwardMessage

static

Dispatch this message to move the cursor forward in the text string.

For example, in text that uses a left-to-right script it moves the cursor to the right.

This message does not have any arguments.

◆ MoveCursorToPreviousWordMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorToPreviousWordMessage

static

Dispatch this message to move the cursor to the previous word boundary in the text string.

For example, in text that uses a left-to-right script it moves the cursor to the closest word boundary on the left side of the cursor.

This message does not have any arguments.

◆ MoveCursorToNextWordMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorToNextWordMessage

static

Dispatch this message to move the cursor to the next word boundary in the text string.

For example, in text that uses a left-to-right script it moves the cursor to the closest word boundary on the right side of the cursor.

This message does not have any arguments.

◆ MoveCursorHomeMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorHomeMessage

static

Dispatch this message to move the cursor to the beginning of the text string.

This message does not have any arguments.

◆ MoveCursorToEndMessage

MessageType<MoveCursorMessageArguments> kanzi::TextBoxConcept::MoveCursorToEndMessage

static

Dispatch this message to move the cursor to the end of the text string.

This message does not have any arguments.

◆ MoveSelectionStartForwardMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionStartForwardMessage

static

Dispatch this message to move the handle at the start of text selection forward by one character in the text string.

This message does not have any arguments.

◆ MoveSelectionStartBackwardMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionStartBackwardMessage

static

Dispatch this message to move the handle at the start of text selection backward by one character in the text string.

This message does not have any arguments.

◆ MoveSelectionStartToNextWordMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionStartToNextWordMessage

static

Dispatch this message to move the handle at the start of text selection forward to the start of the next word in the text string.

This message does not have any arguments.

◆ MoveSelectionStartToPreviousWordMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionStartToPreviousWordMessage

static

Dispatch this message to move the handle at the start of text selection backward to the start of the previous word in the text string.

This message does not have any arguments.

◆ MoveSelectionEndForwardMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionEndForwardMessage

static

Dispatch this message to move the handle at the end of text selection forward by one character in the text string.

This message does not have any arguments.

◆ MoveSelectionEndBackwardMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionEndBackwardMessage

static

Dispatch this message to move the handle at the end of text selection backward by one character in the text string.

This message does not have any arguments.

◆ MoveSelectionEndToNextWordMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionEndToNextWordMessage

static

Dispatch this message to move the handle at the end of text selection forward to the start of the next word in the text string.

This message does not have any arguments.

◆ MoveSelectionEndToPreviousWordMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::MoveSelectionEndToPreviousWordMessage

static

Dispatch this message to move the handle at the end of text selection backward to the start of the previous word in the text string.

This message does not have any arguments.

◆ SelectTextMessage

MessageType<TextRangeMessageArguments> kanzi::TextBoxConcept::SelectTextMessage

static

Dispatch this message to select the text between two character indexes in the current text string.

◆ DeleteTextMessage

MessageType<TextRangeMessageArguments> kanzi::TextBoxConcept::DeleteTextMessage

static

Dispatch this message to delete the text between two character indexes in the current text string.

◆ DeleteSelectionMessage

MessageType<DeleteSelectionMessageArguments> kanzi::TextBoxConcept::DeleteSelectionMessage

static

Dispatch this message to erase any currently selected text.

This message does not have any arguments.

◆ InsertTextMessage

MessageType<TextInsertionMessageArguments> kanzi::TextBoxConcept::InsertTextMessage

static

Dispatch this message to insert given text at a given position.

◆ SelectToHomeMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::SelectToHomeMessage

static

Dispatch this message to select the text from the beginning of the text string to the cursor position.

If the Text Box has selected text, dispatching this message moves the start of the selection to the beginning of the text string.

This message does not have any arguments.

◆ SelectToEndMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::SelectToEndMessage

static

Dispatch this message to select the text from the cursor position to the end of the text string.

If the Text Box has selected text, dispatching this message moves the end of the selection to the end of the text string.

This message does not have any arguments.

◆ ClearSelectionMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::ClearSelectionMessage

static

Dispatch this message to clear the current text selection.

This message does not have any arguments.

◆ SelectAllMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::SelectAllMessage

static

Dispatch this message to select all text.

This message does not have any arguments.

◆ SelectWordAtCursorMessage

MessageType<ModifySelectionMessageArguments> kanzi::TextBoxConcept::SelectWordAtCursorMessage

static

Dispatch this message to select the word at the current cursor position.

This message does not have any arguments.

◆ EnterEditingStateMessage

MessageType<ModifyEditingStateMessageArguments> kanzi::TextBoxConcept::EnterEditingStateMessage

static

Dispatch this message to make a Text Box node enter the editing state.

This message does not have any arguments.

◆ LeaveEditingStateMessage

MessageType<ModifyEditingStateMessageArguments> kanzi::TextBoxConcept::LeaveEditingStateMessage

static

Dispatch this message to make a Text Box node leave the editing state.

This message does not have any arguments.

◆ CommitCompositionTextMessage

MessageType<TextCompositionStateMessageArguments> kanzi::TextBoxConcept::CommitCompositionTextMessage

static

Dispatch this message to make a Text Box commit the composition text.

To use this action, the Text Box must be in editing state.

◆ CancelTextCompositionMessage

MessageType<TextCompositionStateMessageArguments> kanzi::TextBoxConcept::CancelTextCompositionMessage

static

Dispatch this message to make a Text Box cancel the text composition.

To use this action, the Text Box must be in editing state.

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

kanzi/ui/node/concept/text_box.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Editing state

Setting the text content

Controlling the position of the cursor

Selecting text

Disabling a Text Box

Setting the appearance of the cursor and selected text

Showing placeholder content

Setting the width of a Text Box node

Truncating text

Member Enumeration Documentation

◆ EditMode

Member Function Documentation

◆ KZ_METACLASS_PROPERTY_TYPE()

◆ makeEditorInfo()

◆ getTextTop()

◆ getTextHeight()

◆ drawRectangle()

Member Data Documentation

◆ DisplayTextProperty

◆ CompositionTextProperty

◆ SelectionBackgroundBrushProperty

◆ SelectionForegroundBrushProperty

◆ CompositionTextBackgroundBrushProperty

◆ CompositionTextForegroundBrushProperty

◆ CursorPositionProperty

◆ SelectionStartCursorPositionProperty

◆ SelectionEndCursorPositionProperty

◆ HasSelectionProperty

◆ ReadOnlyProperty

◆ MaximumTextLengthProperty

◆ CursorPrefabProperty

◆ SelectionStartPrefabProperty

◆ SelectionEndPrefabProperty

◆ TextHintPrefabProperty

◆ HideTextHintWhenEditingProperty

◆ EchoModeProperty

◆ InputTypeProperty

◆ EditModeProperty

◆ IsEditingProperty

◆ IsComposingTextProperty

◆ CharacterCountProperty

◆ WordCountProperty

◆ PasswordEchoTimeoutProperty

◆ PasswordMaskingCharacterProperty

◆ InputMethodActionProperty

◆ TextKeyNavigationDirectionProperty

◆ InputMethodAvailableMessage

◆ InputMethodUnavailableMessage

◆ CursorMovedMessage

◆ TextChangedMessage

◆ SelectionChangedMessage

◆ SelectionStartedMessage

◆ SelectionClearedMessage

◆ EditingStartedMessage

◆ EditingFinishedMessage

◆ CompositionTextChangedMessage

◆ TextCompositionCanceledMessage

◆ CompositionTextCommittedMessage

◆ EnteredEditingStateMessage

◆ LeftEditingStateMessage

◆ InputMethodActionMessage

◆ InsertTextAtCursorMessage

◆ BackspaceAtCursorMessage

◆ BackspaceWordAtCursorMessage

◆ DeleteAtCursorMessage

◆ DeleteWordAtCursorMessage

◆ MoveCursorBackwardMessage

◆ MoveCursorForwardMessage

◆ MoveCursorToPreviousWordMessage

◆ MoveCursorToNextWordMessage

◆ MoveCursorHomeMessage

◆ MoveCursorToEndMessage

◆ MoveSelectionStartForwardMessage