path: root/docs/reference/pygtk-gtkclipboard.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-gtkclipboard">
 <refnamediv>
    <refname>gtk.Clipboard</refname> <refpurpose>an object to store data to
    and retrieve data from (new in PyGTK 2.2)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Clipboard</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkclipboard">gtk.Clipboard</link></methodname>
	<methodparam><parameter role="keyword">display</parameter><initializer>gtk.gdk.display_get_default()</initializer></methodparam>
	<methodparam><parameter role="keyword">selection</parameter><initializer>"CLIPBOARD"</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--get-display">get_display</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--get-owner">get_owner</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--store">store</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--clear">clear</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--set-can-store">set_can_store</link></methodname>
	<methodparam><parameter role="keyword">targets</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--set-with-data">set_with_data</link></methodname>
	<methodparam><parameter role="keyword">targets</parameter></methodparam>
	<methodparam><parameter role="keyword">get_func</parameter></methodparam>
	<methodparam><parameter role="keyword">clear_func</parameter></methodparam>
	<methodparam><parameter role="keyword">user_data</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--set-text">set_text</link></methodname>
	<methodparam><parameter role="keyword">text</parameter></methodparam>
	<methodparam><parameter role="keyword">len</parameter><initializer>-1</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--set-image">set_image</link></methodname>
	<methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-for-contents">wait_for_contents</link></methodname>
	<methodparam><parameter role="keyword">target</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-for-targets">wait_for_targets</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-for-text">wait_for_text</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkclipboard--wait-for-rich-text">wait_for_rich_text</link></methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-for-image">wait_for_image</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-is-target-available">wait_is_target_available</link></methodname>
	<methodparam><parameter role="keyword">target</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkclipboard--wait-is-uris-available">wait_is_uris_available</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-is-text-available">wait_is_text_available</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkclipboard--wait-is-rich-text-available">wait_is_rich_text_available</link></methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--wait-is-image-available">wait_is_image_available</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--request-contents">request_contents</link></methodname>
	<methodparam><parameter role="keyword">target</parameter></methodparam>
	<methodparam><parameter role="keyword">callback</parameter></methodparam>
	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--request-targets">request_targets</link></methodname>
	<methodparam><parameter role="keyword">callback</parameter></methodparam>
	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--request-text">request_text</link></methodname>
	<methodparam><parameter role="keyword">callback</parameter></methodparam>
	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkclipboard--request-rich-text">request_rich_text</link></methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkclipboard--request-image">request_image</link></methodname>
	<methodparam><parameter role="keyword">callback</parameter></methodparam>
	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
    </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
        <methodname><link linkend="function-gtk--clipboard-get">gtk.clipboard_get</link></methodname>
        <methodparam><parameter role="keyword">selection</parameter><initializer>"CLIPBOARD"</initializer></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkclipboard">gtk.Clipboard</link>
</synopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkclipboard">
    <title>gtk.Clipboard Signal Prototypes</title>

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

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkclipboard--owner-change">owner-change</link></term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
          <methodparam><parameter>clipboard</parameter></methodparam>
          <methodparam><parameter>event</parameter></methodparam>
          <methodparam><parameter>user_param1</parameter></methodparam>
          <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This object is available in PyGTK 2.2 and above.</para>
    </note>

    <para> The <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
object represents a clipboard of data shared between different processes or
between different widgets in the same process. Each clipboard is identified
by a name encoded as a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link>. The
<link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link> is
basically a higher-level interface to the lower-level <link
linkend="class-gtkselectiondata"><classname>gtk.SelectionData</classname></link>
and selection interface. The built-in atoms are:</para>

    <itemizedlist>
      <listitem>
	<simpara>"PRIMARY"</simpara>
      </listitem>
      <listitem>
	<simpara>"SECONDARY"</simpara>
      </listitem>
      <listitem>
	<simpara>"CLIPBOARD"</simpara>
      </listitem>
      <listitem>
	<simpara>"BITMAP"</simpara>
      </listitem>
      <listitem>
	<simpara>"COLORMAP"</simpara>
      </listitem>
      <listitem>
	<simpara>"DRAWABLE"</simpara>
      </listitem>
      <listitem>
	<simpara>"PIXMAP"</simpara>
      </listitem>
      <listitem>
	<simpara>"STRING"</simpara>
      </listitem>
      <listitem>
	<simpara>"WINDOW"</simpara>
      </listitem>
   </itemizedlist>

    <para>Creating a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> from
strings can be done with the <link
linkend="constructor-gdkatom-intern">gtk.gdk.atom_intern</link>()
constructor function though <literal>PyGTK</literal> will usually do the
conversion under the covers as needed. The name of a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> can be
retrieved using the Python <function>str</function>() function:</para>

    <programlisting>
  name = str(atom)
</programlisting>

    <para>The default clipboard corresponds to the "CLIPBOARD" atom; another
commonly used clipboard is the "PRIMARY" clipboard, which, in X,
traditionally contains the currently selected text.</para>

<para>To simultaneously support different formats on the clipboard, the
clipboard mechanism allows you to provide callbacks instead of the actual
data. When you set the contents of the clipboard, you can either supply the
data directly (via a method like <link
linkend="method-gtkclipboard--set-text"><methodname>set_text</methodname>()</link>),
or you can supply a callback to be called when the data is needed (via the
<link
linkend="method-gtkclipboard--set-with-data"><methodname>set_with_data</methodname>()</link>
method.) Providing a callback also avoids making unnecessary copies of the
data.</para>

<para>Along with the methods to get the clipboard contents as an arbitrary
data chunk, there is a method to retrieve it as text, the <link
linkend="method-gtkclipboard--wait-for-text"><methodname>wait_for_text</methodname>()</link>
method. This method takes care of determining which formats are advertised
by the clipboard provider, asking for the clipboard in the best available
format and converting the results into the UTF-8 encoding. (The standard
form for representing strings in <literal>GTK</literal>+.) </para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Clipboard</methodname>
	<methodparam><parameter role="keyword">display</parameter><initializer>gtk.gdk.display_get_default()</initializer></methodparam>
	<methodparam><parameter role="keyword">selection</parameter><initializer>"CLIPBOARD"</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">display</parameter>&nbsp;:</term>
	<listitem><simpara>the <link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
for which the clipboard is to be retrieved or created.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">selection</parameter>&nbsp;:</term>
	<listitem><simpara>a string that identifies the clipboard
to use.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>the appropriate clipboard object or if no
	clipboard already exists, a new one will be created. Once a
	clipboard object has been created, it is persistent for all time and
	cannot be freed.</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Returns the clipboard object for the <link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
specified by <parameter>display</parameter> and the selection specified by
the string in <parameter>selection</parameter>. Cut/copy/paste menu items
and keyboard shortcuts should use the default clipboard, returned by passing
<literal>"CLIPBOARD"</literal> for <parameter>selection</parameter>. The
currently-selected object or text should be provided on the clipboard
identified by <literal>"PRIMARY"</literal>. Cut/copy/paste menu items
conceptually copy the contents of the <literal>"PRIMARY"</literal> clipboard
to the default clipboard, i.e. they copy the selection to what the user sees
as the clipboard.</para>

    <para>See <ulink
url="http://www.freedesktop.org/standards/clipboards-spec/clipboards.txt">
http://www.freedesktop.org/standards/clipboards-spec/clipboards.txt</ulink>
for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections under
the X window system. On Win32 the <literal>"PRIMARY"</literal> clipboard is
essentially ignored.</para>

    <para>It's possible to have arbitrarily named clipboards. If you do
invent new clipboards, you should prefix the selection name with an
underscore (because the ICCCM requires that nonstandard atoms are
underscore-prefixed), and namespace it as well. For example, if your
application called "Foo" has a special-purpose clipboard, you might call it
"_FOO_SPECIAL_CLIPBOARD".</para>

    <para>In PyGTK 2.4 and above, the <parameter>display</parameter>
argument is optional and defaults to the default display returned from the
<link
linkend="function-gdk--display-get-default"><function>gtk.gdk.display_get_default</function>()</link>
function.</para>

    <para>In PyGTK 2.4 and above, the <parameter>selection</parameter>
argument is optional and defaults to "CLIPBOARD".</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkclipboard--get-display">
      <title>gtk.Clipboard.get_display</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_display</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
associated with the clipboard</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_display</methodname>() method returns the
<link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
associated with the clipboard.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--get-owner">
      <title>gtk.Clipboard.get_owner</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_owner</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the owner of the clipboard, if any; otherwise
<literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_owner</methodname>() method returns the
owner set by the <methodname>set_with_owner</methodname>() method if neither
the <link
linkend="method-gtkclipboard--set-with-data"><methodname>set_with_data()</methodname></link>
method nor the <link
linkend="method-gtkclipboard--clear"><methodname>clear()</methodname></link>
method have been subsequently called. This method returns
<literal>None</literal> otherwise.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--store">
      <title>gtk.Clipboard.store</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>store</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
      </variablelist>

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

      <para>The <methodname>store</methodname>() method stores the current
clipboard data (as specified by the <link
linkend="method-gtkclipboard--set-can-store"><methodname>set_can_store</methodname>()</link>
method) somewhere so that it will stay around after the application has
quit.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--clear">
      <title>gtk.Clipboard.clear</title>

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

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

      <para>The <methodname>clear</methodname>() method clears the contents
of the clipboard. Generally this should only be called between the time you
call the <!--<link
linkend="method-gtkclipboard- -set-with-owner"><methodname>set_with_owner()</methodname></link>
or --><link
linkend="method-gtkclipboard--set-with-data"><methodname>set_with_data()</methodname></link>,
and when the <parameter>clear_func</parameter> you supplied is
called. Otherwise, the clipboard may be owned by someone else.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--set-can-store">
      <title>gtk.Clipboard.set_can_store</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_can_store</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">targets</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of 3-tuples containing information about
the available forms that should be stored or <literal>None</literal> to
indicate that all forms should be stored.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_can_store</methodname>() method sets a hint
that the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link> can
store the list of targets specified by <parameter>targets</parameter> can be
stored somewhere when the application exits or when the <link
linkend="method-gtkclipboard--store"><methodname>store</methodname>()</link>
method is called. This value is reset when the clipboard owner
changes. Where the clipboard data is stored is platform dependent, see the
<link
linkend="method-gdkdisplay--store-clipboard"><methodname>gtk.gdk.Display.store_clipboard</methodname>()</link>
method for more information. If <parameter>targets</parameter> is
<literal>None</literal> all target forms currently available on the
clipboard should be stored.</para>

      <para>The 3-tuples listed in <parameter>targets</parameter> contain
the following items:</para>

    <itemizedlist>
      <listitem>
	<simpara>a string representing a target supported by the
clipboard</simpara>
      </listitem>
      <listitem>
	  <simpara>a flags value used for drag and drop - a combination of:
<literal>gtk.TARGET_SAME_APP</literal> and
<literal>gtk.TARGET_SAME_WIDGET</literal></simpara>
      </listitem>
      <listitem>
	<simpara>an application assigned integer that is passed as a signal
parameter to help identify the target type</simpara>
      </listitem>
   </itemizedlist>

    </refsect2>

    <refsect2 id="method-gtkclipboard--set-with-data">
      <title>gtk.Clipboard.set_with_data</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_with_data</methodname>
	  <methodparam><parameter role="keyword">targets</parameter></methodparam>
	  <methodparam><parameter role="keyword">get_func</parameter></methodparam>
	  <methodparam><parameter role="keyword">clear_func</parameter></methodparam>
	  <methodparam><parameter role="keyword">user_data</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">targets</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of 3-tuples containing information about
the available forms for the clipboard data</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">get_func</parameter>&nbsp;:</term>
	  <listitem><simpara>a function to call to get the actual clipboard
data</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">clear_func</parameter>&nbsp;:</term>
	  <listitem><simpara>when the clipboard contents are set again,
this function will be called, and <parameter>get_func</parameter> will not
be subsequently called.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>the user data to pass to
<parameter>get_func</parameter> and
<parameter>clear_func</parameter>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if setting the
clipboard data succeeded. If setting the clipboard data failed the
provided callback functions will be ignored.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_with_data</methodname>() method virtually
sets the contents of the specified clipboard by providing a list of
supported formats (specified by <parameter>targets</parameter>) for the
clipboard data and a function (specified by <parameter>get_func</parameter>)
to call to get the actual data when it is
requested. <parameter>clear_func</parameter> is a function that is called
when the contents of the clipboard are being changed to provide cleanup
operations on
<parameter>user_data</parameter>. <parameter>user_data</parameter> is passed
to <parameter>get_func</parameter> and <parameter>clear_func</parameter>
when they are invoked. The 3-tuples listed in <parameter>targets</parameter>
contain the following items:</para>

    <itemizedlist>
      <listitem>
	<simpara>a string representing a target supported by the
clipboard</simpara>
      </listitem>
      <listitem>
	  <simpara>a flags value used for drag and drop - a combination of:
<literal>gtk.TARGET_SAME_APP</literal> and
<literal>gtk.TARGET_SAME_WIDGET</literal></simpara>
      </listitem>
      <listitem>
	<simpara>an application assigned integer that is passed as a signal
parameter to help identify the target type</simpara>
      </listitem>
   </itemizedlist>

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

      <programlisting>
  def get_func(clipboard, selectiondata, info, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>,
<parameter>selectiondata</parameter> is a <link
linkend="class-gtkselectiondata"><classname>gtk.SelectionData</classname></link>
object to set with the data, <parameter>info</parameter> is the application
assigned integer associated with a target, and <parameter>data</parameter>
is the <parameter>user_data</parameter> argument.</para>

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

      <programlisting>
  def clear_func(clipboard, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link> and
<parameter>data</parameter> is the <parameter>user_data</parameter>
argument.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--set-text">
      <title>gtk.Clipboard.set_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_text</methodname>
	  <methodparam><parameter role="keyword">text</parameter></methodparam>
	  <methodparam><parameter role="keyword">len</parameter><initializer>-1</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">text</parameter>&nbsp;:</term>
	  <listitem><simpara>a string.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">len</parameter>&nbsp;:</term>
	  <listitem><simpara>the length of <parameter>text</parameter>, in
bytes, or -1, to calculate the length.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_text</methodname>() method sets the contents
of the clipboard to the string specified by <parameter>text</parameter>. If
<parameter>len</parameter> is given it determines the length of
<parameter>text</parameter> to be copied. If <parameter>len</parameter> is
not specified it defaults to -1 and the method calculates the text
length.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--set-image">
      <title>gtk.Clipboard.set_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_image</methodname>
	  <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_image</methodname>() method sets the
contents of the clipboard to the <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
specified by <parameter>pixbuf</parameter>. GTK+ will take responsibility
for responding for requests for the image, and for converting the image into
the requested format.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-for-contents">
      <title>gtk.Clipboard.wait_for_contents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_for_contents</methodname>
	  <methodparam><parameter role="keyword">target</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">target</parameter>&nbsp;:</term>
	  <listitem><simpara>an atom or string representing the form into
which the clipboard owner should convert the selection.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a newly-allocated <link
linkend="class-gtkselectiondata"><classname>gtk.SelectionData</classname></link>
object or <literal>None</literal> if retrieving the given target
failed.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_for_contents</methodname>() method requests
the contents of the clipboard using the target specified by
<parameter>target</parameter>. This method waits for the data to be received
using the main loop, so events, timeouts, etc, may be dispatched during the
wait.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-for-targets">
      <title>gtk.Clipboard.wait_for_targets</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_for_targets</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>returns a tuple containing any targets that are
present on the clipboard or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_for_targets</methodname>() method returns a
tuple containing the targets (as <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> objects)
that are present on the clipboard, or <literal>None</literal> if there
aren't any targets available. This function waits for the data to be
received using the main loop, so events, timeouts, etc, may be dispatched
during the wait.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-for-text">
      <title>gtk.Clipboard.wait_for_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_for_text</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string, or <literal>None</literal> if
retrieving the selection data failed. (This could happen for various reasons,
in particular if the clipboard was empty or if the contents of the
clipboard could not be converted into text form.)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_for_text</methodname>() method requests the
contents of the clipboard as text and converts the result to UTF-8 if
necessary. This method waits for the data to be received using the main
loop, so events, timeouts, etc, may be dispatched during the wait.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-for-rich-text">
      <title>gtk.Clipboard.wait_for_rich_text</title>
 
      <programlisting><methodsynopsis language="python">
        <methodname>wait_for_rich_text</methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis></programlisting>
 
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">buffer</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>
          to retrieve the deserialize formats from.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 2-tuple containing the rich text as a string
          and the format string , or <literal>None</literal> if retrieving
          the selection data failed. (This could happen for various reasons,
          in particular if the clipboard was empty or if the contents of the
          clipboard could not be converted into text
          form.)</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>
 
      <para>The <methodname>wait_for_rich_text</methodname>() method
      requests the contents of the clipboard as rich text. This method
      waits for the data to be received using the main loop, so events,
      timeouts, etc, may be dispatched during the wait.</para>
 
    </refsect2>
 
    <refsect2 id="method-gtkclipboard--wait-for-image">
      <title>gtk.Clipboard.wait_for_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_for_image</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>,
or <literal>None</literal> if retrieving the selection data failed.
(This could happen for various reasons, in particular if the clipboard was
empty or if the contents of the clipboard could not be converted into an
image.)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_for_image</methodname>() method requests
the contents of the clipboard as an image and converts the result to a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>. This
method waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-is-target-available">
      <title>gtk.Clipboard.wait_is_target_available</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_is_target_available</methodname>
	  <methodparam><parameter role="keyword">target</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">target</parameter>&nbsp;:</term>
	  <listitem><simpara>an atom or string representing the target of
interest.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the target is
available.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_is_target_available</methodname>() method
tests to see if the target specified by <parameter>target</parameter> is
available to be copied from the clipboard. This method can be used to
determine if a <guimenuitem>Paste</guimenuitem> menu item should be
insensitive or not.</para>

      <para>If you want to see if there's text available on the clipboard,
use the <link
linkend="method-gtkclipboard--wait-is-text-available"><methodname>wait_is_text_available</methodname>()</link>
method instead.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-is-uris-available">
      <title>gtk.Clipboard.wait_is_uris_available</title>
 
      <programlisting><methodsynopsis language="python">
        <methodname>wait_is_uris_available</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
                                                                                
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if is there is an URI list
	  available, <literal>False</literal>
          otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>
 
      <para>
	The <methodname>wait_is_uris_available</methodname>()
	method Test to see if there is a list of URIs available to be pasted This
	is done by requesting the TARGETS atom and checking if it contains the URI targets.
	This function waits for the data to be received using the main loop, so events,
	timeouts, etc, may be dispatched during the wait.
      </para>
       
      <!-- NOT IMPLEMENTED
      <para>This method is a little faster than calling <link
      linkend="method-gtkclipboard- -wait-for-uris"><methodname>gtk.Clipboard.wait_for_uris</methodname></link>()
      since it doesn't need to retrieve the actual text.</para>
      -->
 
    </refsect2>
 
    <refsect2 id="method-gtkclipboard--wait-is-text-available">
      <title>gtk.Clipboard.wait_is_text_available</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_is_text_available</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> is there is text
available.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_is_text_available</methodname>() method
tests to see if there is text available to be copied from the clipboard.
This is done by requesting the "TARGETS" atom and checking if it contains
any of the names: "STRING", "TEXT", "COMPOUND_TEXT", "UTF8_STRING". This
method waits for the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.</para>

      <para>This method is a little faster than calling the <link
linkend="method-gtkclipboard--wait-for-text"><methodname>wait_for_text()</methodname></link>
since it doesn't need to retrieve the actual text.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--wait-is-rich-text-available">
      <title>gtk.Clipboard.wait_is_rich_text_available</title>
 
      <programlisting><methodsynopsis language="python">
        <methodname>wait_is_rich_text_available</methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis></programlisting>
                                                                                
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">buffer</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>
          to retrieve the deserialize formats from.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if is there is rich
          text available, <literal>False</literal>
          otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>
 
      <para>The <methodname>wait_is_rich_text_available</methodname>()
      method tests to see if there is rich text available to be pasted. This
      is done by requesting the <literal>TARGETS</literal> atom and checking
      if it contains any of the supported rich text targets. This method
      waits for the data to be received using the main loop, so events,
      timeouts, etc, may be dispatched during the wait.</para>
       
      <para>This method is a little faster than calling <link
      linkend="method-gtkclipboard--wait-for-rich-text"><methodname>wait_for_rich_text()</methodname></link>
      since it doesn't need to retrieve the actual text.</para>
 
    </refsect2>
 
    <refsect2 id="method-gtkclipboard--wait-is-image-available">
      <title>gtk.Clipboard.wait_is_image_available</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>wait_is_image_available</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> is there is an image
available.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>wait_is_image_available</methodname>() method
tests to see if there is an image available to be copied from the clipboard.
This is done by requesting the "TARGETS" atom and checking if it contains
any of the supported image targets. This method waits for the data to be
received using the main loop, so events, timeouts, etc, may be dispatched
during the wait.</para>

      <para>This method is a little faster than calling the <link
linkend="method-gtkclipboard--wait-for-image"><methodname>wait_for_image()</methodname></link>
since it doesn't need to retrieve the actual image data.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--request-contents">
      <title>gtk.Clipboard.request_contents</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>request_contents</methodname>
	  <methodparam><parameter role="keyword">target</parameter></methodparam>
	  <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">target</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link>
or string representing the form that the clipboard owner should convert
the selection to.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
	  <listitem><simpara>a function to call when the results are received
(or the retrieval fails).</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>user data to pass to <parameter>callback</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>request_contents</methodname>() method requests
the contents of clipboard in the form specified by
<parameter>target</parameter>.  When the results of the request are later
received the function specified by <parameter>callback</parameter> will be
invoked and passed the data specified by
<parameter>user_data</parameter>. The signature of
<parameter>callback</parameter> is:</para>

      <programlisting>
  def callback(clipboard, selection_data, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
that invoked callback and <parameter>selection_data</parameter> is the <link
linkend="class-gtkselectiondata"><classname>gtk.SelectionData</classname></link>
containing the target data and <parameter>data</parameter> is
<parameter>user_data</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--request-targets">
      <title>gtk.Clipboard.request_targets</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>request_targets</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>a function to call when the targets are received,
or the retrieval fails. (It will always be called
one way or the other.)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>user data to pass to
<parameter>callback</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>request_targets</methodname>() method requests
the contents of the clipboard as list of supported targets.  When the list
is later received, <parameter>callback</parameter> will be called with the
data specified by <parameter>user_data</parameter>. The signature of
<parameter>callback</parameter> is:</para>

      <programlisting>
  def callback(clipboard, targets, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
that <parameter>targets</parameter> is retrieved
from. <parameter>targets</parameter> is a tuple containing the <link
linkend="class-gdkatom"><classname>gtk.gdk.Atom</classname></link> objects
corresponding to the targets of clipboard. <parameter>targets</parameter>
will contain the resulting targets if the request succeeded, or an empty
tuple if it failed.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--request-text">
      <title>gtk.Clipboard.request_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>request_text</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>a function to call when the text is received,
or the retrieval fails. (It will always be called
one way or the other.)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>user data to pass to
<parameter>callback</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>request_text</methodname>() method requests the
contents of the clipboard as text. When the text is later received, it will
be converted to UTF-8 if necessary, and <parameter>callback</parameter> will
be called with the data specified by <parameter>user_data</parameter>. The
signature of <parameter>callback</parameter> is:</para>

      <programlisting>
  def callback(clipboard, text, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
that <parameter>text</parameter> is retrieved from and
<parameter>data</parameter> is <parameter>user_data</parameter>.
<parameter>text</parameter> will contain the resulting text if the request
succeeded, or the empty string if it failed. This could happen for various
reasons, in particular if the clipboard was empty or if the contents of the
clipboard could not be converted into text form.</para>

    </refsect2>

    <refsect2 id="method-gtkclipboard--request-rich-text">
      <title>gtk.Clipboard.request_rich_text</title>
 
      <programlisting><methodsynopsis language="python">
        <methodname>request_rich_text</methodname>
        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
        <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">buffer</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtktextbuffer"><classname>gtk.TextBuffer</classname></link>
          to retrieve the deserialize formats from.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
          <listitem><simpara>a function to call when the text is received,
          or the retrieval fails. (It will always be called one way or the
          other.)</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
          <listitem><simpara>user data to pass to
          <parameter>callback</parameter>.</simpara></listitem>
        </varlistentry>
      </variablelist>
 
      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>
 
      <para>The <methodname>request_rich_text</methodname>() method requests
      the contents of the clipboard as rich text. When the rich text is
      later received, the function specified by
      <parameter>callback</parameter> will be called with the argument
      specified by <parameter>user_data</parameter>.</para>

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

      <programlisting>
        def callback(clipboard, format, text, length, data):
      </programlisting>
       
      <para>where <parameter>format</parameter> is the atom indicating the
      text format, <parameter>text</parameter> contains the resulting rich
      text if the request succeeded, or <literal>None</literal> if it
      failed, <parameter>length</parameter> contains the length of
      <parameter>text</parameter> and <parameter>data</parameter> is
      <parameter>user_data</parameter>. This function can fail for various
      reasons, in particular if the clipboard was empty or if the contents
      of the clipboard could not be converted into rich text form.</para>
 
    </refsect2>

    <refsect2 id="method-gtkclipboard--request-image">
      <title>gtk.Clipboard.request_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>request_image</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>a function to call when the image is received,
or the retrieval fails. (It will always be called
one way or the other.)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
	  <listitem><simpara>user data to pass to
<parameter>callback</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>request_image</methodname>() method requests the
contents of the clipboard as a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
image. When the image is later received, it will be converted to a <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> and
<parameter>callback</parameter> will be called with the data specified by
<parameter>user_data</parameter>. The signature of
<parameter>callback</parameter> is:</para>

      <programlisting>
  def callback(clipboard, pixbuf, data):
</programlisting>

      <para>where <parameter>clipboard</parameter> is the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
that <parameter>pixbuf</parameter> is retrieved from and
<parameter>data</parameter> is <parameter>user_data</parameter>.
<parameter>pixbuf</parameter> will contain the resulting image data if the
request succeeded, or <literal>None</literal> if it failed. This could
happen for various reasons, in particular if the clipboard was empty or if
the contents of the clipboard could not be converted into an image.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--clipboard-get">
      <title>gtk.clipboard_get</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.clipboard_get</methodname>
	  <methodparam><parameter
			 role="keyword">selection</parameter><initializer>"CLIPBOARD"</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">selection</parameter>&nbsp;:</term>
	  <listitem><simpara>a string specifying a <link
	  linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>. If
	  not specified it defaults to "CLIPBOARD".</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the appropriate clipboard object or if no
	clipboard already exists, a new one will be created. Once a
	clipboard object has been created, it is persistent for all time and
	cannot be freed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.clipboard_get</function>() function returns
the <link
linkend="class-gtkclipboard"><classname>gtk.Clipboard</classname></link>
specified by selection for the default <link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>. See
the <link linkend="constructor-gtkclipboard">gtk.Clipboard</link>
constructor for more information.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkclipboard--owner-change">
      <title>The "owner-change" gtk.Clipboard Signal</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter>clipboard</parameter>&nbsp;:</term>
          <listitem><simpara>the object that received the signal.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>event</parameter>&nbsp;:</term>
          <listitem><simpara>the event marking the ownership
          change.</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>

      <note>
        <para>This signal is available in GTK+ 2.8 and above.</para>
      </note>

      <para>The "owner-changed" signal is emitted when the owner of the
      clipboard is changed.</para>

    </refsect2>

  </refsect1>

</refentry>