/usr/share/doc/python-gtk2-tutorial/html/sec-SupplyingTheSelection.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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>21.3. Supplying 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="sec-RetrievingTheSelection.html" title="21.2. Retrieving the Selection"><link rel="next" href="ch-DragAndDrop.html" title="Chapter 22. Drag-and-drop (DND)"></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.3. Supplying the Selection</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-RetrievingTheSelection.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Managing Selections</th><td width="20%" align="right"> <a accesskey="n" href="ch-DragAndDrop.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-SupplyingTheSelection"></a>21.3. Supplying the Selection</h2></div></div><div></div></div><p>Supplying the selection is a bit more complicated. You must
register handlers that will be called when your selection is requested. For
each selection-target pair you will handle, you make a call to:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
widget.selection_add_target(<b class="parameter"><tt>selection</tt></b>, <b class="parameter"><tt>target</tt></b>, <b class="parameter"><tt>info</tt></b>)
</pre></td></tr></table><p><i class="parameter"><tt>widget</tt></i>, <i class="parameter"><tt>selection</tt></i>,
and <i class="parameter"><tt>target</tt></i> identify the requests this handler will
manage. When a request for a selection is received, the "selection_get"
signal will be called. <i class="parameter"><tt>info</tt></i> is an integer that can be
used as an enumerator to identify the specific target within the
callback.</p><p>The callback has the signature:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def selection_get(widget, selection_data, info, time):
</pre></td></tr></table><p>The <tt class="classname">gtk.SelectionData</tt> is the same as above,
but this time, we're responsible for filling in the fields
<i class="parameter"><tt>type</tt></i>, <i class="parameter"><tt>format</tt></i> and
<i class="parameter"><tt>data</tt></i>. (The <i class="parameter"><tt>format</tt></i> field is
actually important here - the X server uses it to figure out whether the
<i class="parameter"><tt>data</tt></i> needs to be byte-swapped or not. Usually it will
be 8 - i.e. a character - or 32 - i.e. a integer.) This is done by calling
the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
selection_data.set(<b class="parameter"><tt>type</tt></b>, <b class="parameter"><tt>format</tt></b>, <b class="parameter"><tt>data</tt></b>)
</pre></td></tr></table><p>This PyGTK method can only handle string data so the
<i class="parameter"><tt>data</tt></i> must be loaded into a Python string but
<i class="parameter"><tt>format</tt></i> will be whatever the appropriate size is
(e.g. 32 for atoms and integers, 8 for strings). The Python
<tt class="classname">struct</tt> or <tt class="classname">StringIO</tt> modules can
be used to convert non-string data to string data. For example, you can
convert a list of integers to a string and set the
<i class="parameter"><tt>selection_data</tt></i> by:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
ilist = [1, 2, 3, 4, 5]
data = apply(struct.pack, ['%di'%len(ilist)] + ilist)
selection_data.set("INTEGER", 32, data)
</pre></td></tr></table><p>The following method sets the selection data from the given
string:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
selection_data.set_text(<b class="parameter"><tt>str</tt></b>, <b class="parameter"><tt>len</tt></b>)
</pre></td></tr></table><p>When prompted by the user, you claim ownership of the selection
by calling:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
result = widget.selection_owner_set(<b class="parameter"><tt>selection</tt></b>, <b class="parameter"><tt>time</tt></b>=0L)
</pre></td></tr></table><p><i class="parameter"><tt>result</tt></i> will be <tt class="literal">TRUE</tt> if
program successfully claimed the <i class="parameter"><tt>selection</tt></i>. If
another application claims ownership of the
<i class="parameter"><tt>selection</tt></i>, you will receive a
"selection_clear_event".</p><p>As an example of supplying the selection, the <a href="examples/setselection.py" target="_top"><span><b class="command">setselection.py</b></span></a>
program adds selection functionality to a toggle button enclosed in a
<tt class="classname">gtk.EventBox</tt>. (The
<tt class="classname">gtk.Eventbox</tt> is needed because the selection must be
associated with a <tt class="classname">gtk.gdk.Window</tt> and a
<tt class="classname">gtk.Button</tt> is a "windowless" object in GTK+ 2.0.)
When the toggle button is depressed, the program claims the primary
selection. The only target supported (aside from certain targets like
"TARGETS" supplied by GTK+ itself), is the "STRING" target. When this target
is requested, a string representation of the time is returned. <a href="sec-SupplyingTheSelection.html#setselectionfig" title="Figure 21.2. Set Selection Example">Figure 21.2, “Set Selection Example”</a> illustrates the program display when the program
has taken the primary selection ownership:</p><div class="figure"><a name="setselectionfig"></a><p class="title"><b>Figure 21.2. Set Selection Example</b></p><div class="mediaobject" align="center"><img src="figures/setselection.png" align="middle" alt="Set Selection Example"></div></div><p>The <a href="examples/setselection.py" target="_top"><span><b class="command">setselection.py</b></span></a>
source code is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
1 #!/usr/bin/env python
2
3 # example setselection.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8 import time
9
10 class SetSelectionExample:
11 # Callback when the user toggles the selection
12 def selection_toggled(self, widget, window):
13 if widget.get_active():
14 self.have_selection = window.selection_owner_set("PRIMARY")
15 # if claiming the selection failed, we return the button to
16 # the out state
17 if not self.have_selection:
18 widget.set_active(False)
19 else:
20 if self.have_selection:
21 # Not possible to release the selection in PyGTK
22 # just mark that we don't have it
23 self.have_selection = False
24 return
25
26 # Called when another application claims the selection
27 def selection_clear(self, widget, event):
28 self.have_selection = False
29 widget.set_active(False)
30 return True
31
32 # Supplies the current time as the selection.
33 def selection_handle(self, widget, selection_data, info, time_stamp):
34 current_time = time.time()
35 timestr = time.asctime(time.localtime(current_time))
36
37 # When we return a single string, it should not be null terminated.
38 # That will be done for us
39 selection_data.set_text(timestr, len(timestr))
40 return
41
42 def __init__(self):
43 self.have_selection = False
44 # Create the toplevel window
45 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
46 window.set_title("Set Selection")
47 window.set_border_width(10)
48 window.connect("destroy", lambda w: gtk.main_quit())
49 self.window = window
50 # Create an eventbox to hold the button since it no longer has
51 # a GdkWindow
52 eventbox = gtk.EventBox()
53 eventbox.show()
54 window.add(eventbox)
55
56 # Create a toggle button to act as the selection
57 selection_button = gtk.ToggleButton("Claim Selection")
58 eventbox.add(selection_button)
59
60 selection_button.connect("toggled", self.selection_toggled, eventbox)
61 eventbox.connect_object("selection_clear_event", self.selection_clear,
62 selection_button)
63
64 eventbox.selection_add_target("PRIMARY", "STRING", 1)
65 eventbox.selection_add_target("PRIMARY", "COMPOUND_TEXT", 1)
66 eventbox.connect("selection_get", self.selection_handle)
67 selection_button.show()
68 window.show()
69
70 def main():
71 gtk.main()
72 return 0
73
74 if __name__ == "__main__":
75 SetSelectionExample()
76 main()
</pre></td></tr></table></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-RetrievingTheSelection.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="ch-DragAndDrop.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.2. Retrieving the Selection </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 22. Drag-and-drop (DND)</td></tr></table></div></body></html>
|