docs/html/PangoMarkupFormat.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Text Attribute Markup</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="Pango Reference Manual">
   8 <link rel="up" href="pango.html" title="Basic Pango Interfaces">
   9 <link rel="prev" href="pango-Tab-Stops.html" title="Tab Stops">
  10 <link rel="next" href="pango-Layout-Objects.html" title="Layout Objects">
  11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="pango-Tab-Stops.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="pango.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">Pango Reference Manual</th>
  20 <td><a accesskey="n" href="pango-Layout-Objects.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="PangoMarkupFormat"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">Text Attribute Markup</span></h2>
  27 <p>Text Attribute Markup — Simple
  28 markup language to encode text with attributes</p>
  29 </td>
  30 <td valign="top" align="right"></td>
  31 </tr></table></div>
  32 <div class="refsect1">
  33 <a name="PangoMarkupFormatLanguage"></a><h2>Pango Text Attribute Markup Language</h2>
  34 <p>
  35 Frequently, you want to display some text to the user with attributes
  36 applied to part of the text (for example, you might want bold or
  37 italicized words). With the base Pango interfaces, you could create a
  38 <a class="link" href="pango-Text-Attributes.html#PangoAttrList">PangoAttrList</a> and apply it to the
  39 text; the problem is that you'd need to apply attributes to some
  40 numeric range of characters, for example "characters 12-17." This is
  41 broken from an internationalization standpoint; once the text is
  42 translated, the word you wanted to italicize could be in a different
  43 position.
  44 </p>
  45 <p>
  46 The solution is to include the text attributes in the string to be
  47 translated. Pango provides this feature with a small markup language.
  48 You can parse a marked-up string into the string text plus a
  49 <a class="link" href="pango-Text-Attributes.html#PangoAttrList">PangoAttrList</a> using the function
  50 <a class="link" href="pango-Text-Attributes.html#pango-parse-markup" title="pango_parse_markup ()">pango_parse_markup()</a>.
  51 </p>
  52 <p>
  53 A simple example of a marked-up string might be:
  54 <code class="literal">"&lt;span foreground="blue" size="x-large"&gt;Blue text&lt;/span&gt; is &lt;i&gt;cool&lt;/i&gt;!"</code>
  55 </p>
  56 <p>
  57 Pango uses #GMarkup to parse this language, which means that XML features
  58 such as numeric character entities such as &amp;#169; for © can
  59 be used too.
  60 </p>
  61 <p>
  62 The root tag of a marked-up document is &lt;markup&gt;, but <a class="link" href="pango-Text-Attributes.html#pango-parse-markup" title="pango_parse_markup ()">pango_parse_markup()</a> allows you to
  63 omit this tag, so you will most likely never need to use it. The most
  64 general markup tag is &lt;span&gt;, then there are some convenience
  65 tags. &lt;span&gt; has the following attributes:
  66 </p>
  67 <div class="variablelist">
  68 <p class="title"><b>&lt;span&gt; attributes</b></p>
  69 <table border="0">
  70 <col align="left" valign="top">
  71 <tbody>
  72 <tr>
  73 <td><p><span class="term">font<sup>[<a name="since_1_21" href="#ftn.since_1_21" class="footnote">1</a>]</sup>, </span><span class="term">font_desc</span></p></td>
  74 <td><p>
  75 A font description string, such as "Sans Italic 12". See
  76 <a class="link" href="pango-Fonts.html#pango-font-description-from-string" title="pango_font_description_from_string ()">pango_font_description_from_string()</a>
  77 for a description of the format of the string representation . Note that any
  78 other span attributes will override this description. So if you have
  79 "Sans Italic" and also a style="normal" attribute, you will get Sans normal,
  80 not italic.</p></td>
  81 </tr>
  82 <tr>
  83 <td><p><span class="term">font_family, </span><span class="term">face</span></p></td>
  84 <td><p>
  85 A font family name
  86 </p></td>
  87 </tr>
  88 <tr>
  89 <td><p><span class="term">font_size<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">size</span></p></td>
  90 <td><p>
  91 Font size in 1024ths of a point, or one of the absolute sizes
  92 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
  93 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
  94 If you want to specify a absolute size, it's usually easier
  95 to take advantage of the ability to specify a partial
  96 font description using 'font'; you can use
  97 <code class="literal">font='12.5'</code> rather than
  98 <code class="literal">size='12800'</code>.
  99 </p></td>
 100 </tr>
 101 <tr>
 102 <td><p><span class="term">font_style<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">style</span></p></td>
 103 <td><p>
 104 One of 'normal', 'oblique', 'italic'
 105 </p></td>
 106 </tr>
 107 <tr>
 108 <td><p><span class="term">font_weight<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">weight</span></p></td>
 109 <td><p>
 110 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy',
 111 or a numeric weight
 112 </p></td>
 113 </tr>
 114 <tr>
 115 <td><p><span class="term">font_variant<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">variant</span></p></td>
 116 <td><p>
 117 One of 'normal' or 'smallcaps'
 118 </p></td>
 119 </tr>
 120 <tr>
 121 <td><p><span class="term">font_stretch<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">stretch</span></p></td>
 122 <td><p>
 123 One of 'ultracondensed', 'extracondensed', 'condensed',
 124 'semicondensed', 'normal', 'semiexpanded', 'expanded',
 125 'extraexpanded', 'ultraexpanded'
 126 </p></td>
 127 </tr>
 128 <tr>
 129 <td><p><span class="term">foreground, </span><span class="term">fgcolor<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup>, </span><span class="term">color</span></p></td>
 130 <td><p>
 131 An RGB color specification such as '#00FF00' or a color name such as
 132 'red'
 133 </p></td>
 134 </tr>
 135 <tr>
 136 <td><p><span class="term">background, </span><span class="term">bgcolor<sup>[<a href="PangoMarkupFormat.html#ftn.since_1_21" class="footnoteref">1</a>]</sup></span></p></td>
 137 <td><p>
 138 An RGB color specification such as '#00FF00' or a color name such as
 139 'red'
 140 </p></td>
 141 </tr>
 142 <tr>
 143 <td><p><span class="term">underline</span></p></td>
 144 <td><p>
 145 One of 'none', 'single', 'double', 'low', 'error'
 146 </p></td>
 147 </tr>
 148 <tr>
 149 <td><p><span class="term">underline_color</span></p></td>
 150 <td><p>
 151 The color of underlines; an RGB color specification such as '#00FF00'
 152 or a color name such as 'red'
 153 </p></td>
 154 </tr>
 155 <tr>
 156 <td><p><span class="term">rise</span></p></td>
 157 <td><p>
 158 Vertical displacement, in 10000ths of an em. Can be negative for
 159 subscript, positive for superscript.
 160 </p></td>
 161 </tr>
 162 <tr>
 163 <td><p><span class="term">strikethrough</span></p></td>
 164 <td><p>
 165 'true' or 'false' whether to strike through the text
 166 </p></td>
 167 </tr>
 168 <tr>
 169 <td><p><span class="term">strikethrough_color</span></p></td>
 170 <td><p>
 171 The color of strikethrough lines; an RGB color specification such as
 172 '#00FF00' or a color name such as 'red'
 173 </p></td>
 174 </tr>
 175 <tr>
 176 <td><p><span class="term">fallback</span></p></td>
 177 <td><p>
 178 'true' or 'false' whether to enable fallback. If disabled, then characters
 179 will only be used from the closest matching font on the system. No fallback
 180 will be done to other fonts on the system that might contain the characters
 181 in the text.  Fallback is enabled by default. Most applications should not
 182 disable fallback.
 183 </p></td>
 184 </tr>
 185 <tr>
 186 <td><p><span class="term">lang</span></p></td>
 187 <td><p>
 188 A language code, indicating the text language
 189 </p></td>
 190 </tr>
 191 <tr>
 192 <td><p><span class="term">letter_spacing</span></p></td>
 193 <td><p>
 194 Inter-letter spacing in 1024ths of a point.
 195 </p></td>
 196 </tr>
 197 <tr>
 198 <td><p><span class="term">gravity</span></p></td>
 199 <td><p>
 200 One of 'south', 'east', 'north', 'west', 'auto'.
 201 </p></td>
 202 </tr>
 203 <tr>
 204 <td><p><span class="term">gravity_hint</span></p></td>
 205 <td><p>
 206 One of 'natural', 'strong', 'line'.
 207 </p></td>
 208 </tr>
 209 </tbody>
 210 </table>
 211 </div>
 212 <p>
 213
 214 </p>
 215 <p>
 216 The following convenience tags are provided:
 217
 218 </p>
 219 <div class="variablelist">
 220 <p class="title"><b>Convenience tags</b></p>
 221 <table border="0">
 222 <col align="left" valign="top">
 223 <tbody>
 224 <tr>
 225 <td><p><span class="term">b</span></p></td>
 226 <td><p>
 227 Bold
 228 </p></td>
 229 </tr>
 230 <tr>
 231 <td><p><span class="term">big</span></p></td>
 232 <td><p>
 233 Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
 234 </p></td>
 235 </tr>
 236 <tr>
 237 <td><p><span class="term">i</span></p></td>
 238 <td><p>
 239 Italic
 240 </p></td>
 241 </tr>
 242 <tr>
 243 <td><p><span class="term">s</span></p></td>
 244 <td><p>
 245 Strikethrough
 246 </p></td>
 247 </tr>
 248 <tr>
 249 <td><p><span class="term">sub</span></p></td>
 250 <td><p>
 251 Subscript
 252 </p></td>
 253 </tr>
 254 <tr>
 255 <td><p><span class="term">sup</span></p></td>
 256 <td><p>
 257 Superscript
 258 </p></td>
 259 </tr>
 260 <tr>
 261 <td><p><span class="term">small</span></p></td>
 262 <td><p>
 263 Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
 264 </p></td>
 265 </tr>
 266 <tr>
 267 <td><p><span class="term">tt</span></p></td>
 268 <td><p>
 269 Monospace font
 270 </p></td>
 271 </tr>
 272 <tr>
 273 <td><p><span class="term">u</span></p></td>
 274 <td><p>
 275 Underline
 276 </p></td>
 277 </tr>
 278 </tbody>
 279 </table>
 280 </div>
 281 <p>
 282
 283 </p>
 284 </div>
 285 <div class="footnotes">
 286 <br><hr width="100" align="left">
 287 <div class="footnote"><p><sup>[<a id="ftn.since_1_21" href="#since_1_21" class="para">1</a>] </sup>Since 1.21</p></div>
 288 </div>
 289 </div>
 290 <div class="footer">
 291 <hr>
 292           Generated by GTK-Doc V1.18.1</div>
 293 </body>
 294 </html>