[pygtk] reference: pygtk-gtkclipboard.xml: reorder methods, fixing some links in the process
- From: Dieter Verfaillie <dieterv src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pygtk] reference: pygtk-gtkclipboard.xml: reorder methods, fixing some links in the process
- Date: Thu, 10 Mar 2011 21:15:59 +0000 (UTC)
commit 7e23daed4c9d5eaf7e7b11cfc5d7d9a4e7751e46
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date: Mon Feb 21 10:36:50 2011 +0100
reference: pygtk-gtkclipboard.xml: reorder methods, fixing some links in the process
docs/reference/pygtk-gtkclipboard.xml | 1060 +++++++++++++++++----------------
1 files changed, 531 insertions(+), 529 deletions(-)
---
diff --git a/docs/reference/pygtk-gtkclipboard.xml b/docs/reference/pygtk-gtkclipboard.xml
index 765ed30..fbafb1a 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> :</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> :</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,18 +577,23 @@ argument.</para>
</refsect2>
- <refsect2 id="method-gtkclipboard--get-owner">
- <title>gtk.Clipboard.get_owner</title>
+ <refsect2 id="method-gtkclipboard--set-text">
+ <title>gtk.Clipboard.set_text</title>
<programlisting><methodsynopsis language="python">
- <methodname>get_owner</methodname>
- <methodparam></methodparam>
+ <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><emphasis>Returns</emphasis> :</term>
- <listitem><simpara>the owner of the clipboard, if any; otherwise
-<literal>None</literal>.</simpara></listitem>
+ <term><parameter role="keyword">text</parameter> :</term>
+ <listitem><simpara>a string.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter role="keyword">len</parameter> :</term>
+ <listitem><simpara>the length of <parameter>text</parameter>, in
+bytes, or -1, to calculate the length.</simpara></listitem>
</varlistentry>
</variablelist>
@@ -466,217 +601,40 @@ argument.</para>
<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>
+ <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--clear">
- <title>gtk.Clipboard.clear</title>
+ <refsect2 id="method-gtkclipboard--set-image">
+ <title>gtk.Clipboard.set_image</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>
-
- <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> :</term>
- <listitem><simpara>a string.</simpara></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter role="keyword">len</parameter> :</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--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>
+ <methodname>set_image</methodname>
+ <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
- <term><parameter role="keyword">target</parameter> :</term>
+ <term><parameter role="keyword">pixbuf</parameter> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</term>
- <listitem><simpara><literal>True</literal> is there is text
-available.</simpara></listitem>
- </varlistentry>
+ <varlistentry>
+ <term><parameter role="keyword">buffer</parameter> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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>
-
- </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> :</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>
+ <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--set-image">
- <title>gtk.Clipboard.set_image</title>
+ <refsect2 id="method-gtkclipboard--request-targets">
+ <title>gtk.Clipboard.request_targets</title>
<programlisting><methodsynopsis language="python">
- <methodname>set_image</methodname>
- <methodparam><parameter role="keyword">pixbuf</parameter></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><parameter role="keyword">pixbuf</parameter> :</term>
- <listitem><simpara>a <link
-linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</simpara></listitem>
+ <term><parameter role="keyword">callback</parameter> :</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> :</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> :</term>
- <listitem><simpara><literal>True</literal> is there is an image
-available.</simpara></listitem>
+ <term><parameter role="keyword">callback</parameter> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
