ui text formatting

Text rendered by the Windower UI library can be fully formatted.

Using Formatting Strings

Text formatting is accomplished by attaching a formatting string to the part of the text that you want to format.

Inside the text string itself, wrap the text that you want to format in brackets [], and append the formatting string in curly braces {}.

local formatted_text = '[text to format]{formatting_string}'

The formatting string itself consists of a series of optional tokens that may be specified in any order.

typeface size stretch weight style strikethrough underline color stroke

When the values are unambiguous, the token name may be omitted. In cases where the values may be ambiguous, include the token name and value, separated by a colon. For example: color:red.

For values that include spaces, or for tokens that require multiple values, use quotes to surround the values. For example: typeface:"Courier New" or stroke:"2px black".

Example: Fully-defined, unambiguous formatting string

local format = 'typeface:Arial size:20px stretch:normal weight:bold style:italic strikethrough:false underline:false color:red stroke:"2px black"'

In practice, this can normally be greatly simplified because most token values are inherently unambiguous.

local format = 'Arial 20px bold italic red stroke:"2px black"'

In-Line Formatting

Formatting strings may also be nested within other formatted text, allowing you to perform in-line formatting.

Example: Nested formatting strings

local nested = '[all of the text is italic but [this text]{bold} is also bold]{italic}'

ui.text(nested)

Simulated Output:

all of the text is italic but this text is also bold

Supported Formatting Tokens

The following tokens may be included in a formatting string, in any order:

typeface string

The typeface used for the text. Enclose typefaces with spaces in the name in quotes.

For example: 'Courier New'

size number or string

The size of the text. May be specified as an absolute value, or a string with an attached unit.

For example: 12 or 30px

Supported units: px, pt, pica, %

stretch string [default: normal]

The degree to which the font is stretched horizontally.

Supported token values, from narrowest to widest:

• ultra_condensed
• extra_condensed
• condensed
• semi_condensed
• normal
• medium
• semi_expanded
• expanded
• extra_expanded
• ultra_expanded

Note: Support for each token value is dependent on the specified font. Not all fonts contain variants for each stretch value.

weight string [default: normal]

The density of the typeface, in terms of the lightness or heaviness of the stroke.

Supported token values, from lightest to heaviest:

• thin
• extra_light
• ultra_light
• light
• semi_light
• normal
• regular
• medium
• demi_bold
• semi_bold
• bold
• extra_bold
• ultra_bold
• black
• heavy
• extra_black
• ultra_black

Note: Support for each token value is dependent on the specified font. Not all fonts contain variants for each weight value.

style string [default: normal]

The style of the font face.

Supported tokens:

• normal
• oblique
• italic

Note: Support for each token is dependent on the specified font. Not all fonts contain variants for each style value.

strikethrough boolean [default: false]

Whether the text has a horizontal strike line through it.

Include the strikethrough token for true, exclude it for false.

underline boolean [default: false]

Whether the text is underlined.

Include the underline token for true, exclude it for false.

color color_value [default: white]

The color of the text.

Supported values:

• RGB(A) hex code : For example, #FF000099 or #FF00CC
• keyword token : For example, red

For a complete list of supported color keyword tokens, see the CSS Color Keywords.

stroke size and color_value [default: none]

The outside stroke to apply to the text. The supported values are the same as those for the size and color components.

Note: The stroke token must always be specified unambiguously.

For example: stroke:"2px black"