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
Headings and Paragraphs
Text Formatting
Lists
Images
Links
Text Composition
Code Example

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

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

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

Links¶

This section covers functions for including hyperlinks.

a(linktext, linktype, target[, action=nil][, mouseover=target|linktext])¶

This function creates a hyperlink.

Parameters

linktext (string) – The text to display.
linktype (string) – Type of the link. Use "ui" for internal links and "url" for external (browser) links.
target (string) – The name of the UI element to notify or the URL to open.
action (string or nil) – Only valid for UI links. The action the UI element should perform.
mouseover (string) – The text to show on mouse hovering. This defaults to the target for URLs or the linktext for other links; use "" to disable.

Returns

The linkified and underlined text.

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:

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

richtext.lua¶

Blocks and Positioning¶

Headings and Paragraphs¶

Text Formatting¶

Lists¶

Images¶

Links¶

Text Composition¶

Code Example¶

Table of Contents

Previous topic

Next topic

This Page