6.2. Toggle Buttons
Prev | Chapter 6. The Button Widget | Next

## 6.2. Toggle Buttons

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.

The togglebutton.py program provides a simple example using toggle buttons. Figure 6.2, “Toggle Button Example” illustrates the resulting window with the second toggle button active:

Figure 6.2. Toggle Button Example

The source code for the program is:

        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.

Prev | Up | Next
Chapter 6. The Button Widget | Home | 6.3. Check Buttons