PyGTK ===== Author: James Henstridge This archive contains modules that allow you to use gtk in Python programs. At present, it is a fairly complete set of bindings. Despite the low version number, this piece of software is quite useful, and is usable to write moderately complex programs. (see the examples directory for some examples of the simpler programs you could write). If you have any enhancements or bug reports, please send them to me at james@daa.com.au. If you are going to send me diffs, my prefered format is unified diff (ie. diff -u), followed by context diffs. Please don't send me diffs which don't have any context, as these are almost useless if I try to apply them manually, or have a different version of the source tree. New Versions ============ New versions of this package can be found at: ftp://ftp.daa.com.au/pub/james/python/ ftp://ftp.gtk.org/pub/gtk/python/ ftp://ftp.python.org/pub/contrib/Graphics/ Mailing list ============ There is a mailing list for pygtk. You can subscribe to it by sending mail to pygtk-request@daa.com.au with the word subscribe in the body. The list address is pygtk@daa.com.au. Copyright Information ===================== This software is covered by the GNU Library General Public Licence (version 2, or if you choose, a later version). Basically just don't say you wrote bits you didn't. Compilation =========== This archive contains a single C module called gtkmodule. It contains an almost direct mapping of the functions in GTK including GTK signal handling, and the gtk_object_new/gtk_object_set commands. This version REQUIRES gtk+-1.2.1 or later, as it includes support for features not found in previous versions, and there are incompatibilities between versions. Also if you want the GdkImlib extension, you must have Imlib version 1.8 or greater. I recommend getting the latest stable versions of these libraries before compiling pygtk, as it will make your system more stable. Parts of this module are automatically generated from the .defs file in the generate directory, by the two python scripts in that directory. To compile gtkmodule, first run "./configure" from the base directory of the distribution. It requires that you have python in the path, and python has been installed properly. If python is not in the path, you could try running "PYTHON=/subdir/python ./configure". This should generate the Makefile from the file Makefile.in. Now you should be able to run "make" to compile the module. Now you should install the files. I have provided an install target to the makefile, so you should be able to just type "make install". On systems with Python 1.5 and later, it installs to the site-packages directory (using prefix and exec_prefix where appropriate). For Python 1.4, it installs the python code to $(prefix)/lib/python$(version), and the libraries to $(excec_prefix)/lib/python$(version)/sharedmodules. It also compiles .pyc files from the python code. If you had a copy of gdk_imlib installed on your system (and configure could find it) when you built pygtk, a wrapper for it will have been installed with the main pygtk modules. A simple example of using the GdkImlib module is in the directory examples/imlib. If you have trouble with building or installing any of the code, please tell me -- it is the only way I can fix the problem. If you do mail me, please put something sensible in the subject line so I can tell what it is about. Upgrading ========= Note that from version 0.5.0 up, pygtk uses GTK >= 1.1. Since there were some changes to the API, pygtk has changed accordingly. The main one that will cause problems is the GtkAcceleratorTable. In this version, it has been removed and replaced with the GtkAccelGroup. Also note that some of the functions that refer to that type may have changed slightly. The rest of the changes are mostly invisible, since they are mainly internal, and not touched upon by most people's code. The Gtkinter module has been renamed to gtk.py, which is more consistent with the rest of the module, and the GNOME stuff. Also, I have changed the arguments for the gtk.new function. Now instead of object arguments being passed in as a dictionary, they are passed in as keyword arguments. This is possible because the 'Gtk*::' prefix is no longer needed. If you have a previous 0.5.x version of pygtk, and you weren't using the Gtkinter.py wrapper, there is no _gtkbase module any more, so don't include it. Also don't call pygtk_init, as it is now done automatically during module initialisation. Tests ===== After having compiled and installed gtkmodule, GTK and Gtkinter, you may want to test them. In the examples directory there are a number of programs you may want to use to test gtkmodule and Gtkinter. These programs rely on being able to find gtkmodule, GTK and Gtkinter, so you must have installed them somewhere on your python path. (Typing "PYTHONPATH=../.. python filename.py" from the examples directory is enough, after building gtkmodule) _gtkmodule and GTK.py ==================== This module contains an almost complete translation of the functions in the gtk library. To start up, put in the command "from gtk import *". If you want to use any of the constants, type "from GTK import *". The constants all have the "GTK_" removed from the start. Before creating any GtkObjects, you should execute the command "gtk_init()". Unlike the C equivalent, you don't have to specify an argument list, since there are other ways to get at it. When you are using the functions in this module, you will find that there is no need to use any of the type casting macros on GtkObjects, since they are all stored inside the same python type. Each function in the module does its own type casting. In this module there are only two signal connection functions -- gtk_signal_connect and gtk_signal_connect_after. The other functions can be emulated with the use of callable class instances wrapped around the signal handler. Also signal handlers are not parsed the extra data argument. The reason for this is because the code has to keep track of both the python signal handler and its C wrapper. In the gtk_object_new and gtk_object_set functions, the property setting argumetns have been compressed into a single dictionary as an argument. This dictionary has string keys that correspond to the property names, and the values are the property values. The reason that I did not use keyword arguments is that things like "GtkWindow::title" are not valid keywords, so unfortunately we have to use this clumsy syntax. gtk.py =========== This module is a wrapper for gtkmodule. You start using it by executing the command "from gtk import *". This will give you access to all of Gtkinter, and also import GTK, the constants module, for you. This module implements an object oriented wrapper for gtk. Probably the best way to get a feel for it, is to read some of the source code. Basically, there is a class for each GtkObject type. Each class implements the functions specific to that GtkObject type as methods. (ie. GtkWidget.show() is equivalent to gtk_widget_show()). The classes are set up such that their inheritance tree matches that of the actual GtkObjects. This means that you can call GtkWidget.show() from a GtkWindow class instance. The constructors for each of these classes corresponds to the gtk_*_new functions. Through the use of default arguments, both the gtk_*_new and gtk_*_new_* functions are both supported through the constructor. The drag and drop functions gtk_drag_* map to GtkWidget.drag_*, and the selection functions gtk_selection_* map to GtkWidget.selection_*. There are also a few extra functions in Gtkinter. These are new(), mainloop() and mainquit(). The function new() implements gtk_object_new. It's first argument can be either a string, or one of the classes in the module. The second argument is a dictionary that is almost passed to gtk_object_new after converting Gtkinter Objects to GtkObjects. The function mainloop() is basically just the function gtk_main(), and the function mainquit is equivalent to gtk_main_quit(). For further information on the interface, please see the source file gtk.py. For a more in depth look at the mapping of the C GTK functions to python, read the file MAPPING that is distributed with this package. Should I Use _gtkmodule or gtk.py? =================================== The gtk.py module allows faster prototyping of interfaces, and is easy to convert to C. It also uses object oriented ideas familiar to most Python users. On the other hand, if you want something as close to C as possible, go with _gtkmodule. Contacting the Author ===================== You can contact me at the email address . I try to answer my email quickly, but occasionally there will be a bit of a delay. If you have an idea for a way to extend GTK, have found a problem with the code (I don't think there are many bugs anymore), or would like to contribute some code, please feel free to contact me.