:mod:`styles`
=============

These functions provide functionality to format :ref:`richtext <richtext.lua>` with the styles of
the current :ref:`theme <themes>`.

.. versionadded:: 1.2

.. module:: styles
   :synopsis: Provides helper functions for text formatting using themeable styles

.. moduleauthor:: The Widelands development team

.. currentmodule:: styles


Module Functions
^^^^^^^^^^^^^^^^


.. function:: as_font(style, text)

   Format the given text with the given :ref:`font style <theme_fonts>`.

   :type style: class:`string`
   :arg style: Name of the font style to use.
   :type text: class:`string`
   :arg text: Text to format.

   :returns: The text with richtext tags.

.. function:: as_paragraph(style, text)

   Format the given text as a paragraph with the given :ref:`paragraph style <theme_paragraphs>`.

   :type style: class:`string`
   :arg style: Name of the paragraph style to use.
   :type text: class:`string`
   :arg text: Text to format.

   :returns: The text with richtext tags.

.. function:: as_p_with_attr(style, attributes, text)

   Format the given text as a paragraph with the given :ref:`paragraph style <theme_paragraphs>`
   and extra attributes.

   :type style: class:`string`
   :arg style: Name of the paragraph style to use.
   :type attributes: class:`string`
   :arg attributes: Attributes for the paragraph tag. For possible attributes see the
      :ref:`p tag's documentation <rt_tags_p>`.
   :type text: class:`string`
   :arg text: Text to format.

   :returns: The text with richtext tags.

   Example:

   .. code-block:: lua

      include "scripting/richtext.lua"

      formatted_text = rt(
                          styles.as_paragraph("wui_text",
                                              _("This paragraph is left aligned")
                                             )
                          .. styles.as_p_with_attr("wui_text",
                                                   "align=center",
                                                   _("This paragraph is centered")
                                                  )
                         )


.. function:: open_p(style)

   Return richtext formatting to start a paragraph with the given
   :ref:`paragraph style <theme_paragraphs>`.

   :type style: class:`string`
   :arg style: Name of the paragraph style to use.

   :returns: The richtext formatting that starts a paragraph.

.. function:: open_p_with_attr(style, attributes)

   Return richtext formatting to start a :ref:`paragraph style <theme_paragraphs>` with the given
   style and extra attributes.

   :type style: class:`string`
   :arg style: Name of the paragraph style to use.
   :type attributes: class:`string`
   :arg attributes: Attributes for the paragraph tag. For possible attributes see the
      :ref:`p tag's documentation <rt_tags_p>`.

   :returns: The richtext formatting that starts the paragraph.

.. function:: close_p(style)

   Return richtext formatting to close a paragraph of the given style.

   :type style: class:`string`
   :arg style: Name of the paragraph style to use.

   :returns: The richtext formatting that closes a paragraph.

.. function:: as_font_from_p(p_style, text)

   Format the given text with the font style of the given :ref:`paragraph style <theme_paragraphs>`
   without the paragraph tags.

   :type style: class:`string`
   :arg p_style: Name of the paragraph style to use.
   :type text: class:`string`
   :arg text: Text to format.

   :returns: The text with richtext tags.

.. function:: color(style_name)

   Return the given :ref:`color style <theme_colors>` in hex format suitable for font tags.

   :type style_name: class:`string`
   :arg style_name: Name of the color style to use.

   :returns: The color as 6 characters hexadecimal RGB value.

.. function:: get_size(style_name)

   Return the given :ref:`styled size <theme_sizes>`.

   :type style_name: class:`string`
   :arg style_name: Name of the styled size to get.

   :returns: The integer value of the size, or 0 if no styled size is defined with the given
             `style_name`.