UIText

UIText is the GUI object used for containing and rendering text. It is one of the more complicated UI Objects to work with.

UIText takes the following attributes:

fontfamily
This defines which font should be used via a string argument. The fonts are defined in fontfamily.xml. The 'name' attribute for the different UIFontFamily elements in fontfamily.xml is how they are identified here. If this attribute is not set, then the text field will use the 'Default' font family defined in fontfamily.xml.

nextcontrol
Which control should have focus if the user hits tab while editing this UIText field. It only really makes sense to put UIText field names as the arguments to this attribute, as focus doesn't have any significant meaning for any other type of UIObject. Note that the nextcontrol must be in the same UIScene as this text field.

prevcontrol
Which control should have focus if the user hits shift+tab while editing this UIText field. It only really makes sense to put UIText field names as the arguments to this attribute, as focus doesn't have any significant meaning for any other type of UIObject. Note that the prevcontrol must be in the same UIScene as this text field.

filter
This attribute can be used to limit what text the user can enter into this text field when editing it. By default, any input character is valid. It takes strings as its arguments. The following strings are handled:
alpha - Only letters can be entered in this field.
numeric - Only numbers can be entered in this field.
alphanumeric - Only letters and numbers can be entered in this field.
signed_numeric - Only numbers in this field, except the '-' character, which may only be entered at the front of the string.

maxnumber
This number limits the max number that a user can enter when editing this text field. It only means anything if the text field's filter is set to numeric or signed_numeric.

allowspace
If this attribute is false, then any space characters will not be allowed in this field, including tabs or newlines. It defaults to false.

allowpunc
This attribute only means anything if the filter type is set to alpha or alphanumeric. It allows graphical punctuation characters to be entered in the text field. If no filter type is specified, then this attribute doesn't do anything. It defaults to false, so must be set to true if the intent is to allow users to enter punctuation style characters into this text field.

password
Defaults to false. If set to true, then the characters in this string will be replaced with * marks when this text field gets rendered.

sanitized
Defaults to false. If this attribute is set to true, then any string entered in this text field will be run through the built in swear-filter.

style
This is a modifier to the font that is being used. It takes a string or number as its argument. The following arguments are supported:
normal - Or style 1. This is defined by the UIFontNormal element in fontfamily.xml
bold - Or style 2. This is defined by the UIFontBold element in fontfamily.xml
italic - Or style 3. This is defined by the UIFontItalic element in fontfamily.xml
bolditalic - Or style 4. This is defined by the UIFontBoldItalic element in fontfamily.xml

indent
This is the number of pixels to indent the first line of any text. It defaults to 0.

hangingindent
This is the number of pixels to indent all lines besides the first line in a multi-line text field. It defaults to 0.

align
This is how the text should be aligned in the text field. The following string arguments are handled: left, right, center. Defaults to left.

hilite
Defaults to false. If set true, then the text in this text field will hilight when moused over.

valign
This is how the text should be aligned vertically within the text field. The following string arguments are handled: top, bottom, middle. Defaults to top.

poscenter
This attribute is defunct and no longer does anything.

sizetofit
Defaults to false. If set to true, then the text field will extend its height downward as far as possible in order to contain the length of text within it. This is an old attribute and should be replaced by just setting the height of the text field to DYNAMIC.

buttonoverlay
This only means anything if the text field is a child element of a UIButton element. If left to the default of false, then this text field will become the normal text field that shows up in buttons. If set to true, it becomes Overlay Text. At this time, Overlay Text can only be manipulated by the engine.

editable
Defaults to false. If set to true, then the user can edit the text within this text field by clicking it to place their cursor and typing like normal.

selectable
This attribute does nothing at this time.

maxlines
The max number of lines this text field can contain. Setting this attribute to '1' will keep the engine from trying to break the text into multiple lines. Text that will not fit into the text field after the maximum number of lines has been reached will not get rendered. If not defined, the engine will try to wrap a string and fit it into the space available no matter what, which can sometimes result in no text at all appearing due to spacing errors.

multiline
This attribute toggles whether or not a user can hit enter to start a new line of text within a editable text field. It requires that allowspaces be also set to true or else it will seem to do nothing. It defaults to false. When false, the OnReturn callback will get called when the user hits enter, instead of a new line being inserted.

returnrestricted
This attribute can be a bit confusing. It defaults to false and only means anything when used with multiline=true. What happens is that if this attribute is set to 'true', the text field will accept multiple lines of input and wrap them automatically, but if the user hits their return key, the OnReturn callback gets called instead of inserting a newline. An example of this behavior can be found in the chat input box.

uppercase
Defaults to false. If true, all text rendered in this text field will be rendered in uppercase.

maxlength
This limits the number of characters that can be typed into a text field by the user. Once the user has entered the max limit of characters, no additional characters can be input. If no maxlength is set, the user can keep typing indefinitely.

color
A color to blend with all of the characters within the text field. This can sometimes conflict with the use of the color tags in text fields.

highlightcolor
This attribute defines the color that should be blended with the text when doing a mouse-over style highlight.

selectioncolor
This attribute does nothing at this time.

highlightonmouseover
This is just a clone of the hilite attribute mentioned above.

text
This is for hard coding the text that should show up in this text field. Overrides strref.

strref
This is for coding which string ref should show up in the text field. It is overridden by text.

OnReturn
This callback gets executed when the user hits Enter while the cursor is in this text field. Note that if the text field is set with multiline=true and restrictedreturn=false, then this callback will not get executed.

OnLostFocus
This callback is executed when the cursor is taken out of the text field due to the user clicking elsewhere.