guile-gtk gets overhaul

[Vollmer Marius <mvo zagadka ping de>]

Hi,

I decided to have some time available for Guile-gtk and made some
things happen that have long been overdue.  Please find a snapshot at

    http://www-nt.e-technik.uni-dortmund.de/m_mvo/guile-gtk-19980427.tar.gz

I'd like to release guile-gtk-0.9 soon with these main improvements:

* Use the new ref counting of Gtk+

* Be able to live outside of gnome-guile.

* Make it easy to use the substrate for your own *.defs files, like
  gnome.defs. 

* Be friendly to package maintainers.  I would be very happy to
  include spec files and all.

So I'd like all of you to, but especially the GNOME people and
packagers, to download the snapshot, try it out and tell me if the new
things are at all useful.  I have not yet really tried to make it work
from within gnome-guile as I don't have GNOME installed, but I will
try soon, I think.

Here is the NEWS entry, to wet your appetite:

[whoops there are a bunch of typos/grammos/omitos in there,
 apologies...]

NEWS in 0.9

* Gtk+ version 1.0 is required from now on.

* The symlink to make the (toolkits gtk) be dynamically linkable is no
  longer made during `make install'.  It is tricky to get this right
  on a heterogenous network and it is probably better to do it
  manually.  Package maintainers might want to make an appropriate
  symlink in the post-install actions of the package.

* The Scheme code (toolkits/gtk.scm and event-repl.scm) is now
  installed under the prefix of this package, not under the prefix
  where Guile was installed.  This will not make a difference most of
  the time, because Guile and this package will likely be installed
  with the same prefix, but being too clever about where to install
  Scheme files caused trouble for package maintainers, I think.

* New Scheme function `gtk-standalone?' that returns whether the Guile
  interpreter is running a Gtk-aware read-eval-print-loop or not.
  When `(gtk-standalone?)' returns true you should call `gtk-main' or
  `gtk-exit' from your script at the approriate times, else the repl
  will take care of handling all events and quitting the interpreter.

* New Scheme function `gtk-callback-trampoline' that can be used to
  intercept every callback to a Scheme procedure.  Currently, this is
  used catch errors that occur in callbacks and popup a window showing
  the error message with a backtrace.

* The types `int' and `uint' from the definition files are now handled
  properly.

* The type `string' can now be used as the return type of functions.
  Be sure to understand that the string is assumed to to be in
  malloced memory and that the caller takes ownership of that memory.
  Whe you want to return a string whose memory should not be freed by
  the caller, use the type `static_string' instead.

* New Scheme functions `gtk-object-new' and `gtk-object-set'.
  They can be used to create new GtkObjects or set their attributes
  with a variable-length keyword/value list.  `gtk-widget-new' and
  `gtk-widget-set' are provided, too.

    (gtk-object-new TYPE KEY VAL KEY VAL ...)
    (gtk-widget-new TYPE KEY VAL KEY VAL ...)
    (gtk-object-set OBJ KEY VAL KEY VAL ...)
    (gtk-widget-set OBJ KEY VAL KEY VAL ...)
	
  TYPE is the name of the type that the new object should be created
  of.  It should be a symbol.  KEY is either a symbole or a keyword.
  It can be a fully qualified attribute name like "GtkWidget::parent",
  or it can be a shortened version like "parent".  See
  "examples/simple.scm" for an example.  Here is a very short one:

    (gtk-object-new 'GtkButton 'label "Hi")

  The TYPE names must already be known to either Guile-Gtk or Gtk+.
  This means that they must either be listed in some *.defs file that
  has been translated into glue code and the initialization function
  of that code has been called; or that the type has already been used
  somewhere else (and can thus be found with `gtk_type_from_name').

  The "GtkObject::signal::<name>" form is not supported.

* New Scheme function `gtk-object-get' and `gtk-widget-get'.  Use them
  like

     (gtk-widget-get label 'label)

* Guile-gtk now uses the improved reference counting of Gtk+.  This
  should not be too visible from the outside.

  The difference is that no GtkObject will silently disappear when
  Scheme still has a reference to it.  Destruction of a GtkObject is
  now decoupled from its `finalization'.  Calling `gtk-widget-destroy'
  continues to remove a widget from the display and clean it up in
  other ways, but the actual GtkWidget structure will only be freed
  when the last reference to it has been revoked.  Thus, reference
  counting is now only a resource management technique (as it should
  be) and because Scheme has automatic garbage collection you do not
  need to worry about it.  Consequently, the `gtk_object_ref' and
  `gtk_object_unref' calls are not exported to Scheme.

  Another consequence is that the Scheme value that stands in for a
  particular GtkObject will not vanish as long as the GtkObject is
  there.  This mens that you can have weak references to them that
  will only then be invaliddated when truely no-one cares about the
  GtkObject any longer (both from within Scheme and from the outside).

  Unfortunately, it is possible to form cycles of GtkObjects and other
  Scheme values that are not detected by the garbage collector.  These
  cycles will not be collected altho they are garbage.  The explicit
  destruction of a GtkObject that is part of this cycle will very
  likely break it and make all members collectable; so as long as you
  destroy all your object, everything should be fine.

  For a cycle to go undetected, it must involve one or more Scheme
  value (because GtkObject do not form cycles themselves) and at least
  one `untraced' pointer from one GtkObject to another one.  Currently
  only the parent->child link is traced, but the plan is to extend
  this tracing to all inter-object pointers and thus to eliminate the
  potential for cycles completely.

  Another drawback of untraced references is that they cause certain
  GtkObjects to be collected later than necessary.  For example, a
  GtkAdjustment that is in use by a GtkRange *and* known to Scheme has
  a reference count of 2, one from the GtkRange, the other from the
  Scheme proxy object.  The GC might discover that the GtkRange is
  garbage and collect it, thus releasing one referece to the
  GtkAdjustment.  The GtkAdjustment, however, has not been detected as
  garbage, because there was an unidentified (untraced) reference to
  it.  Only the next GC will collect the GtkAdjustment.

* Boxed types are implemented differently and can now be reliably compared
  with `eq?`.

* The `gen-typeinfo' script has been renamed to `build-guile-gtk'  and 
  is installed.  It is almost ready to be used for generating glue
  code for external *.defs files.

  The usage of build-guile-gtk is

     guile-guile-gtk OP [OPTIONS] DEFS

  The only supported OP currently is "glue", which will write glue
  code for the definitions from the file DEFS to stdout.  DEFS is the
  name of a file with the familiar feature definitions.  When DEFS
  does not exist, it is searched for in the `import path' which
  initially consist of the directory "$(prefix)/share/gtk".  You can
  add directories to the import path with the

     -I dir

  option.  Note that the "-I" and "dir" must be separate arguments.

  From with a DEFS file you can import other files with the statement
  
     (import DEFS)

  This will read DEFS and make all type definitions in it available.
  No glue code will be generated for the definitions in DEFS.  DEFS is
  searched in the same way as the file given on the command line.

  After reading the foo.defs file (either from the command line or due
  to a import statement) build-guile-gtk tries to read a file named
  "foo.defs.guile".

  The statement

     (add-options SYM OPTS...)

  can be used to add extra `options' to arbitrary features from a
  *.defs file.  SYM identifies the feature, it is either a type or
  function name.  OPTS is a list of options.  An option is itself a
  list of the form

     (NAME VALS...)

  where NAME is symbol that identifies the option.  The statement
  `add-options' is Guile-gtk specific and should only be used in
  *.defs.guile files.  In addition, there is also a statement

     (options OPTS)

  that can be used to set global options.  The exact set of options is
  rather ad-hoc currently.
  
* The `guile.details' file is gone.  Its function is now performed by
  the options mentioned in the last paragraph.

* The file `gtk.defs' has been split into `gdk.defs' and `gtk.defs',
  mostly to test out the new features of build-guile-gtk.

* There is a new example program `test-gdk.sccm' that shows how one
  might go about drawing from Scheme.