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 and 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 XML style syntax (<img src='path/to/myimage.png'/>) are supported. The new syntax is recommended. The internal XML parser doesn't support nested tags at the moment (limitation might be removed in the future). Use single quotes inside markup.

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 function. When a link is clicked, the callback function set via register_link_callback will be called with the appropriate name and dst values for the clicked link.

Table Tags

• table: Starts the table.
  • col: (mandatory) Number of columns of the table.
  • width: (optional) Width of the table (in pixels).
• jump: Go to the next column.
• br: Go to the next row.
• endtable: Closes the table.

For now these are all empty (<jump/>) tags, see the example below.

Example:

<table col=3 width=400/>
    Hello<jump/>Hello2<jump/>Hello3<br/>
    Hello<jump/>Hello2<jump/>Hello3<br/>
<endtable/>