<?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-pangocairocairocontext">
  <refnamediv>
    <refname>pangocairo.CairoContext</refname>
    <refpurpose>object providing support for using Cairo (new in
PyGTK 2.8)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pangocairo.CairoContext</classname></ooclass>
      <ooclass><classname><link linkend="class-cairocontext">cairo.Context</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-pangocairocairocontext">pangocairo.CairoContext</link></methodname>
        <methodparam><parameter role="keyword">cr</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--update-context">update_context</link></methodname>
        <methodparam><parameter role="keyword">context</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--create-layout">create_layout</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--update-layout">update_layout</link></methodname>
        <methodparam><parameter role="keyword">layout</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--show-glyph-string">show_glyph_string</link></methodname>
        <methodparam><parameter role="keyword">font</parameter></methodparam>
        <methodparam><parameter role="keyword">glyphs</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--show-layout-line">show_layout_line</link></methodname>
        <methodparam><parameter role="keyword">line</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--show-layout">show_layout</link></methodname>
        <methodparam><parameter role="keyword">layout</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--glyph-string-path">glyph_string_path</link></methodname>
        <methodparam><parameter role="keyword">font</parameter></methodparam>
        <methodparam><parameter role="keyword">glyphs</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--layout-line-path">layout_line_path</link></methodname>
        <methodparam><parameter role="keyword">line</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangocairocairocontext--layout-path">layout_path</link></methodname>
        <methodparam><parameter role="keyword">layout</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- cairo.Context
  +-- <link linkend="class-pangocairocairocontext">pangocairo.CairoContext</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>Cairo is a graphics library that supports vector graphics and
image compositing that can be used with PyGTK. Since 2.8, GTK+ and Pango do
most of their drawing using Cairo. The Cairo drawing model and primitives
are similar to PostScript which uses an imaging model of painting on a two
dimensional surface. There is a Python module that wraps the Cairo API that
is used by PyGTK via subclassing of the cairo.Context class by the <link
linkend="class-pangocairocairocontext"><classname>pangocairo.CairoContext</classname></link>
class. The cairo.Context class provides most of the drawing primitives used
for drawing on Cairo surfaces.</para>

    <para>PyGTK (and GTK+ and GDK) does not wrap the Cairo API, instead
<link
linkend="class-gdkcairocontext"><classname>gtk.gdk.CairoContext</classname></link>
objects can be used to draw on <link
linkend="class-gdkdrawable"><classname>gtk.gdk.Drawable</classname></link>
objects. A <link
linkend="class-gdkcairocontext"><classname>gtk.gdk.CairoContext</classname></link>
is created using the <link
linkend="method-gdkdrawable--cairo-create"><methodname>gtk.gdk.Drawable.cairo_create</methodname>()</link>
method. See the <link
linkend="class-gdkcairocontext"><classname>gtk.gdk.CairoContext</classname></link>
and Python cairo module documentation for additional methods.</para>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>pangocairo.CairoContext</methodname>
	<methodparam><parameter role="keyword">cr</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">cr</parameter>&nbsp;:</term>
        <listitem><simpara>a <classname><link linkend="class-cairocontext">cairo.Context</link></classname>
        </simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-pangocairocairocontext"><classname>pangocairo.CairoContext</classname></link>.</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-pangocairocairocontext"><classname>pangocairo.CairoContext</classname></link></para>


  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-pangocairocairocontext--update-context">
      <title>pangocairo.CairoContext.update_context</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>update_context</methodname>
	  <methodparam><parameter
			 role="keyword">context</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">context</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangocontext"><classname>pango.Context</classname></link>
created by the <link
linkend="method-pangocairocairofontmap--create-context"><methodname>pangocairo.CairoFontMap.create_context</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>update_context</methodname>() method updates a
<link
linkend="class-pangocontext"><classname>pango.Context</classname></link>
previously created for use with Cairo to match the current transformation
and target surface of a Cairo context. If any layouts have been created for
the context, it's necessary to call the <link
linkend="method-pangolayout--context-changed"><methodname>pango.Layout.context_changed</methodname>()</link>
method on those layouts.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--create-layout">
      <title>pangocairo.CairoContext.create_layout</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>create_layout</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
object.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>create_layout</methodname>() method creates a
<link linkend="class-pangolayout"><classname>pango.Layout</classname></link>
object set up to match the current transformation and target surface of the
Cairo context. This layout can then be used for text measurement with
methods like <link
linkend="method-pangolayout--get-size"><methodname>pango.Layout.get_size</methodname>()</link>
or for drawing with methods like <link
linkend="method-pangocairocairocontext--show-layout"><methodname>show_layout</methodname>()</link>. If
you change the transformation or target surface for the context, you need to
call the <link
linkend="method-pangocairocairocontext--update-layout"><methodname>update_layout</methodname>()</link>
method.</para>

      <para>This method is the most convenient way to use Cairo with Pango,
however it is slightly inefficient since it creates a separate <link
linkend="class-pangocontext"><classname>pango.Context</classname></link>
object for each layout. This might be of concern in an application laying
out large amounts of text.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--update-layout">
      <title>pangocairo.CairoContext.update_layout</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>update_layout</methodname>
	  <methodparam><parameter
			 role="keyword">layout</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">layout</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
created by the <link
linkend="method-pangocairocairocontext--create-layout"><methodname>create_layout</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>update_layout</methodname>() method updates the
private <link
linkend="class-pangocontext"><classname>pango.Context</classname></link> of
the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
(specified by <parameter>layout</parameter>) that was created with the <link
linkend="method-pangocairocairocontext--create-layout"><methodname>create_layout</methodname>()</link>
method to match the current transformation and target surface of a Cairo
context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--show-glyph-string">
      <title>pangocairo.CairoContext.show_glyph_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>show_glyph_string</methodname>
	  <methodparam><parameter
			 role="keyword">font</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">glyphs</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">font</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofont"><classname>pango.Font</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">glyphs</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangoglyphstring"><classname>pango.GlyphString</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>show_glyph_string</methodname>() method draws
the <link
linkend="class-pangoglyphstring"><classname>pango.GlyphString</classname></link>
specified by <parameter>glyphs</parameter> in the cairo context using the
<link linkend="class-pangofont"><classname>pango.Font</classname></link>
specified by <parameter>font</parameter>. The origin of the glyphs (the left
edge of the baseline) will be drawn at the current point of the cairo
context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--show-layout-line">
      <title>pangocairo.CairoContext.show_layout_line</title>

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

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

      <para>The <methodname>show_layout_line</methodname>() method draws the
<link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>
specified by <parameter>line</parameter> in the cairo context. The origin of
the glyphs (the left edge of the line) will be drawn at the current point of
the cairo context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--show-layout">
      <title>pangocairo.CairoContext.show_layout</title>

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

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

      <para>The <methodname>show_layout</methodname>() method draws the
<link linkend="class-pangolayout"><classname>pango.Layout</classname></link>
specified by <parameter>layout</parameter> in the cairo context. The
top-left corner of the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link> will
be drawn at the current point of the cairo context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--glyph-string-path">
      <title>pangocairo.CairoContext.glyph_string_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>glyph_string_path</methodname>
	  <methodparam><parameter
			 role="keyword">font</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">glyphs</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">font</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangofont"><classname>pango.Font</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">glyphs</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangoglyphstring"><classname>pango.GlyphString</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>glyph_string_path</methodname>() method adds the
<link
linkend="class-pangoglyphstring"><classname>pango.GlyphString</classname></link>
specified by <parameter>glyphs</parameter> to the current path in the cairo
context using the <link
linkend="class-pangofont"><classname>pango.Font</classname></link> specified
by font. The origin of the added glyphs (the left edge of the baseline) will
be at the current point of the cairo context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--layout-line-path">
      <title>pangocairo.CairoContext.layout_line_path</title>

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

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

      <para>The <methodname>layout_line_path</methodname>() method adds the
text in the <link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>
specified by <parameter>line</parameter> to the current path in the
specified cairo context. The origin of the glyphs (the left edge of the
line) will be at the current point of the cairo context.</para>

    </refsect2>

    <refsect2 id="method-pangocairocairocontext--layout-path">
      <title>pangocairo.CairoContext.layout_path</title>

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

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

      <para>The <methodname>layout_path</methodname>() method adds the text
in the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
specified by <parameter>layout</parameter> to the current path in the
specified cairo context. The top-left corner of the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link> will
be at the current point of the cairo context.</para>

    </refsect2>

  </refsect1>

</refentry>
