Trait ITextBoxConcept

pub trait ITextBoxConcept: Inherits<Object> + Inherits<TextBoxConcept> {
Show 56 methods    // Provided methods
    fn get_display_text(&self) -> Result<KanziString, Error> { ... }
    fn set_display_text(&self, value: impl AsRef<KanziStr>) -> Result<(), Error> { ... }
    fn get_composition_text(&self) -> Result<KanziString, Error> { ... }
    fn set_composition_text(
        &self,
        value: impl AsRef<KanziStr>,
    ) -> Result<(), Error> { ... }
    fn get_selection_background_brush(
        &self,
    ) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_selection_background_brush(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_selection_foreground_brush(
        &self,
    ) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_selection_foreground_brush(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_composition_text_background_brush(
        &self,
    ) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_composition_text_background_brush(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_composition_text_foreground_brush(
        &self,
    ) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_composition_text_foreground_brush(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_cursor_position(&self) -> Result<i32, Error> { ... }
    fn set_cursor_position(&self, value: i32) -> Result<(), Error> { ... }
    fn get_selection_start_cursor_position(&self) -> Result<i32, Error> { ... }
    fn set_selection_start_cursor_position(
        &self,
        value: i32,
    ) -> Result<(), Error> { ... }
    fn get_selection_end_cursor_position(&self) -> Result<i32, Error> { ... }
    fn set_selection_end_cursor_position(&self, value: i32) -> Result<(), Error> { ... }
    fn get_has_selection(&self) -> Result<bool, Error> { ... }
    fn set_has_selection(&self, value: bool) -> Result<(), Error> { ... }
    fn get_read_only(&self) -> Result<bool, Error> { ... }
    fn set_read_only(&self, value: bool) -> Result<(), Error> { ... }
    fn get_maximum_text_length(&self) -> Result<i32, Error> { ... }
    fn set_maximum_text_length(&self, value: i32) -> Result<(), Error> { ... }
    fn get_cursor_prefab(&self) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_cursor_prefab(&self, value: Option<&Resource>) -> Result<(), Error> { ... }
    fn get_selection_start_prefab(
        &self,
    ) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_selection_start_prefab(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_selection_end_prefab(&self) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_selection_end_prefab(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_text_hint_prefab(&self) -> Result<Option<Weak<Resource>>, Error> { ... }
    fn set_text_hint_prefab(
        &self,
        value: Option<&Resource>,
    ) -> Result<(), Error> { ... }
    fn get_hide_text_hint_when_editing(&self) -> Result<bool, Error> { ... }
    fn set_hide_text_hint_when_editing(&self, value: bool) -> Result<(), Error> { ... }
    fn get_echo_mode(&self) -> Result<EchoMode, Error> { ... }
    fn set_echo_mode(&self, value: EchoMode) -> Result<(), Error> { ... }
    fn get_input_type(&self) -> Result<InputType, Error> { ... }
    fn set_input_type(&self, value: InputType) -> Result<(), Error> { ... }
    fn get_edit_mode(&self) -> Result<EditMode, Error> { ... }
    fn set_edit_mode(&self, value: EditMode) -> Result<(), Error> { ... }
    fn get_is_editing(&self) -> Result<bool, Error> { ... }
    fn set_is_editing(&self, value: bool) -> Result<(), Error> { ... }
    fn get_is_composing_text(&self) -> Result<bool, Error> { ... }
    fn set_is_composing_text(&self, value: bool) -> Result<(), Error> { ... }
    fn get_character_count(&self) -> Result<i32, Error> { ... }
    fn set_character_count(&self, value: i32) -> Result<(), Error> { ... }
    fn get_word_count(&self) -> Result<i32, Error> { ... }
    fn set_word_count(&self, value: i32) -> Result<(), Error> { ... }
    fn get_password_echo_timeout(&self) -> Result<i32, Error> { ... }
    fn set_password_echo_timeout(&self, value: i32) -> Result<(), Error> { ... }
    fn get_password_masking_character(&self) -> Result<KanziString, Error> { ... }
    fn set_password_masking_character(
        &self,
        value: impl AsRef<KanziStr>,
    ) -> Result<(), Error> { ... }
    fn get_input_method_action(&self) -> Result<InputMethodAction, Error> { ... }
    fn set_input_method_action(
        &self,
        value: InputMethodAction,
    ) -> Result<(), Error> { ... }
    fn get_text_key_navigation_direction(
        &self,
    ) -> Result<TextKeyNavigationDirection, Error> { ... }
    fn set_text_key_navigation_direction(
        &self,
        value: TextKeyNavigationDirection,
    ) -> Result<(), Error> { ... }
}

Expand 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.