<?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-pangocontext">
  <refnamediv>
    <refname>pango.Context</refname>
    <refpurpose>stores global information used to control
rendering.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pango.Context</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-pangocontext">pango.Context</link></methodname>
	<methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-pangocontext--get-font-map">get_font_map</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-pangocontext--set-font-map">set_font_map</link></methodname>
	<methodparam><parameter role="keyword">font_map</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--list-families">list_families</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--load-font">load_font</link></methodname>
	<methodparam><parameter
		       role="keyword">desc</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--load-fontset">load_fontset</link></methodname>
	<methodparam><parameter
		       role="keyword">desc</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">language</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--get-metrics">get_metrics</link></methodname>
	<methodparam><parameter
		       role="keyword">desc</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">language</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--set-font-description">set_font_description</link></methodname>
	<methodparam><parameter
		       role="keyword">desc</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--get-font-description">get_font_description</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--get-language">get_language</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--set-language">set_language</link></methodname>
	<methodparam><parameter
		       role="keyword">language</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--set-base-dir">set_base_dir</link></methodname>
	<methodparam><parameter
		       role="keyword">direction</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangocontext--get-base-dir">get_base_dir</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-pangocontext">pango.Context</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
    linkend="class-pangocontext"><classname>pango.Context</classname></link>
    object contains global information used to control the rendering
    process. The information accessible using the <link
    linkend="class-pangocontext"><classname>pango.Context</classname></link>
    methods includes:</para>

    <itemizedlist>
      <listitem>
	<simpara>the default <link linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link></simpara>
      </listitem>
      <listitem>
	<simpara>the default <link linkend="class-pangolanguage"><classname>pango.Language</classname></link></simpara>
      </listitem>
      <listitem>
	<simpara>the base direction of the text</simpara>
      </listitem>
   </itemizedlist>

    <para>A <link
linkend="class-pangocontext"><classname>pango.Context</classname></link> can
be created with the <link
linkend="method-gtkwidget--create-pango-context"><methodname>gtk.Widget.create_pango_context</methodname>()</link>
method. The <link
linkend="class-pangocontext"><classname>pango.Context</classname></link>
associated with a <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> is
retrieved using the <link
linkend="method-gtkwidget--get-pango-context"><methodname>gtk.Widget.get_pango_context</methodname>()</link>)
method.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>pango.Context</methodname>
    </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link linkend="class-pangocontext"><classname>pango.Context</classname></link>
            <emphasis>without</emphasis> an associated font map</simpara></listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>Constructor is available in PyGTK 2.16 and above.</para>
    </note>

    <para>Creates a new PangoContext initialized to default values.</para>

    <para>This constructor is not particularly useful as it should always be followed by a
      call to <link linkend="method-pangocontext--set-font-map">set_font_map</link>
      method.  Method <link linkend="method-pangofontmap--create-context">pango.FontMap.create_context</link>
      does these two steps together and hence users are recommended to use that.</para>

    <para>If you are using Pango as part of a higher-level system, that system may have
      it's own way of create a <link linkend="class-pangocontext">pango.Context</link>.
      For instance, the GTK+ toolkit has, among others,
      <link linkend="function-gdk--pango-context-get-for-screen">gtk.gdk.pango_context_get_for_screen</link>
      and <link linkend="method-gtkwidget--get-pango-context">gtk.Widget.get_pango_context</link>.
      Use those instead.
    </para>
  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-pangocontext--get-font-map">
      <title>pango.Context.get_font_map</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_font_map</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the font map for the
              <link linkend="class-pangocontext"><classname>pango.Context</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>
    </refsect2>

    <refsect2 id="method-pangocontext--set-font-map">
      <title>pango.Context.get_font_map</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_font_map</methodname>
	  <methodparam><parameter role="keyword">font_map</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">font_map</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link linkend="class-pangofontmap"><classname>pango.FontMap</classname>
                to set</link> object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.16 and above.</para>
      </note>

      <para>Sets the font map to be searched when fonts are looked-up in this
        context. This is only for internal use by Pango backends,
        a <link linkend="class-pangocontext"><classname>pango.Context</classname></link>
        obtained via one of the recommended methods should already have a suitable font
        map.</para>
    </refsect2>

    <refsect2 id="method-pangocontext--list-families">
      <title>pango.Context.list_families</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>list_families</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing a set of <link
linkend="class-pangofontfamily"><classname>pango.FontFamily</classname></link> 
objects.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>list_families</methodname>() method returns a
tuple containing the list of all the <link
linkend="class-pangofontfamily"><classname>pango.FontFamily</classname></link> 
objects for a context.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--load-font">
      <title>pango.Context.load_font</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>load_font</methodname>
	  <methodparam><parameter
			 role="keyword">desc</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">desc</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
describing the font to load</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangofont"><classname>pango.Font</classname></link> loaded,
or <literal>None</literal> if no font matched.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>load_font</methodname>() method loads and
returns the <link
linkend="class-pangofont"><classname>pango.Font</classname></link> from one
of the fontmaps in the context that is the closest match for the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>desc</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--load-fontset">
      <title>pango.Context.load_fontset</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>load_fontset</methodname>
	  <methodparam><parameter
			 role="keyword">desc</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">language</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">desc</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
describing the fonts to load</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">language</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
the fonts will be used for</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangofontset"><classname>pango.FontSet</classname></link>, or
<literal>None</literal> if no font matched.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>load_fontset</methodname>() method loads and
returns a set of fonts (in a <link
linkend="class-pangofontset"><classname>pango.FontSet</classname></link>)
from the context that can be used to render a font matching the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>desc</parameter> with the <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
specified by <parameter>language</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--get-metrics">
      <title>pango.Context.get_metrics</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_metrics</methodname>
	  <methodparam><parameter
			 role="keyword">desc</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">language</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">desc</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">language</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
that determines the script to get the metrics for, or
<literal>None</literal> to get the metrics for the entire
font.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontmetrics"><classname>pango.FontMetrics</classname></link> 
object.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_metrics</methodname>() method returns the
overall metric information for the font described by the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
specified by <parameter>desc</parameter>. Since the metrics may be
substantially different for different scripts, a <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
(specified by <parameter>language</parameter>) can be provided to indicate
that the metrics should correspond to the script(s) used by that language.
If the value of <parameter>language</parameter> is <literal>None</literal>,
the returned <link
linkend="class-pangofontmetrics"><classname>pango.FontMetrics</classname></link> 
covers the entire font.</para>

      <para>The family name in the <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
may be a comma separated list of families. If characters from multiple of
these families would be used to render the string, then the returned fonts
would be a composite of the metrics for the fonts loaded for the individual
families.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--set-font-description">
      <title>pango.Context.set_font_description</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_font_description</methodname>
	  <methodparam><parameter
			 role="keyword">desc</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">desc</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_font_description</methodname>() method sets
the default <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
(specified by <parameter>desc</parameter>) for the context.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--get-font-description">
      <title>pango.Context.get_font_description</title>

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

      <para>The <methodname>get_font_description</methodname>() method
returns the default <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link> 
for the context.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--get-language">
      <title>pango.Context.get_language</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_language</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the global <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_language</methodname>() method returns the
global <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
for the context.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--set-language">
      <title>pango.Context.set_language</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_language</methodname>
	  <methodparam><parameter
			 role="keyword">language</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">language</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_language</methodname>() method sets the
global <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
for the context to the value specified by
<parameter>language</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangocontext--set-base-dir">
      <title>pango.Context.set_base_dir</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_base_dir</methodname>
	  <methodparam><parameter
			 role="keyword">direction</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">direction</parameter>&nbsp;:</term>
	  <listitem><simpara>the new base direction</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_base_dir</methodname>() method sets the base
text direction for the context to the value specified by
<parameter>direction</parameter>. The value of
<parameter>direction</parameter> must be one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>pango.DIRECTION_LTR</literal></term>
	  <listitem>
	    <simpara>The text is written left-to-right</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.DIRECTION_RTL</literal></term>
	  <listitem>
	    <simpara>The text is written right-to-left</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.DIRECTION_TTB_LTR</literal></term>
	  <listitem>
	    <simpara>The text is written vertically top-to-bottom, with the
rows ordered from left to right.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>pango.DIRECTION_TTB_RTL</literal></term>
	  <listitem>
	    <simpara>The text is written vertically top-to-bottom, with the
rows ordered from right to left.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>


  <refsect2 id="method-pangocontext--get-base-dir">
      <title>pango.Context.get_base_dir</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_base_dir</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the base direction for the
context.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_base_dir</methodname>() method returns the
base text direction for the context. See the <link
linkend="method-pangocontext--set-base-dir"><methodname>set_base_dir</methodname>()</link> 
method for more information.</para>

    </refsect2>

  </refsect1>

</refentry>
