EditBox

The EditBox is the generic text-input window element.

Summary

EditBox	The EditBox is the generic text-input window element.
Implementation Details	While in focus, the edit box will show a blinking cursor and trap (and display) all keyboard input.
XML Definition	This is the EditBox xml definition.
XML Tag
Required Attributes	You need to specify valid values for all of these elements to get the ComboBox to create properly.
font	The name of the Font definition to use.
Optional Attributes	These are optional.
maxchars	The maximum number of characters allowed to be displayed.
scrollbar	The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .
background	The name of a FullResizeImage to use as a background.
linespacing	An override value for the font line spacing.
password	The edit box should work like a password box and display asterisk instead of the actual characters typed.
scrolling	The scrolling mode to use.
input	The type of input this EditBox should accept.
history	The size of the input history (tracked automatically when the enter key is pressed) to track.
Elements
MenuButtonOffset	The offset of the menu buttons within their background.
Elements
TextColor	The color for the text.
TextOffset	The offset for the text within the EditBox dimensions.
Window Callbacks	These are the EditBox specific callback events.
Callbacks
OnTextChanged	Called when the the text inside the edit box changes.
Functions
Functions
EditBoxSetText()	Sets the text currently displayed.
EditBoxGetText()	Returns the text currently displayed.
EditBoxGetTextLines()	Returns the text currently displayed.
Functions
Functions
EditBoxInsertText()	Inserts text at the current cursor location.
EditBoxSetTextColor()	Sets the color for the text display.
EditBoxGetTextColor()	Returns the current text color for the display.
TextEditBoxSelectAll()	Selects all of the text.
EditBoxSetFont()	Sets the font for the text display
EditBoxGetFont()	Returns the name of the font currently used.
EditBoxGetHistory()	Returns the input history for the EditBox.
EditBoxSetHistory()	Sets the input history for the edit box.
EditBoxSetHandleKeyDown()	Allows you to disable text from automatically being added to the EditBox display when a key is pressed.

Implementation Details

While in focus, the edit box will show a blinking cursor and trap (and display) all keyboard input.

You can set focus to an edit box by manually calling <WindowSetFocus()>, or by clicking on it with the mouse.

Scrolling Modes

The edit box can be created in two separate scrolling modes.

horizontal	The text will always remain on one line and scroll left->right based on your cursor position.
vertical	The text will line wrap and and scroll once it reaches the end of the box. ( NOTE: Scrolling is currently broken - text will not extend beyond the bottom of the box)

Input Restrictions

You can restrict an edit box only to accept a certain type of input.

”all”	Accept all characters.
”nospaces”	Accepts all character except for spaces.
”text”	Accepts only text.
”numbers”	Accepts only numbers.

Keyboard Commands

Basic Arrow Keys	Moves you cursor left, right, up, and down in the text.
Shift Up/Down Arrow	Moves backward/forward through the input history.
Shift Left/Right Arrow	Selects character to the left/right of the cursor.
Shift-Control Left/Right Arrow	Selects the entire word to the left/right of the cursor.
Control Left/Right Arrow	Moves the cursor one word to the left/right.
Home Key	Moves the cursor to the beginning of the text.
Shift Home Key	Selects all the text between the cursor location and the beginning of the text.
End Key	Moves the cursor to the end of the text.
Shift End Key	Selects all the text between the cursor location and the end of the text.
Delete Key	Deletes the selected text, or the text immediately after the cursor.
Backspace Key	Deletes the selected text, or the text immediately before the cursor.
Control Backspace Key	Deletes the entire word before the cursor.
Enter Key	Adds the current text to the input history (if a history size is specified). You are responsible for handling the <OnKeyEnter()> event to clear the text if that is the desired behavior
Control-A	Selects all of the text.
Control-C	Copies the selected text to the Window’s Clipboard.
Control-V	Pastes text currently on the Window’s Clipboard into the EditBox.
Control-X	Cuts the selected text to the Window’s Clipboard.

XML Definition

This is the EditBox xml definition.

Summary

XML Tag
Required Attributes	You need to specify valid values for all of these elements to get the ComboBox to create properly.
font	The name of the Font definition to use.
Optional Attributes	These are optional.
maxchars	The maximum number of characters allowed to be displayed.
scrollbar	The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .
background	The name of a FullResizeImage to use as a background.
linespacing	An override value for the font line spacing.
password	The edit box should work like a password box and display asterisk instead of the actual characters typed.
scrolling	The scrolling mode to use.
input	The type of input this EditBox should accept.
history	The size of the input history (tracked automatically when the enter key is pressed) to track.
Elements
MenuButtonOffset	The offset of the menu buttons within their background.
Elements
TextColor	The color for the text.
TextOffset	The offset for the text within the EditBox dimensions.

XML Tag

<EditBox>
....
</EditBox>

Required Attributes

You need to specify valid values for all of these elements to get the ComboBox to create properly.

font

The name of the Font definition to use.

Expects

A string value of a valid Font.

Optional Attributes

These are optional. You can use whichever apply to the EditBox you are creating.

maxchars

The maximum number of characters allowed to be displayed.

Expects

A number greater than 0.

Default Value

scrollbar

The name of a <VerticalScrollBar> to use if the text exceeds the height of the window when in .

Expects

A string value, which is the name of a valid Button.

Default Value

””

Notes

Scrollbars are currently broken for edit boxes

background

The name of a FullResizeImage to use as a background.

Expects

A string value, which is the name of a valid FullResizeImage.

Default Value

””

Notes

none

linespacing

An override value for the font line spacing.

Expects

A number. If 0, the font height is used.

Default Value

password

The edit box should work like a password box and display asterisk instead of the actual characters typed.

Expects

A boolean value.

”true”	Display asterisk.
”false”	Display the actual text.

Default Value

”false”

scrolling

The scrolling mode to use.

Expects

A string value, that is one of the following:

”vert”	Word-wrap the text.
”horiz”	Scroll the text horizontally on one line.

Default Value

”horiz”

input

The type of input this EditBox should accept.

Expects

A string value, that is one of the following:

”all”	Accept all characters.
”nospaces”	Accepts all character expect for spaces.
”text”	Accepts only text.
”numbers”	Accepts only numbers.

Default Value

”all”

history

The size of the input history (tracked automatically when the enter key is pressed) to track.

Expects

A number value, 0 through n. Indicating the history length.

Default Value

0, no history

Elements

MenuButtonOffset

The offset of the menu buttons within their background.

Syntax

<MenuButtonOffset x="10" y="10" />

x	The x-pixel offset from the top left corner of the menu background.
y	The y-pixel offset from the top left corner of the menu background.

Defaults

x	0
y	0

Notes

The menu button size will dictate the size of the background. The offset*2 will be added to the menu background dimensions.

Elements

TextColor

The color for the text.

Syntax

<TextColor r="255" g="255" b="255"  />

r	The red color value
g	The green color value
b	The blue color value

Defaults

r	255
g	255
b	255

TextOffset

The offset for the text within the EditBox dimensions. This allows you restrict the text to only the center portion.

Syntax

<TextOffset x="5" y="10" />

x	The x-pixel offset from the top left corner.
y	The y-pixel offset from the top left corner.

Defaults

x	0
y	0

Notes

The offset is The distance subtraced from both the top/bottom and left/right edges of the EditBox.

Window Callbacks

These are the EditBox specific callback events.

Summary

Callbacks
OnTextChanged	Called when the the text inside the edit box changes.

Callbacks

OnTextChanged

Called when the the text inside the edit box changes.

Syntax

SomeComboBox.OnTextChanged( text )

text	(wstring) The current text.

Functions

Summary

Functions
EditBoxSetText()	Sets the text currently displayed.
EditBoxGetText()	Returns the text currently displayed.
EditBoxGetTextLines()	Returns the text currently displayed.

Functions

EditBoxSetText()

Sets the text currently displayed.

Parameters

editBoxName	(string) The name of the EditBox.
text	(wstring) The text string.

Returns

nil	no return value

Notes

none

Example

TextEditBoxSetText( "LoginWindowUsername", GameData.Account.AccountName )

EditBoxGetText()

Returns the text currently displayed.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

text	(wstring) The text string.

Notes

none

Example

local currText = EditBoxGetText( "SomeEditBox" )

EditBoxGetTextLines()

Returns the text currently displayed.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

text	(wstring vector) The text string vector.

Notes

none

Example

local currText = TextEditBoxGetTextLines( "SomeEditBox" )

Functions

Summary

Functions
EditBoxInsertText()	Inserts text at the current cursor location.
EditBoxSetTextColor()	Sets the color for the text display.
EditBoxGetTextColor()	Returns the current text color for the display.
TextEditBoxSelectAll()	Selects all of the text.
EditBoxSetFont()	Sets the font for the text display
EditBoxGetFont()	Returns the name of the font currently used.
EditBoxGetHistory()	Returns the input history for the EditBox.
EditBoxSetHistory()	Sets the input history for the edit box.
EditBoxSetHandleKeyDown()	Allows you to disable text from automatically being added to the EditBox display when a key is pressed.

Functions

EditBoxInsertText()

Inserts text at the current cursor location. If any text is currently selected, the inserted text will replace it.

Parameters

editBoxName	(string) The name of the EditBox.
text	(wstring) The text string to insert.

Returns

nil	no return value

Notes

none

Example

EditBoxInsertText( "SomeEditBox", someTextToInsert )

EditBoxSetTextColor()

Sets the color for the text display.

Parameters

editBoxName	(string) The name of the EditBox.
red	(number) The red value for the text color (0-255)
green	(number) The green value for the text color (0-255)
blue	(number) The blue value for the text color (0-255)

Returns

nil = no return value

Notes

none

Example

TextEditBoxSetTextColor ("ChatWindowContainerTextInput", 255, 255, 255)

EditBoxGetTextColor()

Returns the current text color for the display.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

red	(number) The red value for the text color (0-255)
green	(number) The green value for the text color (0-255)
blue	(number) The blue value for the text color (0-255)

Notes

none

Example

local r, g, b = EditBoxGetTextColor( "SomeEditBox" )

TextEditBoxSelectAll()

Selects all of the text.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

nil = no return value

Notes

none

Example

TextEditBoxSelectAll ("ChatWindowContainerTextInput" )

EditBoxSetFont()

Sets the font for the text display

Parameters

editBoxName	(string) The name of the EditBox.
fontName	(number) The name of the font to use.
lineSpacing	(number) The line spacing value to use.

Returns

nil = no return value

Related XML

font

Notes

none

Example

EditBoxSetFont( "ChatWindowContainerTextInput", "font_default_text" )

EditBoxGetFont()

Returns the name of the font currently used.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

fontName

(number) The name of the Font.

Related XML

font

Notes

none

Example

local fontName = EditBoxGetFont("SomeWindow")

EditBoxGetHistory()

Returns the input history for the EditBox.

Parameters

editBoxName

(string) The name of the EditBox.

Returns

history

(wstring-table) The items in the history. Index 1 is the most recent item.

Related XML

font

Notes

This command is useful if you wish to save out an input history between instances of an edit box.

Example

EditBoxSetFont( "ChatWindowContainerTextInput", "font_default_text" )

EditBoxSetHistory()

Sets the input history for the edit box.

Parameters

editBoxName	(string) The name of the EditBox.
history	(wstring-table) The items in the history. Index 1 is the most recent item.

Returns

nil = no return value

Notes

This command is useful if you wish to save out an input history between instances of an edit box.

Example

TextEditBoxSetHistory("ChatWindowContainerTextInput", SystemData.UserInput.ChatHistory )

EditBoxSetHandleKeyDown()

Allows you to disable text from automatically being added to the EditBox display when a key is pressed.

Parameters

editBoxName	(string) The name of the EditBox.
handle	(boolean) The name of the EditBox.

Returns

history

(wstring-table) The items in the history. Index 1 is the most recent item.

Related XML

font

Notes

This allows you to override the key input mechanism and set your own display for the text. This is useful for creating a keybinding window.

Example

TextEditBoxSetHandleKeyDown( "KeyMappingWindowTextInput", false )