UE3:UIString (UDK)

Object >> UIRoot >> UIString

Package: 

Engine

Within class: 

UIScreenObject

Direct subclasses:

UIEditboxString, UIListString, UIPreviewString

This class in other games:

UT3

UIString is the core renderable entity for all data that is presented by the UI. UIStrings are divided into one or more UIStringNodes, where each node corresponds to either normal text or markup data. Markup data is defined as text that will be replaced by some data retrieved from a data store, referenced by DataStoreName:PropertyName. Markup can change the current style: <Styles:NormalText>, can enable or disable a style attribute: <Attributes:B> <Attributes:/B>, or it can indicate that the markup should be replaced by the value of the property from the data store specified in the markup: <SomeDataStoreName:PropertyName>. UIStrings dynamically generate UIStringNodes by parsing the input text. For example, passing the following string to a UIString generates 7 tokens: "The name specified '<SceneData:EnteredName>' is not available. Press <ButtonImages:IMG_A> to continue or <ButtonImages:IMG_B> to cancel." The tokens generated correspond to: (0)="The name specified '" (1)=" <SceneData:EnteredName>" (2)="' is not available. Press " (3)="<ButtonImages:IMG_A>" (4)=" to continue or " (5)="<ButtonImages:IMG_B>" (6)=" to cancel."

The source text for a UIString must be specified outside of the UIString itself. There is no such thing as a stand-alone UIString. When used in a label, for example, the property which contains the text which will be used in the label is specified by the UILabel. This value may contain references to other data sources using markup, but UIStrings cannot be bound to a data store by themselves. When used in a list, the element cell will be responsible for giving the UIString its source text.

Todo: UIString is supposed to support persistence, so that designers can override the extents for individual nodes in the string, so it should not be marked transient

Properties

Nodes

Type: array<pointer{FUIStringNode}>

Modifiers: native, transient

The text nodes contained by this UIString. Each text node corresponds to a single atomically renderable element, such as a string of text, an inline image (like a button icon), etc.

StringExtent

Type: Object.Vector2D

Modifiers: transient

the width and height of the entire string

StringStyleData

Type: UIRoot.UICombinedStyleData

Modifiers: transient

The default style that will be used for initializing the styles for all nodes contained by this string. Initialized using the owning widget's style, then modified by any per-widget style customizations enabled for the widget.

Native functions

ContainsMarkup

native final function bool ContainsMarkup () const

Returns:

TRUE if this string's value contains markup text

GetAutoScaleValue

native final function GetAutoScaleValue (Object.Vector2D BoundingRegionSize, Object.Vector2D StringSize, out Object.Vector2D out_AutoScalePercent) const

Retrieves the configured auto-scale percentage.

Parameters:

• BoundingRegionSize - the bounding region to use for determining autoscale factor (only relevant for certain auto-scale modes).
• StringSize - the size of the string, unwrapped and non-scaled; (only relevant for certain auto-scale modes).
• out_AutoScalePercent - receives the autoscale percent value.

GetValue

native final function string GetValue (optional bool bReturnProcessedText) const

Returns the complete text value contained by this UIString, in either the processed or unprocessed state.

Parameters:

• bReturnProcessedText - Determines whether the processed or raw version of the value string is returned. The raw value will contain any markup; the processed string will be text only. Any image tokens are converted to their text counterpart.

Returns:

the complete text value contained by this UIString, in either the processed or unprocessed state.

SetValue

native final virtual function bool SetValue (string InputString, bool bIgnoreMarkup)

Parses a string containing optional markup (such as tokens and inline images) and stores the result in Nodes.

Parameters:

• InputString - A string containing optional markup.
• bIgnoreMarkup - if TRUE, does not attempt to process any markup and only one UITextNode is created

Returns:

TRUE if the string was successfully parsed into the Nodes array.