This object acts as the base interface for text elements, and is never directly instanced. This interface provides functions for manipulating the string content
as well as editing options such as cursor and selection positions.
The interface contains utility events that can be used to simulate list or table like functionality. To support this, the system should either contain controls
in a list or grid formation, or a windowlist with text controls.
Definition
<textbasecontrol
>
|
|
|
<multilinespacing
>
...
</multilinespacing>
|
If present, indicates that the text in the control should span multiple lines, with the line height indicated by the specified number value |
|
<center
/>
|
Indicates the text should be centered |
|
<font
>
...
</font>
|
Name of the font resource used |
|
<color
>
...
</color>
|
A color overriding the font default color, in the form '#aarrggbb' |
|
<selectioncolor
>
...
</selectioncolor>
|
The color used to hilight selected text in the form '#aarrggbb' |
|
</textbasecontrol>
|
|
Interface
getCursorPosition
function getCursorPosition(
)
Retrieve the position of the cursor in the control. This value varies from 1 (before the first character) to n+1 where n is the length
of the content string in characters. The value n+1 indicates that the cursor is positioned after the last character.
Return values
(number)
The cursor position in the range 1 to (string length)+1
getSelectionPosition
function getSelectionPosition(
)
Retrieve the position of the selection marker in the control. Setting the selection marker to a different position from the cursor will
cause the section of the string in the control between the selection marker and the cursor to be hilighted as selected.
This value varies from 1 (before the first character) to n+1 where n is the length of the content string in characters. The value n+1
indicates that the marker is positioned after the last character.
Return values
(number)
The selection marker position in the range 1 to (string length)+1
getValue
function getValue(
)
Retrieve the text in the control.
Return values
(string)
The text value in the control.
onChar
event
function onChar(
keycode
)
If present, this function is executed whenever the user types a character into the text field.
Parameters
keycode (number)
The key code for the typed character. The Lua function string.char can be used to convert the value
into a string.
onDeleteDown
event
function onDeleteDown(
)
If present, this function is executed whenever the user presses the delete key at the end of the text content when editing
the text. This method can be used to support list like operation for controls, e.g. implying that the entry following the one being edited
should be merged at the end of the current entry or deleted if it is empty.
onDeleteUp
event
function onDeleteUp(
)
If present, this function is executed whenever the user presses the backspace key at the beginning of the text content when editing
the text. This method can be used to support list like operation for controls, e.g. implying that the entry being edited should be merged
at the end of the preceding entry or deleted if it is empty.
onEnter
event
function onEnter(
)
If present, this function is executed whenever the user presses enter when editing the text. This method can be used to support
behaviors allowing users to enter multiple records of data using the keyboard.
Return values
(boolean)
If the event returns true, no further processing is done by the framework. If the return value
is false, the framework processes the message after the script function (finishing the edit operation or creating
a new line based on the multi line spacing property).
onNavigateDown
event
function onNavigateDown(
)
If present, this function is executed whenever the user presses the down arrow key on the last line of the text content when editing
the text. This method can be used to support list or table like operation for controls.
onNavigateLeft
event
function onNavigateLeft(
)
If present, this function is executed whenever the user presses the left arrow key at the beginning of the text content when editing
the text. This method can be used to support list or table like operation for controls.
onNavigateRight
event
function onNavigateRight(
)
If present, this function is executed whenever the user presses the right arrow key at the end of the text content when editing
the text. This method can be used to support list or table like operation for controls.
onNavigateUp
event
function onNavigateUp(
)
If present, this function is executed whenever the user presses the up arrow key on the first line of the text content when editing
the text. This method can be used to support list or table like operation for controls.
onTab
event
function onTab(
forward
)
If present, this function is executed whenever the user presses the tab key when editing the text. This method can be used to support
list or table like operation for controls. If the shift key is pressed as well, the parameter will be false
Parameters
forward (boolean)
If the tab key is pressed without the shift key being depressed, the value is true, indicating a
forward tab operation. If the shift key is depressed, the value is false indicating a backward tab operation.
setCursorPosition
function setCursorPosition(
index
)
Set the position of the cursor in the control. The valid values for this setting range from 1 (before the first character) to n+1 where
n is the length of the content string in characters. Setting the value outside this range will set the cursor to the beginning of the string.
The value n+1 indicates that the cursor should be positioned after the last character.
Parameters
index (number)
The desired cursor position in the range 1 to (string length)+1
setSelectionPosition
function setSelectionPosition(
index
)
Set the position of the selection marker in the control. Setting the selection marker to a different position from the cursor will
cause the section of the string in the control between the selection marker and the cursor to be hilighted as selected.
The valid values for this setting range from 1 (before the first character) to n+1 where n is the length of the content string in
characters. Setting the value outside this range will set the selection marker to the cursor position, resetting the selection. The value
n+1 indicates that the marker is positioned after the last character.
Parameters
index (number)
The desired selection marker position in the range 1 to (string length)+1
setValue
function setValue(
value
)
Set the text in the control.
Parameters
value (string)
The new value for the text content
