9.4. Progress Bars
Prev | Chapter 9. Miscellaneous Widgets | Next

## 9.4. Progress Bars

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:

Figure 9.4. ProgressBar Example

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()

Prev | Up | Next
9.3. The Tooltips Object | Home | 9.5. Dialogs