/usr/share/doc/python-gtk2-tutorial/html/sec-RetrievingTheSelection.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 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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>21.2. Retrieving the Selection</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="ch-ManagingSelections.html" title="Chapter 21. Managing Selections"><link rel="previous" href="ch-ManagingSelections.html" title="Chapter 21. Managing Selections"><link rel="next" href="sec-SupplyingTheSelection.html" title="21.3. Supplying the Selection"></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">21.2. Retrieving the Selection</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch-ManagingSelections.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Managing Selections</th><td width="20%" align="right"> <a accesskey="n" href="sec-SupplyingTheSelection.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-RetrievingTheSelection"></a>21.2. Retrieving the Selection</h2></div></div><div></div></div><p>Retrieving the selection is an asynchronous process. To start
the process, you call:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = widget.selection_convert(<b class="parameter"><tt>selection</tt></b>, <b class="parameter"><tt>target</tt></b>, <b class="parameter"><tt>time</tt></b>=0)
</pre></td></tr></table><p>This converts the <i class="parameter"><tt>selection</tt></i> into the form
specified by <i class="parameter"><tt>target</tt></i>. <i class="parameter"><tt>selection</tt></i>
is an atom corresponding to the selection type; the common selections are
the strings:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
PRIMARY
SECONDARY
</pre></td></tr></table><p>If at all possible, the <i class="parameter"><tt>time</tt></i> field should
be the time from the event that triggered the
<i class="parameter"><tt>selection</tt></i>. This helps make sure that events occur in
the order that the user requested them. However, if it is not available (for
instance, if the conversion was triggered by a "clicked" signal), then you
can use 0 which means use the current time. <i class="parameter"><tt>result</tt></i> is
<tt class="literal">TRUE</tt> if the conversion succeeded,
<tt class="literal">FALSE</tt> otherwise.</p><p>When the selection owner responds to the request, a
"selection_received" signal is sent to your application. The handler for
this signal receives a <tt class="classname">gtk.SelectionData</tt> object,
which has the following attributes:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
selection
target
type
format
data
</pre></td></tr></table><p><i class="parameter"><tt>selection</tt></i> and <i class="parameter"><tt>target</tt></i>
are the values you gave in your <tt class="methodname">selection_convert</tt>()
method.</p><p><i class="parameter"><tt>type</tt></i> is an atom that identifies the type of
data returned by the selection owner. Some possible values are "STRING", a
string of latin-1 characters, "ATOM", a series of atoms, "INTEGER", an
integer, "image/x-xpixmap", etc. Most targets can only return one
type.</p><p>The list of standard atoms in X and GTK+ is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
PRIMARY
SECONDARY
ARC
ATOM
BITMAP
CARDINAL
COLORMAP
CURSOR
CUT_BUFFER0
CUT_BUFFER1
CUT_BUFFER2
CUT_BUFFER3
CUT_BUFFER4
CUT_BUFFER5
CUT_BUFFER6
CUT_BUFFER7
DRAWABLE
FONT
INTEGER
PIXMAP
POINT
RECTANGLE
RESOURCE_MANAGER
RGB_COLOR_MAP
RGB_BEST_MAP
RGB_BLUE_MAP
RGB_DEFAULT_MAP
RGB_GRAY_MAP
RGB_GREEN_MAP
RGB_RED_MAP
STRING
VISUALID
WINDOW
WM_COMMAND
WM_HINTS
WM_CLIENT_MACHINE
WM_ICON_NAME
WM_ICON_SIZE
WM_NAME
WM_NORMAL_HINTS
WM_SIZE_HINTS
WM_ZOOM_HINTS
MIN_SPACE
NORM_SPACE
MAX_SPACE END_SPACE,
SUPERSCRIPT_X
SUPERSCRIPT_Y
SUBSCRIPT_X
SUBSCRIPT_Y
UNDERLINE_POSITION
UNDERLINE_THICKNESS
STRIKEOUT_ASCENT
STRIKEOUT_DESCENT
ITALIC_ANGLE
X_HEIGHT
QUAD_WIDTH
WEIGHT
POINT_SIZE
RESOLUTION
COPYRIGHT
NOTICE
FONT_NAME
FAMILY_NAME
FULL_NAME
CAP_HEIGHT
WM_CLASS
WM_TRANSIENT_FOR
CLIPBOARD
</pre></td></tr></table><p><i class="parameter"><tt>format</tt></i> gives the length of the units (for
instance characters) in bits. Usually, you don't care about this when
receiving data.</p><p><i class="parameter"><tt>data</tt></i> is the returned data in the form of a
string.</p><p>PyGTK wraps all received data into a string. This makes it easy
to handle string targets. To retrieve targets of other types (e.g. ATOM or
INTEGER) the program must extract the information from the returned string.
PyGTK provides two methods to retrieve text and a list of targets from the
selection data:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
text = selection_data.get_text()
targets = selection_data.get_targets()
</pre></td></tr></table><p>where <i class="parameter"><tt>text</tt></i> is a string containing the text
of the selection and <i class="parameter"><tt>targets</tt></i> is a list of the targets
supported by the selection.</p><p>Given a <tt class="classname">gtk.SelectionData</tt> containing a
list of targets the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
has_text = selection_data.targets_include_text()
</pre></td></tr></table><p>will return <tt class="literal">TRUE</tt> if one or more of the targets
can provide text.</p><p>The <a href="examples/getselection.py" target="_top"><span><b class="command">getselection.py</b></span></a>
example program demonstrates the retrieving of a "STRING" or "TARGETS"
target from the primary selection and printing the corresponding data to the
console when the associated button is "clicked". <a href="sec-RetrievingTheSelection.html#getselectionfig" title="Figure 21.1. Get Selection Example">Figure 21.1, “Get Selection Example”</a> illustrates the program display:</p><div class="figure"><a name="getselectionfig"></a><p class="title"><b>Figure 21.1. Get Selection Example</b></p><div class="mediaobject" align="center"><img src="figures/getselection.png" align="middle" alt="Get Selection Example"></div></div><p>The source code for the <a href="examples/getselection.py" target="_top"><span><b class="command">getselection.py</b></span></a>
program is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
1 #!/usr/bin/env python
2
3 # example getselection.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class GetSelectionExample:
10 # Signal handler invoked when user clicks on the
11 # "Get String Target" button
12 def get_stringtarget(self, widget):
13 # And request the "STRING" target for the primary selection
14 ret = widget.selection_convert("PRIMARY", "STRING")
15 return
16
17 # Signal handler invoked when user clicks on the "Get Targets" button
18 def get_targets(self, widget):
19 # And request the "TARGETS" target for the primary selection
20 ret = widget.selection_convert("PRIMARY", "TARGETS")
21 return
22
23 # Signal handler called when the selections owner returns the data
24 def selection_received(self, widget, selection_data, data):
25 # Make sure we got the data in the expected form
26 if str(selection_data.type) == "STRING":
27 # Print out the string we received
28 print "STRING TARGET: %s" % selection_data.get_text()
29
30 elif str(selection_data.type) == "ATOM":
31 # Print out the target list we received
32 targets = selection_data.get_targets()
33 for target in targets:
34 name = str(target)
35 if name != None:
36 print "%s" % name
37 else:
38 print "(bad target)"
39 else:
40 print "Selection was not returned as \"STRING\" or \"ATOM\"!"
41
42 return False
43
44
45 def __init__(self):
46 # Create the toplevel window
47 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
48 window.set_title("Get Selection")
49 window.set_border_width(10)
50 window.connect("destroy", lambda w: gtk.main_quit())
51
52 vbox = gtk.VBox(False, 0)
53 window.add(vbox)
54 vbox.show()
55
56 # Create a button the user can click to get the string target
57 button = gtk.Button("Get String Target")
58 eventbox = gtk.EventBox()
59 eventbox.add(button)
60 button.connect_object("clicked", self.get_stringtarget, eventbox)
61 eventbox.connect("selection_received", self.selection_received)
62 vbox.pack_start(eventbox)
63 eventbox.show()
64 button.show()
65
66 # Create a button the user can click to get targets
67 button = gtk.Button("Get Targets")
68 eventbox = gtk.EventBox()
69 eventbox.add(button)
70 button.connect_object("clicked", self.get_targets, eventbox)
71 eventbox.connect("selection_received", self.selection_received)
72 vbox.pack_start(eventbox)
73 eventbox.show()
74 button.show()
75
76 window.show()
77
78 def main():
79 gtk.main()
80 return 0
81
82 if __name__ == "__main__":
83 GetSelectionExample()
84 main()
</pre></td></tr></table><p>Lines 30-38 handle the retrieval of the "TARGETS" selection data
and print the list of target names. The buttons are enclosed in their own
eventboxes because a selection must be associated with a
<tt class="classname">gtk.gdkWindow</tt> and buttons are "windowless" widgets in
GTK+2.0.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch-ManagingSelections.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch-ManagingSelections.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-SupplyingTheSelection.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Managing Selections </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 21.3. Supplying the Selection</td></tr></table></div></body></html>
|