<?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-pangorenderer">
  <refnamediv>
    <refname>pango.Renderer</refname>
    <refpurpose>a base class for pango rendering (new in
PyGTK 2.8)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pango.Renderer</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-layout">draw_layout</link></methodname>
        <methodparam><parameter role="keyword">layout</parameter></methodparam>
        <methodparam><parameter role="keyword">x</parameter></methodparam>
        <methodparam><parameter role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-layout-line">draw_layout_line</link></methodname>
        <methodparam><parameter role="keyword">line</parameter></methodparam>
        <methodparam><parameter role="keyword">x</parameter></methodparam>
        <methodparam><parameter role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-glyphs">draw_glyphs</link></methodname>
        <methodparam><parameter role="keyword">font</parameter></methodparam>
        <methodparam><parameter role="keyword">glyphs</parameter></methodparam>
        <methodparam><parameter role="keyword">x</parameter></methodparam>
        <methodparam><parameter role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-rectangle">draw_rectangle</link></methodname>
        <methodparam><parameter role="keyword">part</parameter></methodparam>
        <methodparam><parameter role="keyword">x</parameter></methodparam>
        <methodparam><parameter role="keyword">y</parameter></methodparam>
        <methodparam><parameter role="keyword">width</parameter></methodparam>
        <methodparam><parameter role="keyword">height</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-error-underline">draw_error_underline</link></methodname>
        <methodparam><parameter role="keyword">x</parameter></methodparam>
        <methodparam><parameter role="keyword">y</parameter></methodparam>
        <methodparam><parameter role="keyword">width</parameter></methodparam>
        <methodparam><parameter role="keyword">height</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--draw-trapezoid">draw_trapezoid</link></methodname>
        <methodparam><parameter role="keyword">part</parameter></methodparam>
        <methodparam><parameter role="keyword">y1_</parameter></methodparam>
        <methodparam><parameter role="keyword">x11</parameter></methodparam>
        <methodparam><parameter role="keyword">x21</parameter></methodparam>
        <methodparam><parameter role="keyword">y2</parameter></methodparam>
        <methodparam><parameter role="keyword">x12</parameter></methodparam>
        <methodparam><parameter role="keyword">x22</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--activate">activate</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--deactivate">deactivate</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--part-changed">part_changed</link></methodname>
        <methodparam><parameter role="keyword">part</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--set-color">set_color</link></methodname>
        <methodparam><parameter role="keyword">part</parameter></methodparam>
        <methodparam><parameter role="keyword">color</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-pangorenderer--get-color">get_color</link></methodname>
        <methodparam><parameter role="keyword">part</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-pangorenderer">pango.Renderer</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><link
linkend="class-pangorenderer"><classname>pango.Renderer</classname></link>
is a base class that contains the necessary logic for rendering a <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link> or
<link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>. By
subclassing <link
linkend="class-pangorenderer"><classname>pango.Renderer</classname></link>
and overriding operations such as <link
linkend="method-pangorenderer--draw-glyphs"><methodname>draw_glyphs</methodname>()</link>
and <link
linkend="method-pangorenderer--draw-rectangle"><methodname>draw_rectangle</methodname>()</link>,
renderers for particular font backends and destinations can be
created.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-pangorenderer--draw-layout">
      <title>pango.Renderer.draw_layout</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_layout</methodname>
	  <methodparam><parameter
			 role="keyword">layout</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</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>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>draw_layout</methodname>() method draws the
<link linkend="class-pangolayout"><classname>pango.Layout</classname></link>
s[ecified by <parameter>layout</parameter> at the position specified by
<parameter>x</parameter> and <parameter>y</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--draw-layout-line">
      <title>pango.Renderer.draw_layout_line</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_layout_line</methodname>
	  <methodparam><parameter
			 role="keyword">line</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</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>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>draw_layout_line</methodname>() method draws the
<link
linkend="class-pangolayoutline"><classname>pango.LayoutLine</classname></link>
specified by <parameter>line</parameter> at the position specified by
<parameter>x</parameter> and <parameter>y</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--draw-glyphs">
      <title>pango.Renderer.draw_glyphs</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_glyphs</methodname>
	  <methodparam><parameter
			 role="keyword">font</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">glyphs</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</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>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position of left edge of baseline,
in user space coordinates in Pango units.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>draw_glyphs</methodname>() method draws the
<link
linkend="class-pangoglyphstring"><classname>pango.GlyphString</classname></link>
specified by <parameter>glyphs</parameter> using the <link
linkend="class-pangofont"><classname>pango.Font</classname></link> specified
by <parameter>font</parameter> at the position specified by
<parameter>x</parameter> and <parameter>y</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--draw-rectangle">
      <title>pango.Renderer.draw_rectangle</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_rectangle</methodname>
	  <methodparam><parameter
			 role="keyword">part</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">width</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">height</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">part</parameter>&nbsp;:</term>
	  <listitem><simpara>the part where the rectangle is to be
rendered</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position at which to draw rectangle,
in user space coordinates in Pango units</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position at which to draw rectangle,
in user space coordinates in Pango units</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">width</parameter>&nbsp;:</term>
	  <listitem><simpara>the width of rectangle in Pango units
in user space coordinates</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">height</parameter>&nbsp;:</term>
	  <listitem><simpara>the height of rectangle in Pango units
in user space coordinates</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>draw_rectangle</methodname>() method draws an
axis-aligned rectangle with the size specified by
<parameter>width</parameter> and <parameter>height</parameter> at the
position specified by <parameter>x</parameter> and <parameter>y</parameter>,
all in user space coordinates. The rectangle will be drawn in the rendering
part (see the <xref linkend="pango-render-part-constants"
endterm="pango-render-part-constants-title"></xref>) specified by
<parameter>part</parameter>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--draw-error-underline">
      <title>pango.Renderer.draw_error_underline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_error_underline</methodname>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">width</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">height</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X coordinate of the underline, in Pango units
in the user coordinate system</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y coordinate of the underline, in Pango units
in the user coordinate system</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">width</parameter>&nbsp;:</term>
	  <listitem><simpara>the width of the underline, in Pango units
in the user coordinate system</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">height</parameter>&nbsp;:</term>
	  <listitem><simpara>the height of the underline, in Pango units
in the user coordinate system</simpara></listitem>
	</varlistentry>
      </variablelist>

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

     <para>The <methodname>draw_error_underline</methodname>() method draws a
squiggly line that approximately covers the rectangle specified by
<parameter>x</parameter>, <parameter>y</parameter>,
<parameter>width</parameter> and <parameter>height</parameter> in the style
of an underline used to indicate a spelling error. (The width of the
underline is rounded to an integer number of up/down segments and the
resulting rectangle is centered in the original rectangle).</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--draw-trapezoid">
      <title>pango.Renderer.draw_trapezoid</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>draw_trapezoid</methodname>
	  <methodparam><parameter
			 role="keyword">part</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y1_</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x11</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x21</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y2</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x12</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x22</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">part</parameter>&nbsp;:</term>
	  <listitem><simpara>where the trapezoid is to be
rendered</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y1_</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y coordinate of the top of the
trapezoid</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x11</parameter>&nbsp;:</term>
	  <listitem><simpara>the X coordinate of the left end of the top of
the trapezoid</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x21</parameter>&nbsp;:</term>
	  <listitem><simpara>the X coordinate of the right end of the top of
the trapezoid</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y2</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y coordinate of the bottom of the
trapezoid</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x12</parameter>&nbsp;:</term>
	  <listitem><simpara>the X coordinate of the left end of the bottom of
the trapezoid</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x22</parameter>&nbsp;:</term>
	  <listitem><simpara>the X coordinate of the left end of the bottom of
the trapezoid</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>draw_trapezoid</methodname>() method draws a
trapezoid with the parallel sides aligned with the X axis using the
coordinates specified by <parameter>y1_</parameter>,
<parameter>x11</parameter>, <parameter>x21</parameter>,
<parameter>y2</parameter>, <parameter>x12</parameter>,
<parameter>x22</parameter>. The coordinates are in device space. The
trapezoid is rendered in the part specified by <parameter>part</parameter>
which must be one of the <xref linkend="pango-render-part-constants"
endterm="pango-render-part-constants-title"></xref>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--activate">
      <title>pango.Renderer.activate</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>activate</methodname>
	</methodsynopsis></programlisting>

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

      <para>The <methodname>activate</methodname>() method does initial
setup before performing the rendering operations on renderer. The <link
linkend="method-pangorenderer--deactivate"><methodname>deactivate</methodname>()</link>
method should be called when drawing is complete. Calls to the <link
linkend="method-pangorenderer--draw-layout"><methodname>draw_layout</methodname>()</link>
method automatically activate the layout before drawing on it. Calls to the
<link
linkend="method-pangorenderer--activate"><methodname>activate</methodname>()</link>
and <link
linkend="method-pangorenderer--deactivate"><methodname>deactivate</methodname>()</link>
methods can be nested and the renderer will only be initialized and
deinitialized once.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--deactivate">
      <title>pango.Renderer.deactivate</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>deactivate</methodname>
	</methodsynopsis></programlisting>

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

      <para>The <methodname>deactivate</methodname>() method cleans up after
rendering operations are completed. See the <link
linkend="method-pangorenderer--activate"><methodname>activate</methodname>()</link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--part-changed">
      <title>pango.Renderer.part_changed</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>part_changed</methodname>
	  <methodparam><parameter
			 role="keyword">part</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">part</parameter>&nbsp;:</term>
	  <listitem><simpara>the part that has its rendering
changed.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>part_changed</methodname>() method informs Pango
that the way that the renderering is done for the part specified by
<parameter>part</parameter> has changed in a way that would prevent multiple
pieces being joined together into one drawing
call. <parameter>part</parameter> must be one of the <xref
linkend="pango-render-part-constants"
endterm="pango-render-part-constants-title"></xref>. For instance, if a
subclass of <link
linkend="class-pangorenderer"><classname>pango.Renderer</classname></link>
was to add a stipple option for drawing underlines, it needs to call:</para>

      <programlisting>
renderer.part_changed(pango.RENDER_PART_UNDERLINE)
</programlisting>

      <para>when the stipple changes or underlines with different stipples
might be joined together. Pango automatically calls this for changes to
colors. (See the <link
linkend="method-pangorenderer--set-color"><methodname>set_color</methodname>()</link>
method for more information).</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--set-color">
      <title>pango.Renderer.set_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_color</methodname>
	  <methodparam><parameter
			 role="keyword">part</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">color</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">part</parameter>&nbsp;:</term>
	  <listitem><simpara>the part to change the color
 of</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">color</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangocolor"><classname>pango.Color</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_color</methodname>() method sets the <link
linkend="class-pangocolor"><classname>pango.Color</classname></link>
specified by <parameter>color</parameter> as the color for the part
specified by <parameter>part</parameter>. <parameter>part</parameter> must
be one of the <xref linkend="pango-render-part-constants"
endterm="pango-render-part-constants-title"></xref>.</para>

    </refsect2>

    <refsect2 id="method-pangorenderer--get-color">
      <title>pango.Renderer.get_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_color</methodname>
	  <methodparam><parameter
			 role="keyword">part</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">part</parameter>&nbsp;:</term>
	  <listitem><simpara>a part</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <term><parameter
role="keyword"></parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangocolor"><classname>pango.Color</classname></link> or
<parameter>None</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_color</methodname>() method returns the
current rendering <link
linkend="class-pangocolor"><classname>pango.Color</classname></link> for the
part specified by <parameter>part</parameter>. <parameter>part</parameter>
must be one of the <xref linkend="pango-render-part-constants"
endterm="pango-render-part-constants-title"></xref>. If
<literal>None</literal> is returned, the color has not been set and should
be inherited from the environment.</para>

    </refsect2>

  </refsect1>

</refentry>
