<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-pangofontdescription">
  <refnamediv>
    <refname>pango.FontDescription</refname>
    <refpurpose>an object representing a description of a font.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pango.FontDescription</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-pangofontdescription">pango.FontDescription</link></methodname>
	<methodparam><parameter role="keyword">str</parameter>
	  <initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--copy">copy</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--copy-static">copy_static</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--hash">hash</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-family">set_family</link></methodname>
	<methodparam><parameter
		       role="keyword">family</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-family-static">set_family_static</link></methodname>
	<methodparam><parameter
		       role="keyword">family</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-family">get_family</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-style">set_style</link></methodname>
	<methodparam><parameter
		       role="keyword">style</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-style">get_style</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-variant">set_variant</link></methodname>
	<methodparam><parameter
		       role="keyword">variant</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-variant">get_variant</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-weight">set_weight</link></methodname>
	<methodparam><parameter
		       role="keyword">weight</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-weight">get_weight</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-stretch">set_stretch</link></methodname>
	<methodparam><parameter
		       role="keyword">stretch</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-stretch">get_stretch</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--set-size">set_size</link></methodname>
	<methodparam><parameter
		       role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-size">get_size</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--get-set-fields">get_set_fields</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--unset-fields">unset_fields</link></methodname>
	<methodparam><parameter
		       role="keyword">to_unset</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--merge">merge</link></methodname>
	<methodparam><parameter
		       role="keyword">desc_to_merge</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">replace_existing</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--merge-static">merge_static</link></methodname>
	<methodparam><parameter
		       role="keyword">desc_to_merge</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">replace_existing</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--better-match">better_match</link></methodname>
	<methodparam><parameter
		       role="keyword">old_match</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">new_match</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--to-string">to_string</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangofontdescription--to-filename">to_filename</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangofontdescription--set-absolute-size">set_absolute_size</link></methodname>
        <methodparam><parameter role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangofontdescription--get-size-is-absolute">get_size_is_absolute</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
represents the description of an ideal font. They are used to both specify
the characteristics of a font to load and to list the available fonts on the
system.</para>

  </refsect1>

  <refsect1 id="constructor-pangofontdescription">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>pango.FontDescription</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
object.</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
object from the representation in the string specified by
<parameter>str</parameter>. The format of the string representation
is:</para>

    <programlisting>
  "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]"
</programlisting>

    <para>where <literal>FAMILY-LIST</literal> is a comma separated list of
families optionally terminated by a comma, <literal>STYLE_OPTIONS</literal>
is a whitespace separated list of words where each <literal>WORD</literal>
describes one of style, variant, weight, or stretch, and
<literal>SIZE</literal> is an decimal number (size in points). For example
the following are all valid string representations:</para>

    <programlisting>
  "sans bold 12"
  "serif,monospace bold italic condensed 16"
  "normal 10"
</programlisting>

    <para>The commonly available font families are: Normal, Sans, Serif and
Monospace. The available styles are:</para>

    <variablelist>
      <varlistentry>
	<term>Normal</term>
	<listitem>
	  <simpara>the font is upright.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Oblique</term>
	<listitem>
	  <simpara>the font is slanted, but in a roman style.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Italic</term>
	<listitem>
	  <simpara>the font is slanted in an italic style. </simpara>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>The available weights are:</para>

    <variablelist>
      <varlistentry>
	<term>Ultra-Light</term>
	<listitem>
	  <simpara>the ultralight weight (= 200)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Light</term>
	<listitem>
	  <simpara>the light weight (=300)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Normal</term>
	<listitem>
	  <simpara>the default weight (= 400)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Bold</term>
	<listitem>
	  <simpara>the bold weight (= 700)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Ultra-Bold</term>
	<listitem>
	  <simpara>the ultra-bold weight (= 800)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Heavy</term>
	<listitem>
	  <simpara>the heavy weight (= 900)</simpara>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>The available variants are:</para>

    <variablelist>
      <varlistentry>
	<term>Normal</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Small-Caps</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>The available stretch styles are:</para>

    <variablelist>
      <varlistentry>
	<term>Ultra-Condensed</term>
	<listitem>
	  <simpara>the smallest width</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Extra-Condensed</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Condensed</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Semi-Condensed</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Normal</term>
	<listitem>
	  <simpara>the normal width</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Semi-Expanded</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Expanded</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Extra-Expanded</term>
	<listitem>
	  <simpara></simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Ultra-Expanded</term>
	<listitem>
	  <simpara>the widest width</simpara>
	</listitem>
      </varlistentry>
    </variablelist>

    <para></para>

 </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-pangofontdescription--copy">
      <title>pango.FontDescription.copy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>copy</methodname>() method returns a new copy of
this font description.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--copy-static">
      <title>pango.FontDescription.copy_static</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy_static</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>..</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>copy_static</methodname>() method is like the
<link
linkend="method-pangofontdescription--copy"><methodname>copy</methodname>()</link> 
method, but only a shallow copy is made of the family name and other
allocated attribute fields. The result can only be used until the original
font description is modified or freed. This is meant to be used when the
copy is only needed temporarily.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--hash">
      <title>pango.FontDescription.hash</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>hash</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the hash value.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>hash</methodname>() method computes and returns
a hash of the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-family">
      <title>pango.FontDescription.set_family</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_family</methodname>
	  <methodparam><parameter
			 role="keyword">family</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">family</parameter>&nbsp;:</term>
	  <listitem><simpara>a string representing the family
name.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_family</methodname>() method sets the family
name attribute field of the font description to the value specified by
<parameter>family</parameter>. The family name represents a family of
related font styles, and will resolve to a particular <link
linkend="class-pangofontfamily"><classname>pango.FontFamily</classname></link>. 
In some uses of <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>, 
it is also possible to use a comma separated list of family names for this
field.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-family-static">
      <title>pango.FontDescription.set_family_static</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_family_static</methodname>
	  <methodparam><parameter
			 role="keyword">family</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">family</parameter>&nbsp;:</term>
	  <listitem><simpara>a string representing the family
name.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The set_family_static() method is like the <link
linkend="method-pangofontdescription--set-family"><methodname>set_family</methodname>()</link>, 
except that no copy of <parameter>family</parameter> is made. The caller
must make sure that the string passed in stays around until the font
description is no longer needed or the family name is set again. This method
can be used if <parameter>family</parameter> is only needed
temporarily.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-family">
      <title>pango.FontDescription.get_family</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_family</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the family name or <literal>None</literal> if
not previously set.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_family</methodname>() method returns the
family name attribute field of the font description. See the <link
linkend="method-pangofontdescription--set-family"><methodname>set_family</methodname>()</link> 
method for more information.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-style">
      <title>pango.FontDescription.set_style</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_style</methodname>
	  <methodparam><parameter
			 role="keyword">style</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">style</parameter>&nbsp;:</term>
	  <listitem><simpara>the style for the font
description</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_style</methodname>() method sets the slant
style attribute field of the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
to the value specified by <parameter>style</parameter>. The value of
<parameter>style</parameter>  must be either
<literal>pango.STYLE_NORMAL</literal>,
<literal>pango.STYLE_ITALIC</literal>, or
<literal>pango.STYLE_OBLIQUE</literal>. Most fonts will either have a italic
style or an oblique style, but not both, and font matching in Pango will
match italic specifications with oblique fonts and vice-versa if an exact
match is not found.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-style">
      <title>pango.FontDescription.get_style</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_style</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the slant style for the font description.
</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_style</methodname>() method returns the
slant style attribute field of the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>. 
See the <link
linkend="method-pangofontdescription--set-style"><methodname>set_style</methodname>()</link> 
method for more details. Use the <link
linkend="method-pangofontdescription--get-set-fields"><methodname>get_set_fields</methodname>()</link> 
method to find out if the field was explicitly set.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-variant">
      <title>pango.FontDescription.set_variant</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_variant</methodname>
	  <methodparam><parameter
			 role="keyword">variant</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">variant</parameter>&nbsp;:</term>
	  <listitem><simpara>the variant type for the font
description.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_variant</methodname>() method sets the
variant attribute field of a font description to the value specified by
<parameter>variant</parameter>. The value of <parameter>variant</parameter>
must be either <literal>pango.VARIANT_NORMAL</literal> or
<literal>pango.VARIANT_SMALL_CAPS</literal>.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-variant">
      <title>pango.FontDescription.get_variant</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_variant</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the variant style of the font
description.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_variant</methodname>() method returns the
variant style of a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>. 
See the <link
linkend="method-pangofontdescription--set-variant"><methodname>set_variant</methodname>()</link> 
method for more information. Use the <link
linkend="method-pangofontdescription--get-set-fields"><methodname>get_set_fields</methodname>()</link> 
method to find out if the field was explicitly set.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-weight">
      <title>pango.FontDescription.set_weight</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_weight</methodname>
	  <methodparam><parameter
			 role="keyword">weight</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">weight</parameter>&nbsp;:</term>
	  <listitem><simpara>the weight for the font
description.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_weight</methodname>() method sets the weight
attribute field of a font description to the value specified by
<parameter>weight</parameter>. The value of <parameter>weight</parameter>
specifies how bold or light the font should be in a range from 100 to 900.
The predefined values of weight are:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>pango.WEIGHT_ULTRALIGHT</literal></term>
	  <listitem>
	    <simpara>the ultralight weight (= 200)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.WEIGHT_LIGHT</literal></term>
	  <listitem>
	    <simpara>the light weight (=300)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.WEIGHT_NORMAL</literal></term>
	  <listitem>
	    <simpara>the default weight (= 400)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.WEIGHT_BOLD</literal></term>
	  <listitem>
	    <simpara>the bold weight (= 700)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.WEIGHT_ULTRABOLD</literal></term>
	  <listitem>
	    <simpara>the ultrabold weight (= 800)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.WEIGHT_HEAVY</literal></term>
	  <listitem>
	    <simpara>the heavy weight (= 900)</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-weight">
      <title>pango.FontDescription.get_weight</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_weight</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the weight field for the font
description.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_weight</methodname>() method returns the
value of the weight attribute of a font description. See the <link
linkend="method-pangofontdescription--set-weight"><methodname>set_weight</methodname>()</link> 
method for more information. Use the <link
linkend="method-pangofontdescription--get-set-fields"><methodname>get_set_fields</methodname>()</link> 
method to determine if the attribute was explicitly set.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-stretch">
      <title>pango.FontDescription.set_stretch</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_stretch</methodname>
	  <methodparam><parameter
			 role="keyword">stretch</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stretch</parameter>&nbsp;:</term>
	  <listitem><simpara>the stretch for the font
description</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_stretch</methodname>() method sets the
stretch attribute field of a font description to the value specified by
<parameter>stretch</parameter>. The value of <parameter>stretch</parameter>
specifies how narrow or wide the font should be relative to the base width
of the font family:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>pango.STRETCH_ULTRA_CONDENSED</literal></term>
	  <listitem>
	    <simpara>the narrowest width</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_EXTRA_CONDENSED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_CONDENSED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_SEMI_CONDENSED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_NORMAL</literal></term>
	  <listitem>
	    <simpara>the normal (base) width</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_SEMI_EXPANDED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_EXPANDED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_EXTRA_EXPANDED</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.STRETCH_ULTRA_EXPANDED</literal></term>
	  <listitem>
	    <simpara>the widest width</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-stretch">
      <title>pango.FontDescription.get_stretch</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_stretch</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the stretch field for the font
description</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_stretch</methodname>() method returns the
stretch attribute field of a font description. See the <link
linkend="method-pangofontdescription--set-stretch"><methodname>set_stretch</methodname>()</link> 
method for more details. Use the <link
linkend="method-pangofontdescription--get-set-fields"><methodname>get_set_fields</methodname>()</link> 
method to determine if the field was explicitly set.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-size">
      <title>pango.FontDescription.set_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_size</methodname>
	  <methodparam><parameter
			 role="keyword">size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the size for the font description in pango
units.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_size</methodname>() method sets the
size attribute field of a font description to the value specified by
<parameter>size</parameter>. The value of <parameter>size</parameter> is
specified in pango units. There are <literal>pango.SCALE</literal> (1024)
pango units in one device unit (the device unit is a point for font
sizes).</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-size">
      <title>pango.FontDescription.get_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the size for the font description in pango
units.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_size</methodname>() method returns the value
of the size attribute field of a font description. See the <link
linkend="method-pangofontdescription--get-size"><methodname>get_size</methodname>()</link> 
method for more information. There are <literal>pango.SCALE</literal> pango
units in one device unit (point). If the stretch attribute field has not
previously been set, 0 is returned. Use the <link
linkend="method-pangofontdescription--get-set-fields"><methodname>get_set_fields</methodname>()</link> 
method to determine if the field was explicitly set.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--get-set-fields">
      <title>pango.FontDescription.get_set_fields</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_set_fields</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a bitmask with bits set corresponding to the
font description attribute fields that have been set.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_set_fields</methodname>() method returns a
value that indicates which attribute fields in a font description have been
set. The value returned is a combination of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_FAMILY</literal></term>
	  <listitem>
	    <simpara>the font family has been set.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_STYLE</literal></term>
	  <listitem>
	    <simpara>the font slant style has been set.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_VARIANT</literal></term>
	  <listitem>
	    <simpara>the font variant has been set.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_WEIGHT</literal></term>
	  <listitem>
	    <simpara>the font weight has been set.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_STRETCH</literal></term>
	  <listitem>
	    <simpara>the font stretch has been set.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.FONT_MASK_SIZE</literal></term>
	  <listitem>
	    <simpara>the font size has been set.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--unset-fields">
      <title>pango.FontDescription.unset_fields</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>unset_fields</methodname>
	  <methodparam><parameter
			 role="keyword">to_unset</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">to_unset</parameter>&nbsp;:</term>
	  <listitem><simpara>a bitmask of attribute fields in the font
description to unset.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>unset_fields</methodname>() method unsets the
attribute fields (specified by <parameter>to_unset</parameter>) in the
<link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>. 
Note that this merely marks the attribute fields cleared, it does not clear
the settings.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--merge">
      <title>pango.FontDescription.merge</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>merge</methodname>
	  <methodparam><parameter
			 role="keyword">desc_to_merge</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">replace_existing</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">desc_to_merge</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
to merge into the font description</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">replace_existing</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal>, replace attribute
fields in the font description with the corresponding values from
<parameter>desc_to_merge</parameter>, even if they are already
exist.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>merge</methodname>() method merges the attribute
fields that are set in the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>desc_to_merge</parameter> into the attribute fields
in the font description. If <parameter>replace_existing</parameter> is
<literal>False</literal>, only fields in the font description that are not
already set are affected. If <parameter>replace_existing</parameter> is
<literal>True</literal>, attribute fields that are already set will also be
replaced.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--merge-static">
      <title>pango.FontDescription.merge_static</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>merge_static</methodname>
	  <methodparam><parameter
			 role="keyword">desc_to_merge</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">replace_existing</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">desc_to_merge</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
to merge from</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">replace_existing</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal>, replace attribute
fields in the font description with the corresponding values from
<parameter>desc_to_merge</parameter>, even if they are already
exist.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>merge_static</methodname>() method is similar to
the <link
linkend="method-pangofontdescription--merge"><methodname>merge</methodname>()</link> 
method, but only a shallow copy is made of the family name and other
allocated fields. The font description can only be used until
<parameter>desc_to_merge</parameter> is modified or freed. This is meant to
be used when the merged font description is only needed temporarily.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--better-match">
      <title>pango.FontDescription.better_match</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>better_match</methodname>
	  <methodparam><parameter
			 role="keyword">old_match</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">new_match</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">old_match</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link>, 
or <literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">new_match</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if
<parameter>new_match</parameter> is a better match</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>better_match</methodname>() method determines if
the attributes of the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>new_match</parameter> are a closer match for the
font description than the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>old_match</parameter>. If
<parameter>old_match</parameter> is <literal>None</literal>, determines if
<parameter>new_match</parameter> is a match at all. The weight and style
attribute need only match approximately but the other attributes must match
exactly.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--to-string">
      <title>pango.FontDescription.to_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>to_string</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string representation of the font
description.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>to_string</methodname>() method returns a string
representation of the font description. See the <link
linkend="constructor-pangofontdescription">pango.FontDescription</link>()
constructor for a description of the format of the string representation.
The family list in the string description will only have a terminating comma
if the last word of the list is a valid style option.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--to-filename">
      <title>pango.FontDescription.to_filename</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>to_filename</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string representation of the font description
as a filename.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>to_filename</methodname>() method returns a
filename representation of a font description. The filename is identical to
the result from calling the <link
linkend="method-pangofontdescription--to-string"><methodname>to_string</methodname>()</link> 
method, but underscores replace characters that are not typically used in
filenames, and it is in lower case only.</para>

    </refsect2>

    <refsect2 id="method-pangofontdescription--set-absolute-size">
      <title>pango.FontDescription.set_absolute_size</title>
 
      <programlisting><methodsynopsis language="python">
        <methodname>set_absolute_size</methodname>
        <methodparam><parameter role="keyword">size</parameter></methodparam>
      </methodsynopsis></programlisting>
 
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">size</parameter>&nbsp;:</term>
          <listitem><simpara>the new size, in Pango units. There are
          <literal>pango.SCALE</literal> Pango units in one device unit. For
          an output backend where a device unit is a pixel, a
          <parameter>size</parameter> value of 10 * pango.SCALE gives a 10
          pixel font.</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>
 
      <para>Sets the size field of a font description, in device units. This
      is mutually exclusive with <link
      linkend="method-pangofontdescription--set-size"><methodname>pango.FontDescription.set_size()</methodname></link>.</para>
 
    </refsect2>
 
    <refsect2 id="method-pangofontdescription--get-size-is-absolute">
      <title>pango.FontDescription.get_size_is_absolute</title>
                                                                                
      <programlisting><methodsynopsis language="python">
        <methodname>get_size_is_absolute</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
 
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>whether the size for the font description is in
          points or device units.  Use <link
          linkend="method-pangofontdescription--get-set-fields"><methodname>pango.FontDescription.get_set_fields()</methodname></link>
          to find out if the size field of the font description was
          explicitly set or not.</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>
 
      <para>Determines whether the size of the font is in points or device
      units.  See <link
      linkend="method-pangofontdescription--set-size"><methodname>pango.FontDescription.set_size()</methodname></link>
      and <link
      linkend="method-pangofontdescription--set-absolute-size"><methodname>pango.FontDescription.set_absolute_size()</methodname></link>.</para>
 
    </refsect2>
 
  </refsect1>

</refentry>
