Help markup

Help Markup (1.19+)

This page documents the new 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.

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 (')
`<`	Left angle bracket (<)
`>`	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: Supported values: monospace, script; sans-serif if not specified (default).
- size/font_size: Must be an integer. (differs from Pango)
- color/fgcolor/foreground: Can be a hex string #rrggbb that specifies the color of the text, or a color name recognized by font::string_to_color.
- bgcolor/background: Can be a hex string #rrggbb that specifies the background color of the text, or a color name recognized by font::string_to_color.
- 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. IPFs are also supported here.
- 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. Only supported for floating images.

clear: When just after a floating images, moves text below it instead of the text wrapping around the image. This tag contains no content, so it can be written as <clear/>.

Note:

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.
Inline images work as custom glyphs, so linebreaks/whitespace works just like they do for text.

Links

ref: Insert a link. The name of the link is the value specified inside <ref> and </ref>.
- dst: Destination of the link. Can be any text.

Rich Label by itself does nothing when the link is clicked. It is up to 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, or a color name recognized by font::string_to_color, or any color names defined in [rich_label_definition][resolution][colors], like here.
  - padding: (optional) One number or two numbers separated by space 10 10. The first is the top padding while the second is the bottom padding. If only one number if specified, it's used for both top and 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 center 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) One number or two numbers separated by space 10 10. The first is the left padding while the second is the right padding. If only one number if specified, it's used for both left and right padding. This is applied to the cell.
    - halign: (optional) Horizontal alignment of the cell. Allowed values: right, center/middle, left. 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>

Help Markup (Pre 1.19)

The markup that is allowed in the text key within a topic tag is in a WML-like markup language with angle brackets.

It consists of plain text, interrupted with markup tags. Between paired start and end tags (like <jump> ... </jump>) you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a text key. You can't nest tags within another tag.

The following key/tags are accepted inside text (source):

<ref>: creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
- dst: the ID of the topic to reference.
- text: the text to display as a link to dst; i.e. when text is clicked on the page dst will be linked to.
- force: shows the cross reference even though the referred topic is not shown.
<jump>: when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.
- to: the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.
- amount: the number of pixels to jump forward
<img>: insert an image in the topic
- src: the path to the image relative to the images/ directory.
- align: the position of the image with respect to the page. Values are here, left, middle, and right.
- float: whether the image should float(have text filled in around it) or not (be seen as included in a line).
<format>: describes a group of text in a different format. Can be used to describe different colors and font sizes.
- bold: whether the text should be displayed in bold(bold).
- italic: whether the text should be displayed in italics(italics).
- color: the color of the text. Only a few colors are currently supported: white(default), green, red, yellow, and black.
- font_size: the height of the text in pixels. Default 9(?)
- text: the text to be displayed using this format.
<italic>: a shortcut to <format> which inputs only the text key. Uses the attribute italic=yes
<bold>: like <italic>, but uses bold=yes
<header>: like <italic>, but uses both the attributes bold=yes and font_size=13(?)

Example:

Select All

[help]
  [toplevel]
    sections=introduction,gameplay
    topics=about
  [/toplevel]
  [section]
    id=gameplay
    sections=combat
    topics=income_and_upkeep,time_of_day,terrain,victory_and_defeat
  [/section]
  [topic]
    id=terrain
    title=Terrain
    text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"
  [/topic]
  [topic]
    id=victory_and_defeat
    title= _ "Victory and Defeat"
    text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up
             box at the beginning of each scenario. Usually you will achieve
             victory by killing all enemy leaders, and only be defeated by having
             your leader killed. But scenarios may have other victory objectives
             — getting your leader to a designated point, say, or rescuing someone,
             or solving a puzzle, or holding out against a siege until a certain
             number of turns have elapsed." + _"
             
             When you win a scenario, the map grays over and the
             <bold>text='End Turn'</bold> button changes to
             <bold>text='End Scenario'</bold>. You can now do things like changing
             your save options or (if you are in a multiplayer game) chatting with
             other players before pressing that button to advance."
    
  [/topic]
[/help]