.. _richtext.lua: 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 :ref:`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 :ref:`richtext_scenarios.lua`. If you want to use the styles of :doc:`themes ` refer to :doc:`autogen_styles`. To make these functions available include this file at the beginning of a script via: .. code-block:: lua 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. .. function:: 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. :arg text_or_attributes: see the :ref:`rt tag's documentation ` for a list of attributes and their descriptions. :type text_or_attributes: :class:`string` :arg text: the text to be enclosed in rich text tags. :type text: :class:`string` :returns: the wrapped rich text. .. function:: div(text_or_attributes[, text = nil]) Wraps a block of text into a div tag. :arg text_or_attributes: see the :ref:`div tag's documentation ` for a list of attributes and their descriptions. :type test_or_attributes: :class:`string` :arg text: the text to be enclosed in div tags. :type text: :class:`string` :returns: the text wrapped in a div tag. .. function:: default_gap() Looks up the size of the default gap in the style library. :returns: the size of the default gap .. function:: space([gap]) Adds a horizontal space :arg gap: the size of the space as pixels. If omitted, the default gap size will be used. :returns: a space tag .. function:: vspace([gap]) Adds a vertical space :arg gap: the size of the space as pixels. If omitted, the default gap size will be used. :returns: a vspace tag .. function:: msg_vspace() Adds a standard vertical space for win condition status messages. :returns: a vspace tag with the standard gap size :ref:`Return to index` Headings and Paragraphs ^^^^^^^^^^^^^^^^^^^^^^^ This section covers functions for defining headings and paragraphs. .. function:: 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. .. function:: 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. .. function:: 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: .. function:: set_fs_style(enable) Change the style for text headings and normal paragraphs between the in-game and the main menu styles. :arg enable: If evaluates to `true`, then the main menu text style will be used for normal paragraphs, otherwise the in-game style. .. function:: fs_color(text) .. deprecated:: 1.2 Use :ref:`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. .. function:: 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. .. function:: h2(text) Like :func:`h1` but smaller. :returns: A paragraph with text formatted as heading. .. function:: h3(text) Like :func:`h2` but smaller. :returns: A paragraph with text formatted as heading. .. function:: h4(text) Like :func:`h3` but smaller. :returns: A paragraph with text formatted as heading. .. function:: inline_header(header, text) Creates a line of h3 formatted text followed by normal paragraph text. :arg header: text in h3 format. :arg text: text in p format. :returns: header text followed by normal text. .. function:: 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 :func:`rt`. :arg text_or_attributes: see the :ref:`p tag's documentation ` for a list of attributes and their descriptions. :type text_or_attributes: :class:`string` :returns: The text wrapped in

%s

.. function:: open_p([attributes = nil]) Returns a paragraph open tag and default font size. Options can be given as first argument similar to :func:`rt`. :arg attributes: see the :ref:`p tag's documentation ` for a list of attributes and their descriptions. :type attributes: :class:`string` :returns:

with added attributes and default font .. function:: close_p() Closes a paragraph. :returns: The closing tags for a paragraph .. function:: 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 :func:`rt`. :arg p_or_font_attributes: Optional paragraph or font attributes. :type p_or_font_attributes: :class:`string` :arg text_or_font_attributes: Optional font attributes or the text itself. :type text_or_font_attributes: :class:`string` See the :ref:`p tag's documentation ` for a list of paragraph attributes and the :ref:`font tag's documentation ` for a list of font attributes. :returns: The text wrapped in

text

:ref:`Return to index` Text Formatting ^^^^^^^^^^^^^^^ This section covers convenience functions for text formatting. .. function:: font(attributes, text) Wraps the text in font tags. See also :any:`p_font`. :arg attributes: see the :ref:`font tag's documentation ` for a list of attributes and their descriptions. :type attributes: :class:`string` :returns: The text wrapped in font tags with the given attributes .. function:: b(text) This makes the text bold. :arg text: the text to format :returns: a font tag containing the bold text .. function:: i(text) This makes the text italic. :arg text: the text to format :returns: a font tag containing the italic text .. function:: u(text) This underlines the text. :arg text: the text to format :returns: a font tag containing the underlined text :ref:`Return to index` Lists ^^^^^ This section covers functions for defining lists. .. function:: dl(dt, dd) This function imitates a HTML description list :arg dt: "description term", will be rendered in bold. :arg dd: "description data", will be rendered normally. :returns: a p tag containing the formatted text .. function:: 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 :arg symbol: the item symbol for the list, e.g. "•" or "→". "•" is the default. :arg text: the text of the list item :returns: a p tag containing the formatted text .. function:: li_arrow(text) Creates a list item with an arrow :arg text: the text of the list item :returns: li("→", text) .. function:: li_image(imagepath, text) Places a paragraph of text to the right of an image :arg imagepath: the full path to the image file :type imagepath: :class:`string` :arg text: the text to be placed next to the image :type text: :class:`string` :returns: the text wrapped in a paragraph and placed next to the image, the outer tag is a div. .. function:: li_object(name, text[, playercolor]) Places a paragraph of text to the right of an image representing the given map object :arg name: the name of the map object to be represented by an image :type name: :class:`string` :arg text: the text to be placed next to the image :type text: :class:`string` :arg playercolor: a playercolor to be applied to the image, in hex notation :type playercolor: :class:`string` :returns: the text wrapped in a paragraph and placed next to the image, the outer tag is a div. :ref:`Return to index` Images ^^^^^^ This section covers functions for including images. .. function:: img(src[, attributes = nil]) Turns an image src path into an image tag for richtext. See also :any:`li_image`. :arg src: the file path to the image. :type src: :class:`string` :arg attributes: see the :ref:`img tag's documentation ` for a list of attributes and their descriptions. :type attributes: :class:`string` :returns: the img tag. .. function:: img_object(object[, attributes = nil]) Creates a richtest image tag for the given map object type. See also :any:`li_object`. :arg name: the name of the map object. :type name: :class:`string` :arg attributes: see the :ref:`img tag's documentation ` for a list of attributes and their descriptions. :type attributes: :class:`string` :returns: the img tag. :ref:`Return to index` Links ^^^^^ This section covers functions for including hyperlinks. .. function:: a(linktext, linktype, target[, action=nil][, mouseover=target|linktext]) This function creates a hyperlink. :arg linktext: The text to display. :type linktext: :class:`string` :arg linktype: Type of the link. Use ``"ui"`` for internal links and ``"url"`` for external (browser) links. :type linktype: :class:`string` :arg target: The name of the UI element to notify or the URL to open. :type target: :class:`string` :arg action: Only valid for UI links. The action the UI element should perform. :type action: :class:`string` or :class:`nil` :arg mouseover: The text to show on mouse hovering. This defaults to the target for URLs or the linktext for other links; use ``""`` to disable. :type mouseover: :class:`string` :returns: The linkified and underlined text. :ref:`Return to index` Text Composition ^^^^^^^^^^^^^^^^ This section covers functions for text composition that help with proper markup to make the text translatable. .. function:: 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. :arg sentence1: text of the first sentence :arg sentence2: text of the second sentence :returns: two concatenated sentences with a localized sentence joiner. .. function:: 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") :arg items: An array of strings :arg 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 :ref:`Return to index` .. _lua_formatting_example: 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): .. code-block:: lua 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: .. image:: images/wlrichtext.png :scale: 100 :alt: sample rendering :align: center Please try to avoid hardcoding colors and non-default spacing and sizes. Best practice is to use :meth:`styles.color` to get color values and :meth:`styles.get_size` to get values for spacing and other sizes from the style manager whenever possible. :ref:`Return to index`