/usr/share/doc/python-gtk2-tutorial/html/ch-NewInPyGTK2.2.html is in python-gtk2-tutorial 2.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 15. New Widgets in PyGTK 2.2</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PyGTK 2.0 Tutorial"><link rel="up" href="index.html" title="PyGTK 2.0 Tutorial"><link rel="previous" href="sec-GenericCellRenderer.html" title="14.12. The Generic CellRenderer"><link rel="next" href="ch-NewInPyGTK2.4.html" title="Chapter 16. New Widgets in PyGTK 2.4"></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">Chapter 15. New Widgets in PyGTK 2.2</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-GenericCellRenderer.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch-NewInPyGTK2.4.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ch-NewInPyGTK2.2"></a>Chapter 15. New Widgets in PyGTK 2.2</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch-NewInPyGTK2.2.html#sec-Clipboards">15.1. Clipboards</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch-NewInPyGTK2.2.html#sec-CreatingClipboard">15.1.1. Creating A Clipboard</a></span></dt><dt><span class="sect2"><a href="ch-NewInPyGTK2.2.html#sec-UsingClipboards">15.1.2. Using Clipboards with Entry, Spinbutton and TextView</a></span></dt><dt><span class="sect2"><a href="ch-NewInPyGTK2.2.html#sec-SettingClipboardData">15.1.3. Setting Data on a Clipboard</a></span></dt><dt><span class="sect2"><a href="ch-NewInPyGTK2.2.html#sec-RetrievingClipboardContents">15.1.4. Retrieving the Clipboard Contents</a></span></dt><dt><span class="sect2"><a href="ch-NewInPyGTK2.2.html#sec-ClipboardExample">15.1.5. A Clipboard Example</a></span></dt></dl></dd></dl></div><p>The <tt class="classname">Clipboard</tt> object was added in PyGTK
2.2. The <tt class="classname">GtkClipboard</tt> was available in GTK+ 2.0 but
was not wrapped by PyGTK 2.0 because it was not a complete
<tt class="classname">GObject</tt>. Some new objects were added to the gtk.gdk
module in PyGTK 2.2 but they will not be described in this tutorial. See the
<a href="http://www.pygtk.org/pygtk2reference/index.html" target="_top">PyGTK 2
Reference Manual</a> for more information on the
<tt class="classname">gtk.gdk.Display</tt>,
<tt class="classname">gtk.gdk.DisplayManager</tt> and
<tt class="classname">gtk.gdk.Screen</tt> objects.</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-Clipboards"></a>15.1. Clipboards</h2></div></div><div></div></div><p>A <tt class="classname">Clipboard</tt> provides a storage area for
sharing data between processes or between different widgets in the same
process. Each <tt class="classname">Clipboard</tt> is identified by a string
name encoded as a <tt class="classname">gdk.Atom</tt>. You can use any name you
want to identify a <tt class="classname">Clipboard</tt> and a new one will be
created if it doesn't exist. If you want to share a
<tt class="classname">Clipboard</tt> with other processes each process will need
to know the <tt class="classname">Clipboard</tt>'s name.</p><p><tt class="classname">Clipboard</tt>s are built on the
<tt class="classname">SelectionData</tt> and selection interfaces. The default
<tt class="classname">Clipboard</tt> used by the
<tt class="classname">TextView</tt>, <tt class="classname">Label</tt> and
<tt class="classname">Entry</tt> widgets is "CLIPBOARD". Other common clipboards
are "PRIMARY" and "SECONDARY" that correspond to the primary and secondary
selections (Win32 ignores these). These can also be specified using the
<tt class="classname">gtk.gdk.Atom</tt> objects:
<tt class="literal">gtk.gdk.SELECTION_CLIPBOARD</tt>,
<tt class="literal">gtk.gdk.SELECTION_PRIMARY</tt> and
<tt class="literal">gtk.gdk.SELECTION_SECONDARY</tt>. See the <a href="http://www.pygtk.org/pygtk2reference/class-gdkatom.html" target="_top">gtk.gdk.Atom
reference documentation</a> for more information.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-CreatingClipboard"></a>15.1.1. Creating A Clipboard</h3></div></div><div></div></div><p>A <tt class="classname">Clipboard</tt> is created using the
constructor:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard = gtk.Clipboard(<b class="parameter"><tt>display</tt></b>, <b class="parameter"><tt>selection</tt></b>)
</pre></td></tr></table><p>where <i class="parameter"><tt>display</tt></i> is the
<tt class="classname">gtk.gdk.Display</tt> associated with the
<tt class="classname">Clipboard</tt> named by
<i class="parameter"><tt>selection</tt></i>. The following convenience function creates
a <tt class="classname">Clipboard</tt> using the default
<tt class="classname">gtk.gdk.Display</tt>:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard = gtk.clipboard_get(<b class="parameter"><tt>selection</tt></b>)
</pre></td></tr></table><p>Finally, a <tt class="classname">Clipboard</tt> can also be
created using the <tt class="classname">Widget</tt> method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard = widget.get_clipboard(<b class="parameter"><tt>selection</tt></b>)
</pre></td></tr></table><p>The widget must be realized and be part of a toplevel window
hierarchy.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-UsingClipboards"></a>15.1.2. Using Clipboards with Entry, Spinbutton and TextView</h3></div></div><div></div></div><p><tt class="classname">Entry</tt>,
<tt class="classname">SpinButton</tt> and <tt class="classname">TextView</tt>
widgets have popup menus that provide the ability to cut and copy the
selected text to and paste from the "CLIPBOARD" clipboard. In addition key
bindings are set to allow keyboard accelerators to cut, copy and paste. Cut
is activated by <span><b class="keycap">Control</b></span>+<span><b class="keycap">X</b></span>; copy,
by <span><b class="keycap">Control</b></span>+<span><b class="keycap">C</b></span>; and,
paste, by <span><b class="keycap">Control</b></span>+<span><b class="keycap">V</b></span>.</p><p>The widgets (<tt class="classname">Entry</tt> and
<tt class="classname">SpinButton</tt>) implement the
<tt class="classname">Editable</tt> interface that has the following methods to
cut, copy and paste to and from the "CLIPBOARD" clipboard:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
editable.cut_clipboard()
editable.copy_clipboard()
editable.paste_clipboard()
</pre></td></tr></table><p>A <tt class="classname">Label</tt> that is selectable (the
"selectable" property is <tt class="literal">TRUE</tt>) also supports copying the
selected text to the "CLIPBOARD" clipboard using a popup menu or the
<span><b class="keycap">Control</b></span>+<span><b class="keycap">C</b></span>
keyboard accelerator.</p><p><tt class="classname">TextBuffer</tt>s have similar methods though
they also allow specifying the clipboard to use:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
textbuffer.copy_clipboard(<b class="parameter"><tt>clipboard</tt></b>)
</pre></td></tr></table><p>The selection text will be copied to the
<tt class="classname">Clipboard</tt> specified by
<i class="parameter"><tt>clipboard</tt></i>.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
textbuffer.cut_clipboard(<b class="parameter"><tt>clipboard</tt></b>, <b class="parameter"><tt>default_editable</tt></b>)
</pre></td></tr></table><p>The selected text will be copied to
<i class="parameter"><tt>clipboard</tt></i>. If <i class="parameter"><tt>default_editable</tt></i>
is <tt class="literal">TRUE</tt> the selected text will also be deleted from the
<tt class="classname">TextBuffer</tt>. Otherwise,
<tt class="methodname">cut_clipboard</tt>() will act like the
<tt class="methodname">copy_clipboard</tt>() method.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
textbuffer.paste_clipboard(<b class="parameter"><tt>clipboard</tt></b>, <b class="parameter"><tt>override_location</tt></b>, <b class="parameter"><tt>default_editable</tt></b>)
</pre></td></tr></table><p>If <i class="parameter"><tt>default_editable</tt></i> is
<tt class="literal">TRUE</tt>, the contents of <i class="parameter"><tt>clipboard</tt></i>
will be inserted into the <tt class="classname">TextBuffer</tt> at the location
specified by the <tt class="classname">TextIter</tt>
<i class="parameter"><tt>override_location</tt></i>. If
<i class="parameter"><tt>default_editable</tt></i> is <tt class="literal">FALSE</tt>,
<tt class="methodname">paste_clipboard</tt>() will not insert the contents of
<i class="parameter"><tt>clipboard</tt></i>. If
<i class="parameter"><tt>override_location</tt></i> is <tt class="literal">None</tt> the
contents of <i class="parameter"><tt>clipboard</tt></i> will be inserted at the cursor
location.</p><p><tt class="classname">TextBuffer</tt>s also have two methods to
manage a set of <tt class="classname">Clipboard</tt>s that are automatically set
with the contents of the current selection:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
textbuffer.add_selection_clipboard(<b class="parameter"><tt>clipboard</tt></b>)
textbuffer.remove_selection_clipboard(<b class="parameter"><tt>clipboard</tt></b>)
</pre></td></tr></table><p>When a <tt class="classname">TextBuffer</tt> is added to a
<tt class="classname">TextView</tt> the "PRIMARY" clipboard is automatically
added to the selection clipboards. Your application can add other clipboards
(for example, the "CLIPBOARD" clipboard).</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-SettingClipboardData"></a>15.1.3. Setting Data on a Clipboard</h3></div></div><div></div></div><p>You can set the <tt class="classname">Clipboard</tt> data
programmatically using either of:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard.set_with_data(<b class="parameter"><tt>targets</tt></b>, <b class="parameter"><tt>get_func</tt></b>, <b class="parameter"><tt>clear_func</tt></b>, <b class="parameter"><tt>user_data</tt></b>)
clipboard.set_text(<b class="parameter"><tt>text</tt></b>, <b class="parameter"><tt>len</tt></b>=-1)
</pre></td></tr></table><p>The <tt class="methodname">set_with_data</tt>() method indicates
which selection data targets are supported and provides functions
(<i class="parameter"><tt>get_func</tt></i> and <i class="parameter"><tt>clear_func</tt></i>) that
are called when the data is asked for or the clipboard data is
changed. <i class="parameter"><tt>user_data</tt></i> is passed to
<i class="parameter"><tt>get_func</tt></i> or <i class="parameter"><tt>clear_func</tt></i> when
called. <i class="parameter"><tt>targets</tt></i> is a list of 3-tuples
containing:</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 - use 0.</li><li>an application assigned integer that is passed as a
parameter to a signal handler to help identify the target type.</li></ul></div><p>The signatures of <i class="parameter"><tt>get_func</tt></i> and
<i class="parameter"><tt>clear_func</tt></i> are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def get_func(clipboard, selectiondata, info, data):
def clear_func(clipboard, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>clipboard</tt></i> is the
<tt class="classname">Clipboard</tt>, <i class="parameter"><tt>selectiondata</tt></i> is a
<tt class="classname">SelectionData</tt> object to set the data in,
<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
<i class="parameter"><tt>user_data</tt></i>.</p><p><tt class="methodname">set_text</tt>() is a convenience method
that uses the <tt class="methodname">set_with_data</tt>() method to set text
data on a <tt class="classname">Clipboard</tt> with the targets: "STRING",
"TEXT", "COMPOUND_TEXT", and "UTF8_STRING". It uses internal get and clear
functions to manage the data. <tt class="methodname">set_text</tt>() is
equivalent to the following:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def my_set_text(self, text, len=-1):
targets = [ ("STRING", 0, 0),
("TEXT", 0, 1),
("COMPOUND_TEXT", 0, 2),
("UTF8_STRING", 0, 3) ]
def text_get_func(clipboard, selectiondata, info, data):
selectiondata.set_text(data)
return
def text_clear_func(clipboard, data):
del data
return
self.set_with_data(targets, text_get_func, text_clear_func, text)
return
</pre></td></tr></table><p>Once data is set on a clipboard, it will be available until the
application is finished or the clipboard data is changed.</p><p>To provide the behavior typical of cut to a clipboard, your
application will have to delete the selected text or object after copying it
to the clipboard.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-RetrievingClipboardContents"></a>15.1.4. Retrieving the Clipboard Contents</h3></div></div><div></div></div><p>The contents of a <tt class="classname">Clipboard</tt> can be
retrieved using the following method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard.request_contents(<b class="parameter"><tt>target</tt></b>, <b class="parameter"><tt>callback</tt></b>, <b class="parameter"><tt>user_data</tt></b>=None)
</pre></td></tr></table><p>The contents specified by <i class="parameter"><tt>target</tt></i> are
retrieved asynchronously in the function specified by
<i class="parameter"><tt>callback</tt></i> which is called with
<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, selectiondata, data):
</pre></td></tr></table><p>where <i class="parameter"><tt>selectiondata</tt></i> is a
<tt class="classname">SelectionData</tt> object containing the contents of
<i class="parameter"><tt>clipboard</tt></i>. <i class="parameter"><tt>data</tt></i> is
<i class="parameter"><tt>user_data</tt></i>. The
<tt class="methodname">request_contents</tt>() method is the most general way
of retrieving the contents of a <tt class="classname">Clipboard</tt>. The
following convenience method retrieves the text contents of a
<tt class="classname">Clipboard</tt>:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard.request_text(<b class="parameter"><tt>callback</tt></b>, <b class="parameter"><tt>user_data</tt></b>=None)
</pre></td></tr></table><p>The text string is returned to the callback function instead
of a <tt class="classname">Selectiondata</tt> object. You can check which
targets are available on the <tt class="classname">Clipboard</tt> by using the
method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
clipboard.request_targets(<b class="parameter"><tt>callback</tt></b>, <b class="parameter"><tt>user_data</tt></b>=None)
</pre></td></tr></table><p>The targets are returned as a tuple of
<tt class="classname">gtk.gdk.Atom</tt> objects to the callback function.</p><p>Two convenience methods are provided to return the
<tt class="classname">Clipboard</tt> contents synchronously:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
selectiondata = clipboard.wait_for_contents(target)
text = clipboard.wait_for_text()
</pre></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sec-ClipboardExample"></a>15.1.5. A Clipboard Example</h3></div></div><div></div></div><p>To illustrate the use of a <tt class="classname">Clipboard</tt>
the <a href="examples/clipboard.py" target="_top">clipboard.py</a> example program
tracks the text items that are cut or copied to the "CLIPBOARD" clipboard
and saves the last ten clipboard entries. There are ten buttons that provide
access to the text of the saved entries. The button label display the first
sixteen characters of the saved text and the tooltips display the targets
that the entry originally had. When an entry button is clicked the text
window is loaded with the associated saved text which is editable. The
button below the text window saves the current text window contents to the
clipboard.</p><p><a href="ch-NewInPyGTK2.2.html#clipboardfig" title="Figure 15.1. Clipboard Example Program">Figure 15.1, “Clipboard Example Program”</a> illustrates the <a href="examples/clipboard.py" target="_top">clipboard.py</a> example program in
operation:</p><div class="figure"><a name="clipboardfig"></a><p class="title"><b>Figure 15.1. Clipboard Example Program</b></p><div class="mediaobject" align="center"><img src="figures/clipboard.png" align="middle" alt="Clipboard Example Program"></div></div><p>The example program polls the clipboard every 1.5 seconds to
see if the contents have changed. The program could be changed to duplicate
the complete set of target contents and then take ownership of the clipboard
using the <tt class="methodname">set_with_data</tt>() method. Later, when
another program sets the contents of the clipboard, the
<i class="parameter"><tt>clear_func</tt></i> will be called and it can be used to
reload the clipboard contents and retake the clipboard ownership.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-GenericCellRenderer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch-NewInPyGTK2.4.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.12. The Generic CellRenderer </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. New Widgets in PyGTK 2.4</td></tr></table></div></body></html>
|