path: root/docs/reference/pygtk-gtkprintjob.xml

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

  <refnamediv>
    <refname>gtkunixprint.PrintJob</refname>
      <refpurpose>an object that represents a print job (new in PyGTK
      2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtkunixprint.PrintJob</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkprintjob">gtkunixprint.PrintJob</link></methodname>
        <methodparam><parameter role="keyword">title</parameter></methodparam>
        <methodparam><parameter role="keyword">printer</parameter></methodparam>
        <methodparam><parameter role="keyword">settings</parameter></methodparam>
        <methodparam><parameter role="keyword">page_setup</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-settings">get_settings</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-printer">get_printer</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-title">get_title</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-status">get_status</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--set-source-file">set_source_file</link></methodname>
        <methodparam><parameter role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-surface">get_surface</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--set-track-print-status">set_track_print_status</link></methodname>
        <methodparam><parameter role="keyword">track_status</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--get-track-print-status">get_track_print_status</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkprintjob--send">send</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkprintjob">gtkunixprint.PrintJob</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkprintjob">
    <title>gtkunixprint.PrintJob Properties</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"page-setup"</entry>
	      <entry>Read-Write-Construct Only</entry>
	      <entry>The Page Setup. Available in GTK+ 2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"printer"</entry>
	      <entry>Read-Write-Construct Only</entry>
	      <entry>The Printer to print the job to. Available in GTK+
	      2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"settings"</entry>
	      <entry>Read-Write-Construct Only</entry>
	      <entry>The Printer Settings. Available in GTK+ 2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"title"</entry>
	      <entry>Read-Write-Construct Only</entry>
	      <entry>Title of the print job.  Default value:
	      <literal>None</literal>. Available in GTK+ 2.10.</entry>
	    </row>

            <row valign="top">
              <entry>"track-print-status"</entry>
              <entry>Read-Write</entry>
              <entry>if <literal>True</literal> the print job will continue
              to emit status-changed signals after the print data has been
              sent to the printer or print server. Available in GTK+
              2.10.</entry>
            </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkprintjob">
    <title>gtkunixprint.PrintJob Signal Prototypes</title>

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

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkprintjob--status-changed">status-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>printjob</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

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

    <para>A <link
    linkend="class-gtkprintjob"><classname>gtkunixprint.PrintJob</classname></link>
    object represents a job that is sent to a printer. You only need to deal
    directly with print jobs if you use the non-portable <link
    linkend="class-gtkprintunixdialog"><classname>gtkunixprint.PrintUnixDialog</classname></link>
    API.</para>

    <para>Use the <link
    linkend="method-gtkprintjob--get-surface"><methodname>get_surface</methodname>()</link>
    method to obtain the cairo surface onto which the pages must be
    drawn. Use the <link
    linkend="method-gtkprintjob--send"><methodname>send</methodname>()</link>
    method to send the finished job to the printer. If you don't use cairo
    <link
    linkend="class-gtkprintjob"><classname>gtkunixprint.PrintJob</classname></link>
    also supports printing of manually generated postscript, via the <link
    linkend="method-gtkprintjob--set-source-file"><methodname>set_source_file</methodname>()</link>
    method.</para>

  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-gtkprintjob">
      <title>gtkunixprint.PrintJob</title>

      <programlisting><constructorsynopsis language="python">
        <methodname>gtkunixprint.PrintJob</methodname>
        <methodparam><parameter role="keyword">title</parameter></methodparam>
        <methodparam><parameter role="keyword">printer</parameter></methodparam>
        <methodparam><parameter role="keyword">settings</parameter></methodparam>
        <methodparam><parameter role="keyword">page_setup</parameter></methodparam>
      </constructorsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">title</parameter>&nbsp;:</term>
          <listitem><simpara>the job title</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">printer</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtkprinter"><classname>gtkunixprint.Printer</classname></link></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">settings</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtkprintsettings"><classname>gtk.PrintSettings</classname></link></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">page_setup</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtkpagesetup"><classname>gtk.PageSetup</classname></link></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
          linkend="class-gtkprintjob"><classname>gtkunixprint.PrintJob</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Creates a new <link
      linkend="class-gtkprintjob"><classname>gtkunixprint.PrintJob</classname></link>.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkprintjob--get-settings">
      <title>gtkunixprint.PrintJob.get_settings</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the settings of the print
          job</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_settings</methodname>() method returns the
      <link
      linkend="class-gtkprintsettings"><classname>gtk.PrintSettings</classname></link>
      of the print job.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--get-printer">
      <title>gtkunixprint.PrintJob.get_printer</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the printer of the print
          job</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_printer</methodname>() method returns the
      <link
      linkend="class-gtkprinter"><classname>gtkunixprint.Printer</classname></link>
      of the print job.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--get-title">
      <title>gtkunixprint.PrintJob.get_title</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the title of the print job</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_title</methodname>() method returns the
      print job title.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--get-status">
      <title>gtkunixprint.PrintJob.get_status</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the status of the print
          job</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_status</methodname>() method returns the
      status of the print job.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--set-source-file">
      <title>gtkunixprint.PrintJob.set_source_file</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_source_file</methodname>
        <methodparam><parameter role="keyword">filename</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
          <listitem><simpara>the file to be printed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>False</literal> if an error
          occurred</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>set_source_file</methodname>() method makes the
      <link
      linkend="class-gtkprintjob"><classname>gtkunixprint.PrintJob</classname></link>
      send the existing document specified by
      <parameter>filename</parameter> to the printing system. The file can
      be in any format understood by the platforms printing system
      (typically PostScript, but on many platforms PDF may work too).</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--get-surface">
      <title>gtkunixprint.PrintJob.get_surface</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the cairo surface of the print
          job</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_surface</methodname>() method returns a
      cairo surface onto which the pages of the print job should be
      rendered.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--set-track-print-status">
      <title>gtkunixprint.PrintJob.set_track_print_status</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_track_print_status</methodname>
        <methodparam><parameter role="keyword">track_status</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">track_status</parameter>&nbsp;:</term>
          <listitem><simpara>if <literal>True</literal> track the status of
          the print job after sending</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>set_track_print_status</methodname>() method
      enable or disables tracking of the print job status based on the value
      specified by <parameter>track_status</parameter>. If
      <parameter>track_status</parameter> is <literal>True</literal>, the
      print job will try to continue report on the status of the print job
      in the printer queues and printer. This can allow your application to
      show things like "out of paper" issues, and when the print job
      actually reaches the printer.</para>
      
      <para>This method is often implemented using some form of polling, so
      tracking should not be enabled unless needed.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--get-track-print-status">
      <title>gtkunixprint.PrintJob.get_track_print_status</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if print job status
          will be reported after printing</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_track_print_status</methodname>() method
      returns wheter jobs will be tracked after printing.  For details, see
      the <link
      linkend="method-gtkprintjob--set-track-print-status"><methodname>set_track_print_status()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="method-gtkprintjob--send">
      <title>gtkunixprint.PrintJob.send</title>

      <programlisting><methodsynopsis language="python">
        <methodname>send</methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
          <listitem><simpara>the function to call when the job
          completes</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
          <listitem><simpara>user data that gets passed to
          <parameter>callback</parameter></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>False</literal> if an error
          occurred</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>send</methodname>() method sends the print job
      off to the printer and registers the function specified by
      <parameter>callback</parameter> ro be called when the job
      completes.</para>

      <para>The signature of <parameter>callback</parameter> is:</para>

      <programlisting>
def callback(print_job, data, errormsg):
      </programlisting>

      <para>where <parameter>data</parameter> is
      <parameter>user_data</parameter> and <parameter>errormsg</parameter>
      is a message indicating what problem has occurred or
      <literal>None</literal> if no error has occurred.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkprintjob--status-changed">
      <title>The "status-changed" Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>gtkprintjob</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>gtkprintjob</parameter>&nbsp;:</term>
	  <listitem><simpara>the gtkprintjob that received the
	  signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
	  any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "status-changed" signal is emitted when the status of a job
      changes. The signal handler can use the <link
      linkend="method-gtkprintjob--get-status"><methodname>get_status</methodname>()</link>
      method to obtain the new status.</para>

    </refsect2>

  </refsect1>

</refentry>