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:
PROGRESS_LEFT_TO_RIGHT PROGRESS_RIGHT_TO_LEFT PROGRESS_BOTTOM_TO_TOP PROGRESS_TOP_TO_BOTTOM |
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:
The source code for progressbar.py is:
1 #!/usr/bin/env python
2
3 # example progressbar.py
4
5 import pygtk
6 pygtk.require('2.0')
7 import gtk, gobject
8
9 # Update the value of the progress bar so that we get
10 # some movement
11 def progress_timeout(pbobj):
12 if pbobj.activity_check.get_active():
13 pbobj.pbar.pulse()
14 else:
15 # Calculate the value of the progress bar using the
16 # value range set in the adjustment object
17 new_val = pbobj.pbar.get_fraction() + 0.01
18 if new_val > 1.0:
19 new_val = 0.0
20 # Set the new value
21 pbobj.pbar.set_fraction(new_val)
22
23 # As this is a timeout function, return TRUE so that it
24 # continues to get called
25 return True
26
27 class ProgressBar:
28 # Callback that toggles the text display within the progress
29 # bar trough
30 def toggle_show_text(self, widget, data=None):
31 if widget.get_active():
32 self.pbar.set_text("some text")
33 else:
34 self.pbar.set_text("")
35
36 # Callback that toggles the activity mode of the progress
37 # bar
38 def toggle_activity_mode(self, widget, data=None):
39 if widget.get_active():
40 self.pbar.pulse()
41 else:
42 self.pbar.set_fraction(0.0)
43
44 # Callback that toggles the orientation of the progress bar
45 def toggle_orientation(self, widget, data=None):
46 if self.pbar.get_orientation() == gtk.PROGRESS_LEFT_TO_RIGHT:
47 self.pbar.set_orientation(gtk.PROGRESS_RIGHT_TO_LEFT)
48 elif self.pbar.get_orientation() == gtk.PROGRESS_RIGHT_TO_LEFT:
49 self.pbar.set_orientation(gtk.PROGRESS_LEFT_TO_RIGHT)
50
51 # Clean up allocated memory and remove the timer
52 def destroy_progress(self, widget, data=None):
53 gobject.source_remove(self.timer)
54 self.timer = 0
55 gtk.main_quit()
56
57 def __init__(self):
58 self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
59 self.window.set_resizable(True)
60
61 self.window.connect("destroy", self.destroy_progress)
62 self.window.set_title("ProgressBar")
63 self.window.set_border_width(0)
64
65 vbox = gtk.VBox(False, 5)
66 vbox.set_border_width(10)
67 self.window.add(vbox)
68 vbox.show()
69
70 # Create a centering alignment object
71 align = gtk.Alignment(0.5, 0.5, 0, 0)
72 vbox.pack_start(align, False, False, 5)
73 align.show()
74
75 # Create the ProgressBar
76 self.pbar = gtk.ProgressBar()
77
78 align.add(self.pbar)
79 self.pbar.show()
80
81 # Add a timer callback to update the value of the progress bar
82 self.timer = gobject.timeout_add (100, progress_timeout, self)
83
84 separator = gtk.HSeparator()
85 vbox.pack_start(separator, False, False, 0)
86 separator.show()
87
88 # rows, columns, homogeneous
89 table = gtk.Table(2, 2, False)
90 vbox.pack_start(table, False, True, 0)
91 table.show()
92
93 # Add a check button to select displaying of the trough text
94 check = gtk.CheckButton("Show text")
95 table.attach(check, 0, 1, 0, 1,
96 gtk.EXPAND | gtk.FILL, gtk.EXPAND | gtk.FILL,
97 5, 5)
98 check.connect("clicked", self.toggle_show_text)
99 check.show()
100
101 # Add a check button to toggle activity mode
102 self.activity_check = check = gtk.CheckButton("Activity mode")
103 table.attach(check, 0, 1, 1, 2,
104 gtk.EXPAND | gtk.FILL, gtk.EXPAND | gtk.FILL,
105 5, 5)
106 check.connect("clicked", self.toggle_activity_mode)
107 check.show()
108
109 # Add a check button to toggle orientation
110 check = gtk.CheckButton("Right to Left")
111 table.attach(check, 0, 1, 2, 3,
112 gtk.EXPAND | gtk.FILL, gtk.EXPAND | gtk.FILL,
113 5, 5)
114 check.connect("clicked", self.toggle_orientation)
115 check.show()
116
117 # Add a button to exit the program
118 button = gtk.Button("close")
119 button.connect("clicked", self.destroy_progress)
120 vbox.pack_start(button, False, False, 0)
121
122 # This makes it so the button is the default.
123 button.set_flags(gtk.CAN_DEFAULT)
124
125 # This grabs this button to be the default button. Simply hitting
126 # the "Enter" key will cause this button to activate.
127 button.grab_default ()
128 button.show()
129
130 self.window.show()
131
132 def main():
133 gtk.main()
134 return 0
135
136 if __name__ == "__main__":
137 ProgressBar()
138 main()
|