Help markup

Help Markup

This page documents the markup used by the Rich Label widget. This is a markup language based on the Pango markup already being used by other GUI2 widgets to show formatted text, combined with features of the earlier GUI1 help markup. Specifically, you can add links, tables and images (inline and floating) alongside formatted text.

Both GUI1 style syntax (<img>src='path/to/myimage.png'</img>) and newer HTML style syntax (<img src='path/to/myimage.png'/>) are supported. The new syntax is recommended. The internal parser doesn't support nested tags when using the old syntax.

Tags

The form of a tag roughly follows HTML, with one significant exception – standalone tags with no content must have a slash before the closing angle bracket. Since the markup language is usually embedded in WML, which uses double quotes, it's recommended to use single quotes in the markup for attribute values. The quotes are optional when the value contains no spaces, however.

The old GUI1 tag style places the attributes inside the tag contents, instead of in the tag header (ie, after the > instead of before it). This format is not compatible with Pango and is thus not recommended.

Tags can be nested arbitrarily deep, as long as only the HTML-style syntax is used.

Escapes

There are two ways of escaping characters in the help markup. The simplest is to precede the character with a backslash. Whenever a backslash is encountered, it is removed, and the following character is taken as literal even if it would usually have a special meaning.

The other way is to use XML character entities. The markup supports the following character entities:

&	Ampersand (&)
"	Double quote (")
'	Apostrophe (')
&lt;	Left angle bracket (<)
&gt;	Right angle bracket (>)
&#ddd;	Unicode character given by decimal ddd
&#xhhhh;	Unicode character given by hexadecimal hhhh

Specific Tags

Formatting Tags

• bold/b: Makes the text bold.
• italic/i: Makes the text italic.
• underline/u: Adds an underline to text.
• header/h: Shows the text formatted as a heading (serif font at size 20 and color white).
• span/format: Applies various types of formatting to the marked up text. Similar to the Pango span tag, but only the following attributes are supported:
  • face/font_family
  • size/font_size
  • color/fgcolor/foreground
  • bgcolor/background
  • weight: Supported values are thin, light, normal (default), semibold, bold, heavy. Depends on selected font family.
  • style: Supported values are italic, oblique, normal (default). Depends on selected font family.

For documentation on these attributes of span/format, please see the Pango docs.

Image Tags

• img: Inserts an image, whose path is specified by the src attribute.
  • src: WML path of the image to be shown, i.e., units/drakes/armageddon.png
  • float: Whether the image is to be shown as a floating image anchored to the current line with text wrapped around it or as an inline image block between paragraphs. Inline mode is default.
  • align: Horizontal alignment of the image with respect to the page. Supported values: left (default), right or middle/center. middle/center only supports single inline images at the moment.

Note:

1. Consecutive images with no text characters in between them will be stacked horizontally for inline images and stacked vertically for floating images. middle/center alignment does not support stacking.
2. Inline image automatically generate a linebreak before them, but not after them. To insert a linebreak between an image and the following text, just start the text with a linebreak character ('\n').

Links

• ref: Insert a link. The name of the link is the value specified inside <ref> and </ref>.
  • dst: Destination of the link.

Rich Label by itself does nothing when the link is clicked. It is upto the dialog that uses the rich label to attach a link handler callback function to the rich label via the register_link_callback (C++) or on_link_click (Lua) functions. When a link is clicked, the callback function set via register_link_callback or on_link_click will be called with the appropriate name and dst values for the clicked link.

Table Tags

• table: Starts the table.
  • width: (optional) Width of the table (in pixels) or the special value fill. If set to fill, the table will stretch to fill available width. If width is not set, the table will try to fit itself in the minimum area based on the size of its contents.
  • row: (subtag) Contains the contents of a row, which are one or more columns.
    • bgcolor: (optional) A hex string #rrggbb that specifies the background color of the row.
    • padding: (optional) Two numbers separated by space 10 10. The first is the top padding while the second is the bottom padding. These are applied to the whole row.
    • valign: (optional) Vertical alignment of the row contents. Allowed values: bottom, center/middle. If value is not specified or is wrong, aligns to top instead.
    • col: (subtag) Contains the contents of a column, which can be any tag mentioned earlier, such as formatting tags, image tag, links and so on.
      • padding: (optional) Two numbers separated by space 10 10. The first is the left padding while the second is the right padding. This is applied to the cell.
      • halign: (optional) Horizontal alignment of the cell. Allowed values: right, center/middle. If value is not specified or is wrong, aligns to left instead.

Spaces in between table and row or between row and col tags are ignored, but spaces inside col tag are significant and will be shown in the output. Note also that each row must contain the same number of columns.

See the example below for usage.

Example:

• Select All

<table width='400'>
    <row>
        <col>Hello</col><col>Hello2</col><col>Hello3</col>
    </row>
    <row>
        <col>Hello</col><col>Hello2</col><col>Hello3</col>
    </row>
</table>