reference: pygtk-gtkclipboard.xml: reorder methods, fixing some links in the process

1 files changed, 509 insertions, 507 deletions

diff --git a/docs/reference/pygtk-gtkclipboard.xml b/docs/reference/pygtk-gtkclipboard.xml
index 765ed303..fbafb1a7 100644
--- a/docs/reference/pygtk-gtkclipboard.xml
+++ b/docs/reference/pygtk-gtkclipboard.xml
@@ -23,99 +23,101 @@
 	<methodparam></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--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-text">set_text</link></methodname>
-	<methodparam><parameter role="keyword">text</parameter></methodparam>
-	<methodparam><parameter role="keyword">len</parameter><initializer>-1</initializer></methodparam>
+	<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--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>
+	<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--request-text">request_text</link></methodname>
-	<methodparam><parameter role="keyword">callback</parameter></methodparam>
-	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+	<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--request-targets">request_targets</link></methodname>
-	<methodparam><parameter role="keyword">callback</parameter></methodparam>
-	<methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+	<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-is-text-available">wait_is_text_available</link></methodname>
-	<methodparam></methodparam>
+        <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-targets">wait_for_targets</link></methodname>
+	<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--set-can-store">set_can_store</link></methodname>
-	<methodparam><parameter role="keyword">targets</parameter></methodparam>  </methodsynopsis>
-      <methodsynopsis language="python">
-	<methodname><link linkend="method-gtkclipboard--store">store</link></methodname>
+	<methodparam><parameter role="keyword">target</parameter></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>
+        <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-for-image">wait_for_image</link></methodname>
+	<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--set-image">set_image</link></methodname>
-	<methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
+        <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-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>
+	<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--wait-for-rich-text">wait_for_rich_text</link></methodname>
-        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
+	<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--wait-is-rich-text-available">wait_is_rich_text_available</link></methodname>
+	<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--wait-is-uris-available">wait_is_uris_available</link></methodname>
-        <methodparam></methodparam>
+	<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>
 
@@ -346,6 +348,134 @@ 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>
 
@@ -447,59 +577,6 @@ argument.</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--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-text">
       <title>gtk.Clipboard.set_text</title>
 
@@ -533,150 +610,31 @@ length.</para>
 
     </refsect2>
 
-    <refsect2 id="method-gtkclipboard--request-contents">
-      <title>gtk.Clipboard.request_contents</title>
+    <refsect2 id="method-gtkclipboard--set-image">
+      <title>gtk.Clipboard.set_image</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>
+	  <methodname>set_image</methodname>
+	  <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
 	</methodsynopsis></programlisting>
       <variablelist>
 	<varlistentry>
-	  <term><parameter role="keyword">target</parameter>&nbsp;:</term>
+	  <term><parameter role="keyword">pixbuf</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-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-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>
+linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</simpara></listitem>
 	</varlistentry>
       </variablelist>
 
       <note>
-	<para>This method is available in PyGTK 2.4 and above.</para>
+	<para>This method is available in PyGTK 2.10 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>
+      <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>
 
@@ -714,6 +672,34 @@ 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>
 
@@ -742,63 +728,71 @@ loop, so events, timeouts, etc, may be dispatched during the wait.</para>
 
     </refsect2>
 
-    <refsect2 id="method-gtkclipboard--wait-is-text-available">
-      <title>gtk.Clipboard.wait_is_text_available</title>
-
+    <refsect2 id="method-gtkclipboard--wait-for-rich-text">
+      <title>gtk.Clipboard.wait_for_rich_text</title>
+ 
       <programlisting><methodsynopsis language="python">
-	  <methodname>wait_is_text_available</methodname>
-	  <methodparam></methodparam>
-	</methodsynopsis></programlisting>
+        <methodname>wait_for_rich_text</methodname>
+        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
+      </methodsynopsis></programlisting>
+ 
       <variablelist>
-	<varlistentry>
-	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
-	  <listitem><simpara><literal>True</literal> is there is text
-available.</simpara></listitem>
-	</varlistentry>
+        <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.2 and above.</para>
+        <para>This method is available in PyGTK 2.10 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>
-
+ 
+      <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-targets">
-      <title>gtk.Clipboard.wait_for_targets</title>
+ 
+    <refsect2 id="method-gtkclipboard--wait-for-image">
+      <title>gtk.Clipboard.wait_for_image</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>wait_for_targets</methodname>
+	  <methodname>wait_for_image</methodname>
+	  <methodparam></methodparam>
 	</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>
+	  <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.4 and above.</para>
+	<para>This method is available in PyGTK 2.10 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>
+      <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>
 
@@ -839,219 +833,291 @@ method instead.</para>
 
     </refsect2>
 
-    <refsect2 id="method-gtkclipboard--set-can-store">
-      <title>gtk.Clipboard.set_can_store</title>
+    <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>set_can_store</methodname>
+	  <methodname>wait_is_text_available</methodname>
+	  <methodparam></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 that should be stored or <literal>None</literal> to
-indicate that all forms should be stored.</simpara></listitem>
+	  <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.6 and above.</para>
+	<para>This method is available in PyGTK 2.2 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>
+      <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>
 
-    <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>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--store">
-      <title>gtk.Clipboard.store</title>
+    <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>store</methodname>
+	  <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.6 and above.</para>
+	<para>This method is available in PyGTK 2.10 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>
+      <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-image">
-      <title>gtk.Clipboard.request_image</title>
+    <refsect2 id="method-gtkclipboard--request-contents">
+      <title>gtk.Clipboard.request_contents</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>request_image</methodname>
+	  <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 image is received,
-or the retrieval fails. (It will always be called
-one way or the other.)</simpara></listitem>
+	  <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>
+	  <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>
+	<para>This method is available in PyGTK 2.4 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
+      <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, pixbuf, data):
+  def callback(clipboard, selection_data, 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>
+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--wait-for-image">
-      <title>gtk.Clipboard.wait_for_image</title>
+    <refsect2 id="method-gtkclipboard--request-targets">
+      <title>gtk.Clipboard.request_targets</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>wait_for_image</methodname>
-	  <methodparam></methodparam>
+	  <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><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>
+	  <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>
-      </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--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>
+	  <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>
+	<para>This method is available in PyGTK 2.4 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>
+      <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--wait-is-image-available">
-      <title>gtk.Clipboard.wait_is_image_available</title>
+    <refsect2 id="method-gtkclipboard--request-text">
+      <title>gtk.Clipboard.request_text</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>wait_is_image_available</methodname>
-	  <methodparam></methodparam>
+	  <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><emphasis>Returns</emphasis>&nbsp;:</term>
-	  <listitem><simpara><literal>True</literal> is there is an image
-available.</simpara></listitem>
+	  <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>
+	<para>This method is available in PyGTK 2.4 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>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>
 
-      <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>
+      <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>
 
@@ -1111,121 +1177,57 @@ since it doesn't need to retrieve the actual image data.</para>
       of the clipboard could not be converted into rich text form.</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-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-uris-available">
-      <title>gtk.Clipboard.wait_is_uris_available</title>
- 
+
+    <refsect2 id="method-gtkclipboard--request-image">
+      <title>gtk.Clipboard.request_image</title>
+
       <programlisting><methodsynopsis language="python">
-        <methodname>wait_is_uris_available</methodname>
-        <methodparam></methodparam>
-      </methodsynopsis></programlisting>
-                                                                                
+	  <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><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>
+	<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.14 and above.</para>
+	<para>This method is available in PyGTK 2.10 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>
-      -->
- 
+
+      <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>