.. _stdlib_ui_text_input_component:

===========
UITextInput
===========


++++++++++++
Enumerations
++++++++++++

.. _enum-ui_text_input_component-ValidationScenario:

.. das:attribute:: ValidationScenario

Predefined validation scenarios for text input.

:Values: * **Standard** = 0 - Accepts any input.

         * **Integer** = 1 - Accepts only integer input (optional leading minus, digits only).

         * **Decimal** = 2 - Accepts decimal numbers (optional leading minus, digits, one dot).

         * **Alphanumeric** = 3 - Accepts only alphanumeric characters (letters and digits).

         * **Name** = 4 - Accepts names (letters, spaces, apostrophes, hyphens).

         * **Custom** = 5 - Uses a custom validation function provided by the user.


+++++++
Classes
+++++++

.. _struct-ui_text_input_component-UITextInput:

.. das:attribute:: UITextInput : UIComponent

.. note:: ``UIFrame``  component is automatically added to the node if it is not already present

A text input field component.

Usage example::

   def init_text_input() {
       get_component(node) $(var textInput : UITextInput?) {
           textInput.onChange = @(newText : string) { print("Text changed to {newText}") }
       }
   }

..note::
  Input is validated on every change according to the selected scenario.

:Fields: * **text** : string = "" - The current text in the input field.

         * **placeholder** : string = "" - Placeholder text when input is empty and the field is not focused.

         * **maxLength** : int = 0 - Maximum length of the input text (0 = unlimited).

         * **onChange** : lambda<(value:string):void> - Called when text changes.

         * **validationScenario** :  :ref:`ValidationScenario <enum-ui_text_input_component-ValidationScenario>`  = ui_text_input_component::ValidationScenario.Standard - Validation scenario.

         * **checkFunction** : lambda<(text:string;insertPos:int;insertStr:string):string> - Custom validation function (used if scenario is Custom).

         * **textField** :  :ref:`UIText <struct-ui_text_component-UIText>` ? - The text field component to display the current value.


.. _function-ui_text_input_component_UITextInput_rq_on_initialize_UITextInput:

.. das:function:: UITextInput.on_initialize()

Initializes the text input component and validates initial text.

.. _function-ui_text_input_component_UITextInput_rq_on_update_UITextInput:

.. das:function:: UITextInput.on_update()

Handles keyboard input when the component is focused.

.. _function-ui_text_input_component_UITextInput_rq_validate_input_UITextInput_string_int_string:

.. das:function:: UITextInput.validate_input(text: string; insertPos: int; insertStr: string) : string

Validates the input text based on the selected validation scenario.

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string

.. _function-ui_text_input_component_UITextInput_rq_invalidate_UITextInput:

.. das:function:: UITextInput.invalidate()

Updates the text field with the current text or placeholder.

+++++++++
Functions
+++++++++

  *  :ref:`validate_standard (text: string; insertPos: int; insertStr: string) : string <function-ui_text_input_component_validate_standard_string_int_string>` 
  *  :ref:`validate_integer (text: string; insertPos: int; insertStr: string) : string <function-ui_text_input_component_validate_integer_string_int_string>` 
  *  :ref:`validate_decimal (text: string; insertPos: int; insertStr: string) : string <function-ui_text_input_component_validate_decimal_string_int_string>` 
  *  :ref:`validate_alphanumeric (text: string; insertPos: int; insertStr: string) : string <function-ui_text_input_component_validate_alphanumeric_string_int_string>` 
  *  :ref:`validate_name (text: string; insertPos: int; insertStr: string) : string <function-ui_text_input_component_validate_name_string_int_string>` 

.. _function-ui_text_input_component_validate_standard_string_int_string:

.. das:function:: validate_standard(text: string; insertPos: int; insertStr: string) : string

Accepts any input.

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string

.. _function-ui_text_input_component_validate_integer_string_int_string:

.. das:function:: validate_integer(text: string; insertPos: int; insertStr: string) : string

Accepts only integer input (optional leading minus, digits only).

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string

.. _function-ui_text_input_component_validate_decimal_string_int_string:

.. das:function:: validate_decimal(text: string; insertPos: int; insertStr: string) : string

Accepts decimal numbers (optional leading minus, digits, one dot).

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string

.. _function-ui_text_input_component_validate_alphanumeric_string_int_string:

.. das:function:: validate_alphanumeric(text: string; insertPos: int; insertStr: string) : string

Accepts only alphanumeric characters (letters and digits).

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string

.. _function-ui_text_input_component_validate_name_string_int_string:

.. das:function:: validate_name(text: string; insertPos: int; insertStr: string) : string

Accepts names (letters, spaces, apostrophes, hyphens).

:Arguments: * **text** : string

            * **insertPos** : int

            * **insertStr** : string