Retrieving the selection is an asynchronous process. To start the process, you call:
result = widget.selection_convert(selection, target, time=0) |
This converts the selection into the form specified by target. selection is an atom corresponding to the selection type; the common selections are the strings:
PRIMARY SECONDARY |
If at all possible, the time field should be the time from the event that triggered the selection. 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. result is TRUE if the conversion succeeded, FALSE otherwise.
When the selection owner responds to the request, a "selection_received" signal is sent to your application. The handler for this signal receives a gtk.SelectionData object, which has the following attributes:
selection target type format data |
selection and target are the values you gave in your selection_convert() method.
type 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.
The list of standard atoms in X and GTK+ is:
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 |
format gives the length of the units (for instance characters) in bits. Usually, you don't care about this when receiving data.
data is the returned data in the form of a string.
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:
text = selection_data.get_text() targets = selection_data.get_targets() |
where text is a string containing the text of the selection and targets is a list of the targets supported by the selection.
Given a gtk.SelectionData containing a list of targets the method:
has_text = selection_data.targets_include_text() |
will return TRUE if one or more of the targets can provide text.
The getselection.py 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". Figure 21.1, “Get Selection Example” illustrates the program display:
The source code for the getselection.py program is:
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()
|
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 gtk.gdkWindow and buttons are "windowless" widgets in GTK+2.0.