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>. 

       - Thanks, Marius

This is some glue code to make Gtk accessible from Guile.
New versions of this package will be available from

    http://www.ping.de/sites/zagadka/guile-gtk/

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.

Bugs
----

My main aim is currently robustness.  It should not be possible to
crash your program from Scheme.  Guile-gtk has to cope with anything.
So if you find that your program crashes and you think it is due to a
bug in your Scheme code, you have actually found a bug in guile-gtk or
Gtk.

Please report these bugs to me <mvo@zagadka.ping.de> or to the
gtk-list.

Contents
--------

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

 gtk.defs        The formal description of the Gtk API.
 guile.details   Guile specific additions to gtk.defs
 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.

 toolkits/gtk.scm
                 The Scheme part of the (toolkits gtk) module.
 event-repl.scm  Support for event driven read-eval-print loops.

 main.c          A simple main program to integrate the Gtk bindings with
                 a Guile interpreter.
 hello.scm       Say what?
 test-gtk.scm    A rewrite of testgtk.c in Scheme.
 calc.scm        A small desktop calculator.

 PROPOSAL        A more detailed description of the types that can appear
                 in gtk.defs
 gtk-interp.patch A patch to Gtk for 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-interp.patch drift into Gtk, and of course gtk.defs should be
maintained alongside Gtk.


Installing
----------

See INSTALL for installation instructions.


Testing
-------

    % ./guile-gtk -e main -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.

You can also try

    % ./guile-gtk -s calc.scm

To see whether dynamically linked modules work for you, you can try

    % guile -e main -s test-gtk.scm

This should start the vanilla Guile standalone interpreter.  The
libguilegtk library will be dlopened and initialized on demand.


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.

- Enumerations are expressed with symbols.  For example
  GTK_WINDOW_TOPLEVEL is written as 'toplevel.  The symbols should be
  easy to guess from their C counterparts, but they are not completely
  systematic.  See gtk.defs for the definite details.

- Flags (or bitmasks) are expressed as lists of symbols.  For example
  GTK_EXPAND|GTK_FILL is '(expand fill).

- Callbacks don't take a client-data argument, so you don't have to
  specify one to gtk_signal_connect, or 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.

  This is likely to change in the future.  Then no GtkObject will be
  destroyed while Scheme has a reference to it.  But right now, this
  is not possible because everyone explicitely destroys GtkWidgets
  when they should disappear from the screen, and preventing them from
  destruction while Scheme has a reference to them means that they
  will never disappear.

- 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.

- Colors and fonts can be specified with strings, like "red" or
  "fixed".

And all the things I forgot about.

"calc.scm" is quite heavily commented, but does not explain Gtk
programming.  It is more an example about extensibility.

Have fun!
