guile-gnome

The GLib type system

One key part of GLib is libgobject, an implementation of a runtime, dynamic type system for C. Besides providing an object system to C, its main design goal was to increase the ease with which C code can be wrapped by interpreted languages, such as Guile or Perl.

Guile's wrapper is implemented by the module (gnome gobject). Go ahead and open up a Guile session and load it up:

guile> (use-modules (gnome gobject))

We will leave off the guile> prompt in the rest of this tutorial. When we want to show the value of an expression, we use ⇒:

(+ 3 5) ⇒ 8

Make some coffee, and let's dig in.

Basic types

When communicating with libgobject, most values need to be strictly-typed. There is a type class corresponding to each basic type in C: <gchar>, <guchar>, <gboolean>, <gint>, <guint>, <glong>, <gulong>, <gint64>, <guint64>, <gfloat>, <gdouble>, and <gchararray>.

You can make instances of these class with make:

(make <gboolean> #:value #f) ⇒ #<gvalue <gboolean> 40529040 #f>

(make <guint> #:value 85) ⇒ #<gvalue <guint> 4054f040 85>

(make <gfloat> #:value 3.1415) ⇒ #<gvalue <gfloat> 40556af0 3.1414999961853>

(make <gchararray> #:value "Hello World!") ⇒ #<gvalue <gchararray> 4055af90 Hello World!>

You can get the normal Scheme values back with gvalue->scm:

(gvalue->scm (make <gchararray> #:value "Hello World!")) ⇒ "Hello World!"

Enums and flags

Enumerated values and bitflags are an essential part of many C APIs, and so they are specially wrapped in the GLib type system. You can create new enumerated types in Scheme by subclassing <genum>:

(define-class <foo> (<genum>)
  #:vtable '#((hello "Hello World" 1) (test "Test" 2)))

Instances are created with make, just like with the other types:

(make <foo> #:value 'hello)
(make <foo> #:value "Hello World")
(make <foo> #:value 1)

;; These three all do the same thing ⇒ #<gvalue <foo> 406275f8 (hello Hello World 1)>

If there's an already existing enum or flags class, you can get information about it:

(genum-class->value-table <foo>) ⇒ #((hello "Hello World" 1) (test "Test" 2))

Enums and flags have a special representation on the Scheme side. You can convert them to Scheme values as symbols, names, or as a numeric value.

(define foo (make <foo> #:value 'hello))
(genum->symbol foo) ⇒ hello
(genum->name foo) ⇒ "Hello World"
(genum->value foo) ⇒ 1

Closures

Another data type provided by libgobject is the closure, an abstraction for callable objects. The actual object is a function in some language, be it C, Scheme, or even Python. You can create a closure in Guile with make (again):

(define (times-eight x)
  (* x 8))

(define closure (make <gclosure> #:return-type <gint>
                  #:param-types (list <gulong>)
                  #:func times-eight))

(gclosure-invoke closure 10) ⇒ 80

The closure you create can then be passed to a C function, so that any C function (even those that know nothing about Guile) can call back into Scheme.

GType

All of the types that GLib knows about are available to Guile, regardless of which language defined them. GLib implements this via a type system, where every type has a name. So if you make a type called ``Foo'' in C, you can get to it in Scheme via gtype-from-name and gtype->class:

;; Retrieve the type for the foo enum we made earlier in the tutorial
(define foo-type (gtype-from-name "Foo"))
(define <foo> (gtype->class foo-type))

(make <foo> #:value 2) ⇒ #<gvalue <foo> 40535e50 (test Test 2)>

GObject

<gobject> (GObject in C) is the basic object type in libgobject. (gnome gobject) allows you to access existing GObject types, as well as to create new GObject types in Scheme.

Before we start, let's pull in some generic functions that reduce the amount of typing we have to do:

(use-modules (gnome gobject generics))

Let's assume we start with <gtk-window> from (gnome gtk). The keyword arguments to make are interpreted as GObject properties to set:

(define window (make <gtk-window>
                 #:type 'toplevel #:title "Hello, World!"))

You can connect to signals on the new instance:

(connect window 'delete-event
         (lambda (window event)
           ;; Returns #t to ignore this event
           #t))

;; connect is a generic function implemented by
;; gtype-instance-signal-connect

And get and set properties...

(get window 'title) ⇒ "Hello, World!"
(set window 'resizable #f)

;; get and set are also generics, implemented by gobject-get-property
;; and gobject-set-property

Deriving your own GObject types

You can create new GObject types directly from Scheme, deriving either from a C object type or one you made in Scheme. Properties and signals for the class, if any, should be set when you derive the class, not afterwards.

;; deriving from <gobject>
(define-class <test> (<gobject>)
  ;; a normal object slot
  my-data

  ;; an object slot exported as a gobject property
  (pub-data #:param-spec (list <gparam-long> #:name 'test))

  ;; a signal with no arguments and no return value
  #:signal '(frobate #f))

;; deriving from <test> -- also inherits properties and signals
(define-class <hungry> (<test>))

Adding a signal automatically defines the default method:

;; This is the default handler for this signal.
(define-method (test:frobate (object <test>))
  (format #t "Frobating ~A\n" object))

;; We can override it for subclasses
(define-method (test:frobate (object <hungry>))
  (next-method) ;; chain up
  (format #t "I'm hungry\n"))

(emit (make <hungry>) 'frobate)
;; Try it!

You can override the initialize, gobject:get-property, and gobject:set-property methods. For an extended example, see tic-tac-toe.scm in the examples/gtk directory of the distribution.