|
Packit |
0ec9dd |
<refentry id="PangoMarkupFormat" revision="11 Dec 2002">
|
|
Packit |
0ec9dd |
<refmeta>
|
|
Packit |
0ec9dd |
<refentrytitle>Text Attribute Markup</refentrytitle>
|
|
Packit |
0ec9dd |
<manvolnum>3</manvolnum>
|
|
Packit |
0ec9dd |
<refmiscinfo>Pango Library</refmiscinfo>
|
|
Packit |
0ec9dd |
</refmeta>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<refnamediv>
|
|
Packit |
0ec9dd |
<refname>Text Attribute Markup</refname><refpurpose>Simple
|
|
Packit |
0ec9dd |
markup language to encode text with attributes</refpurpose>
|
|
Packit |
0ec9dd |
</refnamediv>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<refsect1 id="PangoMarkupFormatLanguage">
|
|
Packit |
0ec9dd |
<title>Pango Text Attribute Markup Language</title>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
Frequently, you want to display some text to the user with attributes
|
|
Packit |
0ec9dd |
applied to part of the text (for example, you might want bold or
|
|
Packit |
0ec9dd |
italicized words). With the base Pango interfaces, you could create a
|
|
Packit |
0ec9dd |
<link linkend="PangoAttrList">PangoAttrList</link> and apply it to the
|
|
Packit |
0ec9dd |
text; the problem is that you'd need to apply attributes to some
|
|
Packit |
0ec9dd |
numeric range of characters, for example "characters 12-17." This is
|
|
Packit |
0ec9dd |
broken from an internationalization standpoint; once the text is
|
|
Packit |
0ec9dd |
translated, the word you wanted to italicize could be in a different
|
|
Packit |
0ec9dd |
position.
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
The solution is to include the text attributes in the string to be
|
|
Packit |
0ec9dd |
translated. Pango provides this feature with a small markup language.
|
|
Packit |
0ec9dd |
You can parse a marked-up string into the string text plus a
|
|
Packit |
0ec9dd |
<link linkend="PangoAttrList">PangoAttrList</link> using either of
|
|
Packit |
0ec9dd |
<link linkend="pango-parse-markup">pango_parse_markup()</link> or
|
|
Packit |
0ec9dd |
<link linkend="pango-markup-parser-new">pango_markup_parser_new()</link>.
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
A simple example of a marked-up string might be:
|
|
Packit |
0ec9dd |
<literal>"<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"</literal>
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
Pango uses #GMarkup to parse this language, which means that XML features
|
|
Packit |
0ec9dd |
such as numeric character entities such as © for © can
|
|
Packit |
0ec9dd |
be used too.
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
The root tag of a marked-up document is <markup>, but
|
|
Packit |
0ec9dd |
linkend="pango-parse-markup">pango_parse_markup()</link> allows you to
|
|
Packit |
0ec9dd |
omit this tag, so you will most likely never need to use it. The most
|
|
Packit |
0ec9dd |
general markup tag is <span>, then there are some convenience
|
|
Packit |
0ec9dd |
tags. <span> has the following attributes:
|
|
Packit |
0ec9dd |
<variablelist><title><span> attributes</title>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font<footnote id='since_1_21'><para>Since 1.21</para></footnote></term>
|
|
Packit |
0ec9dd |
<term>font_desc</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
A font description string, such as "Sans Italic 12". See
|
|
Packit |
0ec9dd |
<link linkend="pango-font-description-from-string">pango_font_description_from_string()</link>
|
|
Packit |
0ec9dd |
for a description of the format of the string representation . Note that any
|
|
Packit |
0ec9dd |
other span attributes will override this description. So if you have
|
|
Packit |
0ec9dd |
"Sans Italic" and also a style="normal" attribute, you will get Sans normal,
|
|
Packit |
0ec9dd |
not italic.</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_family</term>
|
|
Packit |
0ec9dd |
<term>face</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
A font family name
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_size<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>size</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Font size in 1024ths of a point, or one of the absolute sizes
|
|
Packit |
0ec9dd |
'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
|
|
Packit |
0ec9dd |
'xx-large', or one of the relative sizes 'smaller' or 'larger'.
|
|
Packit |
0ec9dd |
If you want to specify a absolute size, it's usually easier
|
|
Packit |
0ec9dd |
to take advantage of the ability to specify a partial
|
|
Packit |
0ec9dd |
font description using 'font'; you can use
|
|
Packit |
0ec9dd |
<literal>font='12.5'</literal> rather than
|
|
Packit |
0ec9dd |
<literal>size='12800'</literal>.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_style<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>style</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'normal', 'oblique', 'italic'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_weight<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>weight</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy',
|
|
Packit |
0ec9dd |
or a numeric weight
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_variant<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>variant</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'normal' or 'smallcaps'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_stretch<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>stretch</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'ultracondensed', 'extracondensed', 'condensed',
|
|
Packit |
0ec9dd |
'semicondensed', 'normal', 'semiexpanded', 'expanded',
|
|
Packit |
0ec9dd |
'extraexpanded', 'ultraexpanded'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>font_features<footnote id='since_1_38'><para>Since 1.38</para></footnote></term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
A comma separated list of OpenType font feature settings, in the same
|
|
Packit |
0ec9dd |
syntax as accepted by CSS. E.g: <literal>font_features='dlig=1, -kern, afrc on'</literal>
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>foreground</term>
|
|
Packit |
0ec9dd |
<term>fgcolor<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<term>color</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
An RGB color specification such as '#00FF00' or a color name such as
|
|
Packit |
0ec9dd |
'red'.
|
|
Packit |
0ec9dd |
Since 1.38, an RGBA color specification such as '#00FF007F' will
|
|
Packit |
0ec9dd |
be interpreted as specifying both a foreground color and foreground alpha.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>background</term>
|
|
Packit |
0ec9dd |
<term>bgcolor<footnoteref linkend='since_1_21'/></term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
An RGB color specification such as '#00FF00' or a color name such as
|
|
Packit |
0ec9dd |
'red'.
|
|
Packit |
0ec9dd |
Since 1.38, an RGBA color specification such as '#00FF007F' will
|
|
Packit |
0ec9dd |
be interpreted as specifying both a background color and background alpha.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>alpha</term>
|
|
Packit |
0ec9dd |
<term>fgalpha<footnoteref linkend='since_1_38'/></term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
An alpha value for the foreground color, either a plain integer between 1 and 65536
|
|
Packit |
0ec9dd |
or a percentage value like '50%'.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry>
|
|
Packit |
0ec9dd |
<term>background_alpha</term>
|
|
Packit |
0ec9dd |
<term>bgalpha<footnoteref linkend='since_1_38'/></term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
An alpha value for the background color, either a plain integer between 1 and 65536
|
|
Packit |
0ec9dd |
or a percentage value like '50%'.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>underline</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'none', 'single', 'double', 'low', 'error'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>underline_color</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
The color of underlines; an RGB color specification such as '#00FF00'
|
|
Packit |
0ec9dd |
or a color name such as 'red'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>rise</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Vertical displacement, in Pango units. Can be negative for
|
|
Packit |
0ec9dd |
subscript, positive for superscript.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>strikethrough</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
'true' or 'false' whether to strike through the text
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>strikethrough_color</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
The color of strikethrough lines; an RGB color specification such as
|
|
Packit |
0ec9dd |
'#00FF00' or a color name such as 'red'
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>fallback</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
'true' or 'false' whether to enable fallback. If disabled, then characters
|
|
Packit |
0ec9dd |
will only be used from the closest matching font on the system. No fallback
|
|
Packit |
0ec9dd |
will be done to other fonts on the system that might contain the characters
|
|
Packit |
0ec9dd |
in the text. Fallback is enabled by default. Most applications should not
|
|
Packit |
0ec9dd |
disable fallback.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>lang</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
A language code, indicating the text language
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>letter_spacing</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Inter-letter spacing in 1024ths of a point.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>gravity</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'south', 'east', 'north', 'west', 'auto'.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<varlistentry><term>gravity_hint</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
One of 'natural', 'strong', 'line'.
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
</variablelist>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<para>
|
|
Packit |
0ec9dd |
The following convenience tags are provided:
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
<variablelist><title>Convenience tags</title>
|
|
Packit |
0ec9dd |
<varlistentry><term>b</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Bold
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>big</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Makes font relatively larger, equivalent to <span size="larger">
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>i</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Italic
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>s</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Strikethrough
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>sub</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Subscript
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>sup</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Superscript
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>small</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Makes font relatively smaller, equivalent to <span size="smaller">
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>tt</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Monospace font
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
<varlistentry><term>u</term>
|
|
Packit |
0ec9dd |
<listitem><para>
|
|
Packit |
0ec9dd |
Underline
|
|
Packit |
0ec9dd |
</para></listitem>
|
|
Packit |
0ec9dd |
</varlistentry>
|
|
Packit |
0ec9dd |
</variablelist>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
</para>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
</refsect1>
|
|
Packit |
0ec9dd |
|
|
Packit |
0ec9dd |
</refentry>
|