1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>gtk.Clipboard</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PyGTK 2.0 Reference Manual"><link rel="up" href="gtk-class-reference.html" title="The gtk Class Reference"><link rel="previous" href="class-gtkcheckmenuitem.html" title="gtk.CheckMenuItem"><link rel="next" href="class-gtkcolorbutton.html" title="gtk.ColorButton"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">gtk.Clipboard</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="class-gtkcheckmenuitem.html">Prev</a></td><th width="60%" align="center">The gtk Class Reference</th><td width="20%" align="right"><a accesskey="n" href="class-gtkcolorbutton.html">Next</a></td></tr></table><hr></div><div class="refentry" lang="en"><a name="class-gtkclipboard"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2>gtk.Clipboard</h2><p>gtk.Clipboard — an object to store data to
and retrieve data from (new in PyGTK 2.2)</p></div><div class="refsect1" lang="en"><a name="id3300382"></a><h2>Synopsis</h2><table bgcolor="#D0E0F0" width="100%"><tr><td><pre class="classsynopsis">class <span class="ooclass"><span class="classname">gtk.Clipboard</span></span>(<span class="ooclass"><span class="classname"><a href="class-gobject.html" title="gobject.GObject">gobject.GObject</a></span></span>):
<code class="constructorsynopsis"> <span class="methodname"><a href="class-gtkclipboard.html#constructor-gtkclipboard" title="Constructor">gtk.Clipboard</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>display</tt></b></span><span class="initializer">=gtk.gdk.display_get_default()</span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>selection</tt></b></span><span class="initializer">="CLIPBOARD"</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--get-display" title="gtk.Clipboard.get_display">get_display</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--set-with-data" title="gtk.Clipboard.set_with_data">set_with_data</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>targets</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>get_func</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>clear_func</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--get-owner" title="gtk.Clipboard.get_owner">get_owner</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--clear" title="gtk.Clipboard.clear">clear</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--set-text" title="gtk.Clipboard.set_text">set_text</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>text</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>len</tt></b></span><span class="initializer">=-1</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--request-contents" title="gtk.Clipboard.request_contents">request_contents</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--request-text" title="gtk.Clipboard.request_text">request_text</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--request-targets" title="gtk.Clipboard.request_targets">request_targets</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--wait-for-contents" title="gtk.Clipboard.wait_for_contents">wait_for_contents</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--wait-for-text" title="gtk.Clipboard.wait_for_text">wait_for_text</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--wait-is-text-available" title="gtk.Clipboard.wait_is_text_available">wait_is_text_available</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--wait-for-targets" title="gtk.Clipboard.wait_for_targets">wait_for_targets</a></span>()</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--wait-is-target-available" title="gtk.Clipboard.wait_is_target_available">wait_is_target_available</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--set-can-store" title="gtk.Clipboard.set_can_store">set_can_store</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>targets</tt></b></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#method-gtkclipboard--store" title="gtk.Clipboard.store">store</a></span>()</code><br></pre></td></tr></table><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
<span class="bold"><b>Functions</b></span>
<code class="methodsynopsis"> def <span class="methodname"><a href="class-gtkclipboard.html#function-gtk--clipboard-get" title="gtk.clipboard_get">gtk.clipboard_get</a></span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>selection</tt></b></span><span class="initializer">="CLIPBOARD"</span></span>)</code></pre></td></tr></table></div><div class="refsect1" lang="en"><a name="id3331570"></a><h2>Ancestry</h2><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="synopsis">+-- <a href="class-gobject.html" title="gobject.GObject">gobject.GObject</a>
+-- <a href="class-gtkclipboard.html" title="gtk.Clipboard">gtk.Clipboard</a>
</pre></td></tr></table></div><div class="refsect1" lang="en"><a name="id3261060"></a><h2>Description</h2><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This object is available in PyGTK 2.2 and above.</p></div><p> The <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>
object represents a clipboard of data shared between different processes or
between different widgets in the same process. Each clipboard is identified
by a name encoded as a <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a>. The
<a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a> is
basically a higher-level interface to the lower-level <a href="class-gtkselectiondata.html" title="gtk.SelectionData"><tt class="classname">gtk.SelectionData</tt></a>
and selection interface. The built-in atoms are:</p><div class="itemizedlist"><ul type="disc"><li>"PRIMARY"</li><li>"SECONDARY"</li><li>"CLIPBOARD"</li><li>"BITMAP"</li><li>"COLORMAP"</li><li>"DRAWABLE"</li><li>"PIXMAP"</li><li>"STRING"</li><li>"WINDOW"</li></ul></div><p>Creating a <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a> from
strings can be done with the <a href="class-gdkatom.html#constructor-gdkatom-intern" title="Constructor">gtk.gdk.atom_intern</a>()
constructor function though <tt class="literal">PyGTK</tt> will usually do the
conversion under the covers as needed. The name of a <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a> can be
retrieved using the Python <tt class="function">str</tt>() function:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
name = str(atom)
</pre></td></tr></table><p>The default clipboard corresponds to the "CLIPBOARD" atom; another
commonly used clipboard is the "PRIMARY" clipboard, which, in X,
traditionally contains the currently selected text.</p><p>To simultaneously support different formats on the clipboard, the
clipboard mechanism allows you to provide callbacks instead of the actual
data. When you set the contents of the clipboard, you can either supply the
data directly (via a method like <a href="class-gtkclipboard.html#method-gtkclipboard--set-text" title="gtk.Clipboard.set_text"><tt class="methodname">set_text</tt>()</a>),
or you can supply a callback to be called when the data is needed (via the
<a href="class-gtkclipboard.html#method-gtkclipboard--set-with-data" title="gtk.Clipboard.set_with_data"><tt class="methodname">set_with_data</tt>()</a>
method.) Providing a callback also avoids making unnecessary copies of the
data.</p><p>Along with the methods to get the clipboard contents as an arbitrary
data chunk, there is a method to retrieve it as text, the <a href="class-gtkclipboard.html#method-gtkclipboard--wait-for-text" title="gtk.Clipboard.wait_for_text"><tt class="methodname">wait_for_text</tt>()</a>
method. This method takes care of determining which formats are advertised
by the clipboard provider, asking for the clipboard in the best available
format and converting the results into the UTF-8 encoding. (The standard
form for representing strings in <tt class="literal">GTK</tt>+.) </p></div><div class="refsect1" lang="en"><a name="constructor-gtkclipboard"></a><h2>Constructor</h2><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="constructorsynopsis"> <span class="methodname">gtk.Clipboard</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>display</tt></b></span><span class="initializer">=gtk.gdk.display_get_default()</span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>selection</tt></b></span><span class="initializer">="CLIPBOARD"</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>display</tt></b>:</span></td><td>the <a href="class-gdkdisplay.html" title="gtk.gdk.Display"><tt class="classname">gtk.gdk.Display</tt></a>
for which the clipboard is to be retrieved or created.</td></tr><tr><td><span class="term"><b class="parameter"><tt>selection</tt></b>:</span></td><td>a string that identifies the clipboard
to use.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>the appropriate clipboard object or if no
clipboard already exists, a new one will be created. Once a
clipboard object has been created, it is persistent for all time and
cannot be freed.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This constructor is available in PyGTK 2.2 and above.</p></div><p>Returns the clipboard object for the <a href="class-gdkdisplay.html" title="gtk.gdk.Display"><tt class="classname">gtk.gdk.Display</tt></a>
specified by <i class="parameter"><tt>display</tt></i> and the selection specified by
the string in <i class="parameter"><tt>selection</tt></i>. Cut/copy/paste menu items
and keyboard shortcuts should use the default clipboard, returned by passing
<tt class="literal">"CLIPBOARD"</tt> for <i class="parameter"><tt>selection</tt></i>. The
currently-selected object or text should be provided on the clipboard
identified by <tt class="literal">"PRIMARY"</tt>. Cut/copy/paste menu items
conceptually copy the contents of the <tt class="literal">"PRIMARY"</tt> clipboard
to the default clipboard, i.e. they copy the selection to what the user sees
as the clipboard.</p><p>See <a href="http://www.freedesktop.org/standards/clipboards-spec/clipboards.txt" target="_top">
http://www.freedesktop.org/standards/clipboards-spec/clipboards.txt</a>
for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections under
the X window system. On Win32 the <tt class="literal">"PRIMARY"</tt> clipboard is
essentially ignored.</p><p>It's possible to have arbitrarily named clipboards. If you do
invent new clipboards, you should prefix the selection name with an
underscore (because the ICCCM requires that nonstandard atoms are
underscore-prefixed), and namespace it as well. For example, if your
application called "Foo" has a special-purpose clipboard, you might call it
"_FOO_SPECIAL_CLIPBOARD".</p><p>In PyGTK 2.4 and above, the <i class="parameter"><tt>display</tt></i>
argument is optional and defaults to the default display returned from the
<a href="class-gdkdisplay.html#function-gdk--display-get-default" title="gtk.gdk.display_get_default"><tt class="function">gtk.gdk.display_get_default</tt>()</a>
function.</p><p>In PyGTK 2.4 and above, the <i class="parameter"><tt>selection</tt></i>
argument is optional and defaults to "CLIPBOARD".</p></div><div class="refsect1" lang="en"><a name="id3333462"></a><h2>Methods</h2><div class="refsect2" lang="en"><a name="method-gtkclipboard--get-display"></a><h3>gtk.Clipboard.get_display</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">get_display</span>(<span class="methodparam"></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>the <a href="class-gdkdisplay.html" title="gtk.gdk.Display"><tt class="classname">gtk.gdk.Display</tt></a>
associated with the clipboard</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">get_display</tt>() method returns the
<a href="class-gdkdisplay.html" title="gtk.gdk.Display"><tt class="classname">gtk.gdk.Display</tt></a>
associated with the clipboard.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--set-with-data"></a><h3>gtk.Clipboard.set_with_data</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_with_data</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>targets</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>get_func</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>clear_func</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>targets</tt></b>:</span></td><td>a list of 3-tuples containing information about
the available forms for the clipboard data</td></tr><tr><td><span class="term"><b class="parameter"><tt>get_func</tt></b>:</span></td><td>a function to call to get the actual clipboard
data</td></tr><tr><td><span class="term"><b class="parameter"><tt>clear_func</tt></b>:</span></td><td>when the clipboard contents are set again,
this function will be called, and <i class="parameter"><tt>get_func</tt></i> will not
be subsequently called.</td></tr><tr><td><span class="term"><b class="parameter"><tt>user_data</tt></b>:</span></td><td>the user data to pass to
<i class="parameter"><tt>get_func</tt></i> and
<i class="parameter"><tt>clear_func</tt></i>.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td><tt class="literal">TRUE</tt> if setting the
clipboard data succeeded. If setting the clipboard data failed the
provided callback functions will be ignored.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">set_with_data</tt>() method virtually
sets the contents of the specified clipboard by providing a list of
supported formats (specified by <i class="parameter"><tt>targets</tt></i>) for the
clipboard data and a function (specified by <i class="parameter"><tt>get_func</tt></i>)
to call to get the actual data when it is
requested. <i class="parameter"><tt>clear_func</tt></i> is a function that is called
when the contents of the clipboard are being changed to provide cleanup
operations on
<i class="parameter"><tt>user_data</tt></i>. <i class="parameter"><tt>user_data</tt></i> is passed
to <i class="parameter"><tt>get_func</tt></i> and <i class="parameter"><tt>clear_func</tt></i>
when they are invoked. The 3-tuples listed in <i class="parameter"><tt>targets</tt></i>
contain the following items:</p><div class="itemizedlist"><ul type="disc"><li>a string representing a target supported by the
clipboard</li><li>a flags value used for drag and drop - a combination of:
<tt class="literal">gtk.TARGET_SAME_APP</tt> and
<tt class="literal">gtk.TARGET_SAME_WIDGET</tt></li><li>an application assigned integer that is passed as a signal
parameter to help identify the target type</li></ul></div><p>The signature of <i class="parameter"><tt>get_func</tt></i> is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def get_func(clipboard, selectiondata, info, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>,
<i class="parameter"><tt>selectiondata</tt></i> is a <a href="class-gtkselectiondata.html" title="gtk.SelectionData"><tt class="classname">gtk.SelectionData</tt></a>
object to set with the data, <i class="parameter"><tt>info</tt></i> is the application
assigned integer associated with a target, and <i class="parameter"><tt>data</tt></i>
is the <i class="parameter"><tt>user_data</tt></i> argument.</p><p>The signature of <i class="parameter"><tt>clear_func</tt></i> is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def clear_func(clipboard, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a> and
<i class="parameter"><tt>data</tt></i> is the <i class="parameter"><tt>user_data</tt></i>
argument.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--get-owner"></a><h3>gtk.Clipboard.get_owner</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">get_owner</span>(<span class="methodparam"></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>the owner of the clipboard, if any; otherwise
<tt class="literal">None</tt>.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">get_owner</tt>() method returns the
owner set by the <tt class="methodname">set_with_owner</tt>() method if neither
the <a href="class-gtkclipboard.html#method-gtkclipboard--set-with-data" title="gtk.Clipboard.set_with_data"><tt class="methodname">set_with_data()</tt></a>
method nor the <a href="class-gtkclipboard.html#method-gtkclipboard--clear" title="gtk.Clipboard.clear"><tt class="methodname">clear()</tt></a>
method have been subsequently called. This method returns
<tt class="literal">None</tt> otherwise.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--clear"></a><h3>gtk.Clipboard.clear</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">clear</span>(<span class="methodparam"></span>)</code></pre></td></tr></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">clear</tt>() method clears the contents
of the clipboard. Generally this should only be called between the time you
call the <a href="class-gtkclipboard.html#method-gtkclipboard--set-with-data" title="gtk.Clipboard.set_with_data"><tt class="methodname">set_with_data()</tt></a>,
and when the <i class="parameter"><tt>clear_func</tt></i> you supplied is
called. Otherwise, the clipboard may be owned by someone else.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--set-text"></a><h3>gtk.Clipboard.set_text</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_text</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>text</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>len</tt></b></span><span class="initializer">=-1</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>text</tt></b>:</span></td><td>a string.</td></tr><tr><td><span class="term"><b class="parameter"><tt>len</tt></b>:</span></td><td>the length of <i class="parameter"><tt>text</tt></i>, in
bytes, or -1, to calculate the length.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">set_text</tt>() method sets the contents
of the clipboard to the string specified by <i class="parameter"><tt>text</tt></i>. If
<i class="parameter"><tt>len</tt></i> is given it determines the length of
<i class="parameter"><tt>text</tt></i> to be copied. If <i class="parameter"><tt>len</tt></i> is
not specified it defaults to -1 and the method calculates the text
length.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--request-contents"></a><h3>gtk.Clipboard.request_contents</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">request_contents</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>target</tt></b>:</span></td><td>a <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a>
or string representing the form that the clipboard owner should convert
the selection to.</td></tr><tr><td><span class="term"><b class="parameter"><tt>callback</tt></b>:</span></td><td>a function to call when the results are received
(or the retrieval fails).</td></tr><tr><td><span class="term"><b class="parameter"><tt>user_data</tt></b>:</span></td><td>user data to pass to <i class="parameter"><tt>callback</tt></i></td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.4 and above.</p></div><p>The <tt class="methodname">request_contents</tt>() method requests
the contents of clipboard in the form specified by
<i class="parameter"><tt>target</tt></i>. When the results of the request are later
received the function specified by <i class="parameter"><tt>callback</tt></i> will be
invoked and passed the data specified by
<i class="parameter"><tt>user_data</tt></i>. The signature of
<i class="parameter"><tt>callback</tt></i> is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback(clipboard, selection_data, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>
that invoked callback and <i class="parameter"><tt>selection_data</tt></i> is the <a href="class-gtkselectiondata.html" title="gtk.SelectionData"><tt class="classname">gtk.SelectionData</tt></a>
containing the target data and <i class="parameter"><tt>data</tt></i> is
<i class="parameter"><tt>user_data</tt></i>.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--request-text"></a><h3>gtk.Clipboard.request_text</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">request_text</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>callback</tt></b>:</span></td><td>a function to call when the text is received,
or the retrieval fails. (It will always be called
one way or the other.)</td></tr><tr><td><span class="term"><b class="parameter"><tt>user_data</tt></b>:</span></td><td>user data to pass to
<i class="parameter"><tt>callback</tt></i>.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.4 and above.</p></div><p>The <tt class="methodname">request_text</tt>() 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 <i class="parameter"><tt>callback</tt></i> will
be called with the data specified by <i class="parameter"><tt>user_data</tt></i>. The
signature of <i class="parameter"><tt>callback</tt></i> is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback(clipboard, text, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>
that <i class="parameter"><tt>text</tt></i> is retrieved from and
<i class="parameter"><tt>data</tt></i> is <i class="parameter"><tt>user_data</tt></i>.
<i class="parameter"><tt>text</tt></i> 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.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--request-targets"></a><h3>gtk.Clipboard.request_targets</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">request_targets</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>callback</tt></b></span></span>, <span class="methodparam"><span class="parameter"><b class="parameter"><tt>user_data</tt></b></span><span class="initializer">=None</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>callback</tt></b>:</span></td><td>a function to call when the targets are received,
or the retrieval fails. (It will always be called
one way or the other.)</td></tr><tr><td><span class="term"><b class="parameter"><tt>user_data</tt></b>:</span></td><td>user data to pass to
<i class="parameter"><tt>callback</tt></i>.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.4 and above.</p></div><p>The <tt class="methodname">request_targets</tt>() method requests
the contents of the clipboard as list of supported targets. When the list
is later received, <i class="parameter"><tt>callback</tt></i> will be called with the
data specified by <i class="parameter"><tt>user_data</tt></i>. The signature of
<i class="parameter"><tt>callback</tt></i> is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback(clipboard, targets, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>
that <i class="parameter"><tt>targets</tt></i> is retrieved
from. <i class="parameter"><tt>targets</tt></i> is a tuple containing the <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a> objects
corresponding to the targets of clipboard. <i class="parameter"><tt>targets</tt></i>
will contain the resulting targets if the request succeeded, or an empty
tuple if it failed.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--wait-for-contents"></a><h3>gtk.Clipboard.wait_for_contents</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">wait_for_contents</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>target</tt></b>:</span></td><td>an atom or string representing the form into
which the clipboard owner should convert the selection.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>a newly-allocated <a href="class-gtkselectiondata.html" title="gtk.SelectionData"><tt class="classname">gtk.SelectionData</tt></a>
object or <tt class="literal">None</tt> if retrieving the given target
failed.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">wait_for_contents</tt>() method requests
the contents of the clipboard using the target specified by
<i class="parameter"><tt>target</tt></i>. This method waits for the data to be received
using the main loop, so events, timeouts, etc, may be dispatched during the
wait.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--wait-for-text"></a><h3>gtk.Clipboard.wait_for_text</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">wait_for_text</span>(<span class="methodparam"></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>a string, or <tt class="literal">None</tt> 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.)</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">wait_for_text</tt>() method requests the
contents of the clipboard as text and converts the result to UTF-8 if
necessary. This method waits for the data to be received using the main
loop, so events, timeouts, etc, may be dispatched during the wait.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--wait-is-text-available"></a><h3>gtk.Clipboard.wait_is_text_available</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">wait_is_text_available</span>(<span class="methodparam"></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td><tt class="literal">TRUE</tt> is there is text
available.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.2 and above.</p></div><p>The <tt class="methodname">wait_is_text_available</tt>() 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.</p><p>This method is a little faster than calling the <a href="class-gtkclipboard.html#method-gtkclipboard--wait-for-text" title="gtk.Clipboard.wait_for_text"><tt class="methodname">wait_for_text()</tt></a>
since it doesn't need to retrieve the actual text.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--wait-for-targets"></a><h3>gtk.Clipboard.wait_for_targets</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">wait_for_targets</span>()</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>returns a tuple containing any targets that are
present on the clipboard or <tt class="literal">None</tt>.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.4 and above.</p></div><p>The <tt class="methodname">wait_for_targets</tt>() method returns a
tuple containing the targets (as <a href="class-gdkatom.html" title="gtk.gdk.Atom"><tt class="classname">gtk.gdk.Atom</tt></a> objects)
that are present on the clipboard, or <tt class="literal">None</tt> 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.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--wait-is-target-available"></a><h3>gtk.Clipboard.wait_is_target_available</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">wait_is_target_available</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>target</tt></b></span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>target</tt></b>:</span></td><td>an atom or string representing the target of
interest.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td><tt class="literal">TRUE</tt> if the target is
available.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.6 and above.</p></div><p>The <tt class="methodname">wait_is_target_available</tt>() method
tests to see if the target specified by <i class="parameter"><tt>target</tt></i> is
available to be copied from the clipboard. This method can be used to
determine if a <span class="guimenuitem">Paste</span> menu item should be
insensitive or not.</p><p>If you want to see if there's text available on the clipboard,
use the <a href="class-gtkclipboard.html#method-gtkclipboard--wait-is-text-available" title="gtk.Clipboard.wait_is_text_available"><tt class="methodname">wait_is_text_available</tt>()</a>
method instead.</p></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--set-can-store"></a><h3>gtk.Clipboard.set_can_store</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_can_store</span>()</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>targets</tt></b>:</span></td><td>a list of 3-tuples containing information about
the available forms that should be stored or <tt class="literal">None</tt> to
indicate that all forms should be stored.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.6 and above.</p></div><p>The <tt class="methodname">set_can_store</tt>() method sets a hint
that the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a> can
store the list of targets specified by <i class="parameter"><tt>targets</tt></i> can be
stored somewhere when the application exits or when the <a href="class-gtkclipboard.html#method-gtkclipboard--store" title="gtk.Clipboard.store"><tt class="methodname">store</tt>()</a>
method is called. This value is reset when the clipboard owner
changes. Where the clipboard data is stored is platform dependent, see the
<a href="class-gdkdisplay.html#method-gdkdisplay--store-clipboard" title="gtk.gdk.Display.store_clipboard"><tt class="methodname">gtk.gdk.Display.store_clipboard</tt>()</a>
method for more information. If <i class="parameter"><tt>targets</tt></i> is
<tt class="literal">None</tt> all target forms currently available on the
clipboard should be stored.</p><p>The 3-tuples listed in <i class="parameter"><tt>targets</tt></i> contain
the following items:</p><div class="itemizedlist"><ul type="disc"><li>a string representing a target supported by the
clipboard</li><li>a flags value used for drag and drop - a combination of:
<tt class="literal">gtk.TARGET_SAME_APP</tt> and
<tt class="literal">gtk.TARGET_SAME_WIDGET</tt></li><li>an application assigned integer that is passed as a signal
parameter to help identify the target type</li></ul></div></div><div class="refsect2" lang="en"><a name="method-gtkclipboard--store"></a><h3>gtk.Clipboard.store</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">store</span>()</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This method is available in PyGTK 2.6 and above.</p></div><p>The <tt class="methodname">store</tt>() method stores the current
clipboard data (as specified by the <a href="class-gtkclipboard.html#method-gtkclipboard--set-can-store" title="gtk.Clipboard.set_can_store"><tt class="methodname">set_can_store</tt>()</a>
method) somewhere so that it will stay around after the application has
quit.</p></div></div><div class="refsect1" lang="en"><a name="id3335270"></a><h2>Functions</h2><div class="refsect2" lang="en"><a name="function-gtk--clipboard-get"></a><h3>gtk.clipboard_get</h3><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">gtk.clipboard_get</span>(<span class="methodparam"><span class="parameter"><b class="parameter"><tt>selection</tt></b></span><span class="initializer">="CLIPBOARD"</span></span>)</code></pre></td></tr></table><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><span class="term"><b class="parameter"><tt>selection</tt></b>:</span></td><td>a string specifying a <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>. If
not specified it defaults to "CLIPBOARD".</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>:</span></td><td>the appropriate clipboard object or if no
clipboard already exists, a new one will be created. Once a
clipboard object has been created, it is persistent for all time and
cannot be freed.</td></tr></tbody></table><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This function is available in PyGTK 2.4 and above.</p></div><p>The <tt class="function">gtk.clipboard_get</tt>() function returns
the <a href="class-gtkclipboard.html" title="gtk.Clipboard"><tt class="classname">gtk.Clipboard</tt></a>
specified by selection for the default <a href="class-gdkdisplay.html" title="gtk.gdk.Display"><tt class="classname">gtk.gdk.Display</tt></a>. See
the <a href="class-gtkclipboard.html#constructor-gtkclipboard" title="Constructor">gtk.Clipboard</a>
constructor for more information.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class-gtkcheckmenuitem.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="gtk-class-reference.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="class-gtkcolorbutton.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">gtk.CheckMenuItem</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">gtk.ColorButton</td></tr></table></div></body></html>
|
