# richtext.lua¶

Functions to simplify and unique text formatting in scenarios and help files. Most of these functions are simple wrapper functions that make working with the widelands rich text formatting system more bearable. Function names generally follow HTML names. We strongly recommend that you make use of these functions rather than hacking the tags manually. If you’re writing a scenario, you should also have a look at richtext_scenarios.lua.

To make these functions available include this file at the beginning of a script via:

include "scripting/richtext.lua"


## Blocks and Positioning¶

This section covers functions for structuring your text layout.

rt(text_or_attributes[, text = nil])

Usually, it is not necessary to wrap your text with this function. If it is missing the backend will take care of it. Wrap your text with this function if you wish to add some attributes to the whole area of text e.g. specifying a different background color for the whole area.

Wraps a block of text into Lua rich text. Only call this once for the whole text that gets sent to the backend.

Parameters
• text_or_attributes (string) – see the rt tag’s documentation for a list of attributes and their descriptions.

• text (string) – the text to be enclosed in rich text tags.

Returns

the wrapped rich text.

div(text_or_attributes[, text = nil])

Wraps a block of text into a div tag.

Parameters
• text_or_attributes – see the div tag’s documentation for a list of attributes and their descriptions.

• text (string) – the text to be enclosed in div tags.

Returns

the text wrapped in a div tag.

space(gap)

Parameters

gap – the size of the space as pixels.

Returns

a space tag

vspace(gap)

Parameters

gap – the size of the space as pixels.

Returns

a vspace tag

This section covers functions for defining headings and paragraphs.

title(font_face, text)

Returns a paragraph formatted as a title heading. Use this on the top of your document only.

Returns

A paragraph with text formatted as title.

h1(text_or_color[, text = nil])

Returns a paragraph formatted as a big heading with a small gap after it.

Returns

A paragraph with text formatted as heading.

h2(text)

Like h1() but smaller.

Returns

A paragraph with text formatted as heading.

h3(text)

Like h2() but smaller.

Returns

A paragraph with text formatted as heading.

h4(text)

Like h3() but smaller.

Returns

A paragraph with text formatted as heading.

inline_header(header, text)

Creates a line of h3 formatted text followed by normal paragraph text.

Parameters
• header – text in h3 format.

• text – text in p format.

Returns

header text followed by normal text.

p(text_or_attributes[, text = nil])

Returns one paragraph with text followed by a small vertical gap. Options can be given as first argument similar to rt().

Parameters

text_or_attributes (string) – see the p tag’s documentation for a list of attributes and their descriptions.

Returns

The text wrapped in <p>%s</p>

fs_color(text)

Returns the given text wrapped in a font tag for the default color that is used for texts in the main menu.

open_p([attributes = nil])

Returns a paragraph open tag and default font size. Options can be given as first argument similar to rt().

Parameters

attributes (string) – see the p tag’s documentation for a list of attributes and their descriptions.

Returns

<p> with added attributes and default font

close_p(t)

Closes a paragraph.

Returns

The closing tags for a paragraph

p_font(p_or_font_attributes, text_or_font_attributes[, text = nil])

Returns one paragraph with text followed by a small vertical gap. Options can be given as first argument similar to rt().

Parameters
• p_or_font_attributes (string) – Optional paragraph or font attributes.

• text_or_font_attributes (string) – Optional font attributes or the text itself.

See the p tag’s documentation for a list of paragraph attributes and the font tag’s documentation for a list of font attributes.

Returns

The text wrapped in <p attributes><font attributes>text</font></p>

## Text Formatting¶

This section covers convenience functions for text formatting.

font(attributes, text)

Wraps the text in font tags. See also p_font.

Parameters

attributes (string) – see the font tag’s documentation for a list of attributes and their descriptions.

Returns

The text wrapped in font tags with the given attributes

b(text)

This makes the text bold.

Parameters

text – the text to format

Returns

a font tag containing the bold text

i(text)

This makes the text italic.

Parameters

text – the text to format

Returns

a font tag containing the italic text

u(text)

This underlines the text.

Parameters

text – the text to format

Returns

a font tag containing the underlined text

## Lists¶

This section covers functions for defining lists.

dl(dt, dd)

This function imitates a HTML description list

Parameters
• dt – “description term”, will be rendered in bold.

• dd – “description data”, will be rendered normally.

Returns

a p tag containing the formatted text

li(text_or_symbol[, text = nil])

Adds the symbol in front of the text to create a list item and wraps it in a paragraph

Parameters
• symbol – the item symbol for the list, e.g. “•” or “→”. “•” is the default.

• text – the text of the list item

Returns

a p tag containing the formatted text

li_arrow(text)

Creates a list item with an arrow

Parameters

text – the text of the list item

Returns

li(“→”, text)

li_image(imagepath, text)

Places a paragraph of text to the right of an image

Parameters
• imagepath (string) – the full path to the image file

• text (string) – the text to be placed next to the image

Returns

the text wrapped in a paragraph and placed next to the image, the outer tag is a div.

li_object(name, text[, playercolor])

Places a paragraph of text to the right of an image representing the given map object

Parameters
• name (string) – the name of the map object to be represented by an image

• text (string) – the text to be placed next to the image

• playercolor (string) – a playercolor to be applied to the image, in hex notation

Returns

the text wrapped in a paragraph and placed next to the image, the outer tag is a div.

## Images¶

This section covers functions for including images.

img(src[, attributes = nil])

Turns an image src path into an image tag for richtext. See also li_image.

Parameters
• src (string) – the file path to the image.

• attributes (string) – see the img tag’s documentation for a list of attributes and their descriptions.

Returns

the img tag.

img_object(object[, attributes = nil])

Creates a richtest image tag for the given map object type. See also li_object.

Parameters
• name (string) – the name of the map object.

• attributes (string) – see the img tag’s documentation for a list of attributes and their descriptions.

Returns

the img tag.

## Text Composition¶

This section covers functions for text composition that help with proper markup to make the text translatable.

join_sentences(sentence1, sentence2)

Joins 2 sentences together. Use this rather than manually concatenating a blank space, because some languages don’t use blank spaces.

Parameters
• sentence1 – text of the first sentence

• sentence2 – text of the second sentence

Returns

two concatenated sentences with a localized sentence joiner.

localize_list(items, listtype)

Turns an array of string items into a localized string list with appropriate concatenation.

e.g. localize_list({“foo”, “bar”, “baz”}, “or”) will return _”foo, bar or baz”

Parameters
• items – An array of strings

• listtype – The type of concatenation to use. Legal values are “&”, “and”, “or”, and “,”

Returns

The concatenated list string, using localized concatenation operators.

Same algorithm as in src/base/i18n

## Code Example¶

Here’s an example on how these functions and their attributes can be used. The double dot (..) is the LUA string concatenation operator. Note that this example also includes translation markup (the _[[Some text]] or _"Some text" function):

include "scripting/richtext.lua"

title = "Text Formatting",
p(_[[Normal paragraph, just with a bit more text to show how it looks like.]]) ..
p("align=center", _[[A centered paragraph, just with a bit more text to show how it looks like.]]) ..
li_image("images/wui/menus/statistics.png", _[[An image with right aligned text. This is just text to show automatic line breaks and behavior in regard with images]]) ..
li(_[[A list item]]) ..
li(font("color=6699ff bold=1", _[[Blue and bold]])) ..
li_arrow(_[[A list item with an arrow]]) ..
p(_[[A more complicated paragraph with ]] ..
font("color=ffffff", _[[white text ]]) ..
_[[and ]] ..
font("italic=1 bold=1", _[[bold italic formatted text.]])
),


This results in the following for a campaign message box: