Gtkmodule and Gtkinter
======================
Author: James Henstridge <james@daa.com.au>


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+-0.99.9, as it includes support for features not
found in previous versions, and there are incompatibilities between
versions.

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.  The file gtkmodule.so should be put in the
shared modules directory (on Red Hat Linux this is
/usr/lib/python1.4/sharedmodules), and GTK.py, GDK.py, GtkExtra.py and
Gtkinter.py should go in the main python library directory (on Red Hat
Linux this is /usr/lib/python1.4).  For the python modules, it is
a good idea to create bytecodes (.pyc files) as root, to increase the
loading speed for pygtk applications.

If you had a copy of gdk_imlib installed on your system (and configure
could find it) when you built pygtk, you should have a copy of
_gdkimlibmodule.so in the base directory.  This file along with
GdkImlib.py can be installed into your python library.  A simple
example of using gdk_imlib can be found in the directory
examples/imlib.

If you have trouble with the imlib code building, please mail me -- it
is still under development.


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 <james@daa.com.au>.  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.

