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.

If you want to use the styles of themes refer to styles.

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.

default_gap()

Looks up the size of the default gap in the style library.

Returns

the size of the default gap

space([gap])

Adds a horizontal space

Parameters

gap – the size of the space as pixels. If omitted, the default gap size will be used.

Returns

a space tag

vspace([gap])

Adds a vertical space

Parameters

gap – the size of the space as pixels. If omitted, the default gap size will be used.

Returns

a vspace tag

msg_vspace()

Adds a standard vertical space for win condition status messages.

Returns

a vspace tag with the standard gap size

Return to index

Headings and Paragraphs

This section covers functions for defining headings and paragraphs.

title(font_face, text)

Returns a paragraph formatted as a title heading. Use this only for the name of the game.

Returns

A paragraph with text formatted as title.

pagetitle(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.

subtitle(text)

Returns a paragraph formatted as a subtitle under a title heading. Use this only after title() or pagetitle().

Returns

A paragraph with text formatted as subtitle.

set_fs_style(enable)

Change the style for text headings and normal paragraphs between the in-game and the main menu styles.

Parameters

enable – If evaluates to true, then the main menu text style will be used for normal paragraphs, otherwise the in-game style.

fs_color(text)

Deprecated since version 1.2: Use set_fs_style() instead.

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

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>

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()

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>

Return to index

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

Return to index

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.

Return to index

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.

Return to index

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

Return to index

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",
body = h1(_([[Normal header]])) ..
       h1("6699ff", _([[Colored header]])) ..
       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:

sample rendering

Please try to avoid hardcoding colors and non-default spacing and sizes. Best practice is to use styles.color() to get color values and styles.get_size() to get values for spacing and other sizes from the style manager whenever possible.

Return to index