Kanzi  3.9.7
Kanzi Engine API
kanzi::TextEditBuffer Class Reference

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
dataUTF-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
dataUTF-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
dataUTF-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
positionCharacter position at which to insert the string text.
textString 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
beginCharacter position where the erasing begins.
endCharacter 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
textThe 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
echoModeThe 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
passwordMaskThe 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
revealCensoredCharacterAtCursorIndicates 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
maxLengthMaximum 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
beginCharacter position for the start index of the substring to return.
endCharacter 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
positionThe 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
startThe start position of the text selection.
endThe 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: