4 General Conventions

Unless otherwise stated, Gtk+ functions and variables are made available in Guile with names transformed to Scheme style. This means underscores become hyphens, and only lower case is used.

For instance the C function gtk_label_new is gtk-label-new in Guile, or GTK_WIDGET_FLAGS is gtk-widget-flags.

The following general rules are applied to parameters and return values.

NULL

NULL is represented as #f, for functions which accept or return that.

int, gint, etc

All integer types are simply Guile integers. Range checks are applied to parameters, and “inexact” values are not accepted, even if they happen to be integers. (see Exact and Inexact Numbers)

gboolean

Booleans are returned as the usual Scheme #t and #f. For parameters, any non-#f value is taken to be true.

GList, GSList etc

Glib lists are returned as Guile lists. For instance gtk-container-children returns a list of widgets. In parameters, either a Guile list or vector can be given.

Arrays

C level arrays are returned as Guile lists. In parameters, either a Guile list or vector can be given. For instance gtk-curve-set-vector takes a list or vector of floats.

Enumerations

Enumerations are represented in Guile as symbols, with names corresponding to the C definitions and without the prefix indicating their type.

For instance GtkWindowType value GTK_WINDOW_TOPLEVEL is just the symbol toplevel, hence a call (gtk-window-new 'toplevel).

Flags

Sets of flags (bitwise ORs at the C level) are represented in Guile as a list of symbols, possibly an empty list, with names corresponding to the C definitions and without the prefix indicating their type.

For example a GdkModifierType value could be the list (shift-mask control-mask).

Multiple return values

Multiple values are returned in a list. This is the C return value plus values stored through pointers.

For example at the C level gtk_pixmap_get returns a GdkPixmap and a GdkBitmap via pointers. Guile Gtk function gtk-pixmap-get returns these in a two-element list.

Or for example gdk_window_at_pointer returns a GdkWindow and stores an x and y through pointers. These are returned from gdk-window-at-pointer in a three element list.

Strings

Gtk generally uses strings encoded in UTF-8. Guile (versions 1.6 and 1.8) has no direct notion of multi-byte characters in strings, so applications will need to be careful.

Converting to GdkWChar with gdk-mbstowc (see Gdk Module) is one way to identify character boundaries at least.

GType

GType (and GtkType which is the same thing) values are represented as a distinct kind of Scheme level objects, except for GTK_TYPE_INVALID which is represented as #f. Types can be compared with equal?.

As a convenience, functions expecting a GtkType can be passed a symbol which is the name of the type. For example,

          (gtk-widget-new 'GtkLabel)

For types known to Guile Gtk (anything appearing in the defs files), Guile Gtk will call the type initialization functions when necessary. Other types will be available only once relevant C code has created them.

GObject

Each GObject is represented uniquely at the Scheme level, so widgets etc can be compared or hashed with eq?. An object is destroyed when garbage collected, if it's not otherwise in use by Gtk.

Type predicates like GTK_IS_CHECK_BUTTON are implemented as for instance gtk-check-button?. There are no type checking casts like in C, Guile Gtk functions expecting a particular object class always check they get it or a sub-class.

GError

GError parameters at the C level are implemented as scm-error style throws see Procedures for Signaling Errors. For example gdk-pixbuf-new-from-file (see GdkPixbuf Module) is called as

          (gdk-pixbuf-new-from-file "myfile.png")

and if an error occurs it may throw for instance

          (scm-error 'g-error "gdk-pixbuf-new-from-file"
                     "Failed to open file 'myfile.png': No such file or directory"
                     '(g-file-error-quark 4))

The data parameter is a list of error domain and code number.

Threading

Guile Gtk programs can use Guile threads in the normal way, but note that the Gtk and Gdk libraries are not thread-safe and that the Guile Gtk interface has no special protection against two threads calling Gtk/Gdk simultaneously. gdk-threads-enter and gdk-threads-leave are available though, and can be used the same as in a C program.

Perhaps in the future additional threading protection will be provided by Guile Gtk. Presently two threads both calling Gtk/Gdk can crash the interpreter, the idea would be to guard against that.