Skip to content

input_api.md

Latest commit

 

History

History
307 lines (219 loc) · 7.52 KB

input_api.md

File metadata and controls

307 lines (219 loc) · 7.52 KB

druid.input API

at /druid/extended/input.lua

Basic Druid text input component. Handles user text input via component with button and text.

Setup

Create input component with druid: input = druid:new_input(button_node_name, text_node_name, keyboard_type)

Notes

  • Input component handles user text input. Input contains button and text components
  • Button needed for selecting/unselecting input field
  • Click outside of button to unselect input field
  • On focus lost (game minimized) input field will be unselected
  • You can setup max length of the text
  • You can setup allowed characters. On add not allowed characters on_input_wrong will be called

Functions

Fields

init

input:init(click_node, text_node, [keyboard_type])
  • Parameters:
    • click_node (node): Node to enabled input component
    • text_node (druid.text|node): Text node what will be changed on user input. You can pass text component instead of text node name Text
    • [keyboard_type] (constant|nil): Gui keyboard type for input field

get_text_selected

input:get_text_selected()
  • Returns:
    • `` (string|unknown):

get_text_selected_replaced

input:get_text_selected_replaced(text)

Replace selected text with new text

  • Parameters:

    • text (string): The text to replace selected text

  • Returns:

    • new_text (string): New input text

set_text

input:set_text([input_text])

Set text for input field

  • Parameters:
    • [input_text] (string?): The string to apply for input field, if nil - will be set to empty string

select

input:select()

Select input field. It will show the keyboard and trigger on_select events

unselect

input:unselect()

Remove selection from input. It will hide the keyboard and trigger on_unselect events

get_text

input:get_text()

Return current input field text

  • Returns:
    • text (string): The current input field text

set_max_length

input:set_max_length(max_length)

Set maximum length for input field. Pass nil to make input field unliminted (by default)

  • Parameters:

    • max_length (number): Maximum length for input text field

  • Returns:

    • self (druid.input): Current input instance

set_allowed_characters

input:set_allowed_characters(characters)

Set allowed charaters for input field. See: https://defold.com/ref/stable/string/ ex: [%a%d] for alpha and numeric ex: [abcdef] to allow only these characters ex: [^%s] to allow only non-space characters

  • Parameters:

    • characters (string): Regular expression for validate user input

  • Returns:

    • self (druid.input): Current input instance

reset_changes

input:reset_changes()

Reset current input selection and return previous value

  • Returns:
    • self (druid.input): Current input instance

select_cursor

input:select_cursor([cursor_index], [start_index], [end_index])

Set cursor position in input field

  • Parameters:

    • [cursor_index] (number|nil): Cursor index for cursor position, if nil - will be set to the end of the text
    • [start_index] (number|nil): Start index for cursor position, if nil - will be set to the end of the text
    • [end_index] (number|nil): End index for cursor position, if nil - will be set to the start_index

  • Returns:

    • self (druid.input): Current input instance

move_selection

input:move_selection(delta, is_add_to_selection, is_move_to_end)

Change cursor position by delta

  • Parameters:

    • delta (number): side for cursor position, -1 for left, 1 for right
    • is_add_to_selection (boolean): (Shift key)
    • is_move_to_end (boolean): (Ctrl key)

  • Returns:

    • self (druid.input): Current input instance

Fields

  • on_input_select (event): fun(self: druid.input, input: druid.input) The event triggered when the input field is selected

  • on_input_unselect (event): fun(self: druid.input, text: string, input: druid.input) The event triggered when the input field is unselected

  • on_input_text (event): fun(self: druid.input) The event triggered when the input field is changed

  • on_input_empty (event): fun(self: druid.input) The event triggered when the input field is empty

  • on_input_full (event): fun(self: druid.input) The event triggered when the input field is full

  • on_input_wrong (event): fun(self: druid.input) The event triggered when the input field is wrong

  • on_select_cursor_change (event): fun(self: druid.input, cursor_index: number, start_index: number, end_index: number) The event triggered when the cursor index is changed

  • style (druid.input.style): The style of the input component

  • druid (druid.instance): The Druid Factory used to create components

  • text (druid.text|node): Basic Druid text component. Text components by default have the text size adjusting.

  • is_selected (boolean)

  • value (unknown)

  • previous_value (unknown)

  • current_value (unknown)

  • marked_value (string)

  • is_empty (boolean)

  • text_width (integer)

  • market_text_width (integer)

  • total_width (integer)

  • cursor_index (integer)

  • start_index (number)

  • end_index (number)

  • max_length (nil)

  • allowed_characters (nil)

  • keyboard_type (constant)

  • button (druid.button): Basic Druid input component. Handle input on node and provide different callbacks on touch events.

  • marked_text_width (number)