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'. If alpha is zero or not defined, FF is assumed. |
|
<selectioncolor
>
...
</selectioncolor>
|
The color used to hilight selected text in the form '#aarrggbb' |
|
<underlineoffset
/>
|
Specifies the distance from the font baseline to set the text underline when underlining is enabled. If the default attribute is set to "on", then text underlining is enabled on initialization. |
|
<lineoffset
/>
|
Specifies the distance from the font baseline to set the control underline when control underlining is enabled. If the default attribute is set to "on", then control underlining is enabled on initialization. |
|
</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
getFont
function getFont(
)
Retrieves the name of the font resource used when rendering the contents of the control.
Return values
(string)
The name of a font resource
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.
setColor
function setColor(
color
)
Sets the color used when rendering the contents of the control. This setting overrides the color defined in the font used. To restore
the use of font resource color, specify nil as the parameter value.
The specified parameter is a color value in a HTML-style string representation, in the format "#AARRGGBB". The components are hexadecimal
digits specifying the value of the alpha (transparency), red, green and blue channels, respectively, in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.
Parameters
color (string)
The color to be used, or nil to reset the setting. See above for details on the string format.
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
setFont
function setFont(
fontname
)
Sets the name of the font resource used to render the text in the control.
Parameters
fontname (string)
The name of a font resource
setLine
function setLine(
state, offset
)
Sets the line flag.
Parameters
state (boolean)
A value of true indicates the entire control should be underlined. A value of false disables control underlining.
offset (number)
Specifies the distance from the font baseline to set the control underline
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 0 (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. The value
zero indicates that the selection should be cleared.
Parameters
index (number)
The desired selection marker position in the range 0 to (string length) + 1
setUnderline
function setUnderline(
state, offset
)
Sets the underline flag.
Parameters
state (boolean)
A value of true indicates the text should be underlined. A value of false disables text underlining.
offset (number)
Specifies the distance from the font baseline to set the text underline
setValue
function setValue(
value
)
Set the text in the control.
Parameters
value (string)
The new value for the text content
