docs/xml/utils.xml

   1 <refentry id="pango-Miscellaneous-Utilities">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Miscellaneous-Utilities.top_of_page">Miscellaneous Utilities</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Miscellaneous Utilities</refname>
  10 <refpurpose>Various convenience and utility functions</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Miscellaneous-Utilities.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17 <link linkend="char">char</link> **             <link linkend="pango-split-file-list">pango_split_file_list</link>               (const <link linkend="char">char</link> *str);
  18 <link linkend="char">char</link> *              <link linkend="pango-trim-string">pango_trim_string</link>                   (const <link linkend="char">char</link> *str);
  19 <link linkend="gint">gint</link>                <link linkend="pango-read-line">pango_read_line</link>                     (<link linkend="FILE--CAPS">FILE</link> *stream,
  20                                                          <link linkend="GString">GString</link> *str);
  21 <link linkend="gboolean">gboolean</link>            <link linkend="pango-skip-space">pango_skip_space</link>                    (const <link linkend="char">char</link> **pos);
  22 <link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-word">pango_scan_word</link>                     (const <link linkend="char">char</link> **pos,
  23                                                          <link linkend="GString">GString</link> *out);
  24 <link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-string">pango_scan_string</link>                   (const <link linkend="char">char</link> **pos,
  25                                                          <link linkend="GString">GString</link> *out);
  26 <link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-int">pango_scan_int</link>                      (const <link linkend="char">char</link> **pos,
  27                                                          <link linkend="int">int</link> *out);
  28 <link linkend="char">char</link> *              <link linkend="pango-config-key-get">pango_config_key_get</link>                (const <link linkend="char">char</link> *key);
  29 <link linkend="void">void</link>                <link linkend="pango-lookup-aliases">pango_lookup_aliases</link>                (const <link linkend="char">char</link> *fontname,
  30                                                          <link linkend="char">char</link> ***families,
  31                                                          <link linkend="int">int</link> *n_families);
  32 <link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-enum">pango_parse_enum</link>                    (<link linkend="GType">GType</link> type,
  33                                                          const <link linkend="char">char</link> *str,
  34                                                          <link linkend="int">int</link> *value,
  35                                                          <link linkend="gboolean">gboolean</link> warn,
  36                                                          <link linkend="char">char</link> **possible_values);
  37 <link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-style">pango_parse_style</link>                   (const <link linkend="char">char</link> *str,
  38                                                          <link linkend="PangoStyle">PangoStyle</link> *style,
  39                                                          <link linkend="gboolean">gboolean</link> warn);
  40 <link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-variant">pango_parse_variant</link>                 (const <link linkend="char">char</link> *str,
  41                                                          <link linkend="PangoVariant">PangoVariant</link> *variant,
  42                                                          <link linkend="gboolean">gboolean</link> warn);
  43 <link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-weight">pango_parse_weight</link>                  (const <link linkend="char">char</link> *str,
  44                                                          <link linkend="PangoWeight">PangoWeight</link> *weight,
  45                                                          <link linkend="gboolean">gboolean</link> warn);
  46 <link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-stretch">pango_parse_stretch</link>                 (const <link linkend="char">char</link> *str,
  47                                                          <link linkend="PangoStretch">PangoStretch</link> *stretch,
  48                                                          <link linkend="gboolean">gboolean</link> warn);
  49 const <link linkend="char">char</link> *        <link linkend="pango-get-sysconf-subdirectory">pango_get_sysconf_subdirectory</link>      (void);
  50 const <link linkend="char">char</link> *        <link linkend="pango-get-lib-subdirectory">pango_get_lib_subdirectory</link>          (void);
  51 <link linkend="guint8">guint8</link> *            <link linkend="pango-log2vis-get-embedding-levels">pango_log2vis_get_embedding_levels</link>  (const <link linkend="gchar">gchar</link> *text,
  52                                                          <link linkend="int">int</link> length,
  53                                                          <link linkend="PangoDirection">PangoDirection</link> *pbase_dir);
  54 <link linkend="gboolean">gboolean</link>            <link linkend="pango-is-zero-width">pango_is_zero_width</link>                 (<link linkend="gunichar">gunichar</link> ch);
  55 <link linkend="void">void</link>                <link linkend="pango-quantize-line-geometry">pango_quantize_line_geometry</link>        (<link linkend="int">int</link> *thickness,
  56                                                          <link linkend="int">int</link> *position);
  57 </synopsis>
  58 </refsynopsisdiv>
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68 <refsect1 id="pango-Miscellaneous-Utilities.description" role="desc">
  69 <title role="desc.title">Description</title>
  70 <para>
  71 The functions and utilities in this section are mostly used from Pango
  72 backends and modules, but may be useful for other purposes too.
  73 </para>
  74 </refsect1>
  75
  76 <refsect1 id="pango-Miscellaneous-Utilities.details" role="details">
  77 <title role="details.title">Details</title>
  78 <refsect2 id="pango-split-file-list" role="function">
  79 <title>pango_split_file_list ()</title>
  80 <indexterm zone="pango-split-file-list"><primary sortas="pango_split_file_list">pango_split_file_list</primary></indexterm><programlisting><link linkend="char">char</link> **             pango_split_file_list               (const <link linkend="char">char</link> *str);</programlisting>
  81 <para>
  82 Splits a <link linkend="G-SEARCHPATH-SEPARATOR--CAPS"><literal>G_SEARCHPATH_SEPARATOR</literal></link>-separated list of files, stripping
  83 white space and substituting ~/ with $HOME/.</para>
  84 <para>
  85 </para><variablelist role="params">
  86 <varlistentry><term><parameter>str</parameter>&#160;:</term>
  87 <listitem><simpara> a <link linkend="G-SEARCHPATH-SEPARATOR--CAPS"><literal>G_SEARCHPATH_SEPARATOR</literal></link> separated list of filenames
  88 </simpara></listitem></varlistentry>
  89 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of strings to be freed with <link linkend="g-strfreev"><function>g_strfreev()</function></link>
  90 </simpara></listitem></varlistentry>
  91 </variablelist></refsect2>
  92 <refsect2 id="pango-trim-string" role="function">
  93 <title>pango_trim_string ()</title>
  94 <indexterm zone="pango-trim-string"><primary sortas="pango_trim_string">pango_trim_string</primary></indexterm><programlisting><link linkend="char">char</link> *              pango_trim_string                   (const <link linkend="char">char</link> *str);</programlisting>
  95 <para>
  96 Trims leading and trailing whitespace from a string.</para>
  97 <para>
  98 </para><variablelist role="params">
  99 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 100 <listitem><simpara> a string
 101 </simpara></listitem></varlistentry>
 102 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link>
 103 </simpara></listitem></varlistentry>
 104 </variablelist></refsect2>
 105 <refsect2 id="pango-read-line" role="function">
 106 <title>pango_read_line ()</title>
 107 <indexterm zone="pango-read-line"><primary sortas="pango_read_line">pango_read_line</primary></indexterm><programlisting><link linkend="gint">gint</link>                pango_read_line                     (<link linkend="FILE--CAPS">FILE</link> *stream,
 108                                                          <link linkend="GString">GString</link> *str);</programlisting>
 109 <para>
 110 Reads an entire line from a file into a buffer. Lines may
 111 be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter
 112 is not written into the buffer. Text after a '#' character is treated as
 113 a comment and skipped. '\' can be used to escape a # character.
 114 '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding
 115 any other character is ignored and written into the output buffer
 116 unmodified.</para>
 117 <para>
 118 </para><variablelist role="params">
 119 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
 120 <listitem><simpara> a stdio stream
 121 </simpara></listitem></varlistentry>
 122 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 123 <listitem><simpara> <link linkend="GString"><type>GString</type></link> buffer into which to write the result
 124 </simpara></listitem></varlistentry>
 125 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the stream was already at an <link linkend="EOF--CAPS"><literal>EOF</literal></link> character, otherwise
 126               the number of lines read (this is useful for maintaining
 127               a line number counter which doesn't combine lines with '\')
 128 </simpara></listitem></varlistentry>
 129 </variablelist></refsect2>
 130 <refsect2 id="pango-skip-space" role="function">
 131 <title>pango_skip_space ()</title>
 132 <indexterm zone="pango-skip-space"><primary sortas="pango_skip_space">pango_skip_space</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_skip_space                    (const <link linkend="char">char</link> **pos);</programlisting>
 133 <para>
 134 Skips 0 or more characters of white space.</para>
 135 <para>
 136 </para><variablelist role="params">
 137 <varlistentry><term><parameter>pos</parameter>&#160;:</term>
 138 <listitem><simpara> in/out string position
 139 </simpara></listitem></varlistentry>
 140 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if skipping the white space leaves
 141 the position at a '\0' character.
 142 </simpara></listitem></varlistentry>
 143 </variablelist></refsect2>
 144 <refsect2 id="pango-scan-word" role="function">
 145 <title>pango_scan_word ()</title>
 146 <indexterm zone="pango-scan-word"><primary sortas="pango_scan_word">pango_scan_word</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_scan_word                     (const <link linkend="char">char</link> **pos,
 147                                                          <link linkend="GString">GString</link> *out);</programlisting>
 148 <para>
 149 Scans a word into a <link linkend="GString"><type>GString</type></link> buffer. A word consists
 150 of [A-Za-z_] followed by zero or more [A-Za-z_0-9]
 151 Leading white space is skipped.</para>
 152 <para>
 153 </para><variablelist role="params">
 154 <varlistentry><term><parameter>pos</parameter>&#160;:</term>
 155 <listitem><simpara> in/out string position
 156 </simpara></listitem></varlistentry>
 157 <varlistentry><term><parameter>out</parameter>&#160;:</term>
 158 <listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which to write the result
 159 </simpara></listitem></varlistentry>
 160 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if a parse error occurred.
 161 </simpara></listitem></varlistentry>
 162 </variablelist></refsect2>
 163 <refsect2 id="pango-scan-string" role="function">
 164 <title>pango_scan_string ()</title>
 165 <indexterm zone="pango-scan-string"><primary sortas="pango_scan_string">pango_scan_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_scan_string                   (const <link linkend="char">char</link> **pos,
 166                                                          <link linkend="GString">GString</link> *out);</programlisting>
 167 <para>
 168 Scans a string into a <link linkend="GString"><type>GString</type></link> buffer. The string may either
 169 be a sequence of non-white-space characters, or a quoted
 170 string with '"'. Instead a quoted string, '\"' represents
 171 a literal quote. Leading white space outside of quotes is skipped.</para>
 172 <para>
 173 </para><variablelist role="params">
 174 <varlistentry><term><parameter>pos</parameter>&#160;:</term>
 175 <listitem><simpara> in/out string position
 176 </simpara></listitem></varlistentry>
 177 <varlistentry><term><parameter>out</parameter>&#160;:</term>
 178 <listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which to write the result
 179 </simpara></listitem></varlistentry>
 180 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if a parse error occurred.
 181 </simpara></listitem></varlistentry>
 182 </variablelist></refsect2>
 183 <refsect2 id="pango-scan-int" role="function">
 184 <title>pango_scan_int ()</title>
 185 <indexterm zone="pango-scan-int"><primary sortas="pango_scan_int">pango_scan_int</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_scan_int                      (const <link linkend="char">char</link> **pos,
 186                                                          <link linkend="int">int</link> *out);</programlisting>
 187 <para>
 188 Scans an integer.
 189 Leading white space is skipped.</para>
 190 <para>
 191 </para><variablelist role="params">
 192 <varlistentry><term><parameter>pos</parameter>&#160;:</term>
 193 <listitem><simpara> in/out string position
 194 </simpara></listitem></varlistentry>
 195 <varlistentry><term><parameter>out</parameter>&#160;:</term>
 196 <listitem><simpara> an int into which to write the result
 197 </simpara></listitem></varlistentry>
 198 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if a parse error occurred.
 199 </simpara></listitem></varlistentry>
 200 </variablelist></refsect2>
 201 <refsect2 id="pango-config-key-get" role="function">
 202 <title>pango_config_key_get ()</title>
 203 <indexterm zone="pango-config-key-get"><primary sortas="pango_config_key_get">pango_config_key_get</primary></indexterm><programlisting><link linkend="char">char</link> *              pango_config_key_get                (const <link linkend="char">char</link> *key);</programlisting>
 204 <para>
 205 Looks up a key in the Pango config database
 206 (pseudo-win.ini style, read from $sysconfdir/pango/pangorc,
 207  ~/.pangorc, and getenv (PANGO_RC_FILE).)</para>
 208 <para>
 209 </para><variablelist role="params">
 210 <varlistentry><term><parameter>key</parameter>&#160;:</term>
 211 <listitem><simpara> Key to look up, in the form "SECTION/KEY".
 212 </simpara></listitem></varlistentry>
 213 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the value, if found, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The value is a
 214 newly-allocated string and must be freed with <link linkend="g-free"><function>g_free()</function></link>.
 215 </simpara></listitem></varlistentry>
 216 </variablelist></refsect2>
 217 <refsect2 id="pango-lookup-aliases" role="function">
 218 <title>pango_lookup_aliases ()</title>
 219 <indexterm zone="pango-lookup-aliases"><primary sortas="pango_lookup_aliases">pango_lookup_aliases</primary></indexterm><programlisting><link linkend="void">void</link>                pango_lookup_aliases                (const <link linkend="char">char</link> *fontname,
 220                                                          <link linkend="char">char</link> ***families,
 221                                                          <link linkend="int">int</link> *n_families);</programlisting>
 222 <para>
 223 Look up all user defined aliases for the alias <parameter>fontname</parameter>.
 224 The resulting font family names will be stored in <parameter>families</parameter>,
 225 and the number of families in <parameter>n_families</parameter>.</para>
 226 <para>
 227 </para><variablelist role="params">
 228 <varlistentry><term><parameter>fontname</parameter>&#160;:</term>
 229 <listitem><simpara> an ascii string
 230 </simpara></listitem></varlistentry>
 231 <varlistentry><term><parameter>families</parameter>&#160;:</term>
 232 <listitem><simpara> will be set to an array of font family names.
 233    this array is owned by pango and should not be freed.
 234 </simpara></listitem></varlistentry>
 235 <varlistentry><term><parameter>n_families</parameter>&#160;:</term>
 236 <listitem><simpara> will be set to the length of the <parameter>families</parameter> array.
 237 </simpara></listitem></varlistentry>
 238 </variablelist></refsect2>
 239 <refsect2 id="pango-parse-enum" role="function" condition="since:1.16">
 240 <title>pango_parse_enum ()</title>
 241 <indexterm zone="pango-parse-enum" role="1.16"><primary sortas="pango_parse_enum">pango_parse_enum</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_parse_enum                    (<link linkend="GType">GType</link> type,
 242                                                          const <link linkend="char">char</link> *str,
 243                                                          <link linkend="int">int</link> *value,
 244                                                          <link linkend="gboolean">gboolean</link> warn,
 245                                                          <link linkend="char">char</link> **possible_values);</programlisting>
 246 <para>
 247 Parses an enum type and stores the result in <parameter>value</parameter>.
 248 </para>
 249 <para>
 250 If <parameter>str</parameter> does not match the nick name of any of the possible values for the
 251 enum and is not an integer, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is returned, a warning is issued
 252 if <parameter>warn</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, and a
 253 string representing the list of possible values is stored in
 254 <parameter>possible_values</parameter>.  The list is slash-separated, eg.
 255 "none/start/middle/end".  If failed and <parameter>possible_values</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>,
 256 returned string should be freed using <link linkend="g-free"><function>g_free()</function></link>.</para>
 257 <para>
 258 </para><variablelist role="params">
 259 <varlistentry><term><parameter>type</parameter>&#160;:</term>
 260 <listitem><simpara> enum type to parse, eg. <link linkend="PANGO-TYPE-ELLIPSIZE-MODE--CAPS"><literal>PANGO_TYPE_ELLIPSIZE_MODE</literal></link>.
 261 </simpara></listitem></varlistentry>
 262 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 263 <listitem><simpara> string to parse.  May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 264 </simpara></listitem></varlistentry>
 265 <varlistentry><term><parameter>value</parameter>&#160;:</term>
 266 <listitem><simpara> integer to store the result in, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 267 </simpara></listitem></varlistentry>
 268 <varlistentry><term><parameter>warn</parameter>&#160;:</term>
 269 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, issue a <link linkend="g-warning"><function>g_warning()</function></link> on bad input.
 270 </simpara></listitem></varlistentry>
 271 <varlistentry><term><parameter>possible_values</parameter>&#160;:</term>
 272 <listitem><simpara> place to store list of possible values on failure, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 273 </simpara></listitem></varlistentry>
 274 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> was successfully parsed.
 275
 276 </simpara></listitem></varlistentry>
 277 </variablelist><para role="since">Since 1.16</para></refsect2>
 278 <refsect2 id="pango-parse-style" role="function">
 279 <title>pango_parse_style ()</title>
 280 <indexterm zone="pango-parse-style"><primary sortas="pango_parse_style">pango_parse_style</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_parse_style                   (const <link linkend="char">char</link> *str,
 281                                                          <link linkend="PangoStyle">PangoStyle</link> *style,
 282                                                          <link linkend="gboolean">gboolean</link> warn);</programlisting>
 283 <para>
 284 Parses a font style. The allowed values are "normal",
 285 "italic" and "oblique", case variations being
 286 ignored.</para>
 287 <para>
 288 </para><variablelist role="params">
 289 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 290 <listitem><simpara> a string to parse.
 291 </simpara></listitem></varlistentry>
 292 <varlistentry><term><parameter>style</parameter>&#160;:</term>
 293 <listitem><simpara> a <link linkend="PangoStyle"><type>PangoStyle</type></link> to store the result in.
 294 </simpara></listitem></varlistentry>
 295 <varlistentry><term><parameter>warn</parameter>&#160;:</term>
 296 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, issue a <link linkend="g-warning"><function>g_warning()</function></link> on bad input.
 297 </simpara></listitem></varlistentry>
 298 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> was successfully parsed.
 299 </simpara></listitem></varlistentry>
 300 </variablelist></refsect2>
 301 <refsect2 id="pango-parse-variant" role="function">
 302 <title>pango_parse_variant ()</title>
 303 <indexterm zone="pango-parse-variant"><primary sortas="pango_parse_variant">pango_parse_variant</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_parse_variant                 (const <link linkend="char">char</link> *str,
 304                                                          <link linkend="PangoVariant">PangoVariant</link> *variant,
 305                                                          <link linkend="gboolean">gboolean</link> warn);</programlisting>
 306 <para>
 307 Parses a font variant. The allowed values are "normal"
 308 and "smallcaps" or "small_caps", case variations being
 309 ignored.</para>
 310 <para>
 311 </para><variablelist role="params">
 312 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 313 <listitem><simpara> a string to parse.
 314 </simpara></listitem></varlistentry>
 315 <varlistentry><term><parameter>variant</parameter>&#160;:</term>
 316 <listitem><simpara> a <link linkend="PangoVariant"><type>PangoVariant</type></link> to store the result in.
 317 </simpara></listitem></varlistentry>
 318 <varlistentry><term><parameter>warn</parameter>&#160;:</term>
 319 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, issue a <link linkend="g-warning"><function>g_warning()</function></link> on bad input.
 320 </simpara></listitem></varlistentry>
 321 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> was successfully parsed.
 322 </simpara></listitem></varlistentry>
 323 </variablelist></refsect2>
 324 <refsect2 id="pango-parse-weight" role="function">
 325 <title>pango_parse_weight ()</title>
 326 <indexterm zone="pango-parse-weight"><primary sortas="pango_parse_weight">pango_parse_weight</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_parse_weight                  (const <link linkend="char">char</link> *str,
 327                                                          <link linkend="PangoWeight">PangoWeight</link> *weight,
 328                                                          <link linkend="gboolean">gboolean</link> warn);</programlisting>
 329 <para>
 330 Parses a font weight. The allowed values are "heavy",
 331 "ultrabold", "bold", "normal", "light", "ultraleight"
 332 and integers. Case variations are ignored.</para>
 333 <para>
 334 </para><variablelist role="params">
 335 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 336 <listitem><simpara> a string to parse.
 337 </simpara></listitem></varlistentry>
 338 <varlistentry><term><parameter>weight</parameter>&#160;:</term>
 339 <listitem><simpara> a <link linkend="PangoWeight"><type>PangoWeight</type></link> to store the result in.
 340 </simpara></listitem></varlistentry>
 341 <varlistentry><term><parameter>warn</parameter>&#160;:</term>
 342 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, issue a <link linkend="g-warning"><function>g_warning()</function></link> on bad input.
 343 </simpara></listitem></varlistentry>
 344 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> was successfully parsed.
 345 </simpara></listitem></varlistentry>
 346 </variablelist></refsect2>
 347 <refsect2 id="pango-parse-stretch" role="function">
 348 <title>pango_parse_stretch ()</title>
 349 <indexterm zone="pango-parse-stretch"><primary sortas="pango_parse_stretch">pango_parse_stretch</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_parse_stretch                 (const <link linkend="char">char</link> *str,
 350                                                          <link linkend="PangoStretch">PangoStretch</link> *stretch,
 351                                                          <link linkend="gboolean">gboolean</link> warn);</programlisting>
 352 <para>
 353 Parses a font stretch. The allowed values are
 354 "ultra_condensed", "extra_condensed", "condensed",
 355 "semi_condensed", "normal", "semi_expanded", "expanded",
 356 "extra_expanded" and "ultra_expanded". Case variations are
 357 ignored and the '_' characters may be omitted.</para>
 358 <para>
 359 </para><variablelist role="params">
 360 <varlistentry><term><parameter>str</parameter>&#160;:</term>
 361 <listitem><simpara> a string to parse.
 362 </simpara></listitem></varlistentry>
 363 <varlistentry><term><parameter>stretch</parameter>&#160;:</term>
 364 <listitem><simpara> a <link linkend="PangoStretch"><type>PangoStretch</type></link> to store the result in.
 365 </simpara></listitem></varlistentry>
 366 <varlistentry><term><parameter>warn</parameter>&#160;:</term>
 367 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, issue a <link linkend="g-warning"><function>g_warning()</function></link> on bad input.
 368 </simpara></listitem></varlistentry>
 369 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> was successfully parsed.
 370 </simpara></listitem></varlistentry>
 371 </variablelist></refsect2>
 372 <refsect2 id="pango-get-sysconf-subdirectory" role="function">
 373 <title>pango_get_sysconf_subdirectory ()</title>
 374 <indexterm zone="pango-get-sysconf-subdirectory"><primary sortas="pango_get_sysconf_subdirectory">pango_get_sysconf_subdirectory</primary></indexterm><programlisting>const <link linkend="char">char</link> *        pango_get_sysconf_subdirectory      (void);</programlisting>
 375 <para>
 376 On Unix, returns the name of the "pango" subdirectory of SYSCONFDIR
 377 (which is set at compile time). On Windows, returns the etc\pango
 378 subdirectory of the Pango installation directory (which is deduced
 379 at run time from the DLL's location).</para>
 380 <para>
 381 </para><variablelist role="params">
 382 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the Pango sysconf directory. The returned string should
 383 not be freed.
 384 </simpara></listitem></varlistentry>
 385 </variablelist></refsect2>
 386 <refsect2 id="pango-get-lib-subdirectory" role="function">
 387 <title>pango_get_lib_subdirectory ()</title>
 388 <indexterm zone="pango-get-lib-subdirectory"><primary sortas="pango_get_lib_subdirectory">pango_get_lib_subdirectory</primary></indexterm><programlisting>const <link linkend="char">char</link> *        pango_get_lib_subdirectory          (void);</programlisting>
 389 <para>
 390 On Unix, returns the name of the "pango" subdirectory of LIBDIR
 391 (which is set at compile time). On Windows, returns the lib\pango
 392 subdirectory of the Pango installation directory (which is deduced
 393 at run time from the DLL's location).</para>
 394 <para>
 395 </para><variablelist role="params">
 396 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the Pango lib directory. The returned string should
 397 not be freed.
 398 </simpara></listitem></varlistentry>
 399 </variablelist></refsect2>
 400 <refsect2 id="pango-log2vis-get-embedding-levels" role="function" condition="since:1.4">
 401 <title>pango_log2vis_get_embedding_levels ()</title>
 402 <indexterm zone="pango-log2vis-get-embedding-levels" role="1.4"><primary sortas="pango_log2vis_get_embedding_levels">pango_log2vis_get_embedding_levels</primary></indexterm><programlisting><link linkend="guint8">guint8</link> *            pango_log2vis_get_embedding_levels  (const <link linkend="gchar">gchar</link> *text,
 403                                                          <link linkend="int">int</link> length,
 404                                                          <link linkend="PangoDirection">PangoDirection</link> *pbase_dir);</programlisting>
 405 <para>
 406 This will return the bidirectional embedding levels of the input paragraph
 407 as defined by the Unicode Bidirectional Algorithm available at:
 408 </para>
 409 <para>
 410   http://www.unicode.org/reports/tr9/
 411 </para>
 412 <para>
 413 If the input base direction is a weak direction, the direction of the
 414 characters in the text will determine the final resolved direction.</para>
 415 <para>
 416 </para><variablelist role="params">
 417 <varlistentry><term><parameter>text</parameter>&#160;:</term>
 418 <listitem><simpara>      the text to itemize.
 419 </simpara></listitem></varlistentry>
 420 <varlistentry><term><parameter>length</parameter>&#160;:</term>
 421 <listitem><simpara>    the number of bytes (not characters) to process, or -1
 422             if <parameter>text</parameter> is nul-terminated and the length should be calculated.
 423 </simpara></listitem></varlistentry>
 424 <varlistentry><term><parameter>pbase_dir</parameter>&#160;:</term>
 425 <listitem><simpara> input base direction, and output resolved direction.
 426 </simpara></listitem></varlistentry>
 427 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated array of embedding levels, one item per
 428               character (not byte), that should be freed using g_free.
 429
 430 </simpara></listitem></varlistentry>
 431 </variablelist><para role="since">Since 1.4</para></refsect2>
 432 <refsect2 id="pango-is-zero-width" role="function" condition="since:1.10">
 433 <title>pango_is_zero_width ()</title>
 434 <indexterm zone="pango-is-zero-width" role="1.10"><primary sortas="pango_is_zero_width">pango_is_zero_width</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_is_zero_width                 (<link linkend="gunichar">gunichar</link> ch);</programlisting>
 435 <para>
 436 Checks <parameter>ch</parameter> to see if it is a character that should not be
 437 normally rendered on the screen.  This includes all Unicode characters
 438 with "ZERO WIDTH" in their name, as well as <firstterm>bidi</firstterm> formatting characters, and
 439 a few other ones.  This is totally different from <link linkend="g-unichar-iszerowidth"><function>g_unichar_iszerowidth()</function></link>
 440 and is at best misnamed.</para>
 441 <para>
 442 </para><variablelist role="params">
 443 <varlistentry><term><parameter>ch</parameter>&#160;:</term>
 444 <listitem><simpara> a Unicode character
 445 </simpara></listitem></varlistentry>
 446 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>ch</parameter> is a zero-width character, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
 447
 448 </simpara></listitem></varlistentry>
 449 </variablelist><para role="since">Since 1.10</para></refsect2>
 450 <refsect2 id="pango-quantize-line-geometry" role="function" condition="since:1.12">
 451 <title>pango_quantize_line_geometry ()</title>
 452 <indexterm zone="pango-quantize-line-geometry" role="1.12"><primary sortas="pango_quantize_line_geometry">pango_quantize_line_geometry</primary></indexterm><programlisting><link linkend="void">void</link>                pango_quantize_line_geometry        (<link linkend="int">int</link> *thickness,
 453                                                          <link linkend="int">int</link> *position);</programlisting>
 454 <para>
 455 Quantizes the thickness and position of a line, typically an
 456 underline or strikethrough, to whole device pixels, that is integer
 457 multiples of <link linkend="PANGO-SCALE--CAPS"><literal>PANGO_SCALE</literal></link>. The purpose of this function is to avoid
 458 such lines looking blurry.
 459 </para>
 460 <para>
 461 Care is taken to make sure <parameter>thickness</parameter> is at least one pixel when this
 462 function returns, but returned <parameter>position</parameter> may become zero as a result
 463 of rounding.</para>
 464 <para>
 465 </para><variablelist role="params">
 466 <varlistentry><term><parameter>thickness</parameter>&#160;:</term>
 467 <listitem><simpara> pointer to the thickness of a line, in Pango units
 468 </simpara></listitem></varlistentry>
 469 <varlistentry><term><parameter>position</parameter>&#160;:</term>
 470 <listitem><simpara> corresponding position
 471 </simpara></listitem></varlistentry>
 472 </variablelist><para role="since">Since 1.12</para></refsect2>
 473
 474 </refsect1>
 475
 476
 477
 478
 479 </refentry>