Difference between revisions of "Help markup"

From The Battle for Wesnoth Wiki
(→‎Image Tags: Add image tag info.)
m (→‎Escapes: typo fix - replace : with ;)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Help Markup ==
 
== Help Markup ==
−
This page documents the markup used by the [[GUIWidgetInstanceWML#Rich_Label|Rich Label]] widget. This is a markup language based on the [[InterfaceActionsWML#Formatting|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.
+
This page documents the markup used by the [[GUIWidgetInstanceWML#Rich_Label|Rich Label]] widget. This is a markup language based on the [[InterfaceActionsWML#Formatting|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 (<code><img>src='path/to/myimage.png'</img></code>) and newer XML style syntax (<code><img src='path/to/myimage.png'/></code>) 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.
+
Both GUI1 style syntax (<code><img>src='path/to/myimage.png'</img></code>) and newer HTML style syntax (<code><img src='path/to/myimage.png'/></code>) 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 &gt; 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:
 +
 
 +
{|class="wikitable"
 +
|<tt>&amp;amp;</tt>
 +
|Ampersand (&amp;)
 +
|-
 +
|<tt>&amp;quot;</tt>
 +
|Double quote (&quot;)
 +
|-
 +
|<tt>&amp;apos;</tt>
 +
|Apostrophe (&apos;)
 +
|-
 +
|<tt>&amp;lt;</tt>
 +
|Left angle bracket (&lt;)
 +
|-
 +
|<tt>&amp;gt;</tt>
 +
|Right angle bracket (&gt;)
 +
|-
 +
|<tt>&amp;#ddd;</tt>
 +
|Unicode character given by decimal ''ddd''
 +
|-
 +
|<tt>&amp;#xhhhh;</tt>
 +
|Unicode character given by hexadecimal ''hhhh''
 +
|}
 +
 
 +
== Specific Tags ==
  
 
=== Formatting Tags ===
 
=== Formatting Tags ===
Line 21: Line 60:
 
* '''img:''' Inserts an image, whose path is specified by the ''src'' attribute.
 
* '''img:''' Inserts an image, whose path is specified by the ''src'' attribute.
 
** '''src:''' WML path of the image to be shown, i.e., <code>units/drakes/armageddon.png</code>
 
** '''src:''' WML path of the image to be shown, i.e., <code>units/drakes/armageddon.png</code>
−
** '''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.
+
** '''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'', ''right'' or ''middle/center''. ''middle/center'' only supports single inline images at the moment.
+
** '''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:'''
 
'''Note:'''
Line 29: Line 68:
  
 
=== Links ===
 
=== Links ===
 +
* '''ref:''' Insert a link. The name of the link is the value specified inside <code>&lt;ref&gt;</code> and <code>&lt;/ref&gt;</code>.
 +
** '''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 [https://devdocs.wesnoth.org/classgui2_1_1rich__label.html#ab2f4f796871def9c8fa18559fbd5451d register_link_callback] function. When a link is clicked, the callback function set via <code>register_link_callback</code> will be called with the appropriate ''name'' and ''dst'' values for the clicked link.
  
 
=== Table Tags ===
 
=== Table Tags ===
 +
 +
* '''table: ''' Starts the table.
 +
** '''width: ''' (optional) Width of the table (in pixels).
 +
** '''row: ''' (subtag) Contains the contents of a row, which are one or more columns.
 +
*** '''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.
 +
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:'''
 +
<syntaxhighlight lang=xml>
 +
<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>
 +
</syntaxhighlight>

Latest revision as of 06:19, 24 September 2024

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:

&amp; Ampersand (&)
&quot; Double quote (")
&apos; 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 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.
    • width: (optional) Width of the table (in pixels).
    • row: (subtag) Contains the contents of a row, which are one or more columns.
      • 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.

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: 

<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>
Retrieved from "https://wiki.wesnoth.org/index.php?title=Help_markup&oldid=73803"
This page was last edited on 24 September 2024, at 06:19.