/usr/share/doc/python-gtk2-tutorial/html/sec-Toolbar.html is in python-gtk2-tutorial 2.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>10.11. Toolbar</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PyGTK 2.0 Tutorial"><link rel="up" href="ch-ContainerWidgets.html" title="Chapter 10. Container Widgets"><link rel="previous" href="sec-ButtonBoxes.html" title="10.10. Button Boxes"><link rel="next" href="sec-Notebooks.html" title="10.12. Notebooks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">10.11. Toolbar</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sec-ButtonBoxes.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Container Widgets</th><td width="20%" align="right"> <a accesskey="n" href="sec-Notebooks.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-Toolbar"></a>10.11. Toolbar</h2></div></div><div></div></div><p><tt class="classname">Toolbars</tt> 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.</p><p>Creating a toolbar is (as one may already suspect) done with the
following function:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
toolbar = gtk.Toolbar()
</pre></td></tr></table><p>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:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
toolbar.append_item(<b class="parameter"><tt>text</tt></b>, <b class="parameter"><tt>tooltip_text</tt></b>, <b class="parameter"><tt>tooltip_private_text</tt></b>, <b class="parameter"><tt>icon</tt></b>, <b class="parameter"><tt>callback</tt></b>, <b class="parameter"><tt>user_data</tt></b>=None)
toolbar.prepend_item(<b class="parameter"><tt>text</tt></b>, <b class="parameter"><tt>tooltip_text</tt></b>, <b class="parameter"><tt>tooltip_private_text</tt></b>, <b class="parameter"><tt>icon</tt></b>, <b class="parameter"><tt>callback</tt></b>, <b class="parameter"><tt>user_data</tt></b>)
</pre></td></tr></table><p>If you want to use the <tt class="methodname">insert_item</tt>()
method, the only additional parameter which must be specified is the
position in which the item should be inserted, thus:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
toolbar.insert_item(<b class="parameter"><tt>text</tt></b>, <b class="parameter"><tt>tooltip_text</tt></b>, <b class="parameter"><tt>tooltip_private_text</tt></b>, <b class="parameter"><tt>icon</tt></b>, <b class="parameter"><tt>callback</tt></b>,
<b class="parameter"><tt>user_data</tt></b>, <b class="parameter"><tt>position</tt></b>)
</pre></td></tr></table><p>To simplify adding spaces between toolbar items, you may use the
following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
toolbar.append_space()
toolbar.prepend_space()
toolbar.insert_space(<b class="parameter"><tt>position</tt></b>)
</pre></td></tr></table><p>If it's required, the orientation of a toolbar, its style and
whether tooltips are available can be changed "on the fly" using the
following methods:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
toolbar.set_orientation(<b class="parameter"><tt>orientation</tt></b>)
toolbar.set_style(<b class="parameter"><tt>style</tt></b>)
toolbar.set_tooltips(<b class="parameter"><tt>enable</tt></b>)
</pre></td></tr></table><p>Where <i class="parameter"><tt>orientation</tt></i> is one of
<tt class="literal">ORIENTATION_HORIZONTAL</tt> or
<tt class="literal">ORIENTATION_VERTICAL</tt>. The <i class="parameter"><tt>style</tt></i> is
used to set appearance of the toolbar items by using one of
<tt class="literal">TOOLBAR_ICONS</tt>, <tt class="literal">TOOLBAR_TEXT</tt>, or
<tt class="literal">TOOLBAR_BOTH</tt>. The <i class="parameter"><tt>enable</tt></i> argument
is either <tt class="literal">TRUE</tt> or <tt class="literal">FALSE</tt>.</p><p>To show some other things that can be done with a toolbar, let's
take the <a href="examples/toolbar.py" target="_top"><span><b class="command">toolbar.py</b></span></a> example
program (we'll interrupt the listing with some additional
explanations):</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>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 (<a href="examples/gtk.xpm" target="_top"><tt class="filename">gtk.xpm</tt></a>)to serve as an
icon for all of the buttons. Line 10 starts the
<tt class="classname">ToolbarExample</tt> class and lines 12-14 define the
callback method which will terminate the program.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>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).</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>The above should be similar to any other PyGTK application. Just
initialization of a <tt class="classname">ToolbarExample</tt> 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.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>Well, what we do above is just a straightforward initialization
of the toolbar widget.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>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
<tt class="methodname">append_item</tt>() method returns a reference to our
newly created button widget, so that we can work with it in the normal
way.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>Here we begin creating a radio buttons group. To do this we use
the <tt class="methodname">append_element</tt>() method. In fact, using this
method one can also add simple items or even spaces
(<i class="parameter"><tt>type</tt></i> = <tt class="literal">gtk.TOOLBAR_CHILD_SPACE</tt> or
<tt class="literal">gtk.TOOLBAR_CHILD_BUTTON</tt>). 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 <a href="sec-RadioButtons.html" title="6.4. Radio Buttons">Section 6.4, “Radio Buttons”</a> earlier in this tutorial). We also save a
reference to the button in the <tt class="classname">ToolbarExample</tt>
instance for later access.</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
86 # following radio buttons refer to previous ones
87 iconw = gtk.Image() # icon widget
88 iconw.set_from_file("gtk.xpm")
89 text_button = toolbar.append_element(
90 gtk.TOOLBAR_CHILD_RADIOBUTTON,
91 icon_button,
92 "Text",
93 "Only texts in toolbar",
94 "Private",
95 iconw,
96 self.radio_event,
97 toolbar)
98 toolbar.append_space()
99 self.text_button = text_button
100
101 iconw = gtk.Image() # icon widget
102 iconw.set_from_file("gtk.xpm")
103 both_button = toolbar.append_element(
104 gtk.TOOLBAR_CHILD_RADIOBUTTON,
105 text_button,
106 "Both",
107 "Icons and text in toolbar",
108 "Private",
109 iconw,
110 self.radio_event,
111 toolbar)
112 toolbar.append_space()
113 self.both_button = both_button
114 both_button.set_active(True)
115
</pre></td></tr></table><p>We create the other radiobuttons the same way except we pass one
of the created radio group buttons to the
<tt class="methodname">append_element</tt>() method to specify the radio
group.</p><p>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).</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>A toggle button can be created in the obvious way (if one knows
how to create radio buttons already).</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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
</pre></td></tr></table><p>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).</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
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()
</pre></td></tr></table><p>Line 142 ends the <tt class="classname">ToolbarExample</tt> class
definition. Lines 144-147 define the <tt class="function">main</tt>() function
which just calls the <tt class="function">gtk.main</tt>() function to start the
event processing loop. Lines 149-151 arrange to create a
<tt class="classname">ToolbarExample</tt> 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, <a href="examples/gtk.xpm" target="_top"><tt class="filename">gtk.xpm</tt></a>.
<a href="sec-Toolbar.html#toolbarfig" title="Figure 10.8. Toolbar Example">Figure 10.8, “Toolbar Example”</a> illustrates the resulting
display:</p><div class="figure"><a name="toolbarfig"></a><p class="title"><b>Figure 10.8. Toolbar Example</b></p><div class="mediaobject" align="center"><img src="figures/toolbar.png" align="middle" alt="Toolbar Example"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sec-ButtonBoxes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch-ContainerWidgets.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-Notebooks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.10. Button Boxes </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 10.12. Notebooks</td></tr></table></div></body></html>
|