EmuInput

A class for creating a text input field element.

Two input fields which the user may type a player name into.

Constructor

Inheritance: EmuCore / EmuCallback

EmuInput(x, y, w, h, text, value, help_text, character_limit, input_type, callback)

Parameter	Type	Description
x	real	The x coordinate where the list will be created
y	real	The y coordinate where the list will be created
w	real	The width of the list
h	real	The height of the list
text	string	The title of the list
value	string	The starting value of the text box
help_text	string	Text that will be displayed if the text box is empty
character_limit	real	The maximum number of characters that you may type into the text box
input_type	E_InputTypes	The type of input the text box will accept
callback	function	The callback that will be invoked when the value inside the input box is changed

Text input will be validated on each keystroke (for more information, see E_InputTypes). Pressing the Enter key will clear the input value. If the input value is empty, the help_text string will be drawn instead, although it will not actually be part of the input string.

Note that this is not a "true" text field and other common operations such as selecting, copying, pasting, and moving the insertion point are not currently supported.

Relevant Methods

EmuInput::SetInputBoxPosition(vx1, vy1, vx2, vy2)

Returns: self

Parameter	Type	Description
vx1	real	The x coordinate of the upper-left corner of the input box
vx2	real	The y coordinate of the upper-left corner of the input box
vy1	real	The x coordinate of the lower-right corner of the input box
vy2	real	The y coordinate of the lower-right corner of the input box

By default the box which the user types text into occupies the rightmost half of the EmuInput element's bounding box, but in some cases - such as large multi-line input boxes, or small input boxes which only accept a few characters - you may wish to set the location of the box yourself.

EmuInput::SetValue(value)

Returns: self

Parameter	Type	Description
value	string	The new value which you would like to assign to the input box

Sets the value inside the input box. If you pass it a value that is not a string it will be converted into a string.

EmuInput::SetRealNumberBounds(lower, upper)

Returns: self

Parameter	Type	Description
lower	real	The lower bound for number value types
upper	real	The upper bound for number value types

Define the lower and upper bounds for real-number input types (integers, real numbers and hex numbers). If lower is greater than upper, the values will be switched automatically. This will not affect string input types.

EmuInput::SetMultiLine(multi_line)

Returns: self

Parameter	Type	Description
multi_line	boolean	Whether or not the text box will recognize multiple lines

If asking the user for a particularly long input string, e.g. a character bio or an item or monster description, you may wish for the input box to be able to wrap and display more than one line. Additionally, enabling this will allow the Enter key to add a line break unless the input box is set to require the Enter key for submission.

When this setting is enabled, a character counter will be drawn in the bottom-right corner of the box to indicate how many characters remain.

EmuInput::SetRequireConfirm(confirm)

Returns: self

Parameter	Type	Description
confirm	boolean	Whether or not the text box will require the Enter key to process the updated value

In some cases, you may only wish for the input value to be processed and the callback to be invoked when the Enter key is pressed rather than every time the text in the box changes. To indicate to the user that this setting is enabled, an icon will be drawn on the right side of the box.

Note that enabling this setting will prevent the Enter key from adding a line break in multi-line text boxes.

Example

var input = new EmuInput(32, 32, 256, 32, "Enter integer:", "15", "0 - 100", 3, E_InputTypes.INT, function() {
    show_debug_message("The current input value: " + value);
});
input.SetRealNumberBounds(0, 100);

container.AddContent(input);

This will create an EmuInput element and which accepts integers from 0 through 100 and adds it to a previously-created container.

Helper Functions

There are several helper functions to go with EmuInputs. These are not necessary for using the framework, although you may find them useful in your own code.

emu_string_hex(value, [padding])

Returns: string

Parameter	Type	Description
value	real	The real number value you would like to convert to a hexadecimal string
[padding]	real	(optional) The number of characters to pad the string out to

Converts a number to a string, represented by a hexidecimal number. Essentially a base-16 equivalent to string(). If you specify a padding value, leading 0s will be added until the string is of the specified length; this can be useful for formatting things such as color values.

emu_hex(str)

Parameter	Type	Description
str	string	The string value you would like to convert to a number

Converts a string representing a hexidecimal number to a real number. Essentially a base-16 equivalent to real(). This function is case-insensitive.

If the string is not a valid hexadecimal number (i.e. it contains characters other than 0 through 9 and a through f) it will throw an EmuException.