<?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-gtkprintcontext">

  <refnamediv>
    <refname>gtk.PrintContext</refname>
      <refpurpose>Encapsulates context for drawing pages (new in PyGTK 2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.PrintContext</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-cairo-context">get_cairo_context</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-page-setup">get_page_setup</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-width">get_width</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-height">get_height</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-dpi-x">get_dpi_x</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-dpi-y">get_dpi_y</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--get-pango-fontmap">get_pango_fontmap</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--create-pango-context">create_pango_context</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--create-pango-layout">create_pango_layout</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintcontext--set-cairo-context">set_cairo_context</link></methodname>
        <methodparam><parameter role="keyword">cr</parameter></methodparam>
        <methodparam><parameter role="keyword">dpi_x</parameter></methodparam>
        <methodparam><parameter role="keyword">dpi_y</parameter></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkprintcontext">gtk.PrintContext</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkprintcontext">
    <title>gtk.PrintContext Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
    linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>
    encapsulates context information that is required when drawing pages for
    printing, such as the cairo context and important parameters like page
    size and resolution. It also lets you easily create <link
    linkend="class-pangolayout"><classname>pango.Layout</classname></link>
    and <link
    linkend="class-pangocontext"><classname>pango.Context</classname></link>
    objects that match the font metrics of the cairo surface.</para>

    <para><link
    linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>
    objects gets passed to the "begin-print", "end-print",
    "request-page-setup" and "draw-page" signals on the <link
    linkend="class-gtkprintoperation"><classname>gtk.PrintOperation</classname></link>.</para>

<example>
<title>Using <link
linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>
in a "draw-page" callback</title>
<programlisting>
def draw_page(operation, context, page_nr):
  cr = context.get_cairo_context()

  # Draw a red rectangle, as wide as the paper (inside the margins)
  cr.set_source_rgb(1.0, 0, 0)
  cr.rectangle(0, 0, context.get_width(), 50)
  
  cr.fill()

  # Draw some lines
  cr.move_to(20, 10)
  cr.line_to(40, 20)
  cr.arc(60, 60, 20, 0, M_PI)
  cr.line_to(80, 20)
  
  cr.set_source_rgb(0, 0, 0)
  cr.set_line_width(5)
  cr.set_line_cap(cairo.LINE_CAP_ROUND)
  cr.set_line_join(cairo.LINE_JOIN_ROUND)
  
  cr.stroke()

  # Draw some text
  layout = cr.create_layout()
  layout.set_text("Hello World! Printing is easy")
  desc = pango.FontDescription("sans 28")
  layout.set_font_description(desc)

  cr.move_to(30, 20)
  cr.layout_path(layout)

  # Font Outline
  cr.set_source_rgb(0.93, 1.0, 0.47)
  cr.set_line_width(0.5)
  cr.stroke_preserve()

  # Font Fill
  cr.set_source_rgb(0, 0.0, 1.0)
  cr.fill()
</programlisting>
</example>

<para>Printing support was added in GTK+ 2.10.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkprintcontext--get-cairo-context">
      <title>gtk.PrintContext.get_cairo_context</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_cairo_context</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the cairo context</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_cairo_context</methodname>() method returns
      the cairo context that is associated with the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-page-setup">
      <title>gtk.PrintContext.get_page_setup</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_page_setup</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the page setup</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_page_setup</methodname>() method returns the
      <link
      linkend="class-gtkpagesetup"><classname>gtk.PageSetup</classname></link>
      that determines the page dimensions of the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-width">
      <title>gtk.PrintContext.get_width</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_width</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the width</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_width</methodname>() method returns the width
      of the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>,
      in pixels.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-height">
      <title>gtk.PrintContext.get_height</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_height</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the height</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_height</methodname>() method returns the
      width of the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>,
      in pixels.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-dpi-x">
      <title>gtk.PrintContext.get_dpi_x</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_dpi_x</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the horizontal resolution</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_dpi_x</methodname>() method returns the
      horizontal resolution of the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>,
      in dots per inch.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-dpi-y">
      <title>gtk.PrintContext.get_dpi_y</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_dpi_y</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the vertical resolution</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_dpi_y</methodname>() method returns the
      vertical resolution of the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>,
      in dots per inch.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--get-pango-fontmap">
      <title>gtk.PrintContext.get_pango_fontmap</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_pango_fontmap</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the font map</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The method returns a <link
      linkend="class-pangofontmap"><classname>pango.FontMap</classname></link>
      that is suitable for use with the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--create-pango-context">
      <title>gtk.PrintContext.create_pango_context</title>

      <programlisting><methodsynopsis language="python">
        <methodname>create_pango_context</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
          linkend="class-pangocontext"><classname>pango.Context</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>create_pango_context</methodname>() method
      creates a new <link
      linkend="class-pangocontext"><classname>pango.Context</classname></link>
      that can be used with the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--create-pango-layout">
      <title>gtk.PrintContext.create_pango_layout</title>

      <programlisting><methodsynopsis language="python">
        <methodname>create_pango_layout</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link linkend="class-pangolayout"><classname>pango.Layout</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>create_pango_layout</methodname>() method
      creates a new <link
      linkend="class-pangolayout"><classname>pango.Layout</classname></link>
      that is suitable for use with the <link
      linkend="class-gtkprintcontext"><classname>gtk.PrintContext</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprintcontext--set-cairo-context">
      <title>gtk.PrintContext.set_cairo_context</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_cairo_context</methodname>
        <methodparam><parameter role="keyword">cr</parameter></methodparam>
        <methodparam><parameter role="keyword">dpi_x</parameter></methodparam>
        <methodparam><parameter role="keyword">dpi_y</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">cr</parameter>&nbsp;:</term>
          <listitem><simpara></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">dpi_x</parameter>&nbsp;:</term>
          <listitem><simpara></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">dpi_y</parameter>&nbsp;:</term>
          <listitem><simpara></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>set_cairo_context</methodname>() method sets the
      CairoContext specified by <parameter>cr</parameter> as the cairo
      context for the print context. <parameter>dpi_x</parameter> and
      <parameter>dpi_y</parameter> specify the horizontal and vertical
      resolution of the print context.</para>

    </refsect2>

  </refsect1>

</refentry>
