NOTE: Although it's getting better, this is still very incomplet and
      incoNsistent [shamelessly stolen from the C++ draft working
      paper].  I very much welcome all your criticism and suggestions
      to make this as useful as possible to as many people as
      possible.  You can find me on the <gtk-list@redhat.com> and
      behind <mvo@zagadka.ping.de>.  Updates to this package will be
      put at http://www.ping.de/sites/zagadka/types.html and maybe
      somewhere on ftp.gimp.org, and/or ftp.gnome.org.

       - Thanks, Marius

This is some glue code to make Gtk accessible from Guile.

I tried hard to make this as generic as possible.  As a result, it
should be easy to extend it to new widgets and other Gtk extensions.
It might even be possible to use some of this code for wrapping
completely different C libraries, but that was not my goal.

I have not refrained from changing Gtk itself when I thought that it
would be the right solution to some problem I faced.  I have tried to
not bias these changes towards a Scheme clientele, so they hopefully
turn out to be useful to other high-level language bindings.

To even further unify the different high-level language bindings (such
as the ones for Perl, Python, Objective C, maybe Java, etc.) I tried
to collect the salient bits of the Gtk API into a formal description.
You should be able to generate large parts of the language specific
glue code from it.

Ok, what's really in this package?

 guile-gtk.c
 guile-gtk.h     Support for converting between Scheme types and Gtk types.

 gtk.defs        The formal description of the Gtk API.
 gen-typeinfo    A Scheme program to generate much of the glue code.

 guile-compat.c
 guile-compat.h  Code to adapt to different versions of Guile.

 gtk-compat.c
 gtk-compat.h    Code to adapt to different versions of Gtk.

 gtk-typeinfo.h
 gtk-typeinfo.c  Automatically generated information about the types that are
                 defined in gtk.defs.

 gtk-funcs.c     Automatically generated stubs for the functions defined
                 in gtk.defs.

 gtk-guile.c     A simple main program to integrate the Gtk bindings with
                 libguile.
 test-gtk.scm    A rewrite of testgtk.c in Scheme.

 PROPOSAL        A more detailed description of the types that can appear
                 in gtk.defs
 gtk-interp.patch A patch to Gtk for a little interpreter support.

The rest is the usual configuration and building cruft.

Some of the files really belong into the Gtk distribution where
everyone can see them: I would like to see most of the functionality
of gtk-compat drift into Gtk, and of course gtk.defs should be
maintained alongside Gtk.


Installing
----------

[Sorry, a bit long winded.  There should be no big surprises but
 please read it anyway.]

You need to have a suitably recent version of Gtk installed for this
package to work correctly.  Gtk+970915 works fine.

It is recommended to apply the gtk-interp.patch mentioned above.  It
should be backward compatible.

It applies to gtk+970915.  Change into the top-level directory of the
Gtk sources and execute

    % patch -p1 <path/to/gtk-interp.patch

Then you should check for *.rej files that indicate failed patches and
remove all *.orig files.  But you probably know that already.

If you don't install the patch, there will be some memory leaks and maybe
other instabilities, but guile-gtk should work.

Then configure, make and install Gtk, as usual.


In addition to Gtk, you need Guile of course.  Guile-1.2 should be
fine, as should be most of the recent snapshots.

Guile-gtk mostly conforms to the GNU standards for source
distributions, so things should be familiar to you.  If you need more
information, look into the file INSTALL.

You might take a closer look at the configure output to see whether
the patch has been picked up.  Configure should find all of the
gtk_*_interp functions.

The Makefile builds a library, libguilegtk, and a program, guile-gtk.


Testing
-------

    % guile-gtk -s test-gtk.scm

should pop up a familiar pile of buttons.  Not every test has been
implemented and not all of them work.  When Guile says

    gtk: Unbound variable: gtk-scrolled-window-new

everything is fine.  It just means that this function has not been
added to gtk.defs.

All other unexpected behaviour is probably a bug and I would be glad
if you would tell me about it.


Documentation
-------------

Nothing available yet, but the Scheme interface to Gtk is very similar
to the C one.  Almost all functions take the same arguments as their C
counterparts.  Exceptions are:

- Booleans are expressed with Scheme's real boolean values #f and #t.
- Callbacks don't take a client-data argument, so you don't have to
  specify one to gtk_signal_connect, ot gtk_timeout_add, etc.
- Signal handlers don't get the Object as their first argument.  In my
  view, this would be more often annoying than helpful.
- NULL pointers are expressed as #f.
- Some parameters are optional and get a default value when left
  unspecified.
- A GtkObject (or derived) can silently turn into a `destroyed
  GtkObject'.  This happens when the real GtkObject is destroyed but
  the Scheme code still holds a reference to it.  You can test for a
  destroyed GtkObject with the `gtk-destroyed?' predicate.
- Each type that is derived from GtkObject has an associated predicate
  function to test whether a Scheme value is of that type.  The
  predicate for GtkObject is called `gtk-object?', the one for
  GtkRadioButton `gtk-radio-button?', etc.
- gtk-radio-button-new and gtk-radio-button-new-with-label don't take
  a list as their group argument but a GtkWidget whose group is used
  instead.
- Likewise for gtk-radio-menu-item.

And all the things I forgot about.


Have fun!
