TextEditBuffer is a model for text input. More...

#include <kanzi/core.ui/text/text_edit_buffer.hpp>

Public Member Functions
void	append (string_view data)
	Appends UTF-8 data to the TextEditBuffer. More...

void	clear ()
	Clears the content of the TextEditBuffer, and cancels text composition. More...

void	clearSelection ()
	Clears the text highlight. More...

void	erase (size_t begin, size_t end)
	Moves the cursor to position begin and erases UTF-8 characters from the TextEditBuffer between positions begin and end. More...

string	getCachedText () const
	Returns the string that contains the cached data of the TextEditBuffer. More...

size_t	getCursorPosition () const
	Returns the position of the cursor. More...

size_t	getLength () const
	Returns the number of UTF-8 characters in the TextEditBuffer. More...

size_t	getMaximumTextLength () const
	Returns the text buffer length limit. More...

string_view	getSelectedText () const
	Returns the text that is currently selected. More...

size_t	getSelectionEnd () const
	Returns the ending point of the selected text. More...

size_t	getSelectionStart () const
	Returns the starting point of the selected text. More...

string_view	getSubString (size_t begin, size_t end) const
	Gets a substring of a TextEditBuffer. More...

bool	hasSelection () const
	Returns whether any of the text is selected. More...

void	insert (size_t position, string_view text)
	Moves the cursor to a given position and inserts text to that position. More...

bool	isEmpty () const
	Returns true if the text buffer is empty, false otherwise. More...

void	selectText (size_t start, size_t end)
	Selects the text between the start and end positions. More...

void	setCursorPosition (size_t position)
	Sets the position of the cursor in the text buffer. More...

void	setData (string_view data)
	Assigns new UTF-8 data to the TextEditBuffer. More...

bool	setMaximumTextLength (size_t maxLength)
	Sets the text buffer length limit. More...

	TextEditBuffer ()=default
	Default constructor. More...

	TextEditBuffer (string_view data)
	Constructor. More...

Text composition functions

void	startTextCompositionAtCursor ()
	Makes the TextEditBuffer enter the text composition state at the cursor position. More...

void	updateCompositionText (string_view text)
	Updates the composition text. More...

void	commitCompositionText ()
	Commits the composition text. The TextEditBuffer must be in the text composition state. More...

void	cancelTextComposition ()
	Cancels the composition. The TextEditBuffer must be in the text composition state. More...

bool	isComposingText () const
	Returns the text composition state of the TextEditBuffer. More...

pair< size_t, size_t >	getTextCompositionEndpoints () const
	Returns the text composition endpoints. The TextEditBuffer must be in the text composition state. More...

string_view	getCompositionText () const
	Returns the composition text. More...

Text display functions
EchoMode	getEchoMode () const
	Returns the echo mode that the TextEditBuffer uses to format the display text. More...

void	setEchoMode (EchoMode echoMode)
	Sets the echo mode to use to format the display text. More...

string_view	getPasswordMaskingCharacter () const
	Returns the character that masks input characters when the echo mode is set to EchoMode::Password. More...

void	setPasswordMaskingCharacter (string_view passwordMask)
	Sets the character that masks input characters when the echo mode is set to EchoMode::Password. More...

string	getDisplayText () const
	Returns a displayable text that is built from the text buffer using the echo mode of the Text Box node. More...

string	getDisplayText (bool revealCensoredCharacterAtCursor) const
	Returns a displayable text that is built from the text buffer using the echo mode of the Text Box node. More...

Detailed Description

TextEditBuffer is a model for text input.

It contains both the cached text as well as the edited text, and operates on the edited text. TextEditBuffer holds text editing information, such as the UTF-8 data, cursor position, text selection or composition text highlight, and text composition state.

The TextEditBuffer operates in these states:

In the normal state the buffer contains only the text that is committed. You can select, insert, and delete text, and move the cursor in the text buffer.
In the text composition state you can insert temporary text into the text buffer, which you later either commit to the text buffer, or discard by canceling the text composition. This temporary text is called the composition text.

While the TextEditBuffer is in the text composition state, the cursor and highlight positions reflect the positions in the composition text, in context with the cached text. During text composition use only the Text composition functions.

You cannot move the cursor within the composition text. Moving the cursor during text composition commits the composition text.

After committing the composition text, or canceling the composition, the TextEditBuffer returns to the normal state.

Since: Kanzi 3.9.0

Constructor & Destructor Documentation

kanzi::TextEditBuffer::TextEditBuffer ( )

explicitdefault

Default constructor.

kanzi::TextEditBuffer::TextEditBuffer ( string_view data )

explicit

Constructor.

Parameters

data	UTF-8 data that the TextEditBuffer stores and operates.

Member Function Documentation

void kanzi::TextEditBuffer::setData ( string_view data )

Assigns new UTF-8 data to the TextEditBuffer.

This resets the cursor position to the end of the text buffer and removes text highlight.

Do not call this method while the TextEditBuffer is in the text composition state.

Parameters

data	UTF-8 data to assign to the TextEditBuffer.

void kanzi::TextEditBuffer::append ( string_view data )

Appends UTF-8 data to the TextEditBuffer.

If the cursor position is at the end of the text buffer before appending data, the cursor moves to the end of the new text buffer content. If the cursor position marks the endpoint of a text highlight, that highlight is cleared. In any other circumstances, the cursor position does not change.

Do not call this method while the TextEditBuffer is in the text composition state.

Parameters

data	UTF-8 data to append to the TextEditBuffer.

void kanzi::TextEditBuffer::insert	(	size_t	position,
		string_view	text
	)

Moves the cursor to a given position and inserts text to that position.

After inserting the text, the cursor is in the end of the inserted text. When the text has selection, if position is between the selection start and end positions, Kanzi replaces the selected text with text and removes the selection.

Do not call this method while the TextEditBuffer is in the text composition state.

Parameters

position	Character position at which to insert the string text.
text	String to insert at character position position.

void kanzi::TextEditBuffer::erase	(	size_t	begin,
		size_t	end
	)

Moves the cursor to position begin and erases UTF-8 characters from the TextEditBuffer between positions begin and end.

Do not call this method while the TextEditBuffer is in the text composition state.

Parameters

begin	Character position where the erasing begins.
end	Character position where the erasing ends.

void kanzi::TextEditBuffer::startTextCompositionAtCursor ( )

Makes the TextEditBuffer enter the text composition state at the cursor position.

void kanzi::TextEditBuffer::updateCompositionText ( string_view text )

Updates the composition text.

The TextEditBuffer must be in the text composition state.

Parameters

text	The composition text to update.

void kanzi::TextEditBuffer::commitCompositionText ( )

Commits the composition text. The TextEditBuffer must be in the text composition state.

void kanzi::TextEditBuffer::cancelTextComposition ( )

Cancels the composition. The TextEditBuffer must be in the text composition state.

bool kanzi::TextEditBuffer::isComposingText ( ) const

Returns the text composition state of the TextEditBuffer.

Returns: If the TextEditBuffer contains composition text, returns true, otherwise false.

pair<size_t, size_t> kanzi::TextEditBuffer::getTextCompositionEndpoints ( ) const

Returns the text composition endpoints. The TextEditBuffer must be in the text composition state.

string_view kanzi::TextEditBuffer::getCompositionText ( ) const

Returns the composition text.

Returns: The composition text. If the TextEditBuffer is not in the text composition state, returns an empty string.

EchoMode kanzi::TextEditBuffer::getEchoMode ( ) const

Returns the echo mode that the TextEditBuffer uses to format the display text.

Returns: The echo mode that the TextEditBuffer uses to format the display text.

See also: getDisplayText()

void kanzi::TextEditBuffer::setEchoMode ( EchoMode echoMode )

Sets the echo mode to use to format the display text.

Parameters

echoMode The echo mode to use to format the display text.

string_view kanzi::TextEditBuffer::getPasswordMaskingCharacter ( ) const

Returns the character that masks input characters when the echo mode is set to EchoMode::Password.

Returns: The password masking character.

void kanzi::TextEditBuffer::setPasswordMaskingCharacter ( string_view passwordMask )

Sets the character that masks input characters when the echo mode is set to EchoMode::Password.

Parameters

passwordMask The password masking character to use.

string kanzi::TextEditBuffer::getDisplayText ( ) const

Returns a displayable text that is built from the text buffer using the echo mode of the Text Box node.

Returns: The displayable text that is built from the text buffer using the echo mode of the Text Box node.

string kanzi::TextEditBuffer::getDisplayText ( bool revealCensoredCharacterAtCursor ) const

Returns a displayable text that is built from the text buffer using the echo mode of the Text Box node.

Parameters

revealCensoredCharacterAtCursor Indicates whether to reveal the password character at the cursor position when echo mode is set to EchoMode::Password. To mask all password characters in the text edit buffer, pass false. To reveal the password character at the cursor position, pass true.

Returns: The displayable text that is built from the text buffer using the echo mode of the Text Box node.

void kanzi::TextEditBuffer::clear ( )

Clears the content of the TextEditBuffer, and cancels text composition.

Sets the cursor and text highlight positions to 0.

size_t kanzi::TextEditBuffer::getLength ( ) const

Returns the number of UTF-8 characters in the TextEditBuffer.

Returns: Number of UTF-8 characters in the TextEditBuffer. If the TextEditBuffer is in the text composition state, the length contains also the length of the composition text.

bool kanzi::TextEditBuffer::isEmpty ( ) const

Returns true if the text buffer is empty, false otherwise.

If the TextEditBuffer is in the text composition state, the method returns true if there is no composition text in the buffer, otherwise returns false.

size_t kanzi::TextEditBuffer::getMaximumTextLength ( ) const

Returns the text buffer length limit.

Returns: Maximum number of UTF-8 characters allowed in the input text buffer. If this value is 0, the length of the text buffer is unlimited.

bool kanzi::TextEditBuffer::setMaximumTextLength ( size_t maxLength )

Sets the text buffer length limit.

The method affects text composition as well as the cached content.

Parameters

maxLength Maximum number of UTF-8 characters allowed in the input text buffer. To remove the limit, use 0.

Returns: If setting the limit changes the content of the text buffer, returns true, otherwise false.

See also: getMaximumTextLength()

string_view kanzi::TextEditBuffer::getSubString	(	size_t	begin,
		size_t	end
	)		const

Gets a substring of a TextEditBuffer.

If the TextEditBuffer is in the text composition state, returns a substring of the entire composition data.

Parameters

begin	Character position for the start index of the substring to return.
end	Character position for the end index of the substring to return.

string kanzi::TextEditBuffer::getCachedText ( ) const

Returns the string that contains the cached data of the TextEditBuffer.

Returns: The cached data of the TextEditBuffer, that is the text that consists of data committed during text composition.

size_t kanzi::TextEditBuffer::getCursorPosition ( ) const

Returns the position of the cursor.

Returns: The cursor position. If any text is selected, the cursor position marks the endpoint of the text selection.

void kanzi::TextEditBuffer::setCursorPosition ( size_t position )

Sets the position of the cursor in the text buffer.

If any text is selected, calling this method clears the text selection.

Do not call this function when the TextEditBuffer is in the text composition state.

Parameters

position The new position of the cursor.

void kanzi::TextEditBuffer::selectText	(	size_t	start,
		size_t	end
	)

Selects the text between the start and end positions.

The lesser value of the start and end positions becomes the start index of the selection and the greater value becomes the end index of the selection.

Do not call this method while the TextEditBuffer is in the text composition state.

Parameters

start	The start position of the text selection.
end	The end position of the text selection. If the selection succeeds, the cursor moves to this position.

string_view kanzi::TextEditBuffer::getSelectedText ( ) const

Returns the text that is currently selected.

Returns: The part of the text that is selected.

bool kanzi::TextEditBuffer::hasSelection ( ) const

Returns whether any of the text is selected.

Returns: If part of the text is selected, true, otherwise false.

size_t kanzi::TextEditBuffer::getSelectionStart ( ) const

Returns the starting point of the selected text.

Returns: The starting point of the selected text. If no text is selected, or the TextEditBuffer is in the text composition state, the method returns the cursor position.

size_t kanzi::TextEditBuffer::getSelectionEnd ( ) const

inline

Returns the ending point of the selected text.

Returns: The endpoint of the selected text, which is the same as the cursor position.

void kanzi::TextEditBuffer::clearSelection ( )

Clears the text highlight.

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

kanzi/core.ui/text/text_edit_buffer.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation