Gtkmodule and Gtkinter ====================== Author: James Henstridge This archive contains modules that allow you to use gtk in Python programs. At this point, it is still very much a work in progress. Despite the low version number, this peice 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), although context diffs are OK as well. 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. 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.0.2 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.3 or greater. This module is generated by SWIG version 1.1p2 or newer (older versions may work -- I just haven't tried them). A copy of the generated gtkmodule.c is included in the base directory of the distribution. If you wish to regenerate this file, you should get into the swigsrc directory in the distribution, and look at the makefile for tips on how to generate gtkmodule.c. The SWIG interface files have some comments in them. 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=/path/to/python ./configure". This should generate Makefile from the files Makefile.pre.in and Setup.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 ========= If you have been using a previous version of pygtk, it would be a good idea to look at the file docs/developers.txt in the GTK source tree, as many of these things affect pygtk as well, with the exception that reference handling is done automatically. It is also a good idea to look at the file Changelog, as this gives a summary of changes to pygtk. It also tells of recent updates that you may find useful for your program. 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. Gtkinter.py =========== This module is a wrapper for gtkmodule. You start using it by executing the command "from Gtkinter 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. 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 Gtkinter.py. Should I Use Gtkmodule or GtkInter? =================================== You should probably use the striaght gtkmodule, if you are using python to prototype a C application that will use GTK, but in most other cases, Gtkinter will probably be a lot easier to use, and will look more natural in a python program. 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.