* examples/*.py Update examples to eliminate deprecated methods
and use import pygtk.
============== 2.1 ================== 2004-07-06 John Finlay <finlay@moeraki.com>
* pygtk2-tut.xml Bump version number to 2.1 and set
pubdate.
* TreeViewWidgets.xml Revise the treeviewdnd.py example to
illustrate row reordering with external drag and drop and
add explanation.
2004-07-03 John Finlay <finlay@moeraki.com>
* TimeoutsIOAndIdleFunctions.xml Update descriptions to use
the gobject functions.
2004-06-30 John Finlay <finlay@moeraki.com>
* TreeViewWidget.xml Extract the CellRenderers section into
CellRenderers.xml.
* CellRenderers.xml Create and add section on editable
CellRendererText.
* TreeViewWidget.xml Extract the TreeModel section and put into
new file TreeModel.xml. Add detail to the TreeViewColumn use of
its sort column ID.
* TreeModel.xml Create and add section on sorting TreeModel rows
using the TreeSortable interface.
2004-06-27 John Finlay <finlay@moeraki.com>
* TreeViewWidget.xml (Cell Data Function) Add filelisting example
using cell data functions. Add XInclude header to include generic
tree model and cell renderer subsections.
Fix typos and errors in links. Fix bugs in example listings.
Add section on TreeModel signals.
2004-06-22 John Finlay <finlay@moeraki.com>
* Introduction.xml Add note about pygtkconsole.py and gpython.py
programs do not work on Windows. Thanks to vector180.
2004-06-14 John Finlay <finlay@moeraki.com>
* DragAndDrop.xml Fix signal lists for drag source and dest.
Add detail to the overview drag cycle. Add detail about signal
handler operation.
* DragAndDrop.xml Add small example program dragtargets.py to
print out drag targets.
2004-05-31 John Finlay <finlay@moeraki.com>
* GettingStarted.xml Change wording in helloworld.py example
program - delete_event() comments confusing. Thanks to Ming Hua.
2004-05-28 John Finlay <finlay@moeraki.com>
* TreeViewWidget.xml (TreeModelFilter) Replace 'file' with 'filter'.
Thanks to Guilherme Salgado.
2004-05-27 John Finlay <finlay@moeraki.com>
* TreeViewWidget.xml (AccessingDataValues) Fix store.set example
column number wrong. Thanks to Rafael Villar Burke and Guilherme
Salgado.
(CellRendererAttributes) Fix error. Thanks to Doug Quale.
(TreeModelIntroduction)
(PythonProtocolSupport) Fix grammatical and spelling errors.
Thanks to Thomas Mills Hinkle.
2004-05-25 John Finlay <finlay@moeraki.com>
* Introduction.xml Add reference links to www.pygtk.org website
and describe some of its resources.
============ 2.0 ============== 2004-05-24 John Finlay <finlay@moeraki.com>
* TreeViewWidget.xml Add beginning of tutorial chapter.
* Introduction.xml Add reference to gpython.py program.
* pygtk2-tut.xml Bump release number to 2.0.
2004-03-31 John Finlay <finlay@moeraki.com>
* MiscellaneousWidgets.xml Fix bug in calendar.py example causing
date string to be off by one day in some time zones. Fixes #138487.
(thanks to Eduard Luhtonen)
2004-01-28 John Finlay <finlay@moeraki.com>
* DrawingArea.xml Modify description of DrawingArea to clarify that
drawing is done on the wrapped gtk.gdk.Window. Modify GC description
to clarify that new GCs created from drawables. (thanks to Antoon
Pardon)
* UndocumentedWidgets.xml Remove the section on Plugs and Sockets -
now in ContainerWidgets.xml.
* ContainerWidgets.xml Add section on Plugs and Sockets written
by Nathan Hurst.
* pygtk2-tut.xml Change date and version number.
2003-11-05 John Finlay <finlay@moeraki.com>
* Introduction.xml Add reference to the PyGTK 2.0 Reference Manual.
2003-11-04 John Finlay <finlay@moeraki.com>
* ContainerWidgets.xml
* RangeWidgets.xml
* WidgetOverview.xml Remove reference to testgtk.py since it doesn't
exist in PyGTK 2.0 (thanks to Steve Chaplin)
2003-10-07 John Finlay <finlay@moeraki.com>
* TextViewWidget.xml Change PANGO_ to pango. (thanks to Stephane Klein)
* pygtk2-tut.xml Change date and version number.
2003-10-06 John Finlay <finlay@moeraki.com>
* GettingStarted.xml Change third to second in description of signal
handler arguments. (thanks to Kyle Smith)
2003-09-26 John Finlay <finlay@moeraki.com>
* ContainerWidgets.xml Fix text layout error in frame shadow
description (thanks to Steve Chaplin)
2003-09-19 John Finlay <finlay@moeraki.com>
* ContainerWidgets.xml
* layout.py Use random module instead of whrandom in
layout.py example program (thanks to Steve Chaplin)
* PackingWidgets.xml
* packbox.py Use set_size_request() instead of set_usize() in
packbox.py example (thanks to Steve Chaplin)
2003-07-11 John Finlay <finlay@moeraki.com>
* ContainerWidgets.xml Fix link references to class-gtkalignment to
use a ulink instead of a link.
* ChangeLog Add this change log file
* pygtk2-tut.xml Change date and add a version number. Add ChangeLog
as an appendix.
The paned window widgets are useful when you want to divide an
area into two parts, with the relative size of the two parts controlled by
the user. A groove is drawn between the two portions with a handle that the
user can drag to change the ratio. The division can either be horizontal
(HPaned) or vertical
(VPaned).
To create a new paned window, call one of:
hpane = gtk.HPaned()
vpane = gtk.VPaned()
After creating the paned window widget, you need to add child
widgets to its two halves. To do this, use the methods:
paned.add1(child)
paned.add2(child)
The add1() method adds the
child widget to
the left or top half of the paned window. The add2()
method adds the child widget to the right or bottom
half of the paned window.
The paned.py example program
creates part of the user interface of an imaginary email program. A window
is divided into two portions vertically, with the top portion being a list
of email messages and the bottom portion the text of the email message. Most
of the program is pretty straightforward. A couple of points to note: text
can't be added to a Text widget until it is realized. This could be done by
calling the realize() method, but as a
demonstration of an alternate technique, we connect a handler to the
"realize" signal to add the text. Also, we need to add the
SHRINK option to some of the items in the table
containing the text window and its scrollbars, so that when the bottom
portion is made smaller, the correct portions shrink instead of being pushed
off the bottom of the window. Figure 10.6, “Paned Example” shows the result
of running the program:
1 #!/usr/bin/env python
2
3 # example paned.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk, gobject
8
9 class PanedExample:
10 # Create the list of "messages"
11 def create_list(self):
12 # Create a new scrolled window, with scrollbars only if needed
13 scrolled_window = gtk.ScrolledWindow()
14 scrolled_window.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
15
16 model = gtk.ListStore(gobject.TYPE_STRING)
17 tree_view = gtk.TreeView(model)
18 scrolled_window.add_with_viewport (tree_view)
19 tree_view.show()
20
21 # Add some messages to the window
22 for i in range(10):
23 msg = "Message #%d" % i
24 iter = model.append()
25 model.set(iter, 0, msg)
26
27 cell = gtk.CellRendererText()
28 column = gtk.TreeViewColumn("Messages", cell, text=0)
29 tree_view.append_column(column)
30
31 return scrolled_window
32
33 # Add some text to our text widget - this is a callback that is invoked
34 # when our window is realized. We could also force our window to be
35 # realized with gtk.Widget.realize(), but it would have to be part of a
36 # hierarchy first
37 def insert_text(self, buffer):
38 iter = buffer.get_iter_at_offset(0)
39 buffer.insert(iter,
40 "From: pathfinder@nasa.gov\n"
41 "To: mom@nasa.gov\n"
42 "Subject: Made it!\n"
43 "\n"
44 "We just got in this morning. The weather has been\n"
45 "great - clear but cold, and there are lots of fun sights.\n"
46 "Sojourner says hi. See you soon.\n"
47 " -Path\n")
48
49 # Create a scrolled text area that displays a "message"
50 def create_text(self):
51 view = gtk.TextView()
52 buffer = view.get_buffer()
53 scrolled_window = gtk.ScrolledWindow()
54 scrolled_window.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
55 scrolled_window.add(view)
56 self.insert_text(buffer)
57 scrolled_window.show_all()
58 return scrolled_window
59
60 def __init__(self):
61 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
62 window.set_title("Paned Windows")
63 window.connect("destroy", lambda w: gtk.main_quit())
64 window.set_border_width(10)
65 window.set_size_request(450, 400)
66
67 # create a vpaned widget and add it to our toplevel window
68 vpaned = gtk.VPaned()
69 window.add(vpaned)
70 vpaned.show()
71
72 # Now create the contents of the two halves of the window
73 list = self.create_list()
74 vpaned.add1(list)
75 list.show()
76
77 text = self.create_text()
78 vpaned.add2(text)
79 text.show()
80 window.show()
81
82 def main():
83 gtk.main()
84 return 0
85
86 if __name__ == "__main__":
87 PanedExample()
88 main()
Statusbars are simple widgets used to
display a text message. They keep a stack of the messages pushed onto them,
so that popping the current message will re-display the previous text
message.
In order to allow different parts of an application to use the
same statusbar to display messages, the statusbar widget issues Context
Identifiers which are used to identify different "users". The message on top
of the stack is the one displayed, no matter what context it is in. Messages
are stacked in last-in-first-out order, not context identifier order.
A statusbar is created with a call to:
statusbar = gtk.Statusbar()
A new Context Identifier is requested using a call to the following
method with a short textual description of the context:
The first, push(), is used to add a new
message to the statusbar. It returns a
message_id, which can be passed later to the
remove() method to remove the message with the
combination message_id and
context_id from the
statusbar's stack.
The pop() method removes the message
highest in the stack with the given
context_id.
The statusbar.py example
program creates a statusbar and two buttons, one for pushing items onto the
statusbar, and one for popping the last item back off.
Figure 9.9, “Statusbar Example” illustrates the result:
The Expander widget is a fairly simple
container widget that can reveal or hide its child widget by clicking on a
triangle similar to the triangle in a TreeView. A new
Expander is created using the constructor:
expander = gtk.Expander(label=None)
where label is a string to be used as the
expander label. If label is None
or not specified, no label is created. Alternatively, you can use the
function:
If you want to use Pango markup (see the Pango
Markup reference for more detail) in the label string, use the
following methods to set and retrieve the setting of the "use-markup"
property:
In most cases the Expander automatically does
exactly what you want when revealing and hiding the child widget. In some
cases your application might want to create a child widget at expansion
time. The "notify::expanded" signal can be used to track changes in the
state of the expander triangle. The signal handler can then create or change
the child widget as needed.
Where pixbuf is a
gtk.gdk.Pixbuf; pixmap and
mask are gtk.gdk.Pixmaps;
image is a gtk.gdk.Image;
stock_id is the name of a
gtk.StockItem; icon_set is a
gtk.IconSet; and, animation is
a gtk.gdk.PixbufAnimation. the
size argument is one of:
1 #!/usr/bin/env python
2
3 # example images.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class ImagesExample:
10 # when invoked (via signal delete_event), terminates the application.
11 def close_application(self, widget, event, data=None):
12 gtk.main_quit()
13 return False
14
15 # is invoked when the button is clicked. It just prints a message.
16 def button_clicked(self, widget, data=None):
17 print "button %s clicked" % data
18
19 def __init__(self):
20 # create the main window, and attach delete_event signal to terminating
21 # the application
22 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
23 window.connect("delete_event", self.close_application)
24 window.set_border_width(10)
25 window.show()
26
27 # a horizontal box to hold the buttons
28 hbox = gtk.HBox()
29 hbox.show()
30 window.add(hbox)
31
32 pixbufanim = gtk.gdk.PixbufAnimation("goalie.gif")
33 image = gtk.Image()
34 image.set_from_animation(pixbufanim)
35 image.show()
36 # a button to contain the image widget
37 button = gtk.Button()
38 button.add(image)
39 button.show()
40 hbox.pack_start(button)
41 button.connect("clicked", self.button_clicked, "1")
42
43 # create several images with data from files and load images into
44 # buttons
45 image = gtk.Image()
46 image.set_from_file("apple-red.png")
47 image.show()
48 # a button to contain the image widget
49 button = gtk.Button()
50 button.add(image)
51 button.show()
52 hbox.pack_start(button)
53 button.connect("clicked", self.button_clicked, "2")
54
55 image = gtk.Image()
56 image.set_from_file("chaos.jpg")
57 image.show()
58 # a button to contain the image widget
59 button = gtk.Button()
60 button.add(image)
61 button.show()
62 hbox.pack_start(button)
63 button.connect("clicked", self.button_clicked, "3")
64
65 image = gtk.Image()
66 image.set_from_file("important.tif")
67 image.show()
68 # a button to contain the image widget
69 button = gtk.Button()
70 button.add(image)
71 button.show()
72 hbox.pack_start(button)
73 button.connect("clicked", self.button_clicked, "4")
74
75 image = gtk.Image()
76 image.set_from_file("soccerball.gif")
77 image.show()
78 # a button to contain the image widget
79 button = gtk.Button()
80 button.add(image)
81 button.show()
82 hbox.pack_start(button)
83 button.connect("clicked", self.button_clicked, "5")
84
85
86 def main():
87 gtk.main()
88 return 0
89
90 if __name__ == "__main__":
91 ImagesExample()
92 main()
9.6.1. Pixmaps
Pixmaps are data structures that
contain pictures. These pictures can be used in various places, but most
commonly as icons on the X desktop, or as cursors.
A pixmap which only has 2 colors is called a bitmap, and there
are a few additional routines for handling this common special case.
To understand pixmaps, it would help to understand how X
window system works. Under X, applications do not need to be running on the
same computer that is interacting with the user. Instead, the various
applications, called "clients", all communicate with a program which
displays the graphics and handles the keyboard and mouse. This program which
interacts directly with the user is called a "display server" or "X server."
Since the communication might take place over a network, it's important to
keep some information with the X server. Pixmaps, for
example, are stored in the memory of the X server. This means that once
pixmap values are set, they don't need to keep getting transmitted over the
network; instead a command is sent to "display pixmap number XYZ here." Even
if you aren't using X with GTK+ currently, using constructs such as
Pixmaps will make your programs work acceptably under
X.
To use pixmaps in PyGTK, we must first build a
gtk.gdk.Pixmap using gtk.gdk functions in PyGTK.
Pixmaps can either be created from in-memory data, or
from data read from a file. We'll go through each of the calls to create a
pixmap.
This routine is used to create a pixmap
from data in memory with the color depth given by
depth. If depth is -1 the
color depth is derived from the depth of window. Each
pixel uses depth bits of data to represent the
color. Width and height are in
pixels. The window argument must refer to a realized
gtk.gdk.Window, since a pixmap's resources are
meaningful only in the context of the screen where it is to be
displayed. fg and bg are the
foreground and background colors of the pixmap.
XPM format is a readable pixmap representation for the X
Window System. It is widely used and many different utilities are available
for creating image files in this format. In the
pixmap_create_from_xpm() function the first argument is
a gtk.gdk.Window type. (Most GTK+ widgets have an
underlying gtk.gdk.Window which can be retrieved by
using the widget's window attribute.) The file, specified by
filename, must contain an image in the XPM format and
the image is loaded into the pixmap structure. The
mask is a bitmap that specifies which bits of
pixmap are opaque; it is created by the function. All
other pixels are colored using the color specified by
transparent_color. An example using this function is
below.
Pixmaps can also be created from data in memory using the
function:
Small images can be incorporated into a program as data in the
XPM format using the above function. A pixmap is created using this data,
instead of reading it from a file. An example of such data is:
window is either a
gtk.gdk.Window. or None. If
window is a gtk.gdk.Window
then depth can be -1 to indicate that the depth
should be determined from the window. If window is
None then the depth must be
specified.
1 #!/usr/bin/env python
2
3 # example pixmap.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 # XPM data of Open-File icon
10 xpm_data = [
11 "16 16 3 1",
12 " c None",
13 ". c #000000000000",
14 "X c #FFFFFFFFFFFF",
15 " ",
16 " ...... ",
17 " .XXX.X. ",
18 " .XXX.XX. ",
19 " .XXX.XXX. ",
20 " .XXX..... ",
21 " .XXXXXXX. ",
22 " .XXXXXXX. ",
23 " .XXXXXXX. ",
24 " .XXXXXXX. ",
25 " .XXXXXXX. ",
26 " .XXXXXXX. ",
27 " .XXXXXXX. ",
28 " ......... ",
29 " ",
30 " "
31 ]
32
33 class PixmapExample:
34 # when invoked (via signal delete_event), terminates the application.
35 def close_application(self, widget, event, data=None):
36 gtk.main_quit()
37 return False
38
39 # is invoked when the button is clicked. It just prints a message.
40 def button_clicked(self, widget, data=None):
41 print "button clicked"
42
43 def __init__(self):
44 # create the main window, and attach delete_event signal to terminating
45 # the application
46 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
47 window.connect("delete_event", self.close_application)
48 window.set_border_width(10)
49 window.show()
50
51 # now for the pixmap from XPM data
52 pixmap, mask = gtk.gdk.pixmap_create_from_xpm_d(window.window,
53 None,
54 xpm_data)
55
56 # an image widget to contain the pixmap
57 image = gtk.Image()
58 image.set_from_pixmap(pixmap, mask)
59 image.show()
60
61 # a button to contain the image widget
62 button = gtk.Button()
63 button.add(image)
64 window.add(button)
65 button.show()
66
67 button.connect("clicked", self.button_clicked)
68
69 def main():
70 gtk.main()
71 return 0
72
73 if __name__ == "__main__":
74 PixmapExample()
75 main()
A disadvantage of using pixmaps is that the displayed object
is always rectangular, regardless of the image. We would like to create
desktops and applications with icons that have more natural shapes. For
example, for a game interface, we would like to have round buttons to push.
The way to do this is using shaped windows.
A shaped window is simply a pixmap where the background pixels
are transparent. This way, when the background image is multi-colored, we
don't overwrite it with a rectangular, non-matching border around our icon.
The wheelbarrow.py
example program displays a full wheelbarrow image on the desktop.
Figure 9.7, “Wheelbarrow Example Shaped Window” shows the wheelbarrow over a terminal
window:
1 #!/usr/bin/env python
2
3 # example wheelbarrow.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 # XPM
10 WheelbarrowFull_xpm = [
11 "48 48 64 1",
12 " c None",
13 ". c #DF7DCF3CC71B",
14 "X c #965875D669A6",
15 "o c #71C671C671C6",
16 "O c #A699A289A699",
17 "+ c #965892489658",
18 "@ c #8E38410330C2",
19 "# c #D75C7DF769A6",
20 "$ c #F7DECF3CC71B",
21 "% c #96588A288E38",
22 "& c #A69992489E79",
23 "* c #8E3886178E38",
24 "= c #104008200820",
25 "- c #596510401040",
26 "; c #C71B30C230C2",
27 ": c #C71B9A699658",
28 "> c #618561856185",
29 ", c #20811C712081",
30 "< c #104000000000",
31 "1 c #861720812081",
32 "2 c #DF7D4D344103",
33 "3 c #79E769A671C6",
34 "4 c #861782078617",
35 "5 c #41033CF34103",
36 "6 c #000000000000",
37 "7 c #49241C711040",
38 "8 c #492445144924",
39 "9 c #082008200820",
40 "0 c #69A618611861",
41 "q c #B6DA71C65144",
42 "w c #410330C238E3",
43 "e c #CF3CBAEAB6DA",
44 "r c #71C6451430C2",
45 "t c #EFBEDB6CD75C",
46 "y c #28A208200820",
47 "u c #186110401040",
48 "i c #596528A21861",
49 "p c #71C661855965",
50 "a c #A69996589658",
51 "s c #30C228A230C2",
52 "d c #BEFBA289AEBA",
53 "f c #596545145144",
54 "g c #30C230C230C2",
55 "h c #8E3882078617",
56 "j c #208118612081",
57 "k c #38E30C300820",
58 "l c #30C2208128A2",
59 "z c #38E328A238E3",
60 "x c #514438E34924",
61 "c c #618555555965",
62 "v c #30C2208130C2",
63 "b c #38E328A230C2",
64 "n c #28A228A228A2",
65 "m c #41032CB228A2",
66 "M c #104010401040",
67 "N c #492438E34103",
68 "B c #28A2208128A2",
69 "V c #A699596538E3",
70 "C c #30C21C711040",
71 "Z c #30C218611040",
72 "A c #965865955965",
73 "S c #618534D32081",
74 "D c #38E31C711040",
75 "F c #082000000820",
76 " ",
77 " .XoO ",
78 " +@#$%o& ",
79 " *=-;#::o+ ",
80 " >,<12#:34 ",
81 " 45671#:X3 ",
82 " +89<02qwo ",
83 "e* >,67;ro ",
84 "ty> 459@>+&& ",
85 "$2u+ ><ipas8* ",
86 "%$;=* *3:.Xa.dfg> ",
87 "Oh$;ya *3d.a8j,Xe.d3g8+ ",
88 " Oh$;ka *3d$a8lz,,xxc:.e3g54 ",
89 " Oh$;kO *pd$%svbzz,sxxxxfX..&wn> ",
90 " Oh$@mO *3dthwlsslszjzxxxxxxx3:td8M4 ",
91 " Oh$@g& *3d$XNlvvvlllm,mNwxxxxxxxfa.:,B* ",
92 " Oh$@,Od.czlllllzlmmqV@V#V@fxxxxxxxf:%j5& ",
93 " Oh$1hd5lllslllCCZrV#r#:#2AxxxxxxxxxcdwM* ",
94 " OXq6c.%8vvvllZZiqqApA:mq:Xxcpcxxxxxfdc9* ",
95 " 2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ",
96 " :,q-6MN.dfmZZrrSS:#riirDSAX@Af5xxxxxfevo",
97 " +A26jguXtAZZZC7iDiCCrVVii7Cmmmxxxxxx%3g",
98 " *#16jszN..3DZZZZrCVSA2rZrV7Dmmwxxxx&en",
99 " p2yFvzssXe:fCZZCiiD7iiZDiDSSZwwxx8e*>",
100 " OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ",
101 " 3206Bwxxszx%et.eaAp77m77mmmf3&eeeg* ",
102 " @26MvzxNzvlbwfpdettttttttttt.c,n& ",
103 " *;16=lsNwwNwgsvslbwwvccc3pcfu<o ",
104 " p;<69BvwwsszslllbBlllllllu<5+ ",
105 " OS0y6FBlvvvzvzss,u=Blllj=54 ",
106 " c1-699Blvlllllu7k96MMMg4 ",
107 " *10y8n6FjvllllB<166668 ",
108 " S-kg+>666<M<996-y6n<8* ",
109 " p71=4 m69996kD8Z-66698&& ",
110 " &i0ycm6n4 ogk17,0<6666g ",
111 " N-k-<> >=01-kuu666> ",
112 " ,6ky& &46-10ul,66, ",
113 " Ou0<> o66y<ulw<66& ",
114 " *kk5 >66By7=xu664 ",
115 " <<M4 466lj<Mxu66o ",
116 " *>> +66uv,zN666* ",
117 " 566,xxj669 ",
118 " 4666FF666> ",
119 " >966666M ",
120 " oM6668+ ",
121 " *4 ",
122 " ",
123 " "
124 ]
125
126 class WheelbarrowExample:
127 # When invoked (via signal delete_event), terminates the application
128 def close_application(self, widget, event, data=None):
129 gtk.main_quit()
130 return False
131
132 def __init__(self):
133 # Create the main window, and attach delete_event signal to terminate
134 # the application. Note that the main window will not have a titlebar
135 # since we're making it a popup.
136 window = gtk.Window(gtk.WINDOW_POPUP)
137 window.connect("delete_event", self.close_application)
138 window.set_events(window.get_events() | gtk.gdk.BUTTON_PRESS_MASK)
139 window.connect("button_press_event", self.close_application)
140 window.show()
141
142 # Now for the pixmap and the image widget
143 pixmap, mask = gtk.gdk.pixmap_create_from_xpm_d(
144 window.window, None, WheelbarrowFull_xpm)
145 image = gtk.Image()
146 image.set_from_pixmap(pixmap, mask)
147 image.show()
148
149 # To display the image, we use a fixed widget to place the image
150 fixed = gtk.Fixed()
151 fixed.set_size_request(200, 200)
152 fixed.put(image, 0, 0)
153 window.add(fixed)
154 fixed.show()
155
156 # This masks out everything except for the image itself
157 window.shape_combine_mask(mask, 0, 0)
158
159 # show the window
160 window.set_position(gtk.WIN_POS_CENTER_ALWAYS)
161 window.show()
162
163 def main():
164 gtk.main()
165 return 0
166
167 if __name__ == "__main__":
168 WheelbarrowExample()
169 main()
To make the wheelbarrow image sensitive, we attached the
"button_press_event" signal to make the program exit. Lines 138-139 make the
picture sensitive to a mouse button being pressed and connect the
close_application() method.
What if you have a function which you want to be called when
nothing else is happening ? Use the function:
source_id = gobject.idle_add(callback, ...)
Any arguments beyond the first (indicated with ...) are passed to
the callback in order. The
source_id is returned to provide a reference to the
handler.
This function causes GTK to call the specified
callback function whenever nothing else is
happening.
The callback signature is:
def callback(...):
where the arguments passed to the callback
are the same as those specified in the
gobject.idle_add() function. As with the other callback
functions, returning FALSE will stop the idle callback
from being called and returning TRUE causes the callback
function to be run at the next idle time.
An idle function can be removed from the queue by calling the
function:
gobject.source_remove(source_id)
with the source_id returned from the
gobject.idle_add() function.
A style contains the graphics information needed by a widget to
draw itself in its various states:
STATE_NORMAL # The state during normal operation.
STATE_ACTIVE # The widget is currently active, such as a button pushed
STATE_PRELIGHT # The mouse pointer is over the widget.
STATE_SELECTED # The widget is selected
STATE_INSENSITIVE # The widget is disabled
A style contains the following attributes:
fg # a list of 5 foreground colors - one for each state
bg # a list of 5 background colors
light # a list of 5 colors - created during set_style() method
dark # a list of 5 colors - created during set_style() method
mid # a list of 5 colors - created during set_style() method
text # a list of 5 colors
base # a list of 5 colors
text_aa # a list of 5 colors halfway between text/base
black # the black color
white # the white color
font_desc # the default pango font description
xthickness #
ythickness #
fg_gc # a list of 5 graphics contexts - created during set_style() method
bg_gc # a list of 5 graphics contexts - created during set_style() method
light_gc # a list of 5 graphics contexts - created during set_style() method
dark_gc # a list of 5 graphics contexts - created during set_style() method
mid_gc # a list of 5 graphics contexts - created during set_style() method
text_gc # a list of 5 graphics contexts - created during set_style() method
base_gc # a list of 5 graphics contexts - created during set_style() method
black_gc # a list of 5 graphics contexts - created during set_style() method
white_gc # a list of 5 graphics contexts - created during set_style() method
bg_pixmap # a list of 5 GdkPixmaps
Each attribute can be accessed directly similar to
style.black and
style.fg_gc[gtk.STATE_NORMAL]. All attributes are
read-only except for style.black,
style.white, style.black_gc and
style.white_gc.
An existing style can be copied for later modification by using
the method:
new_style = style.copy()
which copies the style attributes except
for the graphics context lists and the light, dark and mid color
lists.
The current style of a widget can be retrieved with:
style = widget.get_style()
To change the style of a widget (e.g. to change the widget
foreground color), the following widget methods should be used:
Setting the style will allocate the style
colors and create the graphics contexts. Most widgets will automatically
redraw themselves after the style is changed. If
style is None then the widget
style will revert to the default style.
Not all style changes will affect the widget. For example,
changing the Label (see Section 9.1, “Labels”) widget background color will not change the
label background color because the Label widget does
not have its own gtk.gdk.Window. The background of
the label is dependent on the background color of the label's parent. The
use of an EventBox to hold a Label will allow the
Label background color to be set. See Section 10.1, “The EventBox” for an
example.
The color selection widget is, not surprisingly, a widget for
interactive selection of colors. This composite widget lets the user select
a color by manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation,
Value) triples. This is done either by adjusting single values with sliders
or entries, or by picking the desired color from a hue-saturation
wheel/value bar. Optionally, the opacity of the color can also be
set.
The color selection widget currently emits only one signal,
"color_changed", which is emitted whenever the current color in the widget
changes, either when the user changes it or if it's set explicitly through
the set_color() method.
Lets have a look at what the color selection widget has to offer us.
The widget comes in two flavors: gtk.ColorSelection
and gtk.ColorSelectionDialog.
colorsel = gtk.ColorSelection()
You'll probably not be using this constructor directly. It
creates an orphan ColorSelection widget which you'll
have to parent yourself. The ColorSelection widget
inherits from the VBox widget.
colorseldlg = gtk.ColorSelectionDialog(title)
where title is a string to be used in the
titlebar of the dialog.
This is the most common color selection constructor. It creates
a ColorSelectionDialog. It consists of a
Frame containing a
ColorSelection widget, an
HSeparator and an HBox with
three buttons, Ok, Cancel and
Help. You can reach these buttons by accessing the
ok_button, cancel_button and
help_button attributes of the
ColorSelectionDialog, (i.e.
colorseldlg.ok_button). The
ColorSelection widget is accessed using the attribute
colorsel:
colorsel = colorseldlg.colorsel
The ColorSelection widget has a number of
methods that change its characteristics or provide access to the color
selection.
colorsel.set_has_opacity_control(has_opacity)
The color selection widget supports adjusting the opacity of a
color (also known as the alpha channel). This is disabled by default.
Calling this method with has_opacity set to
TRUE enables opacity. Likewise, has_opacity
set to FALSE will disable opacity.
You can set the current color explicitly by calling the
set_current_color() method with a
gtk.gdk.Color. Setting the opacity (alpha channel) is
done with the set_current_alpha() method. The
alpha value should be between 0 (fully transparent)
and 65636 (fully opaque).
color = colorsel.get_current_color()
alpha = colorsel.get_current_alpha()
When you need to query the current color, typically when you've
received a "color_changed" signal, you use these methods.
The colorsel.py example
program demonstrates the use of the
ColorSelectionDialog. The program displays a window
containing a drawing area. Clicking on it opens a color selection dialog,
and changing the color in the color selection dialog changes the background
color.
Figure 9.13, “Color Selection Dialog Example” illustrates this program in action:
This document, like so much other great software out there, was
created for free by volunteers. If you are at all knowledgeable about any
aspect of PyGTK that does not already have documentation, please consider
contributing to this document.
If you do decide to contribute, please mail your text to John Finlay (finlay@moeraki.com).
Also, be aware that the entirety of this document is free, and any addition
by you provide must also be free. That is, people may use any portion of
your examples in their programs, and copies of this document may be
distributed at will, etc.
This describes the methods used to operate on widgets (and
objects). These can be used to set style, padding, size, etc.
The method:
widget.activate()
causes the widget to emit the "activate" signal.
The method:
widget.set_sensitive(sensitive)
sets the sensitivity of the widget (i.e. does it react to events).
if sensitive is TRUE the widget
will receive events; if FALSE the widget will not receive
events. A widget that is insensitive is usually displayed "grayed
out".
The method:
widget.set_size_request(width, height)
sets the widget size to the given width and
height.
Toolbars are usually used to group some
number of widgets in order to simplify customization of their look and
layout. Typically a toolbar consists of buttons with icons, labels and
tooltips, but any other widget can also be put inside a toolbar. Finally,
items can be arranged horizontally or vertically and buttons can be
displayed with icons, labels, or both.
Creating a toolbar is (as one may already suspect) done with the
following function:
toolbar = gtk.Toolbar()
After creating a toolbar one can append, prepend and insert
items (that means simple text strings) or elements (that means any widget
types) into the toolbar. To describe an item we need a label text, a tooltip
text, a private tooltip text, an icon for the button and a callback for it.
For example, to append or prepend an item you may use the following
methods:
If you want to use the insert_item()
method, the only additional parameter which must be specified is the
position in which the item should be inserted, thus:
Where orientation is one of
ORIENTATION_HORIZONTAL or
ORIENTATION_VERTICAL. The style is
used to set appearance of the toolbar items by using one of
TOOLBAR_ICONS, TOOLBAR_TEXT, or
TOOLBAR_BOTH. The enable argument
is either TRUE or FALSE.
To show some other things that can be done with a toolbar, let's
take the toolbar.py example
program (we'll interrupt the listing with some additional
explanations):
1 #!/usr/bin/env python
2
3 # example toolbar.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class ToolbarExample:
10 # This method is connected to the Close button or
11 # closing the window from the WM
12 def delete_event(self, widget, event=None):
13 gtk.main_quit()
14 return False
15
The above beginning seems should be familiar to you if it's not your
first PyGTK program. There is one additional thing though, we import a nice
XPM picture (gtk.xpm)to serve as an
icon for all of the buttons. Line 10 starts the
ToolbarExample class and lines 12-14 define the
callback method which will terminate the program.
16 # that's easy... when one of the buttons is toggled, we just
17 # check which one is active and set the style of the toolbar
18 # accordingly
19 def radio_event(self, widget, toolbar):
20 if self.text_button.get_active():
21 toolbar.set_style(gtk.TOOLBAR_TEXT)
22 elif self.icon_button.get_active():
23 toolbar.set_style(gtk.TOOLBAR_ICONS)
24 elif self.both_button.get_active():
25 toolbar.set_style(gtk.TOOLBAR_BOTH)
26
27 # even easier, just check given toggle button and enable/disable
28 # tooltips
29 def toggle_event(self, widget, toolbar):
30 toolbar.set_tooltips(widget.get_active())
31
Lines 19-30 are two callback methods that will be called when
one of the buttons on a toolbar is pressed. You should already be familiar
with things like this if you've already used toggle buttons (and radio
buttons).
32 def __init__(self):
33 # Here is our main window (a dialog) and a handle for the handlebox
34 # Ok, we need a toolbar, an icon with a mask (one for all of
35 # the buttons) and an icon widget to put this icon in (but
36 # we'll create a separate widget for each button)
37 # create a new window with a given title, and nice size
38 dialog = gtk.Dialog()
39 dialog.set_title("GTKToolbar Tutorial")
40 dialog.set_size_request(450, 250)
41 dialog.set_resizable(True)
42
43 # typically we quit if someone tries to close us
44 dialog.connect("delete_event", self.delete_event)
45
46 # to make it nice we'll put the toolbar into the handle box,
47 # so that it can be detached from the main window
48 handlebox = gtk.HandleBox()
49 dialog.vbox.pack_start(handlebox, False, False, 5)
50
The above should be similar to any other PyGTK application. Just
initialization of a ToolbarExample object instance
creating the window, etc. There is only one thing that probably needs some
explanation: a handle box. A handle box is just another box that can be used
to pack widgets in to. The difference between it and typical boxes is that
it can be detached from a parent window (or, in fact, the handle box remains
in the parent, but it is reduced to a very small rectangle, while all of its
contents are reparented to a new freely floating window). It is usually nice
to have a detachable toolbar, so these two widgets occur together quite
often.
51 # toolbar will be horizontal, with both icons and text, and
52 # with 5pxl spaces between items and finally,
53 # we'll also put it into our handlebox
54 toolbar = gtk.Toolbar()
55 toolbar.set_orientation(gtk.ORIENTATION_HORIZONTAL)
56 toolbar.set_style(gtk.TOOLBAR_BOTH)
57 toolbar.set_border_width(5)
58 handlebox.add(toolbar)
59
Well, what we do above is just a straightforward initialization
of the toolbar widget.
60 # our first item is <close> button
61 iconw = gtk.Image() # icon widget
62 iconw.set_from_file("gtk.xpm")
63 close_button = toolbar.append_item(
64 "Close", # button label
65 "Closes this app", # this button's tooltip
66 "Private", # tooltip private info
67 iconw, # icon widget
68 self.delete_event) # a signal
69 toolbar.append_space() # space after item
In the above code you see the simplest case: adding a button to
toolbar. Just before appending a new item, we have to construct an image
widget to serve as an icon for this item; this step will have to be repeated
for each new item. Just after the item we also add a space, so the following
items will not touch each other. As you see the
append_item() method returns a reference to our
newly created button widget, so that we can work with it in the normal
way.
71 # now, let's make our radio buttons group...
72 iconw = gtk.Image() # icon widget
73 iconw.set_from_file("gtk.xpm")
74 icon_button = toolbar.append_element(
75 gtk.TOOLBAR_CHILD_RADIOBUTTON, # type of element
76 None, # widget
77 "Icon", # label
78 "Only icons in toolbar", # tooltip
79 "Private", # tooltip private string
80 iconw, # icon
81 self.radio_event, # signal
82 toolbar) # data for signal
83 toolbar.append_space()
84 self.icon_button = icon_button
85
Here we begin creating a radio buttons group. To do this we use
the append_element() method. In fact, using this
method one can also add simple items or even spaces
(type = gtk.TOOLBAR_CHILD_SPACE or
gtk.TOOLBAR_CHILD_BUTTON). In the above case we start
creating a radio group. In creating other radio buttons for this group a
reference to the previous button in the group is required, so that a list of
buttons can be easily constructed (see Section 6.4, “Radio Buttons” earlier in this tutorial). We also save a
reference to the button in the ToolbarExample
instance for later access.
We create the other radiobuttons the same way except we pass one
of the created radio group buttons to the
append_element() method to specify the radio
group.
In the end we have to set the state of one of the buttons
manually (otherwise they all stay in active state, preventing us from
switching between them).
116 # here we have just a simple toggle button
117 iconw = gtk.Image() # icon widget
118 iconw.set_from_file("gtk.xpm")
119 tooltips_button = toolbar.append_element(
120 gtk.TOOLBAR_CHILD_TOGGLEBUTTON,
121 None,
122 "Tooltips",
123 "Toolbar with or without tips",
124 "Private",
125 iconw,
126 self.toggle_event,
127 toolbar)
128 toolbar.append_space()
129 tooltips_button.set_active(True)
130
A toggle button can be created in the obvious way (if one knows
how to create radio buttons already).
131 # to pack a widget into toolbar, we only have to
132 # create it and append it with an appropriate tooltip
133 entry = gtk.Entry()
134 toolbar.append_widget(entry, "This is just an entry", "Private")
135
136 # well, it isn't created within the toolbar, so we must still show it
137 entry.show()
138
As you see, adding any kind of widget to a toolbar is simple.
The one thing you have to remember is that this widget must be shown
manually (contrary to items which will be shown together with the
toolbar).
139 # that's it ! let's show everything.
140 toolbar.show()
141 handlebox.show()
142 dialog.show()
143
144 def main():
145 # rest in gtk_main and wait for the fun to begin!
146 gtk.main()
147 return 0
148
149 if __name__ == "__main__":
150 ToolbarExample()
151 main()
Line 142 ends the ToolbarExample class
definition. Lines 144-147 define the main() function
which just calls the gtk.main() function to start the
event processing loop. Lines 149-151 arrange to create a
ToolbarExample instance and then enter the event
processing loop. So, here we are at the end of toolbar tutorial. Of course,
to appreciate it in full you need also this nice XPM icon, gtk.xpm.
Figure 10.8, “Toolbar Example” illustrates the resulting
display:
Figure 10.8. Toolbar Example
pygtk2tutorial/ch-NewInPyGTK2.2.html 0100644 0001172 0000167 00000044751 10227356773 016312 0 ustar finlay fcf Chapter 15. New Widgets in PyGTK 2.2
The Clipboard object was added in PyGTK
2.2. The GtkClipboard was available in GTK+ 2.0 but
was not wrapped by PyGTK 2.0 because it was not a complete
GObject. 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
PyGTK 2
Reference Manual for more information on the
gtk.gdk.Display,
gtk.gdk.DisplayManager and
gtk.gdk.Screen objects.
15.1. Clipboards
A Clipboard provides a storage area for
sharing data between processes or between different widgets in the same
process. Each Clipboard is identified by a string
name encoded as a gdk.Atom. You can use any name you
want to identify a Clipboard and a new one will be
created if it doesn't exist. If you want to share a
Clipboard with other processes each process will need
to know the Clipboard's name.
Clipboards are built on the
SelectionData and selection interfaces. The default
Clipboard used by the
TextView, Label and
Entry 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
gtk.gdk.Atom objects:
gtk.gdk.SELECTION_CLIPBOARD,
gtk.gdk.SELECTION_PRIMARY and
gtk.gdk.SELECTION_SECONDARY. See the gtk.gdk.Atom
reference documentation for more information.
15.1.1. Creating A Clipboard
A Clipboard is created using the
constructor:
clipboard = gtk.Clipboard(display, selection)
where display is the
gtk.gdk.Display associated with the
Clipboard named by
selection. The following convenience function creates
a Clipboard using the default
gtk.gdk.Display:
clipboard = gtk.clipboard_get(selection)
Finally, a Clipboard can also be
created using the Widget method:
clipboard = widget.get_clipboard(selection)
The widget must be realized and be part of a toplevel window
hierarchy.
15.1.2. Using Clipboards with Entry, Spinbutton and TextView
Entry,
SpinButton and TextView
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 Control+X; copy,
by Control+C; and,
paste, by Control+V.
The widgets (Entry and
SpinButton) implement the
Editable interface that has the following methods to
cut, copy and paste to and from the "CLIPBOARD" clipboard:
A Label that is selectable (the
"selectable" property is TRUE) also supports copying the
selected text to the "CLIPBOARD" clipboard using a popup menu or the
Control+C
keyboard accelerator.
TextBuffers have similar methods though
they also allow specifying the clipboard to use:
textbuffer.copy_clipboard(clipboard)
The selection text will be copied to the
Clipboard specified by
clipboard.
The selected text will be copied to
clipboard. If default_editable
is TRUE the selected text will also be deleted from the
TextBuffer. Otherwise,
cut_clipboard() will act like the
copy_clipboard() method.
If default_editable is
TRUE, the contents of clipboard
will be inserted into the TextBuffer at the location
specified by the TextIteroverride_location. If
default_editable is FALSE,
paste_clipboard() will not insert the contents of
clipboard. If
override_location is None the
contents of clipboard will be inserted at the cursor
location.
TextBuffers also have two methods to
manage a set of Clipboards that are automatically set
with the contents of the current selection:
When a TextBuffer is added to a
TextView the "PRIMARY" clipboard is automatically
added to the selection clipboards. Your application can add other clipboards
(for example, the "CLIPBOARD" clipboard).
15.1.3. Setting Data on a Clipboard
You can set the Clipboard data
programmatically using either of:
The set_with_data() method indicates
which selection data targets are supported and provides functions
(get_func and clear_func) that
are called when the data is asked for or the clipboard data is
changed. user_data is passed to
get_func or clear_func when
called. targets is a list of 3-tuples
containing:
a string representing a target supported by the
clipboard.
a flags value used for drag and drop - use 0.
an application assigned integer that is passed as a
parameter to a signal handler to help identify the target type.
where clipboard is the
Clipboard, selectiondata is a
SelectionData object to set the data in,
info is the application assigned integer associated
with a target, and data is
user_data.
set_text() is a convenience method
that uses the set_with_data() method to set text
data on a Clipboard with the targets: "STRING",
"TEXT", "COMPOUND_TEXT", and "UTF8_STRING". It uses internal get and clear
functions to manage the data. set_text() is
equivalent to the following:
Once data is set on a clipboard, it will be available until the
application is finished or the clipboard data is changed.
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.
15.1.4. Retrieving the Clipboard Contents
The contents of a Clipboard can be
retrieved using the following method:
The contents specified by target are
retrieved asynchronously in the function specified by
callback which is called with
user_data. The signature of
callback is:
def callback(clipboard, selectiondata, data):
where selectiondata is a
SelectionData object containing the contents of
clipboard. data is
user_data. The
request_contents() method is the most general way
of retrieving the contents of a Clipboard. The
following convenience method retrieves the text contents of a
Clipboard:
clipboard.request_text(callback, user_data=None)
The text string is returned to the callback function instead
of a Selectiondata object. You can check which
targets are available on the Clipboard by using the
method:
The targets are returned as a tuple of
gtk.gdk.Atom objects to the callback function.
Two convenience methods are provided to return the
Clipboard contents synchronously:
selectiondata = clipboard.wait_for_contents(target)
text = clipboard.wait_for_text()
15.1.5. A Clipboard Example
To illustrate the use of a Clipboard
the clipboard.py 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.
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 set_with_data() method. Later, when
another program sets the contents of the clipboard, the
clear_func will be called and it can be used to
reload the clipboard contents and retake the clipboard ownership.
The testtext.py example
program (derived from the testtext.c program included
in the GTK+ 2.0.x distribution) demonstrates the use of the
TextView widget and its associated objects:
TextBuffers, TextIters,
TextMarks, TextTags,
TextTagTables. Figure 13.2, “TextView Example”
illustrates its operation:
Figure 13.2. TextView Example
The testtext.py program
defines a number of classes in addition to the application class
TestText:
Buffer class, lines 99-496, is
subclassed from the gtk.TextBuffer type. It provides
the editing buffer capabilities used by the View
objects.
View class, lines 498-1126, is
subclassed from the gtk.Window type and wraps a
gtk.TextView object that uses a
Buffer object instead of a
gtk.TextBuffer object. It provides a window and the
visual display of the contents of a Buffer object as
well as a menubar.
FileSel class, lines 73-97, is
subclassed from the gtk.FileSelection type to provide
selection of filenames for the Buffer
contents.
Stack class to provide simple stack
objects.
The color cycle display is implemented by using text tags applied
to a section of text in a buffer. Lines 109-115 (in the
__init__() method) create these tags and lines
763-784 (do_apply_colors() method) apply the color
tags to a section of text two characters at a time. Lines 202-239 provide
the methods (color_cycle_timeout(),
set_colors() and
cycle_colors()) that produce the color cycle
display when enabled. Color cycling is enabled by setting (line 220) the
foreground_gdk property of the individual
color_tags (which also sets the
foreground_set property). Color cycling is disabled
by setting the foreground_set property to
FALSE (line 222). The colors are periodically changed by
shifting the start_hue (line 237)
A new Buffer is filled with example content
when the
Test->Example
menu item is selected (the fill_example_buffer()
method in lines 302-372). The example buffer contains text of various
colors, styles and languages and pixbufs. The
init_tags() method (lines 260-300) sets up a
variety of TextTags for use with the example text.
The event signal of these tags is connected to the
tag_event_handler() method (lines 241-256) to
illustrate button and motion event capture.
The TextView wrap mode is set to WRAP_WORD
(line 580) and the TextView border windows are
displayed by setting their sizes in lines 587-588 and line 596-597. The left
and right border windows are used to display line numbers and the top and
bottom border windows display the tab locations when custom tabs are
set. The border windows are updated when an "expose-event" signal is
received by the TextView (lines 590 and 599). The
line_numbers_expose() method (lines 1079-1116)
determines whether the left or right border window has an expose event and
if so calculates the size of the expose area. Then the location of the line
start and the line number for each line in the exposed area is calculated in
the get_lines() method (lines 1057-1077). The line
numbers are then drawn in the border window at the location (transformed by
line 1109).
The custom tab locations are displayed in the top and bottom
border windows in a similar fashion (lines 1013-1055). They are displayed
only when the cursor is moved inside a range of text that has the custom tab
attribute set. This is detected by handling the "mark-set" signal in the
cursor_set_handler() method (lines 999-1011) and
invalidating the top and bottom border windows if the mark set is the
insert mark.
Movable widgets are added to a View with
the do_add_children() method (lines 892-899) which
calls the add_movable_children() method (lines
874-890). The children are gtk.Labels that can be
dragged around inside the various windows that are part of a
TextView widget.
Likewise, widgets are added to the TextView
windows of a View and the
Buffer by using the
do_add_focus_children() method (lines
901-949).
Progress bars are used to show the status of an operation. They
are pretty easy to use, as you will see with the code below. But first lets
start out with the call to create a new progress bar.
progressbar = gtk.ProgressBar(adjustment=None)
The adjustment argument specifies an
adjustment to use with the progressbar. If not
specified an adjustment will be created. Now that the progress bar has been
created we can use it.
progressbar.set_fraction(fraction)
The progressbar object is the progress bar
you wish to operate on, and the argument (fraction) is
the amount "completed", meaning the amount the progress bar has been filled
from 0-100%. This is passed to the method as a real number ranging from 0 to
1.
A progress bar may be set to one of a number of orientations
using the method:
progressbar.set_orientation(orientation)
The orientation argument may take one of
the following values to indicate the direction in which the progress bar
moves:
As well as indicating the amount of progress that has occurred,
the progress bar may be set to just indicate that there is some activity.
This can be useful in situations where progress cannot be measured against a
value range. The following function indicates that some progress has been
made.
progressbar.pulse()
The step size of the activity indicator is set using the
following function where fraction is between 0.0 and 1.0.
progressbar.set_pulse_step(fraction)
When not in activity mode, the progress bar can also display a
configurable text string within its trough, using the following
method:
progressbar.set_text(text)
Note
Note that set_text() doesn't support
the printf()-like formatting of the GTK+ 1.2
Progressbar.
You can turn off the display of the string by calling
set_text() again with no argument.
The current text setting of a progressbar can be retrieved with
the following method:
text = progressbar.get_text()
Progress Bars are usually used with timeouts or other such
functions (see Chapter 19, Timeouts, IO and Idle Functions) to
give the illusion of multitasking. All will employ the
set_fraction() or pulse()
methods in the same manner.
The progressbar.py
program provides an example of the progress bar, updated using timeouts.
This code also shows you how to reset the Progress Bar.
Figure 9.4, “ProgressBar Example” illustrates the resulting display:
These all require authors! :) Please consider contributing to our
tutorial.
If you must use one of these widgets that are undocumented, I
strongly suggest you take a look at the *.c files in the PyGTK distribution.
PyGTK's method names are very descriptive. Once you have an understanding of
how things work, it's not difficult to figure out how to use a widget simply
by looking at its method definitions. This, along with a few examples from
others' code, and it should be no problem.
When you do come to understand all the methods of a new
undocumented widget, please consider writing a tutorial on it so others may
benefit from your time.
17.1. Accel Label
pygtk2tutorial/sec-TextMarks.html 0100644 0001172 0000167 00000010226 10227356766 016263 0 ustar finlay fcf 13.5. Text Marks
A TextMark indicates a location in a
TextBuffer between two characters that is preserved
across buffer modifications. TextMarks are created,
moved and deleted using the TextBuffer methods as
described in the TextBuffer section.
A TextBuffer has two built-in
TextMarks named: insert and
selection_bound which refer to the insertion point
and the boundary of the selection (these may refer to the same
location).
The name of a TextMark can be retrieved
using the method:
name = textmark.get_name()
By default marks other than insert are not visible (displayed as a
vertical bar). The visibility of a mark can be set and retrieved using the
methods:
The TextBuffer that contains a
TextMark can be obtained using the method:
buffer = textmark.get_buffer()
You can determine whether a TextMark has
been deleted using the method:
setting = textmark.get_deleted()
The left gravity of a TextMark can be
retrieved using the method:
setting = textmark.get_left_gravity()
The left gravity of a TextMark indicates
where the mark will end up after an insertion. If left gravity is
TRUE the mark will be to the left of the insertion; if
FALSE, to the right of the insertion.
It is unlikely that you will ever need to use the
Viewport widget directly. You are much more likely to
use the ScrolledWindow widget *see Section 10.9, “Scrolled Windows”) which in turn uses the
Viewport.
A viewport widget allows you to place a larger widget within it
such that you can view a part of it at a time. It uses
Adjustment object (see Chapter 7, Adjustments) to define the area that is currently in
view.
As you can see you can specify the horizontal and vertical
Adjustment objects that the widget is to use when you
create the widget. It will create its own if you pass
None as the value of the arguments or pass no
arguments.
You can get and set the adjustments after the widget has been
created using the following four methods:
Tooltips are the little text strings that
pop up when you leave your pointer over a button or other widget for a few
seconds.
Widgets that do not receive events (widgets that do not have
their own window) will not work with tooltips.
The first call you will use creates a new tooltip. You only need
to do this once for a set of tooltips as the
gtk.Tooltips object this function returns can be used
to create multiple tooltips.
tooltips = gtk.Tooltips()
Once you have created a new tooltip, and the widget you wish to use it
on, simply use this call to set it:
The object tooltips is the tooltip you've
already created. The first argument (widget) is the
widget you wish to have this tooltip pop up for; the second
(tip_text), the text you wish it to display. The last
argument (tip_private) is a text string that can be
used as an identifier.
The tooltip.py example
program modifies the arrow.py program to add a
tooltip for each button. Figure 9.3, “Tooltips Example” illustrates the
resulting display with the tooltip for the second arrow button
displayed:
1 #!/usr/bin/env python
2
3 # example tooltip.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 # Create an Arrow widget with the specified parameters
10 # and pack it into a button
11 def create_arrow_button(arrow_type, shadow_type):
12 button = gtk.Button()
13 arrow = gtk.Arrow(arrow_type, shadow_type)
14 button.add(arrow)
15 button.show()
16 arrow.show()
17 return button
18
19 class Tooltips:
20 def __init__(self):
21 # Create a new window
22 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
23
24 window.set_title("Tooltips")
25
26 # It's a good idea to do this for all windows.
27 window.connect("destroy", lambda w: gtk.main_quit())
28
29 # Sets the border width of the window.
30 window.set_border_width(10)
31
32 # Create a box to hold the arrows/buttons
33 box = gtk.HBox(False, 0)
34 box.set_border_width(2)
35 window.add(box)
36
37 # create a tooltips object
38 self.tooltips = gtk.Tooltips()
39
40 # Pack and show all our widgets
41 box.show()
42
43 button = create_arrow_button(gtk.ARROW_UP, gtk.SHADOW_IN)
44 box.pack_start(button, False, False, 3)
45 self.tooltips.set_tip(button, "SHADOW_IN")
46
47 button = create_arrow_button(gtk.ARROW_DOWN, gtk.SHADOW_OUT)
48 box.pack_start(button, False, False, 3)
49 self.tooltips.set_tip(button, "SHADOW_OUT")
50
51 button = create_arrow_button(gtk.ARROW_LEFT, gtk.SHADOW_ETCHED_IN)
52 box.pack_start(button, False, False, 3)
53 self.tooltips.set_tip(button, "SHADOW_ETCHED_IN")
54
55 button = create_arrow_button(gtk.ARROW_RIGHT, gtk.SHADOW_ETCHED_OUT)
56 box.pack_start(button, False, False, 3)
57 self.tooltips.set_tip(button, "SHADOW_ETCHED_OUT")
58
59 window.show()
60
61 def main():
62 gtk.main()
63 return 0
64
65 if __name__ == "__main__":
66 tt = Tooltips()
67 main()
There are other methods that can be used with tooltips. I will
just list them with a brief description of what they do.
tooltips.enable()
Enable a disabled set of tooltips.
tooltips.disable()
Disable an enabled set of tooltips.
tooltips.set_delay(delay)
Sets how many milliseconds you have to hold your pointer over
the widget before the tooltip will pop up. The default is 500 milliseconds
(half a second).
And that's all the methods associated with tooltips. More than
you'll ever want to know :-)
TextView widgets and their associated
objects (TextBuffers,
TextMarks, TextIters,
TextTags and TextTagTables)
provide a powerful framework for multiline text editing.
A TextBuffer (see Section 13.3, “Text Buffers”) contains the text which is displayed by
one or more TextView widgets.
Within GTK+ 2.0, text is encoded in UTF-8 which means that one
character may be encoded as multiple bytes. Within a
TextBuffer it is necessary to differentiate between
the character counts (called offsets) and the byte counts (called
indexes).
TextIters provide a volatile representation
of the position in a TextBuffer between two
characters. TextIters are valid until the number of
characters in the TextBuffer changes; i.e. any time
characters are inserted or deleted from a TextBuffer
all TextIters will become invalid.
TextIters are the primary way to specify locations in
a TextBuffer for manipulating text.
TextMarks are provided to allow
preservation of TextBuffer positions across buffer
modifications. A mark is like a TextIter (see Section 13.4, “Text Iters”) in that it represents a position between
two characters in a TextBuffer) but if the text
surrounding the mark is deleted the mark remains where the deleted text once
was. Likewise, if text is inserted at the mark the mark ends up either to
the left or right of the inserted text depending on the gravity of the mark
- right gravity leaves the mark to the right of the inserted text while left
gravity leaves it to the left. TextMarks (see Section 13.5, “Text Marks”) may be named or anonymous if not given a
name. Each TextBuffer has two predefined named
TextMarks (see Section 13.5, “Text Marks”)
called insert and
selection_bound. These refer to the insertion point
and the boundary of the selection (the selection is between the
insert and the selection_bound
marks).
TextTags (see Section 13.6.1, “Text Tags”) are objects that specify a set of attributes
that can be applied to a range of text in a
TextBuffer. Each TextBuffer
has a TextTagTable (see Section 13.6.2, “Text Tag Tables”) which contains the tags that are
available in that buffer. TextTagTables can be shared
between TextBuffers to provide
commonality. TextTags are generally used to change
the appearance of a range of text but can also be used to prevent a range of
text from being edited.
The show() method arranges to display the
widget by using the realize() and
map() methods.
The hide() method arranges to remove the
widget from the display and also unmaps it using the
unmap() method if necessary.
The show_all() and
hide_all() methods arrange to show or hide the
widget and all its children.
The realize() method arranges to allocate
resources to the widget including its window.
The unrealize() method releases the
widget window and other resources. Unrealizing a widget will also hide and
unmap it.
The map() method arranges to allocate
space on the display for the widget; this only applies to widgets that need
to be handled by the window manager. Mapping a widget will also cause it to
be realized if necessary.
The unmap() method removes a widget from
the display and will also hide it if necessary.
The Calendar widget is an effective way
to display and retrieve monthly date related information. It is a very
simple widget to create and work with.
Creating a gtk.Calendar widget is as
simple as:
calendar = gtk.Calendar()
The calendar will display the current month and year by
default.
There might be times where you need to change a lot of
information within this widget and the following methods allow you to make
multiple changes to a Calendar widget without the
user seeing multiple on-screen updates.
calendar.freeze()
calendar.thaw()
They work just like the freeze/thaw methods of every other
widget.
The Calendar widget has a few options
that allow you to change the way the widget both looks and operates by using
the method:
calendar.display_options(flags)
The flags argument can be formed by
combining either of the following five options using the logical bitwise OR
(|) operation:
CALENDAR_SHOW_HEADING
this option specifies that the month and year should be
shown when drawing the calendar.
CALENDAR_SHOW_DAY_NAMES
this option specifies that the three letter descriptions
should be displayed for each day (e.g. Mon,Tue, etc.).
CALENDAR_NO_MONTH_CHANGE
this option states that the user should not and can not
change the currently displayed month. This can be good if you only need to
display a particular month such as if you are displaying 12 calendar widgets
for every month in a particular year.
CALENDAR_SHOW_WEEK_NUMBERS
this option specifies that the number for each week should
be displayed down the left side of the calendar. (e.g. Jan 1 = Week 1,Dec 31
= Week 52).
CALENDAR_WEEK_START_MONDAY
this option states that the calender week will start on
Monday instead of Sunday which is the default. This only affects the order
in which days are displayed from left to right. Note that in PyGTK 2.4 and
above this option is deprecated.
The following methods are used to set the the currently
displayed date:
result = calendar.select_month(month, year)
calendar.select_day(day)
The return value from the
select_month() method is a boolean value indicating
whether the selection was successful.
With the select_day() method the
specified day number is selected within the current month, if that is
possible. A day value of 0 will deselect any current selection.
In addition to having a day selected, any number of days in the
month may be "marked". A marked day is highlighted within the calendar
display. The following methods are provided to manipulate marked
days:
result = calendar.mark_day(day)
result = calendar.unmark_day(day)
calendar.clear_marks()
mark_day() and
unmark_day() return a boolean indicating whether
the method was successful. Note that marks are persistent across month and
year changes.
The final Calendar widget method is used
to retrieve the currently selected date, month and/or year.
year, month, day = calendar.get_date()
The Calendar widget can generate a number
of signals indicating date selection and change. The names of these signals
are self explanatory, and are:
In GTK+ version 2.0, the signal system has been moved from GTK
to GLib. We won't go into details about the extensions which the GLib 2.0
signal system has relative to the GTK+ 1.2 signal system. The differences
should not be apparent to PyGTK users.
Before we look in detail at helloworld.py, we'll
discuss signals and callbacks. GTK+ is an event driven toolkit, which means
it will sleep in gtk.main() until an event occurs and
control is passed to the appropriate function.
This passing of control is done using the idea of "signals".
(Note that these signals are not the same as the Unix system signals, and
are not implemented using them, although the terminology is almost
identical.) When an event occurs, such as the press of a mouse button, the
appropriate signal will be "emitted" by the widget that was pressed. This is
how GTK+ does most of its useful work. There are signals that all widgets
inherit, such as "destroy", and there are signals that are widget specific,
such as "toggled" on a toggle button.
To make a button perform an action, we set up a signal handler
to catch these signals and call the appropriate function. This is done by
using a GtkWidget (from the
GObject class) method such as:
where object is the GtkWidget instance
which will be emitting the signal, and the first argument
name is a string containing the name of the signal you
wish to catch. The second argument, func, is the
function you wish to be called when it is caught, and the third,
func_data, the data you wish to pass to this function.
The method returns a handler_id that can be used
to disconnect or block the handler.
The function specified in the second argument is called a
"callback function", and should generally be of the form:
def callback_func(widget, callback_data):
where the first argument will be a pointer to the
widget that emitted the signal, and the second
(callback_data) a pointer to the data given as the last
argument to the connect() method as shown above.
If the callback function is an object method then it will have
the general form:
def callback_meth(self, widget, callback_data):
where self is the object instance
invoking the method. This is the form used in the helloworld.py
example program.
Note
The above form for a signal callback function declaration
is only a general guide, as some widget specific signals generate different
calling parameters.
where object is usually a widget.
connect_object() allows the PyGTK widget methods
that only take a single argument (self) to be used as
signal handlers.
pygtk2tutorial/sec-WidgetsWithoutWindows.html 0100644 0001172 0000167 00000005110 10227356760 020674 0 ustar finlay fcf 5.2. Widgets Without Windows
The following widgets do not have an associated window. If you
want to capture events, you'll have to use the
EventBox. See the section on the
EventBox widget.
PyGTK 2.0 is a set of Python modules which provide a Python
interface to GTK+ 2.X. Throughout the rest of this document PyGTK refers to
the 2.X version of PyGTK and GTK and GTK+ refer to the 2.X version of GTK+.
The primary web site for PyGTK is www.pygtk.org. The primary author of
PyGTK is:
who is assisted by the developers listed in the AUTHORS file in the
PyGTK distribution and the PyGTK community.
Python is an extensible, object-oriented interpreted programming
language which is provided with a rich set of modules providing access to a
large number of operating system services, internet services (such as HTML,
XML, FTP, etc.), graphics (including OpenGL, TK, etc.), string handling
functions, mail services (IMAP, SMTP, POP3, etc.), multimedia (audio, JPEG)
and cryptographic services. In addition there are many other modules
available from third parties providing many other services. Python is
licensed under terms similar to the LGPL license and is available for Linux,
Unix , Windows and Macintosh operating systems. More information on Python
is available at www.python.org . The primary Author of Python is:
GTK (GIMP Toolkit) is a library for creating graphical user
interfaces. It is licensed using the LGPL license, so you can develop open
software, free software, or even commercial non-free software using GTK
without having to spend anything for licenses or royalties.
It's called the GIMP toolkit because it was originally written for
developing the GNU Image Manipulation Program (GIMP), but GTK has now been
used in a large number of software projects, including the GNU Network
Object Model Environment (GNOME) project. GTK is built on top of GDK (GIMP
Drawing Kit) which is basically a wrapper around the low-level functions for
accessing the underlying windowing functions (Xlib in the case of the X
windows system). The primary authors of GTK are:
GTK is essentially an object oriented application programmers
interface (API). Although written completely in C, it is implemented using
the idea of classes and callback functions (pointers to functions).
There is also a third component called GLib which contains a few
replacements for some standard calls, as well as some additional functions
for handling linked lists, etc. The replacement functions are used to
increase GTK's portability, as some of the functions implemented here are
not available or are nonstandard on other unixes such as
g_strerror(). Some also contain enhancements to the
libc versions, such as g_malloc that has enhanced
debugging utilities.
In version 2.0, GLib has picked up the type system which forms the
foundation for GTK's class hierarchy, the signal system which is used
throughout GTK, a thread API which abstracts the different native thread
APIs of the various platforms and a facility for loading modules.
As the last component, GTK uses the Pango library for
internationalized text output.
This tutorial describes the Python interface to GTK+ and is based
on the GTK+ 2.0 Tutorial written by Tony Gale and Ian Main. This tutorial
attempts to document as much as possible of PyGTK, but is by no means
complete.
This tutorial assumes some understanding of Python, and how to
create and run Python programs. If you are not familiar with Python, please
read the Python
Tutorial first. This tutorial does not assume an understanding of
GTK; if you are learning PyGTK to learn GTK, please comment on how you found
this tutorial, and what you had trouble with. This tutorial does not
describe how to compile or install Python, GTK+ or PyGTK.
This tutorial is based on:
GTK+ 2.0 through GTK+ 2.4
Python 2.2
PyGTK 2.0 through PyGTK 2.4
The examples were written and tested on a RedHat 9.0 system.
This document is a "work in progress". Please look for updates on
www.pygtk.org.
I would very much like to hear of any problems you have learning PyGTK
from this document, and would appreciate input as to how it may be improved.
Please see the section on Contributing for further information. If you
encounter bugs please file a bug at bugzilla.gnome.org against the pygtk
project. The information at www.pygtk.org about
Bugzilla may help.
The PyGTK website (www.pygtk.org) contains other resources
useful for learning about PyGTK including a link to the extensive FAQ and other articles and
tutorials and an active maillist and IRC channel (see www.pygtk.org for
details).
1.1. Exploring PyGTK
Johan Dahlin has written a small Python program (pygtkconsole.py)
that runs on Linux and allows interactive exploration of PyGTK. The program
provides a Python-like interactive interpreter interface that communicates
with a child process that executes that entered commands. The PyGTK modules
are loaded by default. A simple example session is:
This creates a window containing a button which prints a message
('Hello, World!') when clicked. This program makes it easy to try out
various GTK widgets and PyGTK interfaces.
I also use a program that was developed by Brian McErlean as
ActiveState
recipe 65109 with some mods to make it run with PyGTK 2.X. I call it
gpython.py. It
works similar to the pygtkconsole.py
program.
Note
Both of these programs are known not to work on Microsoft
Windows because they rely on Unix specific interfaces.
You may be wondering how you make GTK do useful work when in
main(). Well, you have several options. Using the
following gobject module function you can create a timeout function that
will be called every "interval" milliseconds.
The interval argument is the number of
milliseconds between calls to your function. The
function argument is the callback you wish to have
called. Any arguments after the second are passed to the function as
data. The return value is an integer "source_id" which may be used to stop
the timeout by calling:
gobject.source_remove(source_id)
You may also stop the timeout callback function from being
called again by returning zero or FALSE from your
callback. If you want your callback to be called again, it should return
TRUE.
Your callback should look something like this:
def timeout_callback(...):
The number of arguments to the callback should match the number
of data arguments specified in timeout_add().
A TextBuffer is the core component of the
PyGTK text editing system. It contains the text, the
TextTags in a TextTagTable and
the TextMarks which together describe how the text is
to be displayed and allow a user to interactively modify the text and text
display. As noted in the previous section a
TextBuffer is associated with one or more
TextViews which display the
TextBuffer contents.
A TextBuffer can be created automatically
when a TextView is created or it can be created with
the function:
textbuffer = TextBuffer(table=None)
where table is a
TextTagTable. If table is not
specified (or is None) a
TextTagTable will be created for the
TextBuffer.
There are a large number of methods that can be used to:
insert and remove text from a buffer
create, delete and manipulate marks
manipulate the cursor and the selection
create, apply and remove tags
specify and manipulate
TextIters
get status information
13.3.1. TextBuffer Status Information
You can retrieve the number of lines in a
textbuffer by using the method:
line_count = textbuffer.get_line_count()
Likewise you can get the number of characters in the
textbuffer using:
char_count = textbuffer.get_char_count()
When the textbuffer contents are changed
the modified flag in the textbuffer is set. The status of the modified flag
can be retrieved using the method:
modified = textbuffer.get_modified()
If the program saves the contents of the textbuffer the
following method can be used to reset the modified flag:
textbuffer.set_modified(setting)
13.3.2. Creating TextIters
A TextIter is used to specify a location
within a TextBuffer between two
characters. TextBuffer methods that manipulate text
use TextIters to specify where the method is to be
applied. TextIters have a large number of methods
that will be described in the >TextIters
section.
The basic TextBuffer methods used to
create TextIters
are:
iter = textbuffer.get_iter_at_offset(char_offset)
iter = textbuffer_get_iter_at_line(line_number)
iter = textbuffer.get_iter_at_line_offset(line_number, line_offset)
iter = textbuffer.get_iter_at_mark(mark)
get_iter_at_offset() creates an iter
that is just after char_offset chars from the start
of the textbuffer.
get_iter_at_line() creates an iter that
is just before the first character in
line_number.
get_iter_at_line_offset() creates an
iter that is just after the line_offset character in
line_number.
get_iter_at_mark() creates an iter that
is at the same position as the given mark.
The following methods create one or more
TextIters at specific buffer locations:
get_start_iter() creates an iter that
is just before the first character in the textbuffer.
get_end_iter() creates an iter that is
just after the last character in the textbuffer.
get_bounds() creates a tuple of two
iters that are just before the first character and just after the last
character in the textbuffer respectively.
get_selection_bounds() creates a tuple
of two iters that have the same location as the
insert and selection_bound
marks in the textbuffer.
13.3.3. Text Insertion, Retrieval and Deletion
The text in a TextBuffer can be set
using the method:
textbuffer.set_text(text)
This method replaces the current contents of textbuffer with
text.
The most general method to insert characters in a textbuffer
is:
textbuffer.insert(iter, text)
which inserts text at the textbuffer
location specified by iter.
If you want to simulate the insertion of text by an
interactive user use the method:
result = textbuffer.insert_interactive(iter, text, default_editable)
which inserts text in the textbuffer at
the location specified by iter but only if the
location is editable (i.e. does not have a tag that specifies the text is
non-editable) and the default_editable value is
TRUE. The result indicates whether the text was
inserted.
default_editable indicates the
editability of text that doesn't have a tag affecting editability;
default_editable is usually determined by a call to
the TextViewget_editable()
method.
Other methods that insert text are:
textbuffer.insert_at_cursor(text)
result = textbuffer.insert_at_cursor_interactive(text, default_editable)
textbuffer.insert_range(iter, start, end)
result = textbuffer.insert_range_interactive(iter, start, end, default_editable)
insert_at_cursor() is a convenience
method that inserts text at the current cursor
(insert) location.
insert_range() copies text, pixbufs and
tags between start and end
from a TextBuffer (if different from textbuffer the
tag table must be the same) and inserts the copy into textbuffer at
iter's location.
The interactive versions of these methods operate the same way
except they will only insert if the location is editable.
Finally, text can be inserted and have tags applied at the
same time using the methods:
insert_with_tags() inserts the
text in the textbuffer at the location specified by
iter and applies the given tags.
insert_with_tags_by_name() does that
same thing but allows you to specify the tags using the tag name.
The text in a textbuffer can be deleted by using the
methods:
textbuffer.delete(start, end)
result = textbuffer.delete_interactive(start, end, default_editable)
delete() removes the text between the
start and endTextIter locations in textbuffer.
delete_interactive() removes all the
editable (as determined by the applicable text tags and the
default_editable argument) text between
start and end.
You can retrieve a copy of the text from a textbuffer by using
the methods:
text = textbuffer.get_text(start, end, include_hidden_chars=TRUE)
text = textbuffer.get_slice(start, end, include_hidden_chars=TRUE)
get_text() returns a copy of the
text in textbuffer between
start and end; undisplayed
text is excluded if include_hidden_chars is
FALSE. Characters which represent embedded images or
widgets are excluded.
get_slice() is the same as
get_text() except that the returned
text includes a 0xFFFC character for each embedded
image or widget.
13.3.4. TextMarks
TextMarks are similar to
TextIters in that they specify a location in a
TextBuffer between two characters. However,
TextMarks maintain their location information across
buffer modifications. The TextMark methods will be
described in the TextMarks section.
A textbuffer contains two built-in marks: the
insert (cursor) mark and the
selection_bound mark. The
insert mark is the default location for the insertion
of text and the selection_bound mark combines with
the insert mark to define a selection range.
The built-in marks can be retrieved by using the
methods:
The insert and
selection_bound marks can be placed simultaneously at
a location by using the method:
textbuffer.place_cursor(where)
where is a textiter specifying the
location. The place_cursor() method is needed to
avoid temporarily creating a selection if the marks were moved
individually.
TextMarks are created by using the
method:
mark = textbuffer.create_mark(mark_name, where, left_gravity=FALSE)
where mark_name is the name assigned to
the created mark (can be None to create an anonymous mark),
where is the textiter specifying the location of the
mark in textbuffer and left_gravity indicates where
the mark will be located after text is inserted at the mark (left if
TRUE or right if FALSE).
A mark can be moved in the textbuffer by using the
methods:
TextTags contain one or more attributes
(e.g. foreground and background colors, font, editability) that can be
applied to one or more ranges of text in a
TextBuffer. The attributes that can be specified by
TextTag properties will be described in Section 13.6.1, “Text Tags”.
A TextTag can be created with attributes
and installed in the TextTagTable of a
TextBuffer by using the convenience method:
tag = textbuffer.create_tag(name=None, attr1=val1, attr2=val2, ...)
where name is a string specifying the
name of the tag or None if the tag is an anonymous tag
and the keyword-value pairs specify the attributes that the tag will
have. See the TextTag> section for information on
what attributes can be set by the TextTag
properties.
A tag can be applied to a range of text in a textbuffer by
using the methods:
tag is the tag to be applied to the text.
name is the name of the tag to be applied.
start and end are textiters
that specify the range of text that the tag is to be
applied to.
A tag can be removed from a range of text by using the
methods:
All tags for a range of text can be removed by using the
method:
textbuffer.remove_all_tags(start, end)
13.3.6. Inserting Images and Widgets
In addition to text a TextBuffer can
contain pixbuf images and an anchor location for widgets. A widget can be
added to a TextView at an anchor location. A
different widget can be added in each TextView which
displays a buffer with an anchor.
A pixbuf can be inserted by using the method:
textbuffer.insert_pixbuf(iter, pixbuf)
where iter specifies the location in the
textbuffer to insert the
pixbuf. The image will be counted as one character
and will be represented in a get_slice() return
(but left out of a get_text() return) as the
Unicode character "0xFFFC".
A GTK+ widget can be inserted in a
TextView at a buffer location specified with a
TextChildAnchor. The
TextChildAnchor will be counted as one character and
represented as "0xFFFC" similar to a pixbuf.
The TextChildAnchor can be created and
inserted in the buffer by using the convenience method:
anchor = text_buffer.create_child_anchor(iter)
where iter is the location for the
child_anchor.
A TextChildAnchor can also be created
and inserted in two operations as:
where the child widget is placed in
which_window at the location specified by
xpos and ypos.
which_window indicates in which of the windows that
make up the TextView the widget is to be
placed:
The Layout container is similar to the
Fixed container except that it implements an infinite
(where infinity is less than 2^32) scrolling area. The X window system has a
limitation where windows can be at most 32767 pixels wide or tall. The
Layout container gets around this limitation by doing
some exotic stuff using window and bit gravities, so that you can have
smooth scrolling even when you have many child widgets in your scrolling
area.
As you can see, you can optionally specify the
Adjustment objects (see Chapter 7, Adjustments) that the Layout
widget will use for its scrolling. If you don't specify the
Adjustment objects, new ones will be created.
You can add and move widgets in the
Layout container using the following two
methods:
The layout.py example
program creates three buttons and puts them in a layout widget. when a
button is clicked, it is moved to a random location in the layout.
Figure 10.3, “Layout Example” illustrates the starting display of the
program:
We've almost seen all there is to see of the button widget. It's
pretty simple. You can use the gtk.Button() function to
create a button with a label by passing a string parameter, or to create a
blank button by not specifying a label string. It's then up to you to pack a
label or pixmap into this new button. To do this, create a new box, and then
pack your objects into this box using the usual
pack_start() method, and then use the
add() method to pack the box into the
button.
The function to create a button is:
button = gtk.Button(label=None, stock=None)
if label text is specified it is used as the text on the button.
If stock is specified it is used to select a stock icon and text label for
the button. The stock items are:
The buttons.py program
provides an example of using gtk.Button() to create a
button with an image and a label in it. I've broken up the code to create a
box from the rest so you can use it in your programs. There are further
examples of using images later in the tutorial. Figure 6.1, “Button with Pixmap and Label”
shows the window containing a button with both a pixmap and a label:
1 #!/usr/bin/env python
2
3 # example-start buttons buttons.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 # Create a new hbox with an image and a label packed into it
10 # and return the box.
11
12 def xpm_label_box(parent, xpm_filename, label_text):
13 # Create box for xpm and label
14 box1 = gtk.HBox(False, 0)
15 box1.set_border_width(2)
16
17 # Now on to the image stuff
18 image = gtk.Image()
19 image.set_from_file(xpm_filename)
20
21 # Create a label for the button
22 label = gtk.Label(label_text)
23
24 # Pack the pixmap and label into the box
25 box1.pack_start(image, False, False, 3)
26 box1.pack_start(label, False, False, 3)
27
28 image.show()
29 label.show()
30 return box1
31
32 class Buttons:
33 # Our usual callback method
34 def callback(self, widget, data=None):
35 print "Hello again - %s was pressed" % data
36
37 def __init__(self):
38 # Create a new window
39 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
40
41 self.window.set_title("Image'd Buttons!")
42
43 # It's a good idea to do this for all windows.
44 self.window.connect("destroy", lambda wid: gtk.main_quit())
45 self.window.connect("delete_event", lambda a1,a2:gtk.main_quit())
46
47 # Sets the border width of the window.
48 self.window.set_border_width(10)
49
50 # Create a new button
51 button = gtk.Button()
52
53 # Connect the "clicked" signal of the button to our callback
54 button.connect("clicked", self.callback, "cool button")
55
56 # This calls our box creating function
57 box1 = xpm_label_box(self.window, "info.xpm", "cool button")
58
59 # Pack and show all our widgets
60 button.add(box1)
61
62 box1.show()
63 button.show()
64
65 self.window.add(button)
66 self.window.show()
67
68 def main():
69 gtk.main()
70 return 0
71
72 if __name__ == "__main__":
73 Buttons()
74 main()
Lines 12-34 define the xpm_label_box()
helper function which creates a horizontal box with a border width of 2
(lines 14-15), populates it with an image (lines 22-23) and a label (line
26).
Lines 36-70 define the Buttons class.
Lines 41-70 define the instance initialization method which creates a window
(line 43), sets the title (line 45), connects the "delete_event" and
"destroy" signals (lines 48-49). Line 55 creates the button without a label.
Its "clicked" signal gets connected to the
callback() method in line 58. The
xpm_label_box() function is called in line 61 to create
the image and label to put in the button in line 64.
The xpm_label_box() function could be used
to pack xpm's and labels into any widget that can be a container.
The Button widget has the following signals:
pressed - emitted when pointer button is pressed within Button widget
released - emitted when pointer button is released within Button widget
clicked - emitted when pointer button is pressed and then released within Button widget
enter - emitted when pointer enters Button widget
leave - emitted when pointer leaves Button widget
The file selection widget is a quick and simple way to display a
File dialog box. It comes complete with Ok,
Cancel, and Help buttons, a
great way to cut down on programming time.
To create a new file selection box use:
filesel = gtk.FileSelection(title=None)
To set the filename, for example to bring up a specific
directory, or give a default filename, use this method:
filesel.set_filename(filename)
To grab the filename text that the user has entered or clicked
on, use this method:
filename = filesel.get_filename()
There are also references to the widgets contained within the file
selection widget. These are the filesel attributes:
Most likely you will want to use the
ok_button, cancel_button, and
help_button attributes to connect their widget
signals to callbacks.
The filesel.py example
program illustrates the use of the FileSelection widget. As you will see,
there is nothing much to creating a file selection widget. While in this
example the Help button appears on the screen, it
does nothing as there is not a signal attached to it. Figure 9.14, “File Selection Example” shows the resulting display:
Figure 9.14. File Selection Example
The source code for filesel.py is:
1 #!/usr/bin/env python
2
3 # example filesel.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class FileSelectionExample:
10 # Get the selected filename and print it to the console
11 def file_ok_sel(self, w):
12 print "%s" % self.filew.get_filename()
13
14 def destroy(self, widget):
15 gtk.main_quit()
16
17 def __init__(self):
18 # Create a new file selection widget
19 self.filew = gtk.FileSelection("File selection")
20
21 self.filew.connect("destroy", self.destroy)
22 # Connect the ok_button to file_ok_sel method
23 self.filew.ok_button.connect("clicked", self.file_ok_sel)
24
25 # Connect the cancel_button to destroy the widget
26 self.filew.cancel_button.connect("clicked",
27 lambda w: self.filew.destroy())
28
29 # Lets set the filename, as if this were a save dialog,
30 # and we are giving a default filename
31 self.filew.set_filename("penguin.png")
32
33 self.filew.show()
34
35 def main():
36 gtk.main()
37 return 0
38
39 if __name__ == "__main__":
40 FileSelectionExample()
41 main()
Labels are used a lot in GTK, and are
relatively simple. Labels emit no signals as they do
not have an associated X window. If you need to catch signals, or do
clipping, place it inside a EventBox (see Section 10.1, “The EventBox”) widget or a Button
(see Section 6.1, “Normal Buttons”) widget.
To create a new label, use:
label = gtk.Label(str)
The sole argument is the string you wish the label to
display. To change the label's text after creation, use the
method:
label.set_text(str)
label is the label you created
previously, and str is the new string. The space
needed for the new string will be automatically adjusted if needed. You can
produce multi-line labels by putting line breaks in the label string.
To retrieve the current string, use:
str = label.get_text()
label is the label you've created, and
str is the return string. The
label text can be justified using:
label.set_justify(jtype)
Values for jtype are:
JUSTIFY_LEFT # the default
JUSTIFY_RIGHT
JUSTIFY_CENTER
JUSTIFY_FILL # does not work
The label widget is also capable of line wrapping the text
automatically. This can be activated using:
label.set_line_wrap(wrap)
The wrap argument takes a
TRUE or FALSE value.
If you want your label underlined, then you can set a pattern on
the label:
label.set_pattern(pattern)
The pattern argument indicates how the
underlining should look. It consists of a string of underscore and space
characters. An underscore indicates that the corresponding character in the
label should be underlined. For example, the string "__
__" would underline the first two characters and fourth and fifth
characters. If you simply want to have an underlined accelerator
("mnemonic") in your label, you should use
set_text_with_mnemonic(str), not
set_pattern().
The label.py program is a
short example to illustrate these methods. This example makes use of the
Frame (see Section 10.5, “Frames”) widget
to better demonstrate the label styles. You can ignore this for now as the
Frame widget is explained later on.
In GTK+ 2.0, label text can contain markup for font and other
text attribute changes, and labels may be selectable (for copy-and-paste).
These advanced features won't be explained here.
Now that we know the theory behind this, let's clarify by
walking through the example helloworld.py
program.
Lines 9-76 define the HelloWorld class
that contains all the callbacks as object methods and the object instance
initialization method. Let's examine the callback methods.
Lines 13-14 define the hello() callback
method that will be called when the button is "clicked". When called the
method, prints "Hello World" to the console. We ignore the object instance,
the widget and the data parameters in this example, but most callbacks use
them. The data is defined with a default value of
None because PyGTK will not pass a data value if it is
not included in the connect() call; this would
trigger an error since the callback is expecting three parameters and may
receive only two. Defining a default value of None allows the callback to be
called with two or three parameters without error. In this case the data
parameter could have been left out since the
hello() method will always be called with just two
parameters (never called with user data). The next example will use the
data argument to tell us which button was
pressed.
The next callback (lines 16-26) is a bit special. The
"delete_event" occurs when the window manager sends this event to the
application. We have a choice here as to what to do about these events. We
can ignore them, make some sort of response, or simply quit the
application.
The value you return in this callback lets GTK+ know what action
to take. By returning TRUE, we let it know that we don't want to have the
"destroy" signal emitted, keeping our application running. By returning
FALSE, we ask that "destroy" be emitted, which in turn will call our
"destroy" signal handler. Note the comments have been removed for
clarity.
The destroy() callback method (lines
28-30) causes the program to quit by calling
gtk.main_quit() . This function tells GTK+ that it is
to exit from gtk.main() when control is returned to
it.
def destroy(widget, data=None):
print "destroy signal occurred"
gtk.main_quit()
Lines 32-71 define the HelloWorld object
instance initialization method __init__() that creates
the window and widgets used by the program.
Line 34 creates a new window, but it is not displayed until we
direct GTK+ to show the window near the end of our program. The window
reference is saved in an object instance attribute (self.window) for later
access.
self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
Lines 41 and 46 illustrate two examples of connecting a signal
handler to an object, in this case, the window. Here, the
"delete_event" and "destroy" signals are caught. The first is emitted when
we use the window manager to kill the window, or when we use the
GtkWidgetdestroy() method
call. The second is emitted when, in the "delete_event" handler, we return
FALSE.
Line 49 sets an attribute of a container object (in this case
the window) to have a blank area along the inside of it
10 pixels wide where no widgets will be placed. There are other similar
methods that we will look at in Chapter 18, Setting Widget Attributes
self.window.set_border_width(10)
Line 52 creates a new button and saves a reference to it in
self.button. The button will have the label "Hello World"
when displayed.
self.button = gtk.Button("Hello World")
In line 57 we attach a signal handler to the button so when it
emits the "clicked" signal, our hello() callback
method is called. We are not passing any data to
hello() so we just pass None as
the data. Obviously, the "clicked" signal is emitted when we click the
button with our mouse pointer. The user data parameter value
None is not required and could be removed. The callback
would then be called with one less parameter.
self.button.connect("clicked", self.hello, None)
We are also going to use this button to exit our program. Line
62 illustrates how the "destroy" signal may come from either the window
manager, or from our program. When the button is "clicked", same as above,
it calls the hello() callback first, and then the
following one in the order they are set up. You may have as many callbacks
as you need, and all will be executed in the order you connected
them.
Since we want to use the GtkWidgetdestroy() method that accepts one argument (the
widget to be destroyed - in this case the window), we use
the connect_object() method and pass it the
reference to the window. The connect_object()
method arranges to pass the window as the first
callback argument instead of the button.
When the gtk.Widgetdestroy() method is called it will cause the
"destroy" signal to be emitted from the window which will in turn cause the
HelloWorlddestroy() method
to be called to end the program.
Line 65 is a packing call, which will be explained in depth
later on in Chapter 4, Packing Widgets . But it is fairly
easy to understand. It simply tells GTK+ that the button is to be placed in
the window where it will be displayed. Note that a GTK+ container can only
contain one widget. There are other widgets, described later, that are
designed to layout multiple widgets in various ways.
self.window.add(self.button)
Now we have everything set up the way we want it to be. With all
the signal handlers in place, and the button placed in the window where it
should be, we ask GTK+ (lines 66 and 69) to "show" the widgets on the screen.
The window widget is shown last so the whole window will pop up at once
rather than seeing the window pop up, and then the button forming inside of
it. Although with such a simple example, you'd never notice.
self.button.show()
self.window.show()
Lines 73-75 define the main() method
which calls the gtk.main() function
def main(self):
gtk.main()
Lines 80-82 allow the program to run automatically if called
directly or as an argument of the python interpreter. Line 81 creates an
instance of the HelloWorld class and saves a
reference to it in the hello variable. Line 82 calls the
HelloWorld class main()
method to start the GTK+ event processing loop.
if __name__ == "__main__":
hello = HelloWorld()
hello.main()
Now, when we click the mouse button on a GTK+ button, the widget
emits a "clicked" signal. In order for us to use this information, our
program sets up a signal handler to catch that signal, which dispatches the
function of our choice. In our example, when the button we created is
"clicked", the hello() method is called with the
None argument, and then the next handler for this signal
is called. The next handler calls the widget
destroy() function with the window as its argument
thereby causing the window to emit the "destroy" signal, which is caught,
and calls our HelloWorlddestroy() method
Another course of events is to use the window manager to kill
the window, which will cause the "delete_event" to be emitted. This will
call our "delete_event" handler. If we return TRUE here,
the window will be left as is and nothing will happen. Returning
FALSE will cause GTK+ to emit the "destroy" signal that
causes the HelloWorld "destroy" callback to be
called, exiting GTK.
The GTK+ signals we have already discussed are for high-level
actions, such as a menu item being selected. However, sometimes it is useful
to learn about lower-level occurrences, such as the mouse being moved, or a
key being pressed. There are also GTK+ signals corresponding to these
low-level events. The handlers for these signals have an extra parameter
which is a gtk.gdk.Event object containing
information about the event. For instance, motion event handlers are passed
a gtk.gdk.Event object containing EventMotion
information which has (in part) attributes like:
type
window
time
x
y
...
state
...
window is the window in which the event
occurred.
x and y give the
coordinates of the event.
type will be set to the event type, in
this case MOTION_NOTIFY. The types (in module gtk.gdk)
are:
NOTHING a special code to indicate a null event.
DELETE the window manager has requested that the toplevel window be
hidden or destroyed, usually when the user clicks on a special
icon in the title bar.
DESTROY the window has been destroyed.
EXPOSE all or part of the window has become visible and needs to be
redrawn.
MOTION_NOTIFY the pointer (usually a mouse) has moved.
BUTTON_PRESS a mouse button has been pressed.
_2BUTTON_PRESS a mouse button has been double-clicked (clicked twice within
a short period of time). Note that each click also generates a
BUTTON_PRESS event.
_3BUTTON_PRESS a mouse button has been clicked 3 times in a short period of
time. Note that each click also generates a BUTTON_PRESS event.
BUTTON_RELEASE a mouse button has been released.
KEY_PRESS a key has been pressed.
KEY_RELEASE a key has been released.
ENTER_NOTIFY the pointer has entered the window.
LEAVE_NOTIFY the pointer has left the window.
FOCUS_CHANGE the keyboard focus has entered or left the window.
CONFIGURE the size, position or stacking order of the window has changed.
Note that GTK+ discards these events for GDK_WINDOW_CHILD windows.
MAP the window has been mapped.
UNMAP the window has been unmapped.
PROPERTY_NOTIFY a property on the window has been changed or deleted.
SELECTION_CLEAR the application has lost ownership of a selection.
SELECTION_REQUEST another application has requested a selection.
SELECTION_NOTIFY a selection has been received.
PROXIMITY_IN an input device has moved into contact with a sensing surface
(e.g. a touchscreen or graphics tablet).
PROXIMITY_OUT an input device has moved out of contact with a sensing surface.
DRAG_ENTER the mouse has entered the window while a drag is in progress.
DRAG_LEAVE the mouse has left the window while a drag is in progress.
DRAG_MOTION the mouse has moved in the window while a drag is in progress.
DRAG_STATUS the status of the drag operation initiated by the window has changed.
DROP_START a drop operation onto the window has started.
DROP_FINISHED the drop operation initiated by the window has completed.
CLIENT_EVENT a message has been received from another application.
VISIBILITY_NOTIFY the window visibility status has changed.
NO_EXPOSE indicates that the source region was completely available when parts
of a drawable were copied. This is not very useful.
SCROLL ?
WINDOW_STATE ?
SETTING ?
state specifies the modifier state when
the event occurred (that is, it specifies which
modifier keys and mouse buttons were pressed). It is the bitwise
OR of some of the following (in module gtk.gdk):
As for other signals, to determine what happens when an event
occurs we call the connect() method. But we also
need to let GTK+ know which events we want to be notified about. To do this,
we call the method:
widget.set_events(events)
The events argument specifies the events
we are interested in. It is the bitwise OR of constants
that specify different types of events. For future reference, the event
types (in module gtk.gdk) are:
There are a few subtle points that have to be observed when
calling the set_events() method. First, it must be
called before the X window for a PyGTK widget is created. In practical
terms, this means you should call it immediately after creating the widget.
Second, the widget must be one which will be realized with an associated X
window. For efficiency, many widget types do not have their own window, but
draw in their parent's window. These widgets include:
To capture events for these widgets, you need to use an
EventBox widget. See Section 10.1, “The EventBox” widget for details.
The event attributes that are set by PyGTK for each type of
event are:
every event type
window
send_event
NOTHING
DELETE
DESTROY # no additional attributes
EXPOSE area
count
MOTION_NOTIFY time
x
y
pressure
xtilt
ytilt
state
is_hint
source
deviceid
x_root
y_root
BUTTON_PRESS
_2BUTTON_PRESS
_3BUTTON_PRESS
BUTTON_RELEASE time
x
y
pressure
xtilt
ytilt
state
button
source
deviceid
x_root
y_root
KEY_PRESS
KEY_RELEASE time
state
keyval
string
ENTER_NOTIFY
LEAVE_NOTIFY subwindow
time
x
y
x_root
y_root
mode
detail
focus
state
FOCUS_CHANGE _in
CONFIGURE x
y
width
height
MAP
UNMAP # no additional attributes
PROPERTY_NOTIFY atom
time
state
SELECTION_CLEAR
SELECTION_REQUEST
SELECTION_NOTIFY selection
target
property
requestor
time
PROXIMITY_IN
PROXIMITY_OUT time
source
deviceid
DRAG_ENTER
DRAG_LEAVE
DRAG_MOTION
DRAG_STATUS
DROP_START
DROP_FINISHED context
time
x_root
y_root
CLIENT_EVENT message_type
data_format
data
VISIBILTY_NOTIFY state
NO_EXPOSE # no additional attributes
24.2.1. Scribble - Event Handling
For our drawing program, we want to know when the mouse button
is pressed and when the mouse is moved, so we specify
POINTER_MOTION_MASK and
BUTTON_PRESS_MASK. We also want to know when we need to
redraw our window, so we specify EXPOSURE_MASK. Although
we want to be notified via a Configure event when our window size changes,
we don't have to specify the corresponding STRUCTURE_MASK
flag, because it is automatically specified for all windows.
It turns out, however, that there is a problem with just
specifying POINTER_MOTION_MASK. This will cause the
server to add a new motion event to the event queue every time the user
moves the mouse. Imagine that it takes us 0.1 seconds to handle a motion
event, but the X server queues a new motion event every 0.05 seconds. We
will soon get way behind the users drawing. If the user draws for 5 seconds,
it will take us another 5 seconds to catch up after they release the mouse
button! What we would like is to only get one motion event for each event we
process. The way to do this is to specify
POINTER_MOTION_HINT_MASK.
When we specify POINTER_MOTION_HINT_MASK, the
server sends us a motion event the first time the pointer moves after
entering our window, or after a button press or release event. Subsequent
motion events will be suppressed until we explicitly ask for the position of
the pointer using the gtk.gdk.Window method:
x, y, mask = window.get_pointer()
window is a
gtk.gdk.Window object. x and
y are the coordinates of the pointer and
mask is the modifier mask to detect which keys are
pressed. (There is a gtk.Widget method,
get_pointer() which provides the same information
as the gtk.gdk.Window get_pointer() method but it
does not return the mask information)
TreeViewColumns and
CellRenderers work together to display a column of
data in a TreeView. The
TreeViewColumn provides the column title and a
vertical space for the CellRenderers to render a
portion of the data from the TreeView data store. A
CellRenderer handles the rendering of each row and
column data within the confines of the
TreeViewColumn. A
TreeViewColumn can contain more than one
CellRenderer to provide a row display similar to an
HBox. A common use of multiple
CellRenderers is to combine a
CellRendererPixbuf and a
CellRendererText in one column.
The application of each CellRenderer is
indicated with a different background color: yellow for the
CellRendererPixbuf, cyan for one
CellRendererText, and pink for the other
CellRendererText. Note that the
CellRendererPixbuf and the first
CellRendererText are in the same column headed by the
"Pixbuf and Text" header. The background color of the
CellRendererText rendering "Print File" is the
default color to show the application area in a single row.
The type of CellRenderer needed is
determined by the type of tree model data display required; PyGTK has three
pre-defined CellRenderers:
CellRendererPixbuf
renders pixbuf images either created by the program or
one of the stock items.
CellRendererText
renders text strings, and numbers that can be converted
to a string (including ints, floats, booleans).
CellRendererToggle
renders a boolean value as a toggle button or a radio
button
14.4.3. CellRenderer Properties
The properties of a CellRenderer determine
how the data will be rendered:
"mode"
Read-Write
The editable mode of the
CellRenderer. One of:
gtk.CELL_RENDERER_MODE_INERT,
gtk.CELL_RENDERER_MODE_ACTIVATABLE or
gtk.CELL_RENDERER_MODE_EDITABLE
"visible"
Read-Write
If TRUE the cell is displayed
"xalign"
Read-Write
The fraction of free space to the left
of the cell in the range 0.0 to 1.0.
"yalign"
Read-Write
The fraction of free space above the
cell in the range 0.0 to 1.0.
"xpad"
Read-Write
The amount of padding to the left and right of the
cell.
"ypad"
Read-Write
The amount of padding above and below cell.
"width"
Read-Write
The fixed width of the cell.
"height"
Read-Write
The fixed height of the cell.
"is-expander"
Read-Write
If TRUE the row has children
"is-expanded"
Read-Write
If TRUE the row has children and it is
expanded to show the children.
"cell-background"
Write
The background color of the cell as a string.
"cell-background-gdk"
Read-Write
The background color of the cell as a
gtk.gdk.Color.
"cell-background-set"
Read-Write
If TRUE the cell background color
is set by this cellrenderer
The above properties are available for all
CellRenderer subclasses. The individual
CellRenderer types also have their own
properties.
The CellRendererPixbuf has these
properties:
"pixbuf"
Read-Write
The pixbuf to render - overridden by "stock-id"
"pixbuf-expander-open"
Read-Write
Pixbuf for open expander.
"pixbuf-expander-closed"
Read-Write
Pixbuf for closed expander.
"stock-id"
Read-Write
The stock ID of the stock icon to render
"stock-size"
Read-Write
The size of the rendered icon
"stock-detail"
Read-Write
Render detail to pass to the theme engine
The CellRendererText has a large number of
properties mostly dealing with style specification:
"text"
Read-Write
Text to render
"markup"
Read-Write
Marked up text to render.
"attributes"
Read-Write
A list of style attributes to apply to the text of the
renderer.
"background"
Write
Background color as a string
"foreground"
Write
Foreground color as a string
"background-gdk"
Read-Write
Background color as a
gtk.gdk.Color
"foreground-gdk"
Read-Write
Foreground color as a
gtk.gdk.Color
"font"
Read-Write
Font description as a string
"font-desc"
Read-Write
Font description as a
pango.FontDescription
"family"
Read-Write
Name of the font family, e.g. Sans, Helvetica, Times,
Monospace
"style"
Read-Write
Font style
"variant"
Read-Write
Font variant
"weight"
Read-Write
Font weight
"stretch"
Read-Write
Font stretch
"size"
Read-Write
Font size
"size-points"
Read-Write
Font size in points
"scale"
Read-Write
Font scaling factor
"editable"
Read-Write
If TRUE the text can be modified by the
user
"strikethrough"
Read-Write
If TRUE strike through the text
"underline"
Read-Write
Style of underline for this text
"rise"
Read-Write
Offset of text above the baseline (below the baseline if
rise is negative)
"language"
Read-Write
The language this text is in, as an ISO code. Pango can use
this as a hint when rendering the text. If you don't understand this parameter,
you probably don't need it. GTK+ 2.4 and above.
"single-paragraph-mode"
Read-Write
If TRUE, keep all text in a single
paragraph. GTK+ 2.4 and above.
"background-set"
Read-Write
If TRUE apply the background
color
"foreground-set"
Read-Write
If TRUE apply the foreground
color
"family-set"
Read-Write
If TRUE apply the font
family
"style-set"
Read-Write
If TRUE apply the font
style
"variant-set"
Read-Write
If TRUE apply the font
variant
"weight-set"
Read-Write
If TRUE apply the font
weight
"stretch-set"
Read-Write
If TRUE apply the font
stretch
"size-set"
Read-Write
If TRUE apply the font
size
"scale-set"
Read-Write
If TRUE scale the font
"editable-set"
Read-Write
If TRUE apply the text
editability
"strikethrough-set"
Read-Write
If TRUE apply the
strikethrough
"underline-set"
Read-Write
If TRUE apply the text
underlining
"rise-set"
Read-Write
If TRUE apply the
rise
"language-set"
Read-Write
If TRUE apply the
language used to render the text. GTK+ 2.4 and above.
Almost every CellRendererText property has
an associated boolean property (with the "-set" suffix) that indicates if
the property is to be applied. This allows you to set a property globally
and selectively enable and disable its application.
The CellRendererToggle has the following
properties:
"activatable"
Read-Write
If TRUE, the toggle button can be
activated
"active"
Read-Write
If TRUE, the button is active.
"radio"
Read-Write
If TRUE, draw the toggle button as a
radio button
"inconsistent"
Read-Write
If TRUE, the button is in an
inconsistent state. GTK+ 2.2 and above.
The properties can be set for all rows by using the
gobject.set_property() method. See the treeviewcolumn.py
program for an example using this method.
14.4.4. CellRenderer Attributes
An attribute associates a tree model column with a
CellRenderer property; the
CellRenderer sets the property from the row's column
value before rendering the cell. This allows you to customize the cell
display using tree model data. An attribute can be added to the current set
by using:
sets, for each row, the text from the first column, the
background color from the second column and the horizontal padding from the
fourth column. See the treeviewcolumn.py
program for an example using these methods.
The attributes of a CellRenderer can be
cleared using:
treeviewcolumn.clear_attributes(cell_renderer)
14.4.5. Cell Data Function
If setting attributes is not sufficient for your needs you can
set a function to be called for each row to set the properties for that
CellRenderer using:
where column is the
TreeViewColumn containing
cell_renderer, tree_model is
the data store and iter is a
TreeIter pointing at a row in
tree_model. user_data is the
value of data that was passed to
set_cell_data_func().
In func you set whatever properties you
want on cell_renderer. For example the following code
fragment sets the text property to display PyGTK objects as an ID
string.
Another use of a cell data function is to control the formatting
of a numerical text display e.g. a float value. A
CellRendererText will display and automatically
convert a float to a string but with a default format "%f".
With cell data functions you can even generate the cell data for
the columns from external data. For example the filelisting.py
program uses a ListStore with just one column that
holds a list of file names. The TreeView displays
columns that include a pixbuf, the file name and the file's size, mode and
time of last change. The data is generated by the following cell data
functions:
These cell data functions retrieve the file information using
the name, extract the needed data and set the cell 'text' or 'pixbuf'
property with the data. Figure 14.4, “File Listing Example Using Cell Data Functions” shows the example
program in action:
Figure 14.4. File Listing Example Using Cell Data Functions
14.4.6. CellRendererText Markup
A CellRendererText can use Pango markup (by
setting the "markup" property) instead of a plain text string to encode
various text attributes and provide a rich text display with multiple font
style changes. See the Pango
Markup reference in the PyGTK Reference Manual
for details on the Pango markup language.
The following code fragment illustrates the use of the
"markup" property:
If you create pango markup on the fly you have to be careful to
replace the characters that are special to the markup language: "<",
">", "&". The Python library function
cgi.escape() can do these basic conversions.
14.4.7. Editable Text Cells
CellRendererText cells can be made editable
to allow a user to edit the contents of the cell that is selected by
clicking it or pressing one of the Return,
Enter, Space or Shift+Space
keys. A CellRendererText is made editable for all
rows by setting its "editable" property to TRUE as
follows:
cellrenderertext.set_property('editable', True)
Individual cells can be set editable by adding an attribute to the
TreeViewColumn using the
CellRendererText similar to:
which sets the "editable" property to the value contained in the
third column of the data store.
Once the cell editing completes, your application should handle
the "edited" signal to retrieve the new text and set the associated data
store value. Otherwise the cell value reverts to its original value. The
signature of the "edited" signal handler is:
def edited_cb(cell, path, new_text, user_data)
where cell is the
CellRendererText, path is the
tree path (as a string) to the row containing the edited cell,
new_text is the edited text and
user_data is context data. Since the
TreeModel is needed to use
path to set new_text in the
data store you probably want to pass the TreeModel as
user_data in the connect()
method:
CellRendererToggle buttons can be made
activatable by setting the "activatable" property to
TRUE. Similar to editable
CellRendererText cells the "activatable" property can
be set for the entire CellRendererToggle set of cells
using the set_property() method or for individual
cells by adding an attribute to the TreeViewColumn
containing the CellRendererToggle.
You should connect to the "toggled" signal to get notification
of user clicks on the toggle buttons so that your application can change the
value in the data store. For example:
where path is the tree path, as a string,
pointing to the row containing the toggle that was clicked. You should pass
the TreeModel and possibly the column index as part
of user_data to provide the necessary context for
setting the data store values. For example, your application can toggle the
data store value as follows:
If your application wants to display the toggle buttons as radio
buttons and have only one be set, it will have to scan the data store to
deactivate the active radio button and then set the toggled button. For
example:
def toggled_cb(cell, path, user_data):
model, column = user_data
for row in model:
row[column] = False
model[path][column] = True
return
takes the lazy approach of setting all data store values to
FALSE before setting the value to TRUE
for the row specified by path.
14.4.9. Editable and Activatable Cell Example Program
The cellrenderer.py
program illustrates the application of editable
CellRendererText and activatable
CellRendererToggle cells in a
TreeStore.
1 #!/usr/bin/env python
2 # vim: ts=4:sw=4:tw=78:nowrap
3 """ Demonstration using editable and activatable CellRenderers """
4 import pygtk
5 pygtk.require("2.0")
6 import gtk, gobject
7
8 tasks = {
9 "Buy groceries": "Go to Asda after work",
10 "Do some programming": "Remember to update your software",
11 "Power up systems": "Turn on the client but leave the server",
12 "Watch some tv": "Remember to catch ER"
13 }
14
15 class GUI_Controller:
16 """ The GUI class is the controller for our application """
17 def __init__(self):
18 # setup the main window
19 self.root = gtk.Window(type=gtk.WINDOW_TOPLEVEL)
20 self.root.set_title("CellRenderer Example")
21 self.root.connect("destroy", self.destroy_cb)
22 # Get the model and attach it to the view
23 self.mdl = Store.get_model()
24 self.view = Display.make_view( self.mdl )
25 # Add our view into the main window
26 self.root.add(self.view)
27 self.root.show_all()
28 return
29 def destroy_cb(self, *kw):
30 """ Destroy callback to shutdown the app """
31 gtk.main_quit()
32 return
33 def run(self):
34 """ run is called to set off the GTK mainloop """
35 gtk.main()
36 return
37
38 class InfoModel:
39 """ The model class holds the information we want to display """
40 def __init__(self):
41 """ Sets up and populates our gtk.TreeStore """
42 self.tree_store = gtk.TreeStore( gobject.TYPE_STRING,
43 gobject.TYPE_BOOLEAN )
44 # places the global people data into the list
45 # we form a simple tree.
46 for item in tasks.keys():
47 parent = self.tree_store.append( None, (item, None) )
48 self.tree_store.append( parent, (tasks[item],None) )
49 return
50 def get_model(self):
51 """ Returns the model """
52 if self.tree_store:
53 return self.tree_store
54 else:
55 return None
56
57 class DisplayModel:
58 """ Displays the Info_Model model in a view """
59 def make_view( self, model ):
60 """ Form a view for the Tree Model """
61 self.view = gtk.TreeView( model )
62 # setup the text cell renderer and allows these
63 # cells to be edited.
64 self.renderer = gtk.CellRendererText()
65 self.renderer.set_property( 'editable', True )
66 self.renderer.connect( 'edited', self.col0_edited_cb, model )
67
68 # The toggle cellrenderer is setup and we allow it to be
69 # changed (toggled) by the user.
70 self.renderer1 = gtk.CellRendererToggle()
71 self.renderer1.set_property('activatable', True)
72 self.renderer1.connect( 'toggled', self.col1_toggled_cb, model ) 73
74 # Connect column0 of the display with column 0 in our list model 75 # The renderer will then display whatever is in column 0 of
76 # our model .
77 self.column0 = gtk.TreeViewColumn("Name", self.renderer, text=0) 78
79 # The columns active state is attached to the second column
80 # in the model. So when the model says True then the button
81 # will show as active e.g on.
82 self.column1 = gtk.TreeViewColumn("Complete", self.renderer1 )
83 self.column1.add_attribute( self.renderer1, "active", 1)
84 self.view.append_column( self.column0 )
85 self.view.append_column( self.column1 )
86 return self.view
87 def col0_edited_cb( self, cell, path, new_text, model ):
88 """
89 Called when a text cell is edited. It puts the new text
90 in the model so that it is displayed properly.
91 """
92 print "Change '%s' to '%s'" % (model[path][0], new_text)
93 model[path][0] = new_text
94 return
95 def col1_toggled_cb( self, cell, path, model ):
96 """
97 Sets the toggled state on the toggle button to true or false.
98 """
99 model[path][1] = not model[path][1]
100 print "Toggle '%s' to: %s" % (model[path][0], model[path][1],)
101 return
102
103 if __name__ == '__main__':
104 Store = InfoModel()
105 Display = DisplayModel()
106 myGUI = GUI_Controller()
107 myGUI.run()
The program provides editable cells in the first column and
activatable cells in the second column. Lines 64-66 create an editable
CellRendererText and connect the "edited" signal to
the col0_edited_cb() callback (lines 87-94) that
changes the appropriate row column value in the
TreeStore. Likewise lines 70-72 create an activatable
CellRendererToggle and connect the "toggled" signal
to the col1_toggled_cb() callback (lines 95-101) to
change the appropriate row value. When an editable or activatable cell is
changed, a message is printed to indicate what the change was.
TextIters represent a position between two
characters in a TextBuffer.
TextIters are usually created by using a
TextBuffer method. TextIters
are invalidated when the number of characters in a
TextBuffer is changed (except for the
TextIter that is used for the insertion or
deletion). Inserting or deleting pixbufs or anchors also counts as a
TextIter invalidating change.
There are a large number of methods associated with a
TextIter object. They are grouped together in the
following sections by similar function.
13.4.1. TextIter Attributes
The TextBuffer that contains the
TextIter can be retrieved using the method:
buffer = iter.get_buffer()
The following methods can be used to get the location of the
TextIter in the
TextBuffer:
offset = iter.get_offset() # returns offset in buffer of iter
line_number = iter.get_line() # returns number of line at iter
line_offset = iter.get_line_offset() # returns iter offset in line
numchars = iter.get_chars_in_line() # returns number of chars in line
13.4.2. Text Attributes at a TextIter
The PangoLanguage used at a given iter
location in the TextBuffer is obtained by calling the
method:
language = iter.get_language()
The more general method used to get the text attributes at a
TextIter's location is:
result = iter.get_attributes(values)
where result indicates whether the given
values (TextAttributes object)
were modified. The given values are obtained by using
the TextView method:
values = textview.get_default_attributes()
The following attributes are accessible from a
TextAttributes object (not implemented in PyGTK <=
1.99.15):
bg_color
background color
fg_color
foreground color
bg_stipple
background stipple bitmap
fg_stipple
foreground stipple bitmap
rise
offset of text above baseline
underline
style of underline
strikethrough
whether text is strikethrough
draw_bg
TRUE if some tags affect the drawing of the background
justification
style of justification
direction
which direction the text runs
font
PangoFontDescription in use
font_scale
scale of the font in use
left_margin
location of left margin
right_margin
location of right margin
pixels_above_lines
pixels spacing above a line
pixels_below_lines
pixel spacing below a line
pixels_inside_wrap
pixel spacing between wrapped lines
tabs
PangoTabArray in use
wrap_mode
mode of wrap in use
language
PangoLanguage in use
invisible
whether text is invisible (not implemented in GTK+ 2.0)
bg_full_height
whether background is fit to full line height
editable
whether the text is editable
realized
text is realized
pad1
pad2
pad3
pad4
13.4.3. Copying a TextIter
A TextIter can be duplicated using the
method:
iter_copy = iter.copy()
13.4.4. Retrieving Text and Objects
Various amounts of text and TextBuffer
objects can be retrieved from a TextBuffer using the
following methods:
char = iter.get_char() # returns char or 0 if at end of buffer
text = start.get_slice(end) # returns the text between start and end iters
text = start.get_text(end) # returns the text between start and end iters
pixbuf = iter.get_pixbuf() # returns the pixbuf at the location (or None)
anchor = iter.get_child_anchor() # returns the child anchor (or None)
mark_list = iter.get_marks() # returns a list of marks
tag_list = iter.get_toggled_tags() # returns a list of tags that are toggled on or off
tag_list = iter.get_tags() # returns a prioritized list of tags
13.4.5. Checking Conditions at a TextIter
Tag conditions at the TextIter location
can be checked using the following methods:
result = iter.begins_tag(tag=None) # TRUE if tag is toggled on at iter
result = iter.ends_tag(tag=None) # TRUE if tag is toggled off at iter
result = iter.toggles_tag(tag=None) # TRUE if tag is toggled on or off at iter
result = iter.has_tag(tag) # TRUE if tag is active at iter
These methods return TRUE if the given
tag satisfies the condition at
iter. If the tag is None for
the first three methods then the result is TRUE if any
tag satisfies the condition at iter.
The following methods indicate whether the text at the
TextIter location is editable or allows text
insertion:
result = iter.editable()
result = iter.can_insert(default_editability)
The editable() method indicates whether
the iter is in an editable range of text while the
can_insert() method indicates whether text can be
inserted at iter considering the default editability
of the TextView, TextBuffer
and applicable tags. The default_editability is
usually determined by calling the method:
default_editability = textview.get_editable()
The equivalence of two TextIters can be
determined with the method:
are_equal = lhs.equal(rhs)
Two TextIters can be compared with the
method:
result = lhs.compare(rhs)
result will be: -1 if
lhs is less than rhs; 0 if
lhs equals rhs; and, 1 if
lhs is greater than rhs.
To determine whether a TextIter is
located between two given TextIters use the
method:
result = iter.in_range(start, end)
result is TRUE if
iter is between start and
end. Note: start and
end must be in ascending order. This can be
guaranteed using the method:
first.order(second)
which will reorder the TextIter offsets
so that first is before
second.
13.4.6. Checking Location in Text
The location of a TextIter with respect
to the text in a TextBuffer can be determined by the
following methods:
result = iter.starts_word()
result = iter.ends_word()
result = iter.inside_word()
result = iter.starts_sentence()
result = iter.ends_sentence()
result = iter.inside_sentence()
result = starts_line()
result = iter.ends_line()
result returns TRUE if
the TextIter is at the given text location. These
methods are somewhat self-explanatory. The definition of the text components
and their boundaries is determined by the language used at the
TextIter. Note that a line is a collection of
sentences similar to a paragraph.
The following methods can be used to determine if a
TextIter is at the start or end of the
TextBuffer:
result = iter.is_start()
result = iter.is_end()
result is TRUE if the
TextIter is at the start or end of the
TextBuffer.
Since a TextBuffer may
contain multiple characters which are effectively viewed as one cursor
position (e.g. carriage return-linefeed combination or letter with an accent
mark) it's possible that a TextIter could be in a
location which is not a cursor position. The following method indicates
whether a TextIter is at a cursor position:
result = iter.is_cursor_position()
13.4.7. Moving Through Text
TextIters can be moved through a
TextBuffer in various text unit strides. The
definition of the text units is set by the
PangoLanguage in use at the
TextIter location. The basic methods are:
result = iter.forward_char() # forward by one character
result = iter.backward_char() # backward by one character
result = iter.forward_word_end() # forward to the end of the word
result = iter.backward_word_start() # backward to the start of the word
result = iter.forward_sentence_end() # forward to the end of the sentence
result = iter.backward_sentence_start() # backward to the start of the sentence
result = iter.forward_line() # forward to the start of the next line
result = iter.backward_line() # backward to the start of the previous line
result = iter.forward_to_line_end() # forward to the end of the line
result = iter.forward_cursor_position() # forward by one cursor position
result = iter.backward_cursor_position() # forward by one cursor position
result is TRUE if the
TextIter was moved and FALSE if
the TextIter is at the start or end of the
TextBuffer.
All of the above methods (except
forward_to_line_end()) have corresponding methods
that take a count (that can be positive or negative) to move the
TextIter in multiple text unit strides:
result = iter.forward_chars(count)
result = iter.backward_chars(count)
result = iter.forward_word_ends(count)
result = iter.backward_word_starts(count)
result = iter.forward_sentence_ends(count)
result = iter.backward_sentence_starts(count)
result = iter.forward_lines(count)
result = iter.backward_lines(count)
result = iter.forward_cursor_positions(count)
result = iter.backward_cursor_positions(count)
13.4.8. Moving to a Specific Location
A TextIter can be moved to a specific
location in the TextBuffer using the
following methods:
iter.set_offset(char_offset) # move to given character offset
iter.set_line(line_number) # move to start of given line
iter.set_line_offset(char_on_line) # move to given character offset in current line
iter.forward_to_end() # move to end of the buffer
In addition, a TextIter can be moved to
a location where a tag is toggled on or off by using the methods:
result = iter.forward_to_tag_toggle(tag)
result = iter.backward_to_tag_taoggle(tag)
result is TRUE if the
TextIter was moved to a new location where
tag is toggled. If tag is
None then the TextIter will be
moved to the next location where any tag is toggled.
13.4.9. Searching in Text
A search for a string in a TextBuffer is
done using the methods:
The return value is a tuple containing
TextIters that indicate the location of the first
character of the match and the first character after the match.
str is the character string to be located.
flags modifies the conditions of the search;
flag values can be:
gtk.TEXT_SEARCH_VISIBLE_ONLY # invisible characters are ignored
gtk.TEXT_SEARCH_TEXT_ONLY # pixbufs and child anchors are ignored
limit is an optional
TextIter that bounds the search range.
TreeSelections are objects that manage
selections in a TreeView. When a
TreeView is created a
TreeSelection is automatically created as well. The
TreeSelection can be retrieved from the TreeView
using the method:
treeselection = treeview.get_selection()
You can retrieve the TreeView associated
with a TreeSelection by calling the method:
treeview = treeselection.get_treeview()
14.8.2. TreeSelection Modes
The TreeSelection supports the following
selection modes:
gtk.SELECTION_NONE
No selection is allowed.
gtk.SELECTION_SINGLE
A single selection is allowed by clicking.
gtk.SELECTION_BROWSE
A single selection allowed by browsing with the pointer.
gtk.SELECTION_MULTIPLE
Multiple items can be selected at once.
You can retrieve the current selection mode by calling the
method:
mode = treeselection.get_mode()
The mode can be set using:
treeselection.set_mode(mode)
where mode is one of the above selection
modes.
14.8.3. Retrieving the Selection
The method to use to retrieve the selection depends on the
current selection mode. If the selection mode is
gtk.SELECTION_SINGLE or
gtk.SELECTION_BROWSE, you should use the following
method:
(model, iter) = treeselection.get_selected()
that returns a 2-tuple containing model,
the TreeModel used by the
TreeView associated with
treeselection and iter, a
TreeIter pointing at the selected row. If no row is
selected then iter is None. If the
selection mode is gtk.SELECTION_MULTIPLE a TypeError
exception is raised.
If you have a TreeView using the
gtk.SELECTION_MULTIPLE selection mode then you should use
the method:
that returns a 2-tuple containing the tree model and a list of
the tree paths of the selected rows. This method is not available in PyGTK
2.0 so you'll have to use a helper function to retrieve the list by
using:
treeselection.selected_foreach(func, data=None)
where func is a function that is called
on each selected row with data. The signature of
func is:
def func(model, path, iter, data)
where model is the
TreeModel, path is the tree
path of the selected row and iter is a
TreeIter pointing at the selected row.
This method can be used to simulate the
get_selected_row() method as follows:
where selection is the
TreeSelection, model is the
TreeModel used with the
TreeView associated with
selection, path is the tree
path of the selected row, is_selected is
TRUE if the row is currently selected and
user_data is
data. func should return
TRUE if the row's selection status should be
toggled.
Setting a select function is useful if:
you want to control the selection or unselection of a row
based on some additional context information. You will need to indicate in
some way that the selection change can't be made and perhaps why. For
example, you can visually differentiate the row or pop up a
MessageDialog.
you need to maintain your own list of selected or
unselected rows though this can also be done by connecting to the "changed"
signal but with more effort.
you want to do some additional processing before a row is
selected or unselected. For example change the look of the row or modify the
row data.
14.8.5. Selecting and Unselecting Rows
You can change the selection programmatically using the
following methods:
These methods select or unselect a single row that is specified
by either path, a tree path or
iter, a TreeIter pointing at
the row. The following methods select or unselect several rows at
once:
The select_all() method requires that
the selection mode be gtk.SELECTION_MULTIPLE as does the
select_range() method. The
unselect_all() and
unselect_range() methods will function with any
selection mode. Note that the unselect_all() method
is not available in PyGTK 2.0
You can check if a row is selected by using one of the
methods:
result = treeselection.path_is_selected(path)
result = treeselection.iter_is_selected(iter)
that return TRUE if the row specified by
path or iter is currently
selected. You can retrieve a count of the number of selected rows using the
method:
count = treeselection.count_selected_rows()
This method is not available in PyGTK 2.0 so you'll have to
simulate it using the selected_foreach() method
similar to the simulation of the
get_selected_rows() method in Section 21.2, “Retrieving the Selection”. For example:
Because of this flexibility, packing boxes in GTK can be
confusing at first. There are a lot of options, and it's not immediately
obvious how they all fit together. In the end, however, there are basically
five different styles. Figure 4.1, “Packing: Five Variations” illustrates the result
of running the program packbox.py with an
argument of 1:
Figure 4.1. Packing: Five Variations
Each line contains one horizontal box (hbox) with several
buttons. The call to pack is shorthand for the call to pack each of the
buttons into the hbox. Each of the buttons is packed into the hbox the same
way (i.e., same arguments to the pack_start()
method).
This is an example of the pack_start() method.
box.pack_start(child, expand, fill, padding)
box is the box you are packing the object
into; the first argument is the child object to be
packed. The objects will all be buttons for now, so we'll be packing buttons
into boxes.
The expand argument to
pack_start() and
pack_end() controls whether the widgets are laid
out in the box to fill in all the extra space in the box so the box is
expanded to fill the area allotted to it (True); or the
box is shrunk to just fit the widgets (False). Setting
expand to False will allow you to do right and left
justification of your widgets. Otherwise, they will all expand to fit into
the box, and the same effect could be achieved by using only one of
pack_start() or
pack_end().
The fill argument to the pack methods
control whether the extra space is allocated to the objects themselves
(True), or as extra padding in the box around these
objects (False). It only has an effect if the expand
argument is also True.
Python allows a method or function to be defined with default
argument values and argument keywords. Throughout this tutorial I'll show
the definition of the functions and methods with defaults and keywords
bolded as applicable. For example the pack_start()
method is defined as:
The homogeneous argument to
gtk.HBox() and gtk.VBox() controls
whether each object in the box has the same size (i.e., the same width in an
hbox, or the same height in a vbox). If it is set, the pack routines
function essentially as if the expand argument was always turned on.
What's the difference between spacing
(set when the box is created) and padding (set when
elements are packed)? Spacing is added between objects, and padding is added
on either side of an object. Figure 4.2, “Packing with Spacing and Padding” illustrates the
difference; pass an argument of 2 to packbox.py :
Figure 4.2. Packing with Spacing and Padding
Figure 4.3, “Packing with pack_end()” illustrates the use of the
pack_end() method (pass an argument of 3 to packbox.py). The label
"end" is packed with the pack_end() method. It will
stick to the right edge of the window when the window is resized.
Radio buttons are similar to check buttons except they are grouped
so that only one may be selected/depressed at a time. This is good for
places in your application where you need to select from a short list of
options.
Creating a new radio button is done with this call:
You'll notice the extra argument to this call. Radio buttons
require a group to operate properly. The first call
to gtk.RadioButton() should pass
None as the first argument and a new radio button group
will be created with the new radio button as its only member.
To add more radio buttons to a group, pass in a reference to a
radio button in group in subsequent calls to
gtk.RadioButton().
If a label argument is specified the text
will be parsed for '_'-prefixed mnemonic characters.
It is also a good idea to explicitly set which button should be
the default depressed button with:
radio_button.set_active(is_active)
This is described in the section on toggle buttons, and works in
exactly the same way. Once the radio buttons are grouped together, only one
of the group may be active at a time. If the user clicks on one radio
button, and then on another, the first radio button will first emit a
"toggled" signal (to report becoming inactive), and then the second will
emit its "toggled" signal (to report becoming active).
The code is fairly straight forward. Lines 63-64 make the
"close" button the default widget so that pressing the "Enter" key when the
window is active causes the "close" button to emit the "clicked"
signal.
The Range widget class is fairly
complicated internally, but, like all the "base class" widgets, most of its
complexity is only interesting if you want to hack on it. Also, almost all
of the methods and signals it defines are only really used in writing
derived widgets. There are, however, a few useful methods that will work on
all range widgets.
8.3.1. Setting the Update Policy
The "update policy" of a range widget defines at what points
during user interaction it will change the value field of its
Adjustment and emit the "value_changed" signal on
this Adjustment. The update policies are:
UPDATE_CONTINUOUS
This is the default. The "value_changed" signal is
emitted continuously, i.e., whenever the slider is moved by even the tiniest
amount.
UPDATE_DISCONTINUOUS
The "value_changed" signal is only emitted once the
slider has stopped moving and the user has released the mouse button.
UPDATE_DELAYED
The "value_changed" signal is emitted when the user
releases the mouse button, or if the slider stops moving for a short period
of time.
The update policy of a range widget can be set by passing it
to this method:
range.set_update_policy(policy)
8.3.2. Getting and Setting Adjustments
Getting and setting the adjustment for a range widget "on the
fly" is done, predictably, with:
The get_adjustment() method returns a
reference to the adjustment to which range is
connected.
The set_adjustment() method does
absolutely nothing if you pass it the adjustment that
range is already using, regardless of whether you
changed any of its fields or not. If you pass it a new
Adjustment, it will unreference the old one if it
exists (possibly destroying it), connect the appropriate signals to the new
one, and will recalculate the size and/or position of the slider and redraw
if necessary. As mentioned in the section on adjustments, if you wish to
reuse the same Adjustment, when you modify its values
directly, you should emit the "changed" signal on it, like this:
adjustment.emit("changed")
pygtk2tutorial/sec-UpgradedHelloWorld.html 0100644 0001172 0000167 00000016143 10227356757 020074 0 ustar finlay fcf 3.2. An Upgraded Hello World
1 #!/usr/bin/env python
2
3 # example helloworld2.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class HelloWorld2:
10
11 # Our new improved callback. The data passed to this method
12 # is printed to stdout.
13 def callback(self, widget, data):
14 print "Hello again - %s was pressed" % data
15
16 # another callback
17 def delete_event(self, widget, event, data=None):
18 gtk.main_quit()
19 return False
20
21 def __init__(self):
22 # Create a new window
23 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
24
25 # This is a new call, which just sets the title of our
26 # new window to "Hello Buttons!"
27 self.window.set_title("Hello Buttons!")
28
29 # Here we just set a handler for delete_event that immediately
30 # exits GTK.
31 self.window.connect("delete_event", self.delete_event)
32
33 # Sets the border width of the window.
34 self.window.set_border_width(10)
35
36 # We create a box to pack widgets into. This is described in detail
37 # in the "packing" section. The box is not really visible, it
38 # is just used as a tool to arrange widgets.
39 self.box1 = gtk.HBox(False, 0)
40
41 # Put the box into the main window.
42 self.window.add(self.box1)
43
44 # Creates a new button with the label "Button 1".
45 self.button1 = gtk.Button("Button 1")
46
47 # Now when the button is clicked, we call the "callback" method
48 # with a pointer to "button 1" as its argument
49 self.button1.connect("clicked", self.callback, "button 1")
50
51 # Instead of add(), we pack this button into the invisible
52 # box, which has been packed into the window.
53 self.box1.pack_start(self.button1, True, True, 0)
54
55 # Always remember this step, this tells GTK that our preparation for
56 # this button is complete, and it can now be displayed.
57 self.button1.show()
58
59 # Do these same steps again to create a second button
60 self.button2 = gtk.Button("Button 2")
61
62 # Call the same callback method with a different argument,
63 # passing a pointer to "button 2" instead.
64 self.button2.connect("clicked", self.callback, "button 2")
65
66 self.box1.pack_start(self.button2, True, True, 0)
67
68 # The order in which we show the buttons is not really important, but I
69 # recommend showing the window last, so it all pops up at once.
70 self.button2.show()
71 self.box1.show()
72 self.window.show()
73
74 def main():
75 gtk.main()
76
77 if __name__ == "__main__":
78 hello = HelloWorld2()
79 main()
You'll notice this time there is no easy way to exit the
program, you have to use your window manager or command line to kill it. A
good exercise for the reader would be to insert a third "Quit" button that
will exit the program. You may also wish to play with the options to
pack_start() while reading the next section. Try
resizing the window, and observe the behavior.
A short commentary on the code differences from the first
helloworld program is in order.
As noted above there is no "destroy" event handler in the
upgraded helloworld.
Lines 13-14 define a callback method which is similar to the
hello() callback in the first helloworld. The
difference is that the callback prints a message including data passed
in.
Line 39 creates a horizontal box
(gtk.HBox) to hold the two buttons that are created
in lines 45 and 60. Line 42 adds the horizontal box to the window
container.
Lines 49 and 64 connect the callback()
method to the "clicked" signal of the buttons. Each button sets up a
different string to be passed to the callback()
method when invoked.
Lines 53 and 66 pack the buttons into the horizontal box. Lines
57 and 70 ask GTK to display the buttons.
Lines 71-72 ask GTK to display the box and the window
respectively.
where title is the string to be used as
the column header label, and cell_renderer is the
first CellRenderer to pack in the column. Additional
arguments that are passed to the constructor are keyword values (in the
format attribute=column) that set attributes on
cell_renderer. For example:
creates a TreeViewColumn with the
CellRendererText cell retrieving its text from the
first column of the tree model and the text color from the second
column.
14.5.2. Managing CellRenderers
A CellRenderer can be added to a
TreeViewColumn using one of the methods:
pack_start() and
pack_end() add cell to the
start or end, respectively, of the TreeViewColumn. If
expand is TRUE,
cell will share in any available extra space
allocated by the TreeViewColumn.
The get_cell_renderers() method:
cell_list = treeviewcolumn.get_cell_renderers()
returns a list of all the CellRenderers
in the column.
The clear() method removes all the
CellRenderer attributes from the
TreeViewColumn:
treeviewcolumn.clear()
There are a large number of other methods available for a
TreeViewColumn - mostly dealing with setting and
getting properties. See the PyGTK Reference
Manual for more information on the
TreeViewColumn properties. The capability of using
the built-in sorting facility is set using the method:
treeviewcolumn.set_sort_column_id(sort_column_id)
sets sort_column_id as the tree model
sort column ID to use when sorting the TreeView
display. This method also sets the "clickable" property of the column that
allows the user to click on the column header to activate the sorting. When
the user clicks on the column header, the
TreeViewColumn sort column ID is set as the
TreeModel sort column ID and the
TreeModel rows are resorted using the associated sort
comparison function. The automatic sorting facility also toggles the sort
order of the column and manages the display of the sort indicator. See Section 14.2.9, “Sorting TreeModel Rows” for more information on sort
column IDs and sort comparison functions. Typically when using a
ListStore or TreeStore the
default sort column ID (i.e. the column index) of the
TreeModel column associated with the
TreeViewColumn is set as the
TreeViewColumn sort column ID.
If you use the TreeViewColumn headers for
sorting by using the set_sort_column_id() method,
you don't need to use the TreeSortableset_sort_column_id() method.
You can track the sorting operations or use a header click for
your own purposes by connecting to the "clicked" signal of the
TreeView column. The callback function should be
defined as:
Ruler widgets are used to indicate the
location of the mouse pointer in a given window. A window can have a
horizontal ruler spanning across the width and a vertical ruler spanning
down the height. A small triangular indicator on the ruler shows the exact
location of the pointer relative to the ruler.
A ruler must first be created. Horizontal and vertical rulers are
created using the functions:
Once a ruler is created, we can define the unit of measurement.
Units of measure for rulers can be PIXELS,
INCHES or CENTIMETERS. This is set
using the method:
ruler.set_metric(metric)
The default measure is PIXELS.
ruler.set_metric(gtk.PIXELS)
Other important characteristics of a ruler are how to mark the
units of scale and where the position indicator is initially placed. These
are set for a ruler using the method:
ruler.set_range(lower, upper, position, max_size)
The lower and
upper arguments define the extent of the ruler, and
max_size is the largest possible number that will be
displayed. Position defines the initial position of
the pointer indicator within the ruler.
A vertical ruler can span an 800 pixel wide window thus:
vruler.set_range(0, 800, 0, 800)
The markings displayed on the ruler will be from 0 to 800, with
a number for every 100 pixels. If instead we wanted the ruler to range from
7 to 16, we would code:
vruler.set_range(7, 16, 0, 20)
The indicator on the ruler is a small triangular mark that
indicates the position of the pointer relative to the ruler. If the ruler is
used to follow the mouse pointer, the "motion_notify_event" signal should be
connected to the "motion_notify_event" method of the ruler. We need to setup
a "motion_notify_event" callback for the area and use
connect_object() to get the ruler to emit a
"motion_notify_signal":
The rulers.py example
program creates a drawing area with a horizontal ruler above it and a
vertical ruler to the left of it. The size of the drawing area is 600 pixels
wide by 400 pixels high. The horizontal ruler spans from 7 to 13 with a mark
every 100 pixels, while the vertical ruler spans from 0 to 400 with a mark
every 100 pixels. Placement of the drawing area and the rulers is done using
a table. Figure 9.8, “Rulers Example” illustrates the result:
1 #!/usr/bin/env python
2
3 # example rulers.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class RulersExample:
10 XSIZE = 400
11 YSIZE = 400
12
13 # This routine gets control when the close button is clicked
14 def close_application(self, widget, event, data=None):
15 gtk.main_quit()
16 return False
17
18 def __init__(self):
19 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
20 window.connect("delete_event", self.close_application)
21 window.set_border_width(10)
22
23 # Create a table for placing the ruler and the drawing area
24 table = gtk.Table(3, 2, False)
25 window.add(table)
26
27 area = gtk.DrawingArea()
28 area.set_size_request(self.XSIZE, self.YSIZE)
29 table.attach(area, 1, 2, 1, 2,
30 gtk.EXPAND|gtk.FILL, gtk.FILL, 0, 0 )
31 area.set_events(gtk.gdk.POINTER_MOTION_MASK |
32 gtk.gdk.POINTER_MOTION_HINT_MASK )
33
34 # The horizontal ruler goes on top. As the mouse moves across the
35 # drawing area, a motion_notify_event is passed to the
36 # appropriate event handler for the ruler.
37 hrule = gtk.HRuler()
38 hrule.set_metric(gtk.PIXELS)
39 hrule.set_range(7, 13, 0, 20)
40 def motion_notify(ruler, event):
41 return ruler.emit("motion_notify_event", event)
42 area.connect_object("motion_notify_event", motion_notify, hrule)
43 table.attach(hrule, 1, 2, 0, 1,
44 gtk.EXPAND|gtk.SHRINK|gtk.FILL, gtk.FILL, 0, 0 )
45
46 # The vertical ruler goes on the left. As the mouse moves across
47 # the drawing area, a motion_notify_event is passed to the
48 # appropriate event handler for the ruler.
49 vrule = gtk.VRuler()
50 vrule.set_metric(gtk.PIXELS)
51 vrule.set_range(0, self.YSIZE, 10, self.YSIZE)
52 area.connect_object("motion_notify_event", motion_notify, vrule)
53 table.attach(vrule, 0, 1, 1, 2,
54 gtk.FILL, gtk.EXPAND|gtk.SHRINK|gtk.FILL, 0, 0 )
55
56 # Now show everything
57 area.show()
58 hrule.show()
59 vrule.show()
60 table.show()
61 window.show()
62
63 def main():
64 gtk.main()
65 return 0
66
67 if __name__ == "__main__":
68 RulersExample()
69 main()
Lines 42 and 52 connect the
motion_notify() callback to the area but passing
hrule in line 42 and vrule in
line 52 as user data. The motion_notify() callback
will be called twice each time the mouse moves - once with
hrule and once with
vrule.
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.
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:
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.
The Arrow widget draws an arrowhead,
facing in a number of possible directions and having a number of possible
styles. It can be very useful when placed on a button in many applications.
Like the Label widget, it emits no signals.
There are only two calls for manipulating an
Arrow widget:
The first creates a new arrow widget with the indicated type and
appearance. The second allows these values to be altered retrospectively.
The arrow_type argument may take one of the following
values:
ARROW_UP
ARROW_DOWN
ARROW_LEFT
ARROW_RIGHT
These values obviously indicate the direction in which the arrow
will point. The shadow_type argument may take one of
these values:
SHADOW_IN
SHADOW_OUT # the default
SHADOW_ETCHED_IN
SHADOW_ETCHED_OUT
# pixmap_path "<dir 1>:<dir 2>:<dir 3>:..."
#
pixmap_path "/usr/include/X11R6/pixmaps:/home/imain/pixmaps"
#
# style <name> [= <name>]
# {
# <option>
# }
#
# widget <widget_set> style <style_name>
# widget_class <widget_class_set> style <style_name>
# Here is a list of all the possible states. Note that some do not apply to
# certain widgets.
#
# NORMAL - The normal state of a widget, without the mouse over top of
# it, and not being pressed, etc.
#
# PRELIGHT - When the mouse is over top of the widget, colors defined
# using this state will be in effect.
#
# ACTIVE - When the widget is pressed or clicked it will be active, and
# the attributes assigned by this tag will be in effect.
#
# INSENSITIVE - When a widget is set insensitive, and cannot be
# activated, it will take these attributes.
#
# SELECTED - When an object is selected, it takes these attributes.
#
# Given these states, we can set the attributes of the widgets in each of
# these states using the following directives.
#
# fg - Sets the foreground color of a widget.
# fg - Sets the background color of a widget.
# bg_pixmap - Sets the background of a widget to a tiled pixmap.
# font - Sets the font to be used with the given widget.
#
# This sets a style called "button". The name is not really important, as
# it is assigned to the actual widgets at the bottom of the file.
style "window"
{
#This sets the padding around the window to the pixmap specified.
#bg_pixmap[<STATE>] = "<pixmap filename>"
bg_pixmap[NORMAL] = "warning.xpm"
}
style "scale"
{
#Sets the foreground color (font color) to red when in the "NORMAL"
#state.
fg[NORMAL] = { 1.0, 0, 0 }
#Sets the background pixmap of this widget to that of its parent.
bg_pixmap[NORMAL] = "<parent>"
}
style "button"
{
# This shows all the possible states for a button. The only one that
# doesn't apply is the SELECTED state.
fg[PRELIGHT] = { 0, 1.0, 1.0 }
bg[PRELIGHT] = { 0, 0, 1.0 }
bg[ACTIVE] = { 1.0, 0, 0 }
fg[ACTIVE] = { 0, 1.0, 0 }
bg[NORMAL] = { 1.0, 1.0, 0 }
fg[NORMAL] = { .99, 0, .99 }
bg[INSENSITIVE] = { 1.0, 1.0, 1.0 }
fg[INSENSITIVE] = { 1.0, 0, 1.0 }
}
# In this example, we inherit the attributes of the "button" style and then
# override the font and background color when prelit to create a new
# "main_button" style.
style "main_button" = "button"
{
font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
bg[PRELIGHT] = { 0.75, 0, 0 }
}
style "toggle_button" = "button"
{
fg[NORMAL] = { 1.0, 0, 0 }
fg[ACTIVE] = { 1.0, 0, 0 }
# This sets the background pixmap of the toggle_button to that of its
# parent widget (as defined in the application).
bg_pixmap[NORMAL] = "<parent>"
}
style "text"
{
bg_pixmap[NORMAL] = "marble.xpm"
fg[NORMAL] = { 1.0, 1.0, 1.0 }
}
style "ruler"
{
font = "-adobe-helvetica-medium-r-normal--*-80-*-*-*-*-*-*"
}
# pixmap_path "~/.pixmaps"
# These set the widget types to use the styles defined above.
# The widget types are listed in the class hierarchy, but could probably be
# just listed in this document for the users reference.
widget_class "GtkWindow" style "window"
widget_class "GtkDialog" style "window"
widget_class "GtkFileSelection" style "window"
widget_class "*Gtk*Scale" style "scale"
widget_class "*GtkCheckButton*" style "toggle_button"
widget_class "*GtkRadioButton*" style "toggle_button"
widget_class "*GtkButton*" style "button"
widget_class "*Ruler" style "ruler"
widget_class "*GtkText" style "text"
# This sets all the buttons that are children of the "main window" to
# the main_button style. These must be documented to be taken advantage of.
widget "main window.*GtkButton*" style "main_button"
The TreeView widget displays lists and trees
displaying multiple columns. It replaces the previous set of List,
CList, Tree and
CTree widgets with a much more powerful and flexible
set of objects that use the Model-View-Controller (MVC) principle to provide
the following features:
two pre-defined models: one for lists and one for
trees
multiple views of the same model are automatically
updated when the model changes
selective display of the model data
use of model data to customize the TreeView display on a
row-by-row basis
pre-defined data rendering objects for displaying text,
images and boolean data
stackable models for providing sorted and filtered views of
the underlying model data
reorderable and resizeable columns
automatic sort by clicking column headers
drag and drop support
support for custom models entirely written in
Python
support for custom cell renderers entirely written in
Python
Of course, all this capability comes at the price of a significantly
more complex set of objects and interfaces that appear overwhelming at
first. In the rest of this chapter we'll explore the TreeView objects and
interfaces to reach an understanding of common usage. The more esoteric
aspects, you'll have to explore on your own.
We'll start with a quick overview tour of the objects and interfaces
and then dive into the TreeModel interface and the
predefined ListStore and
TreeStore classes.
14.1. Overview
A TreeView widget is the user interface
object that displays the data stored in an object that implements the
TreeModel interface. Two base tree model classes are
provided in PyGTK 2.0:
the TreeStore that provides
hierarchical data storage organized as tree rows with columnar data. Each
tree row can have zero or more child rows. All rows must have the same
number of columns.
the ListStore that provides tabular
data storage organized in rows and columns similar to a table in a
relational database. The ListStore is really a
simplified version of a TreeStore where the rows have
no children. It has been created to provide a simpler (and presumably more
efficient) interface to this common data model. And,
The two additional tree models stack on top of (or interpose on)
the base models:
the TreeModelSort that provides a
model where the data of the underlying tree model is maintained in a sorted
order. And,
the TreeModelFilter that provides a
model containing a subset of the data in the underlying model. Note this
model is available only in PyGTK 2.4 and above.
A TreeView displays all of the rows of a
TreeModel but may display only some of the columns.
Also the columns may be
presented in a different order than the TreeModel
stores them.
The TreeView uses
TreeViewColumn objects to organize the display of the
columnar data. Each TreeViewColumn displays one
column with an optional header that may contain the data from several
TreeModel columns. The individual
TreeViewColumns are packed (similar to
HBox containers) with
CellRenderer objects to render the display of the
associated data from a TreeModel row and column
location. There are three predefined CellRenderer
classes:
the CellRendererPixbuf that renders
a pixbuf image into the cells of a
TreeViewColumn.
the CellRendererText that renders a
string into the cells of a TreeViewColumn. It will
convert the column data to a string format if needed i.e. if displaying a
model column containing float data, the
CellRendererText will convert it to a string before
rendering it.
the CellRendererToggle that renders
a boolean value as a toggle button into the cells of a
TreeViewColumn.
A TreeViewColumn can contain several
CellRenderer objects to provide a column that, for
example, may have an image and text packed together.
Finally, the TreeIter,
TreeRowReference and
TreeSelection objects provide a transient pointer to
a row in a TreeModel, a persistent pointer to a row
in a TreeModel and an object managing the selections
in a TreeView.
A TreeView display is composed using the
following general operations not necessarily in this order:
A tree model object is created usually a
ListStore or TreeStore with
one or more columns of a specified data type.
The tree model may be populated with one or more rows of
data.
A TreeView widget is created and
associated with the tree model.
One or more TreeViewColumns are
created and inserted in the TreeView. Each of these
will present a single display column.
For each TreeViewColumn one or more
CellRenderers are created and added to the
TreeViewColumn.
The attributes of each CellRenderer
are set to indicate from which column of the tree model to retrieve the
attribute data. for example the text to be rendered. This allows the
CellRenderer to render each column in a row
differently.
The TreeView is inserted and
displayed in a Window or
ScrolledWindow.
The data in the tree model is manipulated programmatically
in response to user actions. The TreeView will
automatically track the changes.
The example program basictreeview.py
illustrates the creation and display of a simple
TreeView:
1 #!/usr/bin/env python
2
3 # example basictreeview.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class BasicTreeViewExample:
10
11 # close the window and quit
12 def delete_event(self, widget, event, data=None):
13 gtk.main_quit()
14 return False
15
16 def __init__(self):
17 # Create a new window
18 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
19
20 self.window.set_title("Basic TreeView Example")
21
22 self.window.set_size_request(200, 200)
23
24 self.window.connect("delete_event", self.delete_event)
25
26 # create a TreeStore with one string column to use as the model
27 self.treestore = gtk.TreeStore(str)
28
29 # we'll add some data now - 4 rows with 3 child rows each
30 for parent in range(4):
31 piter = self.treestore.append(None, ['parent %i' % parent])
32 for child in range(3):
33 self.treestore.append(piter, ['child %i of parent %i' %
34 (child, parent)])
35
36 # create the TreeView using treestore
37 self.treeview = gtk.TreeView(self.treestore)
38
39 # create the TreeViewColumn to display the data
40 self.tvcolumn = gtk.TreeViewColumn('Column 0')
41
42 # add tvcolumn to treeview
43 self.treeview.append_column(self.tvcolumn)
44
45 # create a CellRendererText to render the data
46 self.cell = gtk.CellRendererText()
47
48 # add the cell to the tvcolumn and allow it to expand
49 self.tvcolumn.pack_start(self.cell, True)
50
51 # set the cell "text" attribute to column 0 - retrieve text
52 # from that column in treestore
53 self.tvcolumn.add_attribute(self.cell, 'text', 0)
54
55 # make it searchable
56 self.treeview.set_search_column(0)
57
58 # Allow sorting on the column
59 self.tvcolumn.set_sort_column_id(0)
60
61 # Allow drag and drop reordering of rows
62 self.treeview.set_reorderable(True)
63
64 self.window.add(self.treeview)
65
66 self.window.show_all()
67
68 def main():
69 gtk.main()
70
71 if __name__ == "__main__":
72 tvexample = BasicTreeViewExample()
73 main()
In real programs the TreeStore would likely
be populated with data after the TreeView is
displayed due to some user action. We'll look at the details of the
TreeView interfaces in more detail in the sections to
come. Figure 14.1, “Basic TreeView Example Program” shows the window created by the
basictreeview.py
program after a couple of parent rows have been expanded.
Figure 14.1. Basic TreeView Example Program
Next let's examine the TreeModel interface
and the models that implement it.
pygtk2tutorial/ch-Scribble.html 0100644 0001172 0000167 00000005670 10227357004 015677 0 ustar finlay fcf Chapter 24. Scribble, A Simple Example Drawing Program
Chapter 24. Scribble, A Simple Example Drawing Program
In this section, we will build a simple drawing program. In the
process, we will examine how to handle mouse events, how to draw in a
window, and how to do drawing better by using a backing pixmap.
In addition to the signal mechanism described above, there is a
set of events that reflect the X event mechanism. Callbacks may also be
attached to these events. These events are:
In order to connect a callback function to one of these events
you use the method connect() , as described above,
using one of the above event names as the name parameter.
The callback function (or method) for events has a slightly different form
than that for signals:
GdkEvent is a python object type whose
type attribute will indicate which of the above events has occurred. The
other attributes of the event will depend upon the type of the event.
Possible values for the types are:
This assumes that button is a GtkButton
widget. Now, when the mouse is over the button and a mouse button is
pressed, the function button_press_callback will be
called. This function may be defined as:
def button_press_callback(widget, event, data ):
The value returned from this function indicates whether the
event should be propagated further by the GTK+ event handling mechanism.
Returning True indicates that the event has been
handled, and that it should not propagate further. Returning
False continues the normal event handling. See Chapter 20, Advanced Event and Signal Handling for more details on this
propagation process.
Client specified arbitrary drag-and-drop type (a name and
number pair).
Sent and received data format type.
Drag actions are quite obvious, they specify if the widget can
drag with the specified action(s),
e.g. gtk.gdk.ACTION_COPY and/or
gtk.gdk.ACTION_MOVE. An
gtk.gdk.ACTION_COPY would be a typical drag-and-drop
without the source data being deleted while
gtk.gdk.ACTION_MOVE would be just like
gtk.gdk.ACTION_COPY but the source data will be
'suggested' to be deleted after the received signal handler is called. There
are additional drag actions including gtk.gdk.ACTION_LINK
which you may want to look into when you get to more advanced levels of
drag-and-drop.
The client specified arbitrary drag-and-drop type is much more
flexible, because your application will be defining and checking for that
specifically. You will need to set up your destination widgets to receive
certain drag-and-drop types by specifying a name and/or number. It would be
more reliable to use a name since another application may just happen to use
the same number for an entirely different meaning.
Sent and received data format types (selection
target) come into play only in your request and received data
handler functions. The term selection target is
somewhat misleading. It is a term adapted from GTK+ selection (cut/copy and
paste). What selection target actually means is the
data's format type (i.e. gtk.gdk.Atom, integer, or
string) that is being sent or received. Your request data handler function
needs to specify the type (selection target) of data
that it sends out and your received data handler needs to handle the type
(selection target) of data received.
As PyGTK is an object oriented widget set, it has a hierarchy of
inheritance. This inheritance mechanism applies for signals. Therefore, you
should refer to the widget hierarchy tree when using the signals listed in
this section.
GTK has various widgets that can be visually adjusted by the user
using the mouse or the keyboard, such as the range widgets, described in the
Range Widgets section. There are also a few widgets that display some
adjustable portion of a larger area of data, such as the text widget and the
viewport widget.
Obviously, an application needs to be able to react to changes the
user makes in range widgets. One way to do this would be to have each widget
emit its own type of signal when its adjustment changes, and either pass the
new value to the signal handler, or require it to look inside the widget's
data structure in order to ascertain the value. But you may also want to
connect the adjustments of several widgets together, so that adjusting one
adjusts the others. The most obvious example of this is connecting a
scrollbar to a panning viewport or a scrolling text area. If each widget has
its own way of setting or getting the adjustment value, then the programmer
may have to write their own signal handlers to translate between the output
of one widget's signal and the "input" of another's adjustment setting
method.
GTK solves this problem using the
Adjustment object, which is not a widget but a way
for widgets to store and pass adjustment information in an abstract and
flexible form. The most obvious use of Adjustment is
to store the configuration parameters and values of range widgets, such as
scrollbars and scale controls. However, since
Adjustments are derived from
Object, they have some special powers beyond those of
normal data structures. Most importantly, they can emit signals, just like
widgets, and these signals can be used not only to allow your program to
react to user input on adjustable widgets, but also to propagate adjustment
values transparently between adjustable widgets.
You will see how adjustments fit in when you see the other widgets
that incorporate them: Progress Bars, Viewports, Scrolled Windows, and
others.
7.1. Creating an Adjustment
Many of the widgets which use adjustment objects do so
automatically, but some cases will be shown in later examples where you may
need to create one yourself. You create an adjustment using:
The value argument is the initial value
you want to give to the adjustment, usually
corresponding to the topmost or leftmost position of an adjustable
widget. The lower argument specifies the lowest value
which the adjustment can hold. The
step_incr argument specifies the "smaller" of the two
increments by which the user can change the value, while the
page_incr is the "larger" one. The
page_size argument usually corresponds somehow to the
visible area of a panning widget. The upper argument
is used to represent the bottom most or right most coordinate in a panning
widget's child. Therefore it is not always the largest number that
value can take, since the
page_size of such widgets is usually non-zero.
Ok, you say, that's nice, but what if I want to create my own
handlers to respond when the user adjusts a range widget or a spin button,
and how do I get at the value of the adjustment in these handlers? To answer
these questions and more, let's start by taking a look at the attributes of
a gtk.Adjustment itself:
lower
upper
value
step_increment
page_increment
page_size
Given a gtk.Adjustment instance
adj, each of the attributes are retrieved or set by
adj.lower, adj.value,
etc.
Since, when you set the value of an adjustment, you generally
want the change to be reflected by every widget that uses this adjustment,
PyGTK provides a method to do this:
adjustment.set_value(value)
As mentioned earlier, Adjustment is a
subclass of Object just like all the various widgets,
and thus it is able to emit signals. This is, of course, why updates happen
automagically when you share an adjustment object between a scrollbar and
another adjustable widget; all adjustable widgets connect signal handlers to
their adjustment's value_changed signal, as can your program. Here's the
definition of this signal callback:
def value_changed(adjustment):
The various widgets that use the
Adjustment object will emit this signal on an
adjustment whenever they change its value. This happens both when user input
causes the slider to move on a range widget, as well as when the program
explicitly changes the value with the set_value()
method. So, for example, if you have a scale widget, and you want to change
the rotation of a picture whenever its value changes, you would create a
callback like this:
What about when a widget reconfigures the
upper or lower fields of its
adjustment, such as when a user adds more text to a text widget? In this
case, it emits the changed signal, which looks like this:
def changed(adjustment):
Range widgets typically connect a handler
to this signal, which changes their appearance to reflect the change - for
example, the size of the slider in a scrollbar will grow or shrink in
inverse proportion to the difference between the lower and upper values of
its adjustment.
You probably won't ever need to attach a handler to this signal,
unless you're writing a new type of range widget. However, if you change any
of the values in a Adjustment directly, you should
emit this signal on it to reconfigure whatever widgets are using it, like
this:
The TreeModelSort and
TreeModelFilter objects are tree models that
interpose between the base TreeModel (either a
TreeStore or a ListStore) and
the TreeView to provide a modified model while still
retaining the original structure of the base model. These interposing models
implement the TreeModel and
TreeSortable interfaces but do not provide any
methods for inserting or removing rows in the model; you have to insert or
remove rows from the underlying store. The
TreeModelSort provides a model where the rows are
always sorted while the TreeModelFilter provides a
model containing a subset of the rows of the base model.
These models can be chained to an arbitrary length if desired; i.e
a TreeModelFilter could have a child
TreeModelSort that could have a child
TreeModelFilter, and so on. As long as there is a
TreeStore or ListStore as the
anchor of the chain it should just work. In PyGTK 2.0 and 2.2 the
TreeModelSort and
TreeModelFilter objects do not support the
TreeModel Python mapping protocol.
14.10.1. TreeModelSort
The TreeModelSort maintains a sorted
model of the child model specified in its constructor. The main use of a
TreeModelSort is to provide multiple views of a model
that can be sorted differently. If you have multiple views of the same model
then any sorting activity is reflected in all the views. By using the
TreeModelSort the base store is left in its original
unsorted state and the sort models absorb all the sorting activity. To
create a TreeModelSort use the constructor:
treemodelsort = gtk.TreeModelSort(child_model)
where child_model is a
TreeModel. Most of the methods of a
TreeModelSort deal with converting tree paths and
TreeIters from the child model to the sorted model
and back:
These path conversion methods return None if
the given path cannot be converted to a path in the sorted model or the
child model respectively. The TreeIter conversion
methods are:
The TreeIter conversion methods duplicate
the converted argument (its both the return value and the first argument)
due to backward compatibility issues; you should set the first arguments to
None and just use the return value. For example:
Each of the columns in the windows can be clicked to change the
sort order independent of the other windows. When the "Add a
Row" button is clicked a new row is added to the base
ListStore and the new row is displayed in each
TreeView as the selected row.
14.10.2. TreeModelFilter
Note
The TreeModelFilter is available in
PyGTK 2.4 and above.
A TreeModelFilter object provides several
ways of modifying the view of the base TreeModel
including:
displaying a subset of the rows in the child model either
based on boolean data in a "visible column", or based on the boolean return
value of a "visible function" that takes the child model, a
TreeIter pointing at a row in the child model and
user data. In both cases if the boolean value is TRUE the
row will be displayed; otherwise, the row will be hidden.
using a virtual root node to provide a view of a subtree
of the children of a row in the child model. This only makes sense if the
underlying store is a TreeStore.
synthesizing the columns and data of a model based on the
data in the child model. For example, you can provide a column where the
data is calculated from data in several child model columns.
A TreeModelFilter object is created using
the TreeModel method:
treemodelfilter = treemodel.filter_new(root=None)
where root is a tree path in
treemodel specifying the virtual root for the model
or None if the root node of
treemodel is to be used.
By setting a "virtual root" when creating the
TreeModelFilter, you can limit the model view to the
child rows of "root" row in the child model hierarchy. This, of course is
only useful when the child model is based on a
TreeStore. For example, you might want to provide a
view of the parts list that makes up a CDROM drive separate from the full
parts list of a computer.
The visibility modes are mutually exclusive and can only be set
once i.e. once a visibility function or column is set it cannot be changed
and the alternative mode cannot be set. The simplest visibility mode
extracts a boolean value from a column in the child model to determine if
the row should be displayed. The visibility columns is set using:
treemodelfilter.set_visible_column(column)
where column is the number of the column
in the child TreeModel to extract the boolean values
from. For example, the following code fragment uses the values in the third
column to set the visibility of the rows:
Thus any rows in treestore that have a
value of TRUE in the third column will be
displayed.
If you have more complicated visibility criteria setting a
visibility function should provide sufficient power:
treemodelfilter.set_visible_func(func, data=None)
where func is the function called for
each child model row to determine if it should be displayed and
data is user data passed to
func. func should return
TRUE if the row should be displayed. The signature of
func is:
def func(model, iter, user_data)
where model is the child
TreeModel, iter is a
TreeIter pointing at a row in
model and user_data is the
passed in data.
If you make a change to the visibility criteria you should
call:
treemodelfilter.refilter()
to force a refiltering of the child model rows.
For example, the following code fragment illustrates a
TreeModelFilter that displays rows based on a
comparison between the value in the third column and the contents of the
user data:
By toggling the buttons at the bottom the contents of the
TreeView are changed to display only the rows that
match one of the active buttons.
A modify function gives you another level of control over the
TreeView display to the point where you can
synthesize one or more (or even all) columns that are represented by the
TreeModelFilter. You still have to use a base child
model that is a TreeStore or
ListStore to determine the number of rows and the
hierarchy but the columns can be anything you specify in the method:
where types is a sequence (list or tuple)
specifying the column types being represented, func
is a function called to return the value for a row and column and
data is an argument to be passed to
func. The signature of func
is:
def func(model, iter, column, user_data)
where model is the
TreeModelFilter, iter is a
TreeIter that points to a row in model,
column is the number of the column that a value is
needed for and user_data is the parameter
data. func must return a value
matching the type for column.
A modify function is useful where you want to provide a column
of data that needs to be generated using the data in the child model
columns. For example if you had a column containing birth dates and wanted
to provide a column displaying ages, a modify function could generate the
age information using the birth date and the current date. Another example
would be to decide what image to display based on some analysis of the data
(say, a filename) in a column. This effect can also be achieved using the
TreeViewColumnset_cell_data_func() method.
Usually within the modify function, you will have to convert the
TreeModelFilterTreeIter to a
TreeIter in the child model using:
Of course, you'll also need to retrieve the child model
using:
child_model = treemodelfilter.get_model()
These give you access to the child model row and its values for
generating the value for the specified
TreeModelFilter row and column. There's also a method
to convert a child TreeIter to a filter model
TreeIter and methods to convert filter model paths to
and from child tree paths:
Of course, you can combine the visibility modes and the modify
function to both filter rows and synthesize columns. To get even more
control over the view you would have to use a custom
TreeModel.
The UIManager provides a way to create
menus and toolbars from an XML-like description. The
UIManager uses ActionGroup
objects to manage the Action objects providing the
common substructure for the menu and toolbar items.
Using the UIManager you can dynamically
merge and demerge multiple UI descriptions and actions. This allows you to
modify the menus and toolbars when the mode changes in the application (for
example, changing from text editing to image editing), or when new plug-in
features are added or removed from your application.
A UIManager can be used to create the menus
and toolbars for an application user interface as follows:
Create a UIManager instance
Extract the AccelGroup from the
UIManager and add it to the top level
Window
Create the ActionGroup instances and
populate them with the appropriate Action
instances.
Add the ActionGroup instances to the
UIManager in the order that the
Action instances should be found.
Add the UI XML descriptions to the
UIManager. Make sure that all
Actions referenced by the descriptions are available
in the UIManagerActionGroup
instances.
Extract references to the menubar, menu and toolbar widgets
by name for use in building the user interface.
Dynamically modify the user interface by adding and
removing UI descriptions and by adding, rearranging and removing the
associated ActionGroup instances.
16.7.2. Creating a UIManager
A UIManager instance is created by the
constructor:
uimamager = gtk.UIManager()
A new UIManager is created with an
associated AccelGroup that can be retrieved using the
method:
accelgroup = uimanager.get_accel_group()
The AccelGroup should be added to the top
level window of the application so that the Action
accelerators can be used by your users. For example:
As described in Section 16.1.2, “ActionGroups”,
ActionGroups can be populated with
Actions by using the
add_actions(),
add_toggle_actions() and
add_radio_actions() convenience methods. An
ActionGroup can be used by a
UIManager after it has been added to its
ActionGroup list by using the method:
uimanager.insert_action_group(action_group, pos)
where pos is the index of the position
where action_group should be inserted. A
UIManager may contain several
ActionGroups with duplicate
Action names. The order of the
ActionGroup objects is important because the lookup
of an Action stops when the first
Action with the given name is encountered. This means
that actions in earlier ActionGroup objects mask
those in later ActionGroup objects.
The actions referenced in a UI XML description must be added to a
UIManager before the description can be added to the
UIManager.
An ActionGroup can be removed from a
UIManager by using the method:
uimanager.remove_action_group(action_group)
A list of the ActionGroup objects
associated with a UIManager can be retrieved using
the method:
actiongrouplist = uimanager.get_action_groups()
16.7.4. UI Descriptions
The UI descriptions accepted by UIManager
are simple XML definitions with the following elements:
ui
The root element of a UI description. It can be
omitted. Can contain menubar, popup, toolbar and
accelerator elements.
menubar
A top level element describing a
MenuBar structure that can contain MenuItem, separator,
placeholder and menu elements. It has an optional
name attribute. If name is not
specified, "menubar" is used as the name.
popup
A top level element describing a popup
Menu structure that can contain menuitem, separator,
placeholder, and menu elements. It has an optional
name attribute. If name is not
specified, "popup" is used as the name.
toolbar
A top level element describing a
Toolbar structure that can contain toolitem, separator
and placeholder elements. It has an
optional name attribute. If name
is not specified, "toolbar" is used as the name.
placeholder
An element identifying a position in a menubar, toolbar,
popup or menu. A placeholder can contain menuitem, separator,
placeholder, and menu elements. Placeholder elements are used when merging UI
descriptions to allow, for example, a menu to be built up from UI
descriptions using common placeholder
names. It has an optional name attribute. If
name is not specified, "placeholder" is used as the
name.
menu
An element describing a Menu
structure that can contain menuitem,
separator, placeholder, and menu elements. A menu element has a required attribute
action that names an Action
object to be used to create the Menu. It also has
optional name and position
attributes. If name is not specified, the
action name is used as the name. The
position attribute can have either the value "top" or
"bottom" with "bottom" the default if position is not
specified.
menuitem
An element describing a
MenuItem. A menuitem
element has a required attribute action that names an
Action object to be used to create the
MenuItem. It also has optional
name and position attributes. If
name is not specified, the action
name is used as the name. The position attribute can
have either the value "top" or "bottom" with "bottom" the default if
position is not specified.
toolitem
An element describing a toolbar
ToolItem. A toolitem
element has a required attribute action that names an
Action object to be used to create the
Toolbar. It also has optional
name and position attributes. If
name is not specified, the action
name is used as the name. The position attribute can
have either the value "top" or "bottom" with "bottom" the default if
position is not specified.
separator
An element describing a
SeparatorMenuItem or a
SeparatorToolItem as appropriate.
accelerator
An element describing a keyboard accelerator. An
accelerator element has a required
attribute action that names an
Action object that defines the accelerator key
combination and is activated by the accelerator. It also has an optional
name attribute. If name is not
specified, the action name is used as the
name.
Note that this description just uses the action attribute names for the names of most elements
rather than specifying name attributes. Also I would
recommend not specifying the ui element as
it appears to be unnecessary.
The widget hierarchy created using a UI description is very
similar to the XML element hierarchy except that placeholder elements are merged into their
parents.
A widget in the hierarchy created by a UI description can be
accessed using its path which is composed of the name of the widget element
and its ancestor elements joined by slash ("/") characters. For example
using the above description the following are valid widget paths:
Note that the placeholder name
must be included in the path. Usually you just access the top level widgets
(for example, "/MenuBar" and "/Toolbar") but you may need to access a lower
level widget to, for example, change a property.
16.7.5. Adding and Removing UI Descriptions
Once a UIManager is set up with an
ActionGroup a UI description can be added and merged
with the existing UI by using one of the following methods:
where buffer is a string containing a UI
description and filename is the file containing a UI
description. Both methods return a merge_id which is
a unique integer value. If the method fails, the GError
exception is raised. The merge_id can be used to
remove the UI description from the UIManager by using
the method:
uimanager.remove_ui(merge_id)
The same methods can be used more than once to add additional UI
descriptions that will be merged to provide a combined XML UI
description. Merged UIs will be discussed in more detail in Section 16.7.8, “Merging UI Descriptions” section.
A single UI element can be added to the current UI description by
using the method:
where merge_id is a unique integer value,
path is the path where the new element should be
added, action is the name of an
Action or None to add a separator, type is the element
type to be added and top is a boolean value. If
top is TRUE the element will be
added before its siblings, otherwise it is added after.
merge_id should be obtained from the
method:
merge_id = uimanager.new_merge_id()
The integer values returned from the
new_merge_id() method are monotonically
increasing.
path is a string composed of the name of
the element and the names of its ancestor elements separated by slash ("/")
characters but not including the optional root node "/ui". For example,
"/MenuBar/RadioBand" is the path of the menu element named "RadioBand" in the following UI
description:
The type of the UI element (menuitem, toolitem or
separator) is set according to the context.
gtk.UI_MANAGER_MENUBAR
A menubar.
gtk.UI_MANAGER_MENU
A menu.
gtk.UI_MANAGER_TOOLBAR
A toolbar.
gtk.UI_MANAGER_PLACEHOLDER
A placeholder.
gtk.UI_MANAGER_POPUP
A popup menu.
gtk.UI_MANAGER_MENUITEM
A menuitem.
gtk.UI_MANAGER_TOOLITEM
A toolitem.
gtk.UI_MANAGER_SEPARATOR
A separator.
gtk.UI_MANAGER_ACCELERATOR
An accelerator.
add_ui() fails silently if the element is
not added. Using add_ui() is so low level that you
should always try to use the convenience methods
add_ui_from_string() and
add_ui_from_file() instead.
Adding a UI description or element causes the widget hierarchy to
be updated in an idle function. You can make sure that the widget hierarchy
has been updated before accessing it by calling the method:
uimanager.ensure_update()
16.7.6. Accessing UI Widgets
You access a widget in the UI widget hierarchy by using the
method:
widget = uimanager.get_widget(path)
where path is a string containing the name
of the widget element and it's ancestors as described in Section 16.7.4, “UI Descriptions”.
Likewise the lower level widgets in the hierarchy are accessed by
using their paths. For example the RadioToolButton
named "SSB" is accessed as follows:
As a convenience all the top level widgets of a type can be
retrieved using the method:
toplevels = uimanager.get_toplevels(type)
where type specifies the type of widgets to
return using a combination of the flags:
gtk.UI_MANAGER_MENUBAR,
gtk.UI_MANAGER_TOOLBAR and
gtk.UI_MANAGER_POPUP. You can use the
gtk.Widget.get_name() method to determine which top
level widget you have.
You can retrieve the Action that is used by
the proxy widget associated with a UI element by using the method:
action = uimanager_get_action(path)
where path is a string containing the path
to a UI element in uimanager. If the element has no
associated Action, None is
returned.
The uimanager.py
example program uses the XML description of Section 16.7.6, “Accessing UI Widgets”. The text of the two labels are
changed in response to the activation of the "Mute"
ToggleAction and "AM", "FM" and "SSB"
RadioActions. All the actions are contained in a
single ActionGroup allowing the sensitivity and
visibility of all the action proxy widgets to be toggled on and off by using
the "Sensitive" and "Visible" toggle buttons. The use of the placeholder element will be described in Section 16.7.8, “Merging UI Descriptions”.
16.7.8. Merging UI Descriptions
The merging of UI descriptions is done based on the name of the
XML elements. As noted above the individual elements in the hierarchy can be
accessed using a pathname consisting of the element name and the names of
its ancestors. For example, using the UI description in Section 16.7.4, “UI Descriptions” the "AM" toolitem element has the pathname
"/Toolbar/RadioBandItems/AM" while the "FM" menuitem element has the pathname
"/MenuBar/RadioBand/FM".
If a UI description is merged with that UI description the
elements are added as siblings to the existing elements. For example, if
the UI description:
Examining the merged XML you can see that the "New" and "Save"
menuitem elements have been merged before
the "Quit" element as a result of the "position" attribute being set to
"top" which means the element should be prepended. Likewise, the "New" and
"Save" toolitem elements have been
prepended to "Toolbar". Note that the "New" and "Save" elements are reversed
by the merging process.
The "Loudness" toolitem element
is appended to the "Toolbar" elements and appears last in the merged UI
description even though it's not last in its UI description. The
"RadioBandItems" placeholder element in
both UI descriptions combines the "CB" and "Shortwave" toolitem elements with the "AM", "FM", and "SSB"
elements. If the "RadioBandItems" placeholder element was not used the "CB" and
"Shortwave" elements would have been placed after the "Loudness"
element.
A representation of the UI description used by a
UIManager can be retrieved using the method:
The example program uses three ActionGroup
objects:
Action objects for the "File",
"Sound" and "Radio Band" menus
Action objects for the "Quit",
"Mute", "AM", "FM", "SSB" and "Radio Band" menus
Action objects for the "Loudness",
"CB" and "Shortwave" elements
The "Sensitive" and Visible" ToggleButton
widgets control the sensitivity and visibility of only the second
ActionGroup.
16.7.9. UIManager Signals
The UIManager has a couple of interesting
signals that your application can connect to. The "actions-changed" signal
is emitted when an ActionGroup is added or
removed from a UIManager. The signature of the
callback is:
def callback(uimanager, ...)
The "add-widget" signal is emitted when a proxy
MenuBar or Toolbar widget is
created. The callback signature is:
The example program table.py makes a window
with three buttons in a 2x2 table. The first two buttons will be placed in
the upper row. A third, quit button, is placed in the lower row, spanning
both columns. Figure 4.4, “Packing using a Table” illustrates the resulting window:
Figure 4.4. Packing using a Table
Here's the source code:
1 #!/usr/bin/env python
2
3 # example table.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class Table:
10 # Our callback.
11 # The data passed to this method is printed to stdout
12 def callback(self, widget, data=None):
13 print "Hello again - %s was pressed" % data
14
15 # This callback quits the program
16 def delete_event(self, widget, event, data=None):
17 gtk.main_quit()
18 return False
19
20 def __init__(self):
21 # Create a new window
22 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
23
24 # Set the window title
25 self.window.set_title("Table")
26
27 # Set a handler for delete_event that immediately
28 # exits GTK.
29 self.window.connect("delete_event", self.delete_event)
30
31 # Sets the border width of the window.
32 self.window.set_border_width(20)
33
34 # Create a 2x2 table
35 table = gtk.Table(2, 2, True)
36
37 # Put the table in the main window
38 self.window.add(table)
39
40 # Create first button
41 button = gtk.Button("button 1")
42
43 # When the button is clicked, we call the "callback" method
44 # with a pointer to "button 1" as its argument
45 button.connect("clicked", self.callback, "button 1")
46
47
48 # Insert button 1 into the upper left quadrant of the table
49 table.attach(button, 0, 1, 0, 1)
50
51 button.show()
52
53 # Create second button
54
55 button = gtk.Button("button 2")
56
57 # When the button is clicked, we call the "callback" method
58 # with a pointer to "button 2" as its argument
59 button.connect("clicked", self.callback, "button 2")
60 # Insert button 2 into the upper right quadrant of the table
61 table.attach(button, 1, 2, 0, 1)
62
63 button.show()
64
65 # Create "Quit" button
66 button = gtk.Button("Quit")
67
68 # When the button is clicked, we call the main_quit function
69 # and the program exits
70 button.connect("clicked", lambda w: gtk.main_quit())
71
72 # Insert the quit button into the both lower quadrants of the table
73 table.attach(button, 0, 2, 1, 2)
74
75 button.show()
76
77 table.show()
78 self.window.show()
79
80 def main():
81 gtk.main()
82 return 0
83
84 if __name__ == "__main__":
85 Table()
86 main()
The Table class is defined in line 9-78.
Lines 12-13 define the callback() method which is
called when two of the buttons are "clicked". The callback just prints a
message to the console indicating which button was pressed using the passed
in string data.
Lines 16-18 define the delete_event()
method which is called when the window is slated for deletion by the window
manager.
Lines 20-78 define the Table instance
initialization method __init__() . It creates a
window (line 22), sets the window title (line 25), connects the
delete_event() callback to the "delete_event"
signal (line 29), and sets the border width (line 32). A
gtk.Table is created in line 35 and added to the
window in line 38.
The two upper buttons are created (lines 41 and 55), their
"clicked" signals are connected to the callback()
method (lines 45 and 59), and attached to the table in the first row (lines
49 and 61). Lines 66-72 create the "Quit" button, connect its "clicked"
signal to the main_quit() function and attach it to the
table spanning the whole second row.
Here is the code
used to create the above images. It's commented fairly heavily so I hope you
won't have any problems following it. Run it yourself and play with
it.
1 #!/usr/bin/env python
2
3 # example packbox.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8 import sys, string
9
10 # Helper function that makes a new hbox filled with button-labels. Arguments
11 # for the variables we're interested are passed in to this function. We do
12 # not show the box, but do show everything inside.
13
14 def make_box(homogeneous, spacing, expand, fill, padding):
15
16 # Create a new hbox with the appropriate homogeneous
17 # and spacing settings
18 box = gtk.HBox(homogeneous, spacing)
19
20 # Create a series of buttons with the appropriate settings
21 button = gtk.Button("box.pack")
22 box.pack_start(button, expand, fill, padding)
23 button.show()
24
25 button = gtk.Button("(button,")
26 box.pack_start(button, expand, fill, padding)
27 button.show()
28
29 # Create a button with the label depending on the value of
30 # expand.
31 if expand == True:
32 button = gtk.Button("True,")
33 else:
34 button = gtk.Button("False,")
35
36 box.pack_start(button, expand, fill, padding)
37 button.show()
38
39 # This is the same as the button creation for "expand"
40 # above, but uses the shorthand form.
41 button = gtk.Button(("False,", "True,")[fill==True])
42 box.pack_start(button, expand, fill, padding)
43 button.show()
44
45 padstr = "%d)" % padding
46
47 button = gtk.Button(padstr)
48 box.pack_start(button, expand, fill, padding)
49 button.show()
50 return box
51
52 class PackBox1:
53 def delete_event(self, widget, event, data=None):
54 gtk.main_quit()
55 return False
56
57 def __init__(self, which):
58
59 # Create our window
60 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
61
62 # You should always remember to connect the delete_event signal
63 # to the main window. This is very important for proper intuitive
64 # behavior
65 self.window.connect("delete_event", self.delete_event)
66 self.window.set_border_width(10)
67
68 # We create a vertical box (vbox) to pack the horizontal boxes into.
69 # This allows us to stack the horizontal boxes filled with buttons one
70 # on top of the other in this vbox.
71 box1 = gtk.VBox(False, 0)
72
73 # which example to show. These correspond to the pictures above.
74 if which == 1:
75 # create a new label.
76 label = gtk.Label("HBox(False, 0)")
77
78 # Align the label to the left side. We'll discuss this method
79 # and others in the section on Widget Attributes.
80 label.set_alignment(0, 0)
81
82 # Pack the label into the vertical box (vbox box1). Remember that
83 # widgets added to a vbox will be packed one on top of the other in
84 # order.
85 box1.pack_start(label, False, False, 0)
86
87 # Show the label
88 label.show()
89
90 # Call our make box function - homogeneous = False, spacing = 0,
91 # expand = False, fill = False, padding = 0
92 box2 = make_box(False, 0, False, False, 0)
93 box1.pack_start(box2, False, False, 0)
94 box2.show()
95
96 # Call our make box function - homogeneous = False, spacing = 0,
97 # expand = True, fill = False, padding = 0
98 box2 = make_box(False, 0, True, False, 0)
99 box1.pack_start(box2, False, False, 0)
100 box2.show()
101
102 # Args are: homogeneous, spacing, expand, fill, padding
103 box2 = make_box(False, 0, True, True, 0)
104 box1.pack_start(box2, False, False, 0)
105 box2.show()
106
107 # Creates a separator, we'll learn more about these later,
108 # but they are quite simple.
109 separator = gtk.HSeparator()
110
111 # Pack the separator into the vbox. Remember each of these
112 # widgets is being packed into a vbox, so they'll be stacked
113 # vertically.
114 box1.pack_start(separator, False, True, 5)
115 separator.show()
116
117 # Create another new label, and show it.
118 label = gtk.Label("HBox(True, 0)")
119 label.set_alignment(0, 0)
120 box1.pack_start(label, False, False, 0)
121 label.show()
122
123 # Args are: homogeneous, spacing, expand, fill, padding
124 box2 = make_box(True, 0, True, False, 0)
125 box1.pack_start(box2, False, False, 0)
126 box2.show()
127
128 # Args are: homogeneous, spacing, expand, fill, padding
129 box2 = make_box(True, 0, True, True, 0)
130 box1.pack_start(box2, False, False, 0)
131 box2.show()
132
133 # Another new separator.
134 separator = gtk.HSeparator()
135 # The last 3 arguments to pack_start are:
136 # expand, fill, padding.
137 box1.pack_start(separator, False, True, 5)
138 separator.show()
139 elif which == 2:
140 # Create a new label, remember box1 is a vbox as created
141 # near the beginning of __init__()
142 label = gtk.Label("HBox(False, 10)")
143 label.set_alignment( 0, 0)
144 box1.pack_start(label, False, False, 0)
145 label.show()
146
147 # Args are: homogeneous, spacing, expand, fill, padding
148 box2 = make_box(False, 10, True, False, 0)
149 box1.pack_start(box2, False, False, 0)
150 box2.show()
151
152 # Args are: homogeneous, spacing, expand, fill, padding
153 box2 = make_box(False, 10, True, True, 0)
154 box1.pack_start(box2, False, False, 0)
155 box2.show()
156
157 separator = gtk.HSeparator()
158 # The last 3 arguments to pack_start are:
159 # expand, fill, padding.
160 box1.pack_start(separator, False, True, 5)
161 separator.show()
162
163 label = gtk.Label("HBox(False, 0)")
164 label.set_alignment(0, 0)
165 box1.pack_start(label, False, False, 0)
166 label.show()
167
168 # Args are: homogeneous, spacing, expand, fill, padding
169 box2 = make_box(False, 0, True, False, 10)
170 box1.pack_start(box2, False, False, 0)
171 box2.show()
172
173 # Args are: homogeneous, spacing, expand, fill, padding
174 box2 = make_box(False, 0, True, True, 10)
175 box1.pack_start(box2, False, False, 0)
176 box2.show()
177
178 separator = gtk.HSeparator()
179 # The last 3 arguments to pack_start are:
180 # expand, fill, padding.
181 box1.pack_start(separator, False, True, 5)
182 separator.show()
183
184 elif which == 3:
185
186 # This demonstrates the ability to use pack_end() to
187 # right justify widgets. First, we create a new box as before.
188 box2 = make_box(False, 0, False, False, 0)
189
190 # Create the label that will be put at the end.
191 label = gtk.Label("end")
192 # Pack it using pack_end(), so it is put on the right
193 # side of the hbox created in the make_box() call.
194 box2.pack_end(label, False, False, 0)
195 # Show the label.
196 label.show()
197
198 # Pack box2 into box1
199 box1.pack_start(box2, False, False, 0)
200 box2.show()
201
202 # A separator for the bottom.
203 separator = gtk.HSeparator()
204
205 # This explicitly sets the separator to 400 pixels wide by 5
206 # pixels high. This is so the hbox we created will also be 400
207 # pixels wide, and the "end" label will be separated from the
208 # other labels in the hbox. Otherwise, all the widgets in the
209 # hbox would be packed as close together as possible.
210 separator.set_size_request(400, 5)
211 # pack the separator into the vbox (box1) created near the start
212 # of __init__()
213 box1.pack_start(separator, False, True, 5)
214 separator.show()
215
216 # Create another new hbox.. remember we can use as many as we need!
217 quitbox = gtk.HBox(False, 0)
218
219 # Our quit button.
220 button = gtk.Button("Quit")
221
222 # Setup the signal to terminate the program when the button is clicked
223 button.connect("clicked", lambda w: gtk.main_quit())
224 # Pack the button into the quitbox.
225 # The last 3 arguments to pack_start are:
226 # expand, fill, padding.
227 quitbox.pack_start(button, True, False, 0)
228 # pack the quitbox into the vbox (box1)
229 box1.pack_start(quitbox, False, False, 0)
230
231 # Pack the vbox (box1) which now contains all our widgets, into the
232 # main window.
233 self.window.add(box1)
234
235 # And show everything left
236 button.show()
237 quitbox.show()
238
239 box1.show()
240 # Showing the window last so everything pops up at once.
241 self.window.show()
242
243 def main():
244 # And of course, our main loop.
245 gtk.main()
246 # Control returns here when main_quit() is called
247 return 0
248
249 if __name__ =="__main__":
250 if len(sys.argv) != 2:
251 sys.stderr.write("usage: packbox.py num, where num is 1, 2, or 3.\n")
252 sys.exit(1)
253 PackBox1(string.atoi(sys.argv[1]))
254 main()
A brief tour of the packbox.py code starts
with lines 14-50 which define a helper function
make_box() that creates a horizontal box and populates
it with buttons according to the specified parameters. A reference to the
horizontal box is returned.
Lines 52-241 define the PackBox1 class
initialization method __init__() that creates a
window and a child vertical box that is populated with a different widget
arrangement depending on the argument passed to it. If a 1 is passed, lines
75-138 create a window displaying the five unique packing arrangements that
are available when varying the homogeneous, expand and fill parameters. If a
2 is passed, lines 140-182 create a window displaying the various
combinations of fill with spacing and padding. Finally, if a 3 is passed,
lines 188-214 create a window displaying the use of the
pack_start() method to left justify the buttons and
pack_end() method to right justify a label. Lines
215-235 create a horizontal box containing a button that is packed into the
vertical box. The button "clicked" signal is connected to the PyGTK
main_quit() function to terminate the program.
Lines 250-252 check the command line arguments and exit the
program using the sys.exit() function if there isn't
exactly one argument. Line 253 creates a PackBox1 instance. Line 254 invokes
the main() function to start the GTK event processing
loop.
In this example program, the references to the various widgets
(except the window) are not saved in the object instance attributes because
they are not needed later.
Check buttons inherit many properties and methods from the the
toggle buttons above, but look a little different. Rather than being buttons
with text inside them, they are small squares with the text to the right of
them. These are often used for toggling options on and off in
applications.
The creation method is similar to that of the normal
button.
check_button = gtk.CheckButton(label=None)
If the label argument is specified the method
creates a check button with a label beside it. The label
text is parsed for '_'-prefixed mnemonic characters.
Checking and setting the state of the check button are
identical to that of the toggle button.
The first four methods connect a signal handler
(cb) to a gtk.Object
(object) for the given signal name. and return a
handler_id that identifies the connection.
cb_args is zero or more arguments that will be passed
last (in order) to cb. The
connect_after() and
connect_object_after() methods will have their
signal handlers called after other signal handlers (including the default
handlers) connected to the same object and signal name. Each object signal
handler has its own set of arguments that it expects. You have to refer to
the GTK+ documentation to figure out what arguments need to be handled by a
signal handler though information for the common widgets is available in
Appendix A, GTK Signals. The general signal handler is
similar to:
def signal_handler(object, ...., cb_args):
Signal handlers that are defined as part of a Python object
class (specified in the connect() methods as
self.cb) will have an additional argument passed as
the first argument - the object instance self:
signal_handler(self, object, ...., cb_args)
The connect_object() and
connect_object_after() methods call the signal
handler with the slot_object substituted in place of
the object as the first argument:
emit and stop the signal name
respectively. Emitting the signal causes its default and user defined
handlers to be run. The emit_stop_by_name() method
will abort the current signal name emission.
You can check for the ability to read from or write to a file
(either a Python file or a lower level OS file) and then automatically
invoke a callback. This is especially useful for networking applications.
The gobject module function:
where the first argument (source) is the
open file (Python file object or lower level file descriptor integer) you
wish to have watched. The gobject.io_add_watch()
function uses the lower level file descriptor integer internally but the
function will extract it from the Python file object using the
fileno() method as needed. The second argument
(condition) specifies what you want to look for. This
may be one of:
gobject.IO_IN - There is data ready for reading from your file.
gobject.IO_OUT - The file is ready for writing.
gobject.IO_PRI - There is urgent data to read.
gobject.IO_ERR - Error condition.
gobject.IO_HUP - Hung up (the connection has been broken, usually for
pipes and sockets).
These are defined in the gobject module. As I'm sure you've
figured out already, the third argument is the callback
you wish to have called when the above conditions are satisfied.
The return value source_id may be used
to stop the monitoring of the file by using the following function:
gobject.source_remove(source_id)
The callback function should be similar to:
def input_callback(source, condition):
where source and
condition are as specified above. The source value
will be the lower level file descriptor integer and not the Python file
object (i.e. the value that is returned from the Python file method
fileno()).
You may also stop the callback function from being called again
by returning zero or FALSE from your callback. If you
want your callback to be called again, it should return
TRUE.
16.6. File Selections using FileChooser-based Widgets
The new way to select files in PyGTK 2.4 is to use the variants of
the FileChooser widget. The two objects that
implement this new interface in PyGTK 2.4 are
FileChooserWidget and
FileChooserDialog. The latter is the complete dialog
with the window and easily defined buttons. The former is a widget useful
for embedding within another widget.
Both the FileChooserWidget and
FileChooserDialog possess the means for navigating
the filesystem tree and selecting files. The view of the widgets depends on
the action used to open a widget.
To create a new file chooser dialog to select an existing file (as
in typical
File->Open
option of a typical application), use:
In the above examples, the two buttons (the stock
Cancel and Open items) are
created and connected to their respective responses (stock
Cancel and OK responses).
To set the folder displayed in the file chooser, use the
method:
chooser.set_current_folder(pathname)
To set the suggested file name as if it was typed by a user (the
typical File->Save
Assituation), use the method:
chooser.set_current_name(name)
The above method does not require the filename to exist. If you want
to preselect a particular existing file (as in the
File->Open
situation), you should use the method:
chooser.set_filename(filename)
To obtain the filename that the user has entered or clicked
on, use this method:
filename = chooser.get_filename()
It is possible to allow multiple file selections (only for the
gtk.FILE_CHOOSER_ACTION_OPEN action) by using the
method:
chooser.set_select_multiple(select_multiple)
where select_mutiple should be
TRUE to allow multiple selections. In this case, you will
need to use the following method to retrieve a list of the selected
filenames:
filenames = chooser.get_filenames()
An important feature of all file choosers is the ability to add file
selection filters. The filter may be added by the method:
chooser.add_filter(filter)
In the example above, filter must be an
instance of the FileFilterclass.
The left panel of the file chooser lists some shortcut folders such
as Home, Filesystem,
CDROM, etc. You may add a folder to the list of these
shortcuts and remove it from the list by using these methods:
The Entry widget allows text to be typed
and displayed in a single line text box. The text may be set with method
calls that allow new text to replace, prepend or append the current contents
of the Entry widget.
The function for creating an Entry widget
is:
entry = gtk.Entry(max=0)
If the max argument is given it sets a
limit on the length of the text within the Entry. If
max is 0 then there is no limit.
The maximum length of the entry can be changed using the
method:
entry.set_max_length(max)
The next method alters the text which is currently within the
Entry widget.
entry.set_text(text)
The set_text() method sets the contents
of the Entry widget to text,
replacing the current contents. Note that the class
Entry implements the Editable
interface (yes, gobject supports Java-like
interfaces) which contains some more functions for manipulating the
contents. For example, the method:
entry.insert_text(text, position=0)
inserts text at the given position within
the entry.
The contents of the Entry can be
retrieved by using a call to the following method. This is useful in the
callback methods described below.
text = entry.get_text()
If we don't want the contents of the
Entry to be changed by someone typing into it, we can
change its editable state.
entry.set_editable(is_editable)
The above method allows us to toggle the editable state of the
Entry widget by passing in a TRUE
or FALSE value for the is_editable
argument.
If we are using the Entry where we don't
want the text entered to be visible, for example when a password is being
entered, we can use the following method, which also takes a boolean
flag.
entry.set_visibility(visible)
A region of the text may be set as selected by using the
following method. This would most often be used after setting some default
text in an Entry, making it easy for the user to
remove it.
entry.select_region(start, end)
If we want to be notified when the user has entered text, we can
connect to the "activate" or "changed" signal. Activate is raised when the
user hits the enter key within the Entry widget.
Changed is raised when the any change is made to the text, e.g. for every
character entered or removed.
The NoteBook Widget is a collection of
"pages" that overlap each other; each page contains different information
with only one page visible at a time. This widget has become more common
lately in GUI programming, and it is a good way to show blocks of similar
information that warrant separation in their display.
The first function call you will need to know, as you can probably
guess by now, is used to create a new notebook widget.
notebook = gtk.Notebook()
Once the notebook has been created, there are a number of
methods that operate on the notebook widget. Let's look at them
individually.
The first one we will look at is how to position the page
indicators. These page indicators or "tabs" as they are referred to, can be
positioned in four ways: top, bottom, left, or right.
notebook.set_tab_pos(pos)
pos will be one of the following, which are
pretty self explanatory:
POS_LEFT
POS_RIGHT
POS_TOP
POS_BOTTOM
POS_TOP is the default.
Next we will look at how to add pages to the notebook. There are
three ways to add pages to a NoteBook. Let's look at
the first two together as they are quite similar.
These methods add pages to the notebook by inserting them from
the back of the notebook (append), or the front of the notebook (prepend).
child is the widget that is placed within the notebook
page, and tab_label is the label for the page being
added. The child widget must be created separately, and
is typically a set of options setup within one of the other container
widgets, such as a table.
The final method for adding a page to the notebook contains all
of the properties of the previous two, but it allows you to specify what
position you want the page to be in the notebook.
notebook.insert_page(child, tab_label, position)
The parameters are the same as append()
and prepend() except it contains an extra
parameter, position. This parameter is used to
specify what place this page will be inserted into; the first page having
position zero.
Now that we know how to add a page, lets see how we can remove a
page from the notebook.
notebook.remove_page(page_num)
This method takes the page specified by
page_num and removes it from the widget pointed to by
notebook.
To find out what the current page is in a notebook use the
method:
page = notebook.get_current_page()
These next two methods are simple calls to move the notebook
page forward or backward. Simply provide the respective method call with the
notebook widget you wish to operate on.
notebook.next_page()
notebook.prev_page()
Note
When the notebook is currently on the last
page, and next_page() is called, nothing happens.
Likewise, if the notebook is on the first page, and
prev_page() is called, nothing happens.
This next method sets the "active" page. If you wish the
notebook to be opened to page 5 for example, you would use this method.
Without using this method, the notebook defaults to displaying the first
page.
notebook.set_current_page(page_num)
The next two methods add or remove the notebook page tabs and
the notebook border respectively.
The next method is useful when the you have a large number of
pages, and the tabs don't fit on the page. It allows the tabs to be scrolled
through using two arrow buttons.
notebook.set_scrollable(scrollable)
show_tabs,
show_border and scrollable can
be either TRUE or FALSE.
Now let's look at an example.
The notebook.py
program creates a window with a notebook and six buttons. The notebook
contains 11 pages, added in three different ways, appended, inserted, and
prepended. The buttons allow you rotate the tab positions, add or remove the
tabs and border, remove a page, change pages in both a forward and backward
manner, and exit the program.
Figure 10.9, “Notebook Example” illustrates the program display:
The return value from a connect() call is
an integer tag that identifies your callback. As stated above, you may have
as many callbacks per signal and per object as you need, and each will be
executed in turn, in the order they were attached.
This tag allows you to remove this callback from the list by using:
object.disconnect(id)
So, by passing in the tag returned by one of the signal connect
methods, you can disconnect a signal handler.
You can also temporarily disable signal handlers with the
signal_handler_block() and
signal_handler_unblock() pair of methods.
The aspect frame widget is like a frame widget, except that it
also enforces the aspect ratio (that is, the ratio of the width to the
height) of the child widget to have a certain value, adding extra space if
necessary. This is useful, for instance, if you want to preview a larger
image. The size of the preview should vary when the user resizes the window,
but the aspect ratio needs to always match the original image.
label specifies the text to be displayed
as the label. xalign and
yalign specify alignment as with gtk.Alignment
widgets. If obey_child is TRUE,
the aspect ratio of a child widget will match the aspect ratio of the ideal
size it requests. Otherwise, it is given by
ratio.
To change the options of an existing aspect frame, you can
use:
As an example, the aspectframe.py
program uses an AspectFrame to present a drawing area
whose aspect ratio will always be 2:1, no matter how the user resizes the
top-level window.
Figure 10.5, “Aspect Frame Example” illustrates the display of the
program:
where n is the index (starting from 0)
of the column to retrieve. A column can be removed using the method:
treeview.remove_column(column)
where column is a
TreeViewColumn in
treeview.
Rows that have child rows are displayed in the
TreeView with an expander arrow (see Figure 14.3, “CellRenderer Data Function”) that the user clicks on to hide or reveal the
child row(s). The column that the expander arrow is displayed in can be
changed using the method:
treeview.set_expander_column(column)
where column is a
TreeViewColumn in treeview. This method is useful
when you want the first column to not indent. For example, Figure 14.7, “Expander Arrow in Second Column” illustrates the expander arrow in the
second column:
Figure 14.7. Expander Arrow in Second Column
14.6.2. Expanding and Collapsing Child Rows
All the rows displayed in a TreeView can
be programmatically expanded or collapsed using the following
methods:
treeview.expand_all()
treeview.collapse_all()
These methods are useful if you want to initialize the
TreeView display to a known state. Individual rows
can be expanded or collapsed using:
where path is the tree path to a row in
treeview, and if open_all is TRUE
all descendant rows of path are expanded; otherwise
just the immediate children are expanded.
You can determine if a row is expanded using the method:
The following widget methods set and get the name of a
widget:
widget.set_name(name)
name = widget.get_name()
name is the string that will be associated
with the widget. This is useful for specifying styles
to be used with specific widgets within an application. The name of the
widget can be used to narrow the application of the style as opposed to
using the widget's class. See Chapter 23, GTK's rc Files for more
details.
Toggle buttons are derived from normal buttons and are very
similar, except they will always be in one of two states, alternated by a
click. They may be depressed, and when you click again, they will pop back
up. Click again, and they will pop back down.
Toggle buttons are the basis for check buttons and radio
buttons, as such, many of the calls used for toggle buttons are inherited by
radio and check buttons. I will point these out when we come to them.
Creating a new toggle button:
toggle_button = gtk.ToggleButton(label=None)
As you can imagine, these work identically to the normal button
widget calls. If no label is specified the button will be blank. The label
text will be parsed for '_'-prefixed mnemonic characters.
To retrieve the state of the toggle widget, including radio and
check buttons, we use a construct as shown in our example below. This tests
the state of the toggle, by calling the get_active()
method of the toggle button object. The signal of interest to us that is
emitted by toggle buttons (the toggle button, check button, and radio button
widgets) is the "toggled" signal. To check the state of these buttons, set
up a signal handler to catch the toggled signal, and access the object
attributes to determine its state. The callback will look something
like:
def toggle_button_callback(widget, data):
if widget.get_active():
# If control reaches here, the toggle button is down
else:
# If control reaches here, the toggle button is up
To force the state of a toggle button, and its children, the
radio and check buttons, use this method:
toggle_button.set_active(is_active)
The above method can be used to set the state of the toggle
button, and its children the radio and check buttons. Specifying a
TRUE or FALSE for the
is_active argument indicates whether the button
should be down (depressed) or up (released). When the toggle button is
created its default is up or FALSE.
Note that when you use the set_active()
method, and the state is actually changed, it causes the "clicked" and
"toggled" signals to be emitted from the button.
toggle_button.get_active()
This method returns the current state of the toggle button as a
boolean TRUE or FALSE value.
1 #!/usr/bin/env python
2
3 # example togglebutton.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 class ToggleButton:
10 # Our callback.
11 # The data passed to this method is printed to stdout
12 def callback(self, widget, data=None):
13 print "%s was toggled %s" % (data, ("OFF", "ON")[widget.get_active()])
14
15 # This callback quits the program
16 def delete_event(self, widget, event, data=None):
17 gtk.main_quit()
18 return False
19
20 def __init__(self):
21 # Create a new window
22 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
23
24 # Set the window title
25 self.window.set_title("Toggle Button")
26
27 # Set a handler for delete_event that immediately
28 # exits GTK.
29 self.window.connect("delete_event", self.delete_event)
30
31 # Sets the border width of the window.
32 self.window.set_border_width(20)
33
34 # Create a vertical box
35 vbox = gtk.VBox(True, 2)
36
37 # Put the vbox in the main window
38 self.window.add(vbox)
39
40 # Create first button
41 button = gtk.ToggleButton("toggle button 1")
42
43 # When the button is toggled, we call the "callback" method
44 # with a pointer to "button" as its argument
45 button.connect("toggled", self.callback, "toggle button 1")
46
47
48 # Insert button 1
49 vbox.pack_start(button, True, True, 2)
50
51 button.show()
52
53 # Create second button
54
55 button = gtk.ToggleButton("toggle button 2")
56
57 # When the button is toggled, we call the "callback" method
58 # with a pointer to "button 2" as its argument
59 button.connect("toggled", self.callback, "toggle button 2")
60 # Insert button 2
61 vbox.pack_start(button, True, True, 2)
62
63 button.show()
64
65 # Create "Quit" button
66 button = gtk.Button("Quit")
67
68 # When the button is clicked, we call the main_quit function
69 # and the program exits
70 button.connect("clicked", lambda wid: gtk.main_quit())
71
72 # Insert the quit button
73 vbox.pack_start(button, True, True, 2)
74
75 button.show()
76 vbox.show()
77 self.window.show()
78
79 def main():
80 gtk.main()
81 return 0
82
83 if __name__ == "__main__":
84 ToggleButton()
85 main()
The interesting lines are 12-13 which define the
callback() method that prints the toggle button
label and its state when it is toggled. Lines 45 and 59 connect the
"toggled" signal of the toggle buttons to the
callback() method.
pygtk2tutorial/sec-DrawingAreaWidgetAndDrawing.html 0100644 0001172 0000167 00000031620 10227357004 021613 0 ustar finlay fcf 24.3. The DrawingArea Widget, And Drawing
We now turn to the process of drawing on the screen. The widget
we use for this is the DrawingArea (see Chapter 12, Drawing Area) widget. A drawing area widget is
essentially an X window and nothing more. It is a blank canvas in which we
can draw whatever we like. A drawing area is created using the call:
darea = gtk.DrawingArea()
A default size for the widget can be specified by
calling:
darea.set_size_request(width, height)
This default size can be overridden, as is true for all widgets,
by calling the set_size_request() method, and that,
in turn, can be overridden if the user manually resizes the the window
containing the drawing area.
It should be noted that when we create a
DrawingArea widget, we are completely responsible for
drawing the contents. If our window is obscured then uncovered, we get an
exposure event and must redraw what was previously hidden.
Having to remember everything that was drawn on the screen so we
can properly redraw it can, to say the least, be a nuisance. In addition, it
can be visually distracting if portions of the window are cleared, then
redrawn step by step. The solution to this problem is to use an offscreen
backing pixmap. Instead of drawing directly to the screen, we draw to an
image stored in server memory but not displayed, then when the image changes
or new portions of the image are displayed, we copy the relevant portions
onto the screen.
To create an offscreen pixmap, we call the function:
The window parameter specifies a
gtk.gdk.Window that this pixmap takes some of its
properties from. width and
height specify the size of the
pixmap. depth specifies the
color depth, that is the number of bits per pixel, for the new window. If
the depth is specified as -1 or omitted, it will
match the depth of window.
We create the pixmap in our "configure_event" handler. This
event is generated whenever the window changes size, including when it is
originally created.
32 # Create a new backing pixmap of the appropriate size
33 def configure_event(widget, event):
34 global pixmap
35
36 x, y, width, height = widget.get_allocation()
37 pixmap = gtk.gdk.Pixmap(widget.window, width, height)
38 pixmap.draw_rectangle(widget.get_style().white_gc,
39 True, 0, 0, width, height)
40
41 return True
The call to draw_rectangle() clears the
pixmap initially to white. We'll say more about that in a moment.
Our exposure event handler then simply copies the relevant
portion of the pixmap onto the drawing area (widget) using the
draw_pixmap() method. (We determine the area we
need to redraw by using the event.area attribute of
the exposure event):
43 # Redraw the screen from the backing pixmap
44 def expose_event(widget, event):
45 x , y, width, height = event.area
46 widget.window.draw_drawable(widget.get_style().fg_gc[gtk.STATE_NORMAL],
47 pixmap, x, y, x, y, width, height)
48 return False
We've now seen how to keep the screen up to date with our
pixmap, but how do we actually draw interesting stuff on our pixmap? There
are a large number of calls in PyGTK for drawing on drawables. A drawable is
simply something that can be drawn upon. It can be a window, a pixmap, or a
bitmap (a black and white image). We've already seen two such calls above,
draw_rectangle() and
draw_pixmap(). The complete list is:
The drawing area methods are the same as the drawable drawing
methods so you can use the methods described in Section 12.2, “Drawing Methods” for further details on these
methods. These methods all share the same first arguments. The first
argument is a graphics context (gc).
A graphics context encapsulates information about things such as
foreground and background color and line width. PyGTK has a full set of
functions for creating and modifying graphics contexts, but to keep things
simple we'll just use predefined graphics contexts. See Section 12.1, “Graphics Context” section for more information on
graphics contexts. Each widget has an associated style. (Which can be
modified in a gtkrc file, see Chapter 23, GTK's rc Files.) This, among other things, stores a number
of graphics contexts. Some examples of accessing these graphics contexts
are:
For instance, for STATE_SELECTED the default
foreground color is white and the default background color, dark
blue.
Our function draw_brush(), which does the
actual drawing on the pixmap, is then:
50 # Draw a rectangle on the screen
51 def draw_brush(widget, x, y):
52 rect = (int(x-5), int(y-5), 10, 10)
53 pixmap.draw_rectangle(widget.get_style().black_gc, True,
54 rect[0], rect[1], rect[2], rect[3])
55 widget.queue_draw_area(rect[0], rect[1], rect[2], rect[3])
After we draw the rectangle representing the brush onto the
pixmap, we call the function:
widget.queue_draw_area(x, y, width, height)
which notifies X that the area given needs to be updated. X will
eventually generate an expose event (possibly combining the areas passed in
several calls to draw()) which will cause our expose
event handler to copy the relevant portions to the screen.
We have now covered the entire drawing program except for a few
mundane details like creating the main window.
The Dialog widget is very simple, and is
actually just a window with a few things pre-packed into it for you. It
simply creates a window, and then packs a VBox into
the top, which contains a separator and then an HBox
called the "action_area".
The Dialog widget can be used for pop-up
messages to the user, and other similar tasks. It is really basic, and there
is only one function for the dialog box, which is:
where title is the text to be used in the
titlebar, parent is the main application window and
flags set various modes of operation for the
dialog:
DIALOG_MODAL - make the dialog modal
DIALOG_DESTROY_WITH_PARENT - destroy dialog when its parent is destroyed
DIALOG_NO_SEPARATOR - omit the separator between the vbox and the action_area
The buttons argument is a tuple of button
text and response pairs. All arguments have defaults and can be specified
using keywords.
This will create the dialog box, and it is now up to you to use
it. You could pack a button in the action_area:
And you could add to the vbox area by
packing, for instance, a label in it, try something like this:
label = gtk.Label("Dialogs are groovy")
dialog.vbox.pack_start(label, TRUE, TRUE, 0)
label.show()
As an example in using the dialog box, you could put two buttons
in the action_area, a Cancel
button and an Ok button, and a label in the
vbox area, asking the user a question or giving an
error, etc. Then you could attach a different signal to each of the buttons
and perform the operation the user selects.
If the simple functionality provided by the default vertical and
horizontal boxes in the two areas doesn't give you enough control for your
application, then you can simply pack another layout widget into the boxes
provided. For example, you could pack a table into the vertical box.
The ComboBox replaces the
OptionMenu with a powerful widget that uses a
TreeModel (usually a
ListStore) to provide the list items to display. The
ComboBox implements the
CellLayout interface that provides a number of
methods for managing the display of the list items. One or more
CellRenderers can be packed into a
ComboBox to customize the list item display.
16.2.1.1. Basic ComboBox Use
The easy way to create and populate a
ComboBox is to use the convenience function:
combobox = gtk.combo_box_new_text()
This function creates a ComboBox and its
associated ListStore and packs it with a
CellRendererText. The following convenience methods
are used to populate or remove the contents of the
ComboBox and its
ListStore:
where text is the string to be added to the
ComboBox and position is the
index where text is to be inserted or removed. In
most cases the convenience function and methods are all you need.
Unfortunately, the GTK+ developers did not
provide a convenience method to retrieve the active text. That would seem to
be a useful method. You'll have to create your own similar to:
def get_active_text(combobox):
model = combobox.get_model()
active = combobox.get_active()
if active < 0:
return None
return model[active][0]
The index of the active item is retrieved using the method:
active = combobox.get_active()
The active item can be set using the method:
combobox.set_active(index)
where index is an integer larger than
-2. If index is -1 there is no active item and the
ComboBox display will be blank. If index is less than
-1, the call will be ignored. If index is greater
than -1 the list item with that index value will be displayed.
You can connect to the "changed" signal of a
ComboBox to be notified when the active item has been
changed. The signature of the "changed" handler is:
def changed_cb(combobox, ...):
where ... represents the zero or more
arguments passed to the GObject.connect()
method.
16.2.1.2. Advanced ComboBox Use
Creating a ComboBox using the
gtk.combo_box_new_text() function is roughly
equivalent to the following code:
The ComboBox list items can be displayed
in a grid if you have a large number of items to display. Otherwise the list
will have scroll arrows if the entire list cannot be displayed. The
following method is used to set the number of columns to display:
combobox.set_wrap_width(width)
where width is the number of columns of
the grid displaying the list items. For example, the comboboxwrap.py program displays a
list of 50 items in 5 columns. Figure 16.6, “ComboBox with Wrapped Layout”
illustrates the program in operation:
Figure 16.6. ComboBox with Wrapped Layout
With a large number of items, say more than 50, the use of the
set_wrap_width() method will have poor performance
because of the computation for the grid layout. To get a feel for the affect
modify the comboboxwrap.py
program line 18 to display 150 items.
for n in range(150):
Run the program and get a time estimate for startup. Then modify
it by commenting out line 17:
#combobox.set_wrap_width(5)
Run and time it again. It should start up significantly
faster. My experience is about 20 times faster.
In addition to the get_active() method
described above, you can retrieve a TreeIter pointing
at the active row by using the method:
iter = combobox.get_active_iter()
You can also set the active list item using a
TreeIter with the method:
combobox.set_active_iter(iter)
The set_row_span_column() and
set_column_span_column() methods are supposed to
allow the specification of a TreeModel column number
that contains the number of rows or columns that the list item is supposed
to span in a grid layout. Unfortunately, in GTK+ 2.4 these methods are
broken.
Since the ComboBox implements the
CellLayout interface which has similar capabilities
as the TreeViewColumn (see Section 14.5, “TreeViewColumns” for more information). Briefly, the
interface provides:
set attributes for the CellRenderer
specified by cell. The
add_attribute() method takes a string
attribute name (e.g. 'text') and an integer
column number of the column in the
TreeModel to use to set
attribute. The additional arguments to the
set_attributes() method are
attribute=column pairs (e.g text=1).
16.2.2. ComboBoxEntry Widgets
The ComboBoxEntry widget replaces the
Combo widget. It is subclassed from the
ComboBox widget and contains a child
Entry widget that has its contents set by selecting
an item in the dropdown list or by direct text entry either from the
keyboard or by pasting from a Clipboard or a
selection.
16.2.2.1. Basic ComboBoxEntry Use
Like the ComboBox, the
ComboBoxEntry can be created using the convenience
function:
You can retrieve the Entry text using its
get_text() method.
Like the ComboBox, you can track changes
in the active list item by connecting to the "changed"
signal. Unfortunately, this doesn't help track changes to the text in the
Entry child that are direct entry. When a direct
entry is made to the child Entry widget the "changed"
signal will be emitted but the index returned by the
get_active() method will be -1. To track all
changes to the Entry text, you'll have to use the
Entry "changed" signal. For example:
will print out the text after every change in the child
Entry widget. For example, the comboboxentrybasic.py program
demonstrates the use of the convenience API. Figure 16.7, “Basic ComboBoxEntry” illustrates the program in
operation:
Figure 16.7. Basic ComboBoxEntry
Note that when the Entry text is changed
due to the selection of a dropdown list item the "changed" handler is called
twice: once when the text is cleared; and, once when the text is set with
the selected list item text.
where model is a
TreeModel and column is the
number of the column in model to use for setting the
list items. If column is not specified the default value is -1 which means
the text column is unset.
Creating a ComboBoxEntry using the
convenience function gtk.combo_box_entry_new_text() is
equivalent to the following:
The text column can also be retrieved and set using the
"text-column" property. See Section 16.2.1.2, “Advanced ComboBox Use” for
more information on the advanced use of the
ComboBoxEntry.
Note
Your application must set the text column for the
ComboBoxEntry to set the Entry
contents from the dropdown list. The text column can only be set once,
either by using the constructor or by using the
set_text_column() method.
When a ComboBoxEntry is created it is
packed with a new CellRendererText which is not
accessible. The 'text' attribute for the
CellRendererText has to be set as a side effect of
setting the text column using the set_text_column()
method. You can pack additional CellRenderers into a
ComboBoxEntry for display in the dropdown list. See
Section 16.2.1.2, “Advanced ComboBox Use” for more information.
A ColorButton widget provides a convenient
way of displaying a color in a button that can be clicked to open a
ColorSelectionDialog. It's useful for displaying and
setting colors in a user preference dialog. A
ColorButton takes care of setting up, displaying and
retrieving the result of a ColorSelectionDialog. A
ColorButton is created using the constructor:
The initial color can be specified using the
color parameter or set later using the method:
colorbutton.set_color(color)
The title for the ColorSelectionDialog that
is displayed when the button is clicked can be set and retrieved using the
methods:
colorbutton.set_title(title)
title = colorbutton.get_title()
The opacity of the color is set using the alpha channel. The
following methods get and set the color opacity in the range from 0
(transparent) to 65535 (opaque):
By default the alpha is ignored because the "use_alpha" property
is FALSE. The value of the "use_alpha" property can be
set and retrieved using the method:
If "use_alpha" is TRUE the
ColorSelectionDialog displays a slider for setting
the opacity and displays the color using a checkerboard background.
You can track changes in the selected color by connecting to the
"color-set" signal that is emitted when the user sets the color. The signal
callback signature is:
Like the ColorButton, the
FontButton is a convenience widget that provides a
display of the currently selected font and, when clicked, opens a
FontSelectionDialog. A
FontButton takes care of setting up, displaying and
retrieving the result of a FontSelectionDialog. A
FontButton is created using the constructor:
fontbutton = gtk.FontButton(fontname=None)
where fontname is a string specifying the
current font for the FontSelectionDialog. For example
the font name can be specified like 'Sans 12', 'Sans Bold 14', or 'Monospace
Italic 14'. You need to specify the font family and size at minimum.
The current font can also be set and retrieved using the following
methods:
result = fontbutton.set_font_name(fontname)
fontname = fontbutton.get_font_name()
where result returns
TRUE or FALSE to indicate whether the
font was successfully set. The FontButton has a
number of properties and associated methods that affect the display of the
current font in the FontButton. The "show-size" and
show-style" properties contain boolean values that control whether the font
size and style will be displayed in the button label. The following methods
set and retrieve the value of these properties:
Alternatively, you can have the current font size and style used
by the label to directly illustrate the font selection. The "use-size" and
"use-font" properties and the associated methods:
Using the current font in the label seems like a useful
illustration technique in spite of the inevitable changes in size of the
button but using the selected size doesn't seem as useful especially when
using really large or small font sizes. Note if you set "use-font" or
"use-size" to TRUE and later set them to
FALSE, the last set font and size will be retained. For
example, if "use-font" and "use-size" are TRUE and the
current font is Monospace Italic 20, the
FontButton label is displayed using
Monospace Italic 20; then if "use-font" and "use-size"
are set to FALSE and then the current font is changed to
Sans 12 the label will still be displayed in
Monospace Italic 20. Use the example program fontbutton.py to see how this
works.
Finally, the title of the
FontSelectionDialog can be set and retrieved using
the methods:
fontbutton.set_title(title)
title = fontbutton.get_title()
Like the ColorButton, you can track changes
in the current font by connecting to the "font-set" signal that is emitted
when the user sets the font. The signal callback signature is:
def font_set_cb(fontbutton, user_data):
The example program fontbutton.py illustrates the use of a
FontButton. You can set the "use-font", "use-size",
"show-size" and "show-style" properties using toggle buttons. Figure 16.9, “FontButton Example” shows the program in operation.
invoke gtk.* - one of various functions to create a
new widget. These are all detailed in this section.
Connect all signals and events we wish to use to
the appropriate handlers.
Set the attributes of the
widget.
Pack the widget into a container using the
appropriate call such as gtk.Container.add() or gtk.Box.pack_start()
.
gtk.Widget.show() the widget.
show() lets GTK know that we are done setting
the attributes of the widget, and it is ready to be displayed. You may also
use gtk.Widget.hide() to make it disappear again. The
order in which you show the widgets is not important, but I suggest showing
the window last so the whole window pops up at once rather than seeing the
individual widgets come up on the screen as they're formed. The children of
a widget (a window is a widget too) will not be displayed until the window
itself is shown using the show() method.
5.1. Widget Hierarchy
For your reference, here is the class hierarchy tree used to
implement widgets. (Deprecated widgets and auxiliary classes have been
omitted.)
All of the GTK+ range widgets react to mouse clicks in more or
less the same way. Clicking button-1 in the
trough will cause its adjustment's page_increment to
be added or subtracted from its value, and the slider
to be moved accordingly. Clicking mouse button-2
in the trough will jump the slider to the point at which the button was
clicked. Clicking any button on a scrollbar's arrows will cause its
adjustment's value to change step_increment at a
time.
Scrollbars are not focusable, thus have no key bindings. The key
bindings for the other range widgets (which are, of course, only active when
the widget has focus) do not differentiate between horizontal and vertical
range widgets.
All range widgets can be operated with the left
arrow, right arrow, up arrow and
down arrow keys, as well as with the Page
Up and Page Down keys. The arrows move the slider
by step_increment, while Page Up and
Page Down move it by
page_increment.
The user can also move the slider all the way to one end or the
other of the trough using the keyboard. This is done with the
Home and End keys.
pygtk2tutorial/ch-NewInPyGTK2.4.html 0100644 0001172 0000167 00000150723 10227356777 016315 0 ustar finlay fcf Chapter 16. New Widgets in PyGTK 2.4
Quite a few new widgets and support objects were added in PyGTK
2.4 including:
Action,
RadioAction, ToggleAction -
objects that represent actions that a user can take. Actions contain
information to be used to create proxy widgets ( for example, icons, menu
items and toolbar items).
ActionGroup - an object containing
Actions that have some relationship, for example, actions to open, close and
print a document.
Border - an object containing the
values for a border.
ColorButton - a button used to
launch a ColorSelectionDialog.
ComboBox - a widget providing a list
of items to choose from. It replaces the
OptionMenu.
ComboBoxEntry - a widget providing a
text entry field with a dropdown list of items to choose from. It replaces
the Combo.
EntryCompletion - an object
providing completion for an Entry widget.
Expander - a container that can show
and hide its child in response to its button click.
FileChooser - an interface for
choosing files.
FileChooserWidget - a widget
implementing the FileChooser interface. It replaces
the FileSelection widget.
FileChooserDialog - a dialog used
for "File/Open" and "File/Save" actions. It replaces the
FileSelectionDialog.
FileFilter - an object used to
filter files based on an internal set of rules.
FontButton - a button that launches
the FontSelectionDialog.
IconInfo - an object containing
information about an icon in an IconTheme.
IconTheme - an object providing
lookup of icons by name and size.
ToolItem,
ToolButton, RadioToolButton,
SeparatorToolItem,
ToggleToolButton - widgets that can be added to a
Toolbar. These replace the previous
Toolbar items.
TreeModelFilter - an object providing
a powerful mechanism for revising the representation of an underlying
TreeModel. This is described in Section 14.10.2, “TreeModelFilter”.
UIManager - an object providing a
way to construct menus and toolbars from an XML UI description. It also has
methods to manage the merging and separation of multiple UI
descriptions.
16.1. The Action and ActionGroup Objects
The Action and
ActionGroup objects work together to provide the
images, text, callbacks and accelerators for your application menus and
toolbars. The UIManager uses
Actions and ActionGroups to
build the menubars and toolbars automatically based on a XML
specification. It's much easier to create and populate menus and toolbars
using the UIManager described in a later section. The
following sections on the Action and
ActionGroup objects describe how to directly apply
these objects but I recommend using the UIManager
whenever possible.
16.1.1. Actions
An Action object represents an action that
the user can take using an application user interface. It contains
information used by proxy UI elements (for example,
MenuItems or Toolbar items) to
present the action to the user. There are two subclasses of
Action:
ToggleAction
An Action that can be toggled
between two states.
RadioAction
An Action that can be grouped so
that only one can be active.
For example, the standard File->Quit menu item can be represented
with an icon, mnemonic text and accelerator. When activated, the menu item
triggers a callback that could exit the application. Likewise a
ToolbarQuit button could
share the icon, mnemonic text and callback. Both of these UI elements could
be proxies of the same Action.
Ordinary Button,
ToggleButton and RadioButton
widgets can also act as proxies for an Action though
there is no support for these in the
UIManager.
name is a string used to identify the
Action in an ActionGroup or in
a UIManager
specification. label and
tooltip are strings used as the label and tooltip in
proxy widgets. If label is None
then the stock_id must be a string specifying a Stock
Item to get the label from. If tooltip is
None the Action will not have a
tooltip.
As we'll see in Section 16.1.2, “ActionGroups” it's
much easier to create Action objects using the
ActionGroup convenience methods:
More about these later but first I'll describe how to use an
Action with a Button to
illustrate the basic operations of connecting an
Action to a proxy widget.
16.1.1.2. Using Actions
The basic procedure for using an Action
with a Button proxy is illustrated by the simpleaction.py example program. The
Button is connected to the
Action using the method:
action.connect_proxy(proxy)
where proxy is a MenuItem,
ToolItem or Button
widget.
An Action has one signal the "activate"
signal that is triggered when the Action is activated
usually as the result of a proxy widget being activated (for example a
ToolButton is clicked). You just have connect a
callback to this signal to handle the activation of any of the proxy
widgets.
1 #!/usr/bin/env python
2
3 import pygtk
4 pygtk.require('2.0')
5 import gtk
6
7 class SimpleAction:
8 def __init__(self):
9 # Create the toplevel window
10 window = gtk.Window()
11 window.set_size_request(70, 30)
12 window.connect('destroy', lambda w: gtk.main_quit())
13
14 # Create an accelerator group
15 accelgroup = gtk.AccelGroup()
16 # Add the accelerator group to the toplevel window
17 window.add_accel_group(accelgroup)
18
19 # Create an action for quitting the program using a stock item
20 action = gtk.Action('Quit', None, None, gtk.STOCK_QUIT)
21 # Connect a callback to the action
22 action.connect('activate', self.quit_cb)
23
24 # Create an ActionGroup named SimpleAction
25 actiongroup = gtk.ActionGroup('SimpleAction')
26 # Add the action to the actiongroup with an accelerator
27 # None means use the stock item accelerator
28 actiongroup.add_action_with_accel(action, None)
29
30 # Have the action use accelgroup
31 action.set_accel_group(accelgroup)
32
33 # Connect the accelerator to the action
34 action.connect_accelerator()
35
36 # Create the button to use as the action proxy widget
37 quitbutton = gtk.Button()
38 # add it to the window
39 window.add(quitbutton)
40
41 # Connect the action to its proxy widget
42 action.connect_proxy(quitbutton)
43
44 window.show_all()
45 return
46
47 def quit_cb(self, b):
48 print 'Quitting program'
49 gtk.main_quit()
50
51 if __name__ == '__main__':
52 sa = SimpleAction()
53 gtk.main()
The example creates an Action (line 20)
that uses a Stock Item to provide the label text with mnemonic, icon,
accelerator and translation domain. If a Stock Item is not used you'll need
to specify a label instead. Line 22 connects the "activate" signal of
action to the self.quit_cb()
method so that it is invoked when the Action is
activated by quitbutton. Line 42 connects
quitbutton to action as a
proxy widget. When quitbutton is clicked it will
activate action and thereby invoke the
self.quit_cb() method. The simpleaction.py example uses quite a
bit of code (lines 15, 17, 31 and 34 to setup the accelerator for the
Button. The procedure is similar for
MenuItems and ToolbarToolItems.
In the previous section we saw that an existing widget could be
connected to an Action as a proxy. In this section
we'll see how a proxy widget can be created using the
Action methods:
The basicaction.py
example illustrates a MenuItem,
ToolButton and a Button
sharing an Action. The
MenuItem and the ToolButton
are created using the above methods. The basicaction.py example program source
code is:
1 #!/usr/bin/env python
2
3 import pygtk
4 pygtk.require('2.0')
5 import gtk
6
7 class BasicAction:
8 def __init__(self):
9 # Create the toplevel window
10 window = gtk.Window()
11 window.connect('destroy', lambda w: gtk.main_quit())
12 vbox = gtk.VBox()
13 vbox.show()
14 window.add(vbox)
15
16 # Create an accelerator group
17 accelgroup = gtk.AccelGroup()
18 # Add the accelerator group to the toplevel window
19 window.add_accel_group(accelgroup)
20
21 # Create an action for quitting the program using a stock item
22 action = gtk.Action('Quit', '_Quit me!', 'Quit the Program',
23 gtk.STOCK_QUIT)
24 action.set_property('short-label', '_Quit')
25 # Connect a callback to the action
26 action.connect('activate', self.quit_cb)
27
28 # Create an ActionGroup named BasicAction
29 actiongroup = gtk.ActionGroup('BasicAction')
30 # Add the action to the actiongroup with an accelerator
31 # None means use the stock item accelerator
32 actiongroup.add_action_with_accel(action, None)
33
34 # Have the action use accelgroup
35 action.set_accel_group(accelgroup)
36
37 # Create a MenuBar
38 menubar = gtk.MenuBar()
39 menubar.show()
40 vbox.pack_start(menubar, False)
41
42 # Create the File Action and MenuItem
43 file_action = gtk.Action('File', '_File', None, None)
44 actiongroup.add_action(file_action)
45 file_menuitem = file_action.create_menu_item()
46 menubar.append(file_menuitem)
47
48 # Create the File Menu
49 file_menu = gtk.Menu()
50 file_menuitem.set_submenu(file_menu)
51
52 # Create a proxy MenuItem
53 menuitem = action.create_menu_item()
54 file_menu.append(menuitem)
55
56 # Create a Toolbar
57 toolbar = gtk.Toolbar()
58 toolbar.show()
59 vbox.pack_start(toolbar, False)
60
61 # Create a proxy ToolItem
62 toolitem = action.create_tool_item()
63 toolbar.insert(toolitem, 0)
64
65 # Create and pack a Label
66 label = gtk.Label('''
67 Select File->Quit me! or
68 click the toolbar Quit button or
69 click the Quit button below or
70 press Control+q
71 to quit.
72 ''')
73 label.show()
74 vbox.pack_start(label)
75
76 # Create a button to use as another proxy widget
77 quitbutton = gtk.Button()
78 # add it to the window
79 vbox.pack_start(quitbutton, False)
80
81 # Connect the action to its proxy widget
82 action.connect_proxy(quitbutton)
83 # Have to set tooltip after toolitem is added to toolbar
84 action.set_property('tooltip', action.get_property('tooltip'))
85 tooltips = gtk.Tooltips()
86 tooltips.set_tip(quitbutton, action.get_property('tooltip'))
87
88 window.show()
89 return
90
91 def quit_cb(self, b):
92 print 'Quitting program'
93 gtk.main_quit()
94
95 if __name__ == '__main__':
96 ba = BasicAction()
97 gtk.main()
This example introduces an ActionGroup to
hold the Actions used in the program. Section 16.1.2, “ActionGroups” will go into more detail on the use of
ActionGroups.
The code in lines 9-14 sets up a top level window containing a
VBox. Lines 16-35 set up the "Quit"
Action similar to that in the simpleaction.py example program and
add it with the gtk.STOCK_QUIT Stock Item accelerator
(line 32) to the "BasicAction" ActionGroup (created
in line 29). Note that, unlike the simpleaction.py example program, you
don't have to call the connect_accelerator() method
for the action since it is called automatically when the
create_menu_item() method is called in line
53.
Lines 38-40 create a MenuBar and pack it
into the VBox. Lines 43-44 create an
Action (file_action) for the
File menu and add it to
actiongroup. The File and
Quit menu items are created in lines 45 and 53
and added to menubar and
file_menu respectively in lines 46 and 54.
Likewise a Toolbar is created and added
to the VBox in lines 57-59. The proxy
ToolItem is created and added to
toolbar in lines 62-63. Note the
Action tooltip must be set (line 84) after the
ToolItem is added to the
Toolbar for it to be used. Also the
Button tooltip must be added manually (lines
84-86).
A proxy widget can be disconnected from an
Action by using the method:
action.disconnect_proxy(proxy)
16.1.1.4. Action Properties
An Action has a number of properties that
control the display and function of its proxy widgets. The most important of
these are the "sensitive" and "visible" properties. The "sensitive" property
determines the sensitivity of the proxy widgets. If "sensitive" is
FALSE the proxy widgets are not activatable and will
usually be displayed "grayed out". Likewise, the "visible" property
determines whether the proxy widgets will be visible. If an
Action's "visible" property is
FALSE its proxy widgets will be hidden.
As we'll see in the next section, an
Action's sensitivity or visibility is also controlled
by the sensitivity or visibility of the ActionGroup
it belongs to. Therefore, for an Action to be
sensitive (or visible) both it and its ActionGroup
must be sensitive (or visible). To determine the effective sensitivity or
visibility of an Action you should use the following
methods:
result = action.is_sensitive()
result = action.is_visible()
The name assigned to an Action is
contained in its "name" property which is set when the
Action is created. You can retrieve that name using
the method:
name = action.get_name()
Other properties that control the display of the proxy widgets
of an Action include:
"hide-if-empty"
If TRUE, empty menu proxies for this
action are hidden.
"is-important"
If TRUE,
ToolItem proxies for this action show text in
gtk.TOOLBAR_BOTH_HORIZ mode.
"visible-horizontal"
If TRUE, the
ToolItem is visible when the toolbar is in a
horizontal orientation.
"visible-vertical"
If TRUE, the
ToolItem is visible when the toolbar is in a vertical
orientation.
Other properties of interest include:
"label"
The label used for menu items and buttons that activate
this action.
"short-label"
A shorter label that may be used on toolbar buttons and
buttons.
"stock-id"
The Stock Item to be used to retrieve the icon, label
and accelerator to be used in widgets representing this action.
"tooltip"
A tooltip for this action.
Note that the basicaction.py example program
overrides the gtk.STOCK_QUIT label with "_Quit me!" and
sets the "short-label" property to "_Quit". The short label is used for the
ToolButton and the Button
labels but the full label is used for the MenuItem
label. Also note that the tooltip cannot be set on a
ToolItem until it is added to a
Toolbar.
16.1.1.5. Actions and Accelerators
An Action has three methods that are used
to set up an accelerator:
These, in conjunction with the
gtk.ActionGroup.add_action_with_accel() method,
should cover most cases of accelerator set up.
An AccelGroup must always be set for an
Action. The set_accel_path()
method is called by the
gtk.ActionGroup.add_action_with_accel() method. If
set_accel_path() is used the accelerator path
should match the default format:
"<Actions>/actiongroup_name/action_name". Finally, the
connect_accelerator() method is called to complete
the accelerator set up.
Note
An Action must have an
AccelGroup and an accelerator path associated with it
before connect_accelerator() is called.
Since the connect_accelerator() method
can be called several times (i.e. once for each proxy widget), the number of
calls is counted so that an equal number of
disconnect_accelerator() calls must be made before
removing the accelerator.
As illustrated in the previous example programs, an
Action accelerator can be used by all the proxy
widgets. An Action should be part of an
ActionGroup in order to use the default accelerator
path that has the format:
"<Actions>/actiongroup_name/action_name". The easiest way to add an
accelerator is to use the
gtk.ActionGroup.add_action_with_accel() method and
the following general procedure:
Create an AccelGroup and add it to
the top level window.
Create a new ActionGroup
Create an Action specifying a
Stock Item with an accelerator.
Add the Action to the
ActionGroup using the
gtk.ActionGroup.add_action_with_accel() method
specifying None to use the Stock Item accelerator or an
accelerator string acceptable to
gtk.accelerator_parse().
Set the AccelGroup for the
Action using the
gtk.Action.set_accel_group() method.
Complete the accelerator set up using the
gtk.Action.connect_accelerator() method.
Any proxy widgets created by or connected to the
Action will use the accelerator.
16.1.1.6. Toggle Actions
As mentioned previously a ToggleAction is
a subclass of Action that can be toggled between two
states. The constructor for a ToggleAction takes the
same parameters as an Action:
set and get the current state of
toggleaction. is_active is a
boolean value.
You can connect to the "toggled" signal specifying a callback
with the signature:
def toggled_cb(toggleaction, user_data)
The "toggled" signal is emitted when the
ToggleAction changes state.
A MenuItem proxy widget of a
ToggleAction will be displayed like a
CheckMenuItem by default. To have the proxy
MenuItem displayed like a
RadioMenuItem set the "draw-as-radio" property to
TRUE using the method:
toggleaction.set_draw_as_radio(draw_as_radio)
You can use the following method to determine whether the
ToggleActionMenuItems will be
displayed like RadioMenuItems:
draw_as_radio = toggleaction.get_draw_as_radio()
16.1.1.7. Radio Actions
A RadioAction is a subclass of
ToggleAction that can be grouped so that only one
RadioAction is active at a time. The corresponding
proxy widgets are the RadioMenuItem and
RadioToolButton.
The constructor for a RadioAction takes
the same arguments as an Action with the addition of
a unique integer value that is used to identify the active
RadioAction in a group:
The group for a RadioAction can be set
using the method:
radioaction.set_group(group)
where group is another
RadioAction that radioaction
should be grouped with. The group containing a
RadioAction can be retrieved using the method:
group = radioaction.get_group()
that returns a list of the group of
RadioAction objects that includes
radioaction.
The value of the currently active group member can retrieved
using the method:
active_value = radioaction.get_current_value()
You can connect a callback to the "changed" signal to be
notified when the active member of the RadioAction
group has been changed. Note that you only have to connect to one of the
RadioAction objects to track changes. The callback
signature is:
def changed_cb(radioaction, current, user_data)
where current is the currently active
RadioAction in the group.
16.1.1.8. An Actions Example
The actions.py example
program illustrates the use of the Action,
ToggleAction and RadioAction
objects. Figure 16.3, “Actions Example” displays the example
program in operation:
Figure 16.3. Actions Example
This example is similar enough to the basicaction.py example program that a
detailed description is not necessary.
16.1.2. ActionGroups
As mentioned in the previous section, related
Action objects should be added to an
ActionGroup to provide common control over their
visibility and sensitivity. For example, in a text processing application
the menu items and toolbar buttons for specifying the text justification
could be contained in an ActionGroup. A user
interface is expected to have multiple ActionGroup
objects that cover various aspects of the application. For example, global
actions like creating new documents, opening and saving a document and
quitting the application likely form one ActionGroup
while actions such as modifying the view of the document would form
another.
16.1.2.1. Creating ActionGroups
An ActionGroup is created using the
constructor:
actiongroup = gtk.ActionGroup(name)
where name is a unique name for the
ActionGroup. The name should be unique because it is
used to form the default accelerator path for its
Action objects.
The ActionGroup name can be retrieved
using the method:
name = actiongroup.get_name()
or by retrieving the contents of the "name" property.
16.1.2.2. Adding Actions
As illustrated in Section 16.1.1, “Actions” an
existing Action can be added to an
ActionGroup using one of the methods:
where action is the
Action to be added and
accelerator is a string accelerator specification
acceptable to gtk.accelerator_parse(). If
accelerator is None the
accelerator (if any) associated with the "stock-id" property of
action will be used. As previously noted the
add_action_wih_accel() method is preferred if you
want to use accelerators.
The ActionGroup offers three convenience
methods that make the job of creating and adding
Action objects to an
ActionGroup much easier:
The entries parameter is a sequence of
action entry tuples that provide the information used to create the actions
that are added to the ActionGroup. The
RadioAction with the value of
value is initially set
active. on_change is a callback that is connected to
the "changed" signal of the first RadioAction in the
group. The signature of on_changed is:
The stock id for the action. Optional with a default
value of None if a label is specified.
The label for the action. Optional with a default value of
None if a stock id is specified.
The accelerator for the action, in the format understood by
the gtk.accelerator_parse() function. Optional with a
default value of None.
The tooltip for the action. Optional with a default value
of None.
The callback function invoked when the action is
activated. Optional with a default value of
None.
You must minimally specify a value for the
name field and a value in either the stock
id field or the label field. If you
specify a label then you can specify None for the stock
id if you aren't using one. For example the following method call:
actiongroup.add_actions([('quit', gtk.STOCK_QUIT, '_Quit me!', None,
'Quit the Program', quit_cb)])
adds an action to actiongroup for
exiting a program.
The entry tuples for the ToggleAction
objects are similar to the Action entry tuples except
there is an additional optional flag field containing
a boolean value indicating whether the action is active. The default value
for the flag field is FALSE. For
example the following method call:
actiongroup.add_toggle_actions([('mute, None, '_Mute', '<control>m',
'Mute the volume', mute_cb, True)])
adds a ToggleAction to
actiongroup and sets it to be initially
active.
The entry tuples for the RadioAction
objects are similar to the Action entry tuples but
specify a value field instead of a
callback field:
The name of the action. Must be specified.
The stock id for the action. Optional with a default
value of None if a label is specified.
The label for the action.Optional with a default value of
None if a stock id is specified.
The accelerator for the action, in the format understood by
the gtk.accelerator_parse() function. Optional with a
default value of None.
The tooltip for the action. Optional with a default value
of None.
The value to set on the radio action. Optional with a
default value of 0. Should always be specified in
applications.
creates three RadioAction objects and
sets the initial active action to 'am' and the callback that is invoked when
any of the actions is activated to changed_cb.
16.1.2.3. Retrieving Actions
An Action can be retrieved by name from
an ActionGroup by using the method:
action = actiongroup.get_action(action_name)
A list of all the Action objects
contained in an ActionGroup can be retrieved using
the method:
actionlist = actiongroup.list_actions()
16.1.2.4. Controlling Actions
The sensitivity and visibility of all
Action objects in an
ActionGroup can be controlled by setting the
associated property values. The following convenience methods get and set
the properties:
Finally you can remove an Action from an
ActionGroup using the method:
actiongroup.remove_action(action)
16.1.2.5. An ActionGroup Example
The actiongroup.py
example program duplicates the menubar and toolbar of the actions.py example program using the
ActionGroup methods. In addition the program provides
buttons to control the sensitivity and visibility of the menu items and
toolbar items. Figure 16.4, “ActionGroup Example” illustrates the
program in operation:
Figure 16.4. ActionGroup Example
16.1.2.6. ActionGroup Signals
Your application can track the connection and removal of proxy
widgets to the Action objects in an
ActionGroup using the "connect-proxy" and
disconnect-proxy" signals. The signatures of your signal handler callbacks
should be:
For example, you might want to track these changes to make some
additional changes to the properties of the new proxy widget when it is
connected or to update some other part of the user interface when a proxy
widget is disconnected.
The "pre-activate" and "post-activate" signals allow your
application to do some additional processing immediately before or after an
action is activated. The signatures of the signal handler callbacks should
be:
1 #!/usr/bin/env python
2
3 # example scribblesimple.py
4
5 # GTK - The GIMP Toolkit
6 # Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
7 # Copyright (C) 2001-2002 John Finlay
8 #
9 # This library is free software; you can redistribute it and/or
10 # modify it under the terms of the GNU Library General Public
11 # License as published by the Free Software Foundation; either
12 # version 2 of the License, or (at your option) any later version.
13 #
14 # This library is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 # Library General Public License for more details.
18 #
19 # You should have received a copy of the GNU Library General Public
20 # License along with this library; if not, write to the
21 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 # Boston, MA 02111-1307, USA.
23
24
25 import gtk
26
27 # Backing pixmap for drawing area
28 pixmap = None
29
30 # Create a new backing pixmap of the appropriate size
31 def configure_event(widget, event):
32 global pixmap
33
34 x, y, width, height = widget.get_allocation()
35 pixmap = gtk.gdk.Pixmap(widget.window, width, height)
36 pixmap.draw_rectangle(widget.get_style().white_gc,
37 True, 0, 0, width, height)
38
39 return True
40
41 # Redraw the screen from the backing pixmap
42 def expose_event(widget, event):
43 x , y, width, height = event.area
44 widget.window.draw_drawable(widget.get_style().fg_gc[gtk.STATE_NORMAL],
45 pixmap, x, y, x, y, width, height)
46 return False
47
48 # Draw a rectangle on the screen
49 def draw_brush(widget, x, y):
50 rect = (x - 5, y - 5, 10, 10)
51 pixmap.draw_rectangle(widget.get_style().black_gc, True,
52 rect[0], rect[1], rect[2], rect[3])
53 widget.queue_draw_area(rect[0], rect[1], rect[2], rect[3])
54
55 def button_press_event(widget, event):
56 if event.button == 1 and pixmap != None:
57 draw_brush(widget, event.x, event.y)
58 return True
59
60 def motion_notify_event(widget, event):
61 if event.is_hint:
62 x, y, state = event.window.get_pointer()
63 else:
64 x = event.x
65 y = event.y
66 state = event.state
67
68 if state & gtk.gdk.BUTTON1_MASK and pixmap != None:
69 draw_brush(widget, x, y)
70
71 return True
72
73 def main():
74 window = gtk.Window(gtk.WINDOW_TOPLEVEL)
75 window.set_name ("Test Input")
76
77 vbox = gtk.VBox(False, 0)
78 window.add(vbox)
79 vbox.show()
80
81 window.connect("destroy", gtk.mainquit)
82
83 # Create the drawing area
84 drawing_area = gtk.DrawingArea()
85 drawing_area.set_size_request(200, 200)
86 vbox.pack_start(drawing_area, True, True, 0)
87
88 drawing_area.show()
89
90 # Signals used to handle backing pixmap
91 drawing_area.connect("expose_event", expose_event)
92 drawing_area.connect("configure_event", configure_event)
93
94 # Event signals
95 drawing_area.connect("motion_notify_event", motion_notify_event)
96 drawing_area.connect("button_press_event", button_press_event)
97
98 drawing_area.set_events(gtk.gdk.EXPOSURE_MASK
99 | gtk.gdk.LEAVE_NOTIFY_MASK
100 | gtk.gdk.BUTTON_PRESS_MASK
101 | gtk.gdk.POINTER_MOTION_MASK
102 | gtk.gdk.POINTER_MOTION_HINT_MASK)
103
104 # .. And a quit button
105 button = gtk.Button("Quit")
106 vbox.pack_start(button, False, False, 0)
107
108 button.connect_object("clicked", lambda w: w.destroy(), window)
109 button.show()
110
111 window.show()
112
113 gtk.main()
114
115 return 0
116
117 if __name__ == "__main__":
118 main()
The category of range widgets includes the ubiquitous scrollbar
widget and the less common "scale" widget. Though these two types of widgets
are generally used for different purposes, they are quite similar in
function and implementation. All range widgets share a set of common graphic
elements, each of which has its own X window and receives events. They all
contain a "trough" and a "slider" (what is sometimes called a "thumbwheel"
in other GUI environments). Dragging the slider with the pointer moves it
back and forth within the trough, while clicking in the trough advances the
slider towards the location of the click, either completely, or by a
designated amount, depending on which mouse button is used.
As mentioned in Chapter 7, Adjustments above, all
range widgets are associated with an Adjustment
object, from which they calculate the length of the slider and its position
within the trough. When the user manipulates the slider, the range widget
will change the value of the adjustment.
8.1. Scrollbar Widgets
These are your standard, run-of-the-mill scrollbars. These
should be used only for scrolling some other widget, such as a list, a text
box, or a viewport (and it's generally easier to use the scrolled window
widget in most cases). For other purposes, you should use scale widgets, as
they are friendlier and more featureful.
There are separate types for horizontal and vertical scrollbars.
There really isn't much to say about these. You create them with the
following methods:
and that's about it. The adjustment
argument can either be a reference to an existing
Adjustment (see Chapter 7, Adjustments), or nothing, in which case one will be
created for you. Specifying nothing might be useful in the case, where you
wish to pass the newly-created adjustment to the constructor function of
some other widget which will configure it for you, such as a text
widget.
The example program (rangewidgets.py)
puts up a window with three range widgets all connected to the same
adjustment, and a couple of controls for adjusting some of the parameters
mentioned above and in the section on adjustments, so you can see how they
affect the way these widgets work for the user. Figure 8.1, “Range Widgets Example”
illustrates the result of running the program:
1 #!/usr/bin/env python
2
3 # example rangewidgets.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk
8
9 # Convenience functions
10
11 def make_menu_item(name, callback, data=None):
12 item = gtk.MenuItem(name)
13 item.connect("activate", callback, data)
14 item.show()
15 return item
16
17 def scale_set_default_values(scale):
18 scale.set_update_policy(gtk.UPDATE_CONTINUOUS)
19 scale.set_digits(1)
20 scale.set_value_pos(gtk.POS_TOP)
21 scale.set_draw_value(True)
22
23 class RangeWidgets:
24 def cb_pos_menu_select(self, item, pos):
25 # Set the value position on both scale widgets
26 self.hscale.set_value_pos(pos)
27 self.vscale.set_value_pos(pos)
28
29 def cb_update_menu_select(self, item, policy):
30 # Set the update policy for both scale widgets
31 self.hscale.set_update_policy(policy)
32 self.vscale.set_update_policy(policy)
33
34 def cb_digits_scale(self, adj):
35 # Set the number of decimal places to which adj->value is rounded
36 self.hscale.set_digits(adj.value)
37 self.vscale.set_digits(adj.value)
38
39 def cb_page_size(self, get, set):
40 # Set the page size and page increment size of the sample
41 # adjustment to the value specified by the "Page Size" scale
42 set.page_size = get.value
43 set.page_incr = get.value
44 # Now emit the "changed" signal to reconfigure all the widgets that
45 # are attached to this adjustment
46 set.emit("changed")
47
48 def cb_draw_value(self, button):
49 # Turn the value display on the scale widgets off or on depending
50 # on the state of the checkbutton
51 self.hscale.set_draw_value(button.get_active())
52 self.vscale.set_draw_value(button.get_active())
53
54 # makes the sample window
55
56 def __init__(self):
57 # Standard window-creating stuff
58 self.window = gtk.Window (gtk.WINDOW_TOPLEVEL)
59 self.window.connect("destroy", lambda w: gtk.main_quit())
60 self.window.set_title("range controls")
61
62 box1 = gtk.VBox(False, 0)
63 self.window.add(box1)
64 box1.show()
65
66 box2 = gtk.HBox(False, 10)
67 box2.set_border_width(10)
68 box1.pack_start(box2, True, True, 0)
69 box2.show()
70
71 # value, lower, upper, step_increment, page_increment, page_size
72 # Note that the page_size value only makes a difference for
73 # scrollbar widgets, and the highest value you'll get is actually
74 # (upper - page_size).
75 adj1 = gtk.Adjustment(0.0, 0.0, 101.0, 0.1, 1.0, 1.0)
76
77 self.vscale = gtk.VScale(adj1)
78 scale_set_default_values(self.vscale)
79 box2.pack_start(self.vscale, True, True, 0)
80 self.vscale.show()
81
82 box3 = gtk.VBox(False, 10)
83 box2.pack_start(box3, True, True, 0)
84 box3.show()
85
86 # Reuse the same adjustment
87 self.hscale = gtk.HScale(adj1)
88 self.hscale.set_size_request(200, 30)
89 scale_set_default_values(self.hscale)
90 box3.pack_start(self.hscale, True, True, 0)
91 self.hscale.show()
92
93 # Reuse the same adjustment again
94 scrollbar = gtk.HScrollbar(adj1)
95 # Notice how this causes the scales to always be updated
96 # continuously when the scrollbar is moved
97 scrollbar.set_update_policy(gtk.UPDATE_CONTINUOUS)
98 box3.pack_start(scrollbar, True, True, 0)
99 scrollbar.show()
100
101 box2 = gtk.HBox(False, 10)
102 box2.set_border_width(10)
103 box1.pack_start(box2, True, True, 0)
104 box2.show()
105
106 # A checkbutton to control whether the value is displayed or not
107 button = gtk.CheckButton("Display value on scale widgets")
108 button.set_active(True)
109 button.connect("toggled", self.cb_draw_value)
110 box2.pack_start(button, True, True, 0)
111 button.show()
112
113 box2 = gtk.HBox(False, 10)
114 box2.set_border_width(10)
115
116 # An option menu to change the position of the value
117 label = gtk.Label("Scale Value Position:")
118 box2.pack_start(label, False, False, 0)
119 label.show()
120
121 opt = gtk.OptionMenu()
122 menu = gtk.Menu()
123
124 item = make_menu_item ("Top", self.cb_pos_menu_select, gtk.POS_TOP)
125 menu.append(item)
126
127 item = make_menu_item ("Bottom", self.cb_pos_menu_select,
128 gtk.POS_BOTTOM)
129 menu.append(item)
130
131 item = make_menu_item ("Left", self.cb_pos_menu_select, gtk.POS_LEFT)
132 menu.append(item)
133
134 item = make_menu_item ("Right", self.cb_pos_menu_select, gtk.POS_RIGHT)
135 menu.append(item)
136
137 opt.set_menu(menu)
138 box2.pack_start(opt, True, True, 0)
139 opt.show()
140
141 box1.pack_start(box2, True, True, 0)
142 box2.show()
143
144 box2 = gtk.HBox(False, 10)
145 box2.set_border_width(10)
146
147 # Yet another option menu, this time for the update policy of the
148 # scale widgets
149 label = gtk.Label("Scale Update Policy:")
150 box2.pack_start(label, False, False, 0)
151 label.show()
152
153 opt = gtk.OptionMenu()
154 menu = gtk.Menu()
155
156 item = make_menu_item("Continuous", self.cb_update_menu_select,
157 gtk.UPDATE_CONTINUOUS)
158 menu.append(item)
159
160 item = make_menu_item ("Discontinuous", self.cb_update_menu_select,
161 gtk.UPDATE_DISCONTINUOUS)
162 menu.append(item)
163
164 item = make_menu_item ("Delayed", self.cb_update_menu_select,
165 gtk.UPDATE_DELAYED)
166 menu.append(item)
167
168 opt.set_menu(menu)
169 box2.pack_start(opt, True, True, 0)
170 opt.show()
171
172 box1.pack_start(box2, True, True, 0)
173 box2.show()
174
175 box2 = gtk.HBox(False, 10)
176 box2.set_border_width(10)
177
178 # An HScale widget for adjusting the number of digits on the
179 # sample scales.
180 label = gtk.Label("Scale Digits:")
181 box2.pack_start(label, False, False, 0)
182 label.show()
183
184 adj2 = gtk.Adjustment(1.0, 0.0, 5.0, 1.0, 1.0, 0.0)
185 adj2.connect("value_changed", self.cb_digits_scale)
186 scale = gtk.HScale(adj2)
187 scale.set_digits(0)
188 box2.pack_start(scale, True, True, 0)
189 scale.show()
190
191 box1.pack_start(box2, True, True, 0)
192 box2.show()
193
194 box2 = gtk.HBox(False, 10)
195 box2.set_border_width(10)
196
197 # And, one last HScale widget for adjusting the page size of the
198 # scrollbar.
199 label = gtk.Label("Scrollbar Page Size:")
200 box2.pack_start(label, False, False, 0)
201 label.show()
202
203 adj2 = gtk.Adjustment(1.0, 1.0, 101.0, 1.0, 1.0, 0.0)
204 adj2.connect("value_changed", self.cb_page_size, adj1)
205 scale = gtk.HScale(adj2)
206 scale.set_digits(0)
207 box2.pack_start(scale, True, True, 0)
208 scale.show()
209
210 box1.pack_start(box2, True, True, 0)
211 box2.show()
212
213 separator = gtk.HSeparator()
214 box1.pack_start(separator, False, True, 0)
215 separator.show()
216
217 box2 = gtk.VBox(False, 10)
218 box2.set_border_width(10)
219 box1.pack_start(box2, False, True, 0)
220 box2.show()
221
222 button = gtk.Button("Quit")
223 button.connect("clicked", lambda w: gtk.main_quit())
224 box2.pack_start(button, True, True, 0)
225 button.set_flags(gtk.CAN_DEFAULT)
226 button.grab_default()
227 button.show()
228 self.window.show()
229
230 def main():
231 gtk.main()
232 return 0
233
234 if __name__ == "__main__":
235 RangeWidgets()
236 main()
You will notice that the program does not call the
connect() method for the "delete_event", but only for
the "destroy" signal. This will still perform the desired operation, because
an unhandled "delete_event" will result in a "destroy" signal being given to
the window.
There is only one function for creating a new
TextView widget.
textview = gtk.TextView(buffer=None)
When a TextView is created it will create
an associated TextBuffer and
TextTagTable by default. If you want to use an
existing TextBuffer in a
TextView specify it in the above method. To change
the TextBuffer used by a
TextView use the following method:
textview.set_buffer(buffer)
Use the following method to retrieve a reference to the
TextBuffer from a
TextView:
buffer = textview.get_buffer()
A TextView widget doesn't have scrollbars
to adjust the view in case the text is larger than the window. To provide
scrollbars, you add the TextView to a
ScrolledWindow (see Section 10.9, “Scrolled Windows”).
A TextView can be used to allow the user
to edit a body of text, or to display multiple lines of read-only text to
the user. To switch between these modes of operation, the use the following
method:
textview.set_editable(setting)
The setting argument is a
TRUE or FALSE value that specifies
whether the user is permitted to edit the contents of the
TextView widget. The editable mode of the
TextView can be overridden in text ranges within the
TextBuffer by TextTags.
You can retrieve the current editable setting using the
method:
setting = textview.get_editable()
When the TextView is not editable, you
probably should hide the cursor using the method:
textview.set_cursor_visible(setting)
The setting argument is a
TRUE or FALSE value that specifies
whether the cursor should be visible The TextView can
wrap lines of text that are too long to fit onto a single line of the
display window. Its default behavior is to not wrap lines. This can be
changed using the next method:
textview.set_wrap_mode(wrap_mode)
This method allows you to specify that the text widget should
wrap long lines on word or character boundaries. The
word_wrap argument is one of:
gtk.WRAP_NONE
gtk.WRAP_CHAR
gtk.WRAP_WORD
The default justification of the text in a
TextView can be set and retrieved using the
methods:
The justification will be
JUSTIFY_LEFT if the wrap_mode is
WRAP_NONE. Tags in the associated
TextBuffer may override the default
justification.
Other default attributes that can be set and retrieved in a
TextView are: left margin, right margin, tabs, and
paragraph indentation using the following methods:
left_margin,
right_margin, indent,
pixels_above_lines,
pixels_below_lines and
pixels_inside_wrap are specified in pixels. These
default values may be overridden by tags in the associated
TextBuffer. tabs is a
pango.TabArray.
The textview-basic.py
example program illustrates basic use of the TextView
widget:
Lines 10-34 define the callbacks for the radio and check buttons
used to change the default attributes of the
TextView. Lines 55-63 create a
ScrolledWindow to contain the
TextView. The ScrolledWindow
is packed into a VBox with the check and radio
buttons created in lines 72-140. The TextBuffer
associated with the TextView is loaded with the
contents of the source file in lines 64-70.
An EntryCompletion is an object that is used
with an Entry widget to provide completion
functionality. As the user types into the Entry the
EntryCompletion will popup a window with a set of
strings matching the Entry text.
An EntryCompletion is created using the
constructor:
completion = gtk.EntryCompletion()
You can use the Entry method
set_completion() to associate an
EntryCompletion with an
Entry:
entry.set_completion(completion)
The strings used by the EntryCompletion for
matching are retrieved from a TreeModel (usually a
ListStore) that must be set using the method:
completion.set_model(model)
The EntryCompletion implements the
CellLayout interface that is similar to the
TreeViewColumn in managing the display of the
TreeModel data. The following convenience method sets
up an EntryCompletion in the most common
configuration - a list of strings:
The example program starts with a small number of completion strings
that can be increased by typing into the entry field and pressing the
Enter key. If the string is unique it is added to the list
of completion strings.
The built-in match function is a case insensitive string comparison
function. If you need a more specialized match function, you can use the
following method to install your own match function:
completion.set_match_func(func, user_data)
The signature of func is:
def func(completion, key_string, iter, data):
where key_string contains the current
contents of the Entry, iter is
a TreeIter pointing at a row in the associated
TreeModel, and data is
user_data. func should return
TRUE if the row's completion string should be
displayed.
The simple example code snippet below uses a match function to
display completion names that begin with the entry contents and have the
given suffix, in this case, a name ending in .png for a
PNG file.
...
completion.set_match_func(end_match, (0, '.png'))
...
def end_match(completion, entrystr, iter, data):
column, suffix = data
model = completion.get_model()
modelstr = model[iter][column]
return modelstr.startswith(entrystr) and modelstr.endswith(suffix)
...
For example if the user types 'foo' and the completion model
contains strings like 'foobar.png', smiley.png', 'foot.png' and 'foo.tif', the
'foobar.png' and 'foot.png' strings would be displayed as
completions.
