Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.IText

The IText property interface.

This interface represents a generic way to describe an object used for text output.


Table members

Methods


GetFontResourceTarget()

Get a constant Graph::IFontResourceTarget container. This method returns a constant pointer to a Graph::IFontResourceTarget container, which allows to query the font resources referenced by a node implementing this interface.

Murl.Graph.IGenericResourceTarget.ResourceIFont GetFontResourceTarget()

Returns
Murl.Graph.IGenericResourceTarget.ResourceIFont The constant Graph::IFontResourceTarget container, or null if not available

SetSystemFontName(fontName)

Set the ID of the system font used to render the text.

Boolean SetSystemFontName(String fontName)

Parameters
fontNameA valid system font name, e.g. "SansBold".
Returns
Boolean true if successful.

GetSystemFontName()

Get the ID of the system font used to render the text.

String GetSystemFontName()

Returns
String The predefined system font ID.

SetFontType(fontType)

Set the type of font used for rendering. If not specified, the actual font type is retrieved from the given values for either system font name or the font resource. Once initialized, the node's font type cannot be changed anymore.

Boolean SetFontType(Murl.IEnums.FontType fontType)

Parameters
fontTypeThe font type.
Returns
Boolean true if successful.

GetFontType()

Get the type of font used for rendering.

Murl.IEnums.FontType GetFontType()

Returns
Murl.IEnums.FontType The font type.

SetFontSize(fontSize)

Set the font size.

Boolean SetFontSize(Number fontSize)

Parameters
fontSizeThe font size in system units.
Returns
Boolean true if successful.

GetFontSize()

Get the font size.

Number GetFontSize()

Returns
Number The font size in system units.

SetTextColor(textColor)

Set the foreground (text) color used for rendering the text.

Boolean SetTextColor(Murl.Color textColor)

Parameters
textColorThe text color.
Returns
Boolean true if successful.

GetTextColor()

Get the text color.

Murl.Color GetTextColor()

Returns
Murl.Color The text color.

SetBackgroundColor(backgroundColor)

Set the background color used for rendering.

Boolean SetBackgroundColor(Murl.Color backgroundColor)

Parameters
backgroundColorThe background color.
Returns
Boolean true if successful.

GetBackgroundColor()

Get the background color.

Murl.Color GetBackgroundColor()

Returns
Murl.Color The background color.

GetParentTextNodeTarget()

Get the optional constant Graph::ITextNodeTarget parent container. This method returns a constant pointer to a Graph::ITextNodeTarget container, which allows to query the parent text node that is used as a source for the displayed text.

Murl.Graph.IGenericNodeTarget.GraphIText GetParentTextNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphIText The constant Graph::ITextNodeTarget parent container, or null if not available

GetOutputTextureNodeTarget()

Get the optional constant output Graph::ITextureNodeTarget container. This method returns a constant pointer to a Graph::ITextureNodeTarget container, which allows to query the texture node that is used as an optional output surface for the displayed text.

Murl.Graph.IGenericNodeTarget.GraphITexture GetOutputTextureNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITexture The constant output Graph::ITextureNodeTarget container, or null if not available

GetTextResourceTarget()

Get a constant Graph::ITextResourceTarget container. This method returns a constant pointer to a Graph::ITextResourceTarget container, which allows to query the text resources referenced by a node implementing this interface.

Murl.Graph.IGenericResourceTarget.ResourceIText GetTextResourceTarget()

Returns
Murl.Graph.IGenericResourceTarget.ResourceIText The constant Graph::ITextResourceTarget container, or null if not available

SetText(text)

Set the text to be displayed.

Boolean SetText(String text)

Parameters
textA string containing the text to be displayed.
Returns
Boolean true if successful.

GetText()

Get the displayed text.

String GetText()

Returns
String A constant reference to the string representing the displayed text.

SetSpacing(spacing)

Set the character spacing value. This method sets the character spacing used for output, i.e. the horizontal distance between neighbored characters. The given spacing value adds to the default value specified in the font used for rendering this text; a value of 0.0 represents the font's original spacing, a positive value increases the horizontal distance between characters, and a negative value decreases it.

Note: The given spacing value is not scaled by the font used; if e.g. a positive value is used for a large font, the same value used with a smaller version of that same font will result in a (relatively) larger distance between characters. It is however influenced by a possible additional scaling operation performed by a text rendering object.

Boolean SetSpacing(Number spacing)

Parameters
spacingThe character spacing value.
Returns
Boolean true if successful.

GetSpacing()

Get the character spacing value.

Number GetSpacing()

Returns
Number The character spacing value.

SetLeading(leading)

Set the leading value. This method sets the leading value used for output, i.e. the vertical distance between subsequent text lines. The given leading value adds to the default value specified in the font used for rendering this text; a value of 0.0 represents the font's original leading, a positive value increases the vertical distance between lines, and a negative value decreases it.

Note: The given leading value is not scaled by the font used; if e.g. a positive value is used for a large font, the same value used with a smaller version of that same font will result in a (relatively) larger distance between lines. It is however influenced by a possible additional scaling operation performed by a text rendering object.

Boolean SetLeading(Number leading)

Parameters
leadingThe leading value.
Returns
Boolean true if successful.

GetLeading()

Get the leading value.

Number GetLeading()

Returns
Number The leading value.

SetEmbolding(strength)

Set the embolding strength value. The embolding strength determines the "boldness" or "weight" of the font's rendered glyphs. Positive values result in thicker lines, and negative values can be used to make the font "thinner". Useful values are in the range from -1 to +1, but can also lie beyond that range.

Note that not all types of fonts allow glyph embolding. If not supported, this method returns false.

Boolean SetEmbolding(Number strength)

Parameters
strengthThe embolding strength value.
Returns
Boolean true if successful.

GetEmbolding()

Get the embolding strength value.

Number GetEmbolding()

Returns
Number The embolding strength value.

SetBlur(strength)

Set the blur strength value.

Boolean SetBlur(Number strength)

Parameters
strengthThe positive blur strength value.
Returns
Boolean true if successful.

GetBlur()

Get the blur strength value.

Number GetBlur()

Returns
Number The blur strength value.

SetSpaceWidthFactor(factor)

Set the space width factor. This method sets a factor used to control the actual width of the white space character. In some cases, it is useful to manually control the space character's width, when a font's default space width produces too small or too big a distance between subsequent words. A space width factor of 1.0 represents the original width defined by the font used for rendering.

Boolean SetSpaceWidthFactor(Number factor)

Parameters
factorThe space width factor.
Returns
Boolean true if successful.

GetSpaceWidthFactor()

Get the space width factor.

Number GetSpaceWidthFactor()

Returns
Number The space width factor.

SetDigitWidthFactor(factor)

Set the digit width factor. This method sets a factor used to control the horizontal advance of all digit characters of a font ('0'-'9'). A digit width factor of 1.0 represents the original width defined by the font used for rendering.

Note, that this value only influences distance and not visual width; a value of e.g. 0.1 will result in overlapping digits without actually scaling them.

Boolean SetDigitWidthFactor(Number factor)

Parameters
factorThe digit width factor.
Returns
Boolean true if successful.

GetDigitWidthFactor()

Get the digit width factor.

Number GetDigitWidthFactor()

Returns
Number The digit width factor.

SetSameDigitWidthEnabled(enabled)

Enable/disable unified digit width. For certain use cases, such as a score counter in an action game, it is useful to set a common width for all digits ('0'-'9'); doing so prevents the counter from jittering due to different digit widths.

Boolean SetSameDigitWidthEnabled(Boolean enabled)

Parameters
enabledIf true, all digits use the same horizontal advance value.
Returns
Boolean true if successful.

IsSameDigitWidthEnabled()

Check if unified digit width is enabled.

Boolean IsSameDigitWidthEnabled()

Returns
Boolean true if all digits use the same horizontal advance value.

SetWordWrappingEnabled(enabled)

Enable/disable word wrapping.

Boolean SetWordWrappingEnabled(Boolean enabled)

Parameters
enabledIf true, word wrapping is enabled.
Returns
Boolean true if successful.

IsWordWrappingEnabled()

Check if word wrapping is enabled.

Boolean IsWordWrappingEnabled()

Returns
Boolean true if word wrapping is enabled.

SetTextAlignmentX(alignment)

Set the horizontal text alignment.

Boolean SetTextAlignmentX(Murl.IEnums.TextAlignmentX alignment)

Parameters
alignmentThe horizontal text alignment.
Returns
Boolean true if successful.

GetTextAlignmentX()

Get the horizontal text alignment.

Murl.IEnums.TextAlignmentX GetTextAlignmentX()

Returns
Murl.IEnums.TextAlignmentX The horizontal text alignment.

SetTextAlignmentY(alignment)

Set the vertical text alignment.

Boolean SetTextAlignmentY(Murl.IEnums.TextAlignmentY alignment)

Parameters
alignmentThe vertical text alignment.
Returns
Boolean true if successful.

GetTextAlignmentY()

Get the vertical text alignment.

Murl.IEnums.TextAlignmentY GetTextAlignmentY()

Returns
Murl.IEnums.TextAlignmentY The vertical text alignment.

QueryTextSize(text, sizeX, sizeY)

Query the dimensions of a given UTF8 text.

Boolean, Number, Number QueryTextSize(String text, Number sizeX, Number sizeY)

Parameters
textThe text to query
sizeXA reference to a Real variable receiving the horizontal text size.
sizeYA reference to a Real variable receiving the vertical text size.
Returns
Boolean true if successful.
Number sizeX A reference to a Real variable receiving the horizontal text size.
Number sizeY A reference to a Real variable receiving the vertical text size.