TextInput
This module handles text input.
Unlike a lot of other games and projects, this module is designed to make text input seamless, like a tranditional text editor. This involves moving the cursor around, selecting and inserting text, and using the clipboard.
Many keybinds are implemented. Cut, copy and paste are supported, as well as selecting all text. Ctrl+arrows are also implemented for word navigation.
Multi-line input fields are supported, as well as single-line fields which submit on enter. The system is also UTF-8 aware.
Methods
TextInput.attachInput(tbl: string[], options: (TextInput.inputOptions)?)
Arguments:
| tbl: string[] | |
| options: (TextInput.inputOptions)? |
TextInput.checkSelecting()
return #1:
| "selecting"
| "stopped"
| "not_selecting"
Returns:
| 1: "not_selecting"|"selecting"|"stopped" |
TextInput.draw(options: (TextInput.drawOptions)?)
Draw the current text input, with the cursor.
@param options — The options table. While optional, it won't be very pretty by default.
Arguments:
| options: (TextInput.drawOptions)? | The options table. While optional, it won't be very pretty by default. |
TextInput.getNextWordEnd()
Get the end of the next word.
@return position — The end position of the next word.
Returns:
| position: integer | The end position of the next word. |
TextInput.getPreviousWordStart()
Get the start of the previous word.
@return position — The start position of the previous word.
Returns:
| position: integer | The start position of the previous word. |
TextInput.insertString(str: string)
Insert a string where the cursor is currently positioned.
Used for pretty much everything which needs to insert text, like typing, pasting, etc.
Arguments:
| str: string |
TextInput.reset()
Reset the text input system.
This does NOT change the system's options.
TextInput.sendCursorToEnd()
Sends the cursor to the end of the input.
TextInput.sendCursorToEndOfLine()
Sends the cursor to the end of the current line.
TextInput.sendCursorToStart()
Sends the cursor to the start of the input.
TextInput.sendCursorToStartOfLine(to_indent: boolean?)
Sends the cursor to the start of the line. If to_indent is true, it will first go to the end of the indent.
@param to_indent — Whether or not the cursor should go to the end of an indent first. Defaults to false.
Arguments:
| to_indent: boolean? | Whether or not the cursor should go to the end of an indent first. Defaults to false. |
TextInput.setOptions(options: (TextInput.inputOptions)?)
Set the system's options.
This does not reset the system, and should be used alongside {@link TextInput.reset}, or anything which calls it.
@param options — The new options to use. If nil, the default options are used.
Arguments:
| options: (TextInput.inputOptions)? | The new options to use. If nil, the default options are used. |
TextInput.submit()
This is internally called when you submit your input.
If you want to run custom code on submit, use the submit callback.
TextInput.update()
The update function, to update the cursor timer.
Fields
TextInput.active: boolean
Whether text input is active or not.
TextInput.allow_overtyping: boolean
Whether overtyping is allowed.
TextInput.clear_after_submit: boolean
Whether the input should be cleared after submitting.
TextInput.cursor_select_x: integer
The X position of where a selection started.
TextInput.cursor_select_y: integer
The Y position of where a selection started.
TextInput.cursor_x: integer
The current cursor X position.
TextInput.cursor_x_tallest: integer
The "tallest" (furthest to the right) cursor X position (used for multiline).
TextInput.cursor_y: integer
The current cursor Y position.
TextInput.down_limit_callback: fun()?
A callback that is called when the cursor reaches the bottom of the input.
TextInput.enter_submits: boolean
Whether pressing enter submits the input.
TextInput.flash_timer: number
A timer for flashing the cursor.
TextInput.input: string[]
A reference to an input table.
TextInput.multiline: boolean
Whether this input is multiline.
TextInput.overtyping: boolean
Whether overtyping is active or not.
TextInput.pressed_callback: (fun( string)boolean|nil)?
A callback that is called when a key is pressed.
TextInput.return_grace_timer: number
The timer that blocks immediate return submission.
TextInput.selecting: boolean
Whether selection is active or not.
TextInput.submit_callback: fun()?
A callback that is called when the input is submitted.
TextInput.text_callback: fun( string)?
A callback that is called when text is inputted.
TextInput.text_restriction: (fun( string)boolean|string)?
A function which restricts (and transforms) the text input.
TextInput.up_limit_callback: fun()?
A callback that is called when the cursor reaches the top of the input.