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.

Blocks and Positioning

This section covers functions for structuring your text layout.

rt(text_or_attributes[, text = nil])

Wraps a block of text into Lua rich text. Only call this once for the whole text that gets sent to the backend. There is no general need to wrap an rt tag around your text, because the backend will take care of it. So, only use this function if you wish to add some attributes to the tag.

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)

Adds a horizontal space

Parameters:gap – the size of the space as pixels.
Returns:a space tag
vspace(gap)

Adds a vertical space

Parameters:gap – the size of the space as pixels.
Returns:a vspace tag

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

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)

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
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, former_textdomain)

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

e.g. localize_list({“foo”, “bar”, “baz”}, “or”, “widelands”) 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 “,”
  • former_textdomain – The textdomain to restore after running this function.
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/menu_toggle_menu.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

Return to index