PyGTK Tutorial
<<< Previous Next >>>

Chapter 2. Getting Started

Table of Contents
2.1. Hello World in PyGTK
2.2. Theory of Signals and Callbacks
2.3. Events
2.4. Stepping Through Hello World
To begin our introduction to PyGTK, we'll start with the simplest program possible. This program (base.py) will create a 200x200 pixel window and has no way of exiting except to be killed by using the shell.
  
    1   #!/usr/bin/env python
    2   
    3   # example base.py
    4   
    5   import gtk
    6   
    7   class Base:
    8       def __init__(self):
    9           self.window = gtk.GtkWindow(gtk.WINDOW_TOPLEVEL)
   10           self.window.show()
   11   
   12   def main():
   13       gtk.mainloop()
   14   
   15   if __name__ == "__main__":
   16       base = Base()
   17       main()

You can run the above program using:
  
python base.py

If base.py is made executable and can be found in your PATH, it can be run using:
  
base.py

Line 1 will invoke python to run base.py in this case. Lines 15-17 check if the __name__ variable is "__main__" which indicates that the program is being run directly from python and not being imported into a running python interpreter. In this case the program creates a new instance of the Base class and saves a reference to it in the variable base. It then invokes the function main() to start the GTK event processing loop.

A window similar to Figure 2.1 should popup on your display.

Figure 2.1 Simple PyGTK Window

The first line allows the program base.py to be invoked from a Linux or Unix shell program assuming that python is found your PATH. This line will be the first line in all the example programs.

Line 5 imports the PyGTK module and initializes the GTK+ environment. The PyGTK module defines the python interfaces to the GTK+ functions that will be used in the program.

For those familiar with GTK+ the initialization includes calling the gtk_init() function.  This sets up a few things for us such as the default visual and color map, default signal handlers, and checks the arguments passed to your application on the command line, looking for one or more of the following:

It removes these from the argument list, leaving anything it does not recognize for your application to parse or ignore. These are a set of standard arguments accepted by all GTK+ applications.

Lines 7-10 define a python class named Base taht defines a class instance initialization function __init__(). The __init__() function creates a top level window (line 9) and directs GTK+ to display it (line 10). The GtkWindow is created in line 9 with the argument gtk.WINDOW_TOPLEVEL that specifies that we want the window to undergo window manager decoration and placement. Rather than create a window of 0x0 size, a window without children is set to 200x200 by default so you can still manipulate it.

Lines 12-13 define the main() function which calls the PyGTK mainloop() function which, in turn, invokes the GTK+ main event processing loop to handle mouse and keyboard events as well as window events.

Lines 15-17 allow the program to start automatically is called directly or passed as an argument to the python interpreter; in these cases the program name contained in the python variable __name__ will be the string "__main__" and the code in lines 16-17 will be executed. If the program is loaded into a running python interpreter using an import statement, lines 16-17 will not be executed.

Line 16 creates an instance of the Base class called base. A GtkWIndow is created and displayed as a result.

Line 17 calls the main() function which starts the GTK+ event processing loop.

2.1. Hello World in GTK

Now for a program with a widget (a button). It's the PyGTK version of the classic hello world program (helloworld.py).
  
    1   #!/usr/bin/env python
    2   
    3   # example helloworld.py
    4   
    5   import gtk
    6   
    7   class HelloWorld:
    8   
    9       # This is a callback function. The data arguments are ignored
   10       # in this example. More on callbacks below.
   11       def hello(self, widget, data=None):
   12           print "Hello World"
   13   
   14       def delete_event(self, widget, event, data=None):
   15           # If you return FALSE in the "delete_event" signal handler,
   16           # GTK will emit the "destroy" signal. Returning TRUE means
   17           # you don't want the window to be destroyed.
   18           # This is useful for popping up 'are you sure you want to quit?'
   19           # type dialogs.
   20           print "delete event occurred"
   21   
   22           # Change TRUE to FALSE and the main window will be destroyed with
   23           # a "delete_event".
   24           return gtk.FALSE
   25   
   26       # Another callback
   27       def destroy(self, widget, data=None):
   28           gtk.mainquit()
   29   
   30       def __init__(self):
   31           # create a new window
   32           self.window = gtk.GtkWindow(gtk.WINDOW_TOPLEVEL)
   33       
   34           # When the window is given the "delete_event" signal (this is given
   35           # by the window manager, usually by the "close" option, or on the
   36           # titlebar), we ask it to call the delete_event () function
   37           # as defined above. The data passed to the callback
   38           # function is NULL and is ignored in the callback function.
   39           self.window.connect("delete_event", self.delete_event)
   40       
   41           # Here we connect the "destroy" event to a signal handler.  
   42           # This event occurs when we call gtk_widget_destroy() on the window,
   43           # or if we return FALSE in the "delete_event" callback.
   44           self.window.connect("destroy", self.destroy)
   45       
   46           # Sets the border width of the window.
   47           self.window.set_border_width(10)
   48       
   49           # Creates a new button with the label "Hello World".
   50           self.button = gtk.GtkButton("Hello World")
   51       
   52           # When the button receives the "clicked" signal, it will call the
   53           # function hello() passing it None as its argument.  The hello()
   54           # function is defined above.
   55           self.button.connect("clicked", self.hello, None)
   56       
   57           # This will cause the window to be destroyed by calling
   58           # gtk_widget_destroy(window) when "clicked".  Again, the destroy
   59           # signal could come from here, or the window manager.
   60           self.button.connect_object("clicked", self.window.destroy, self.window)
   61       
   62           # This packs the button into the window (a GTK container).
   63           self.window.add(self.button)
   64       
   65           # The final step is to display this newly created widget.
   66           self.button.show()
   67       
   68           # and the window
   69           self.window.show()
   70   
   71   def main():
   72       # All PyGTK applications must have a gtk.mainloop(). Control ends here
   73       # and waits for an event to occur (like a key press or mouse event).
   74       gtk.mainloop()
   75   
   76   # If the program is run directly or passed as an argument to the python
   77   # interpreter then create a HelloWorld instance and show it
   78   if __name__ == "__main__":
   79       hello = HelloWorld()
   80       main()
Figure 2.2 shows the window created by helloworld.py.

Figure 2.2 HelloWorld Example Program

The variables and functions that are defined in the gtk.py module are named as gtk.*. For example, the helloworld.py program uses:
  
gtk.FALSE
gtk.mainquit()
gtk.GtkWindow()
gtk.GtkButton()

from the gtk.py module (and the GTK.py module which is imported in the gtk.py module). In future sections I will not specify the gtk module prefix but it will be assumed. The example programs will of course use the modules prefixes.

<<< Previous Home Next >>>
Introduction   Theory of Signals and Callbacks