doc/gobject/guile-gnome-gobject.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename guile-gnome-gobject.info
@settitle Guile-GNOME: GObject
@c %**end of header

@copying
This manual is for Guile-GNOME: GObject (version 2.16.0, updated 12 June 2008)

Copyright 2003,2004,2005,2006,2007,2008 Free Software Foundation

@quotation
Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU General Public License, Version 2 or any later version
published by the Free Software Foundation.

@end quotation

@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile-GNOME: GObject: (guile-gnome-gobject.info).  The GLib object system in Scheme.
@end direntry

@titlepage
@title Guile-GNOME: GObject
@subtitle version 2.16.0, updated 12 June 2008
@author Andy Wingo (@email{wingo at pobox.com})
@author Martin Baulig (@email{baulig at suse.de})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top
@top Guile-GNOME: GObject
@insertcopying
@menu
* gnome-2::              Guile-GNOME is stable and parallel-installable
* gnome gobject::        One module to bind them
* gnome gobject gtype::  The base of the GObject type system
* gnome gobject gvalue::  Generic boxed values
* gnome gobject gparameter::  Parameters with constraints and default values
* gnome gobject gclosure::  Language-portable closures
* gnome gobject gsignal::  Using closures as extension points
* gnome gobject gobject::  GLib's main object implementation
* gnome gobject generics::  Shorthand for many common GObject operations
* gnome gobject utils::  Miscellaneous useful functions
* gnome gw generics::    A home for generated generic functions
* gnome gw support gobject::  Integration between G-Wrap and GObject types
* gnome gw support defs::  Create G-Wrap wrapsets from ``defs'' files
* gnome gw support gtk-doc::  Parse C documentation from gtk-doc into texinfo
* gnome gw support modules::  Fondling Guile's module system

* Type Index::
* Function Index::
@end menu

@end ifnottex

@iftex
@shortcontents
@end iftex

@node gnome-2
@chapter (gnome-2)
@section Overview
Selects version 2 of the Guile-GNOME libraries. This module is used for its side
effects; it exports no procedures.

@section Rationale
Early in the development of guile-gnome, we realized that at some point we might
need to make incompatible changes. Of course, we would not want to force a
correctly-written program to break when guile-gnome gets upgraded. For this
reason, we decided to make guile-gnome parallel-installable. A program is
completely specified when it indicates which version of guile-gnome it should
use.

Guile-gnome has the concept of an API version, which indicates a stable API
series. For example, a program written against API version 2 of guile-gnome will
continue to work against all future releases of that API version. It is
permitted to add interfaces within a stable series, but never to remove or
change them incompatibly.

Changing the API version is expected to be a relatively infrequent operation.
The current API version is 2.

There are two manners for a program to specify the guile-gnome version:

@enumerate
@item
Via importing the @code{(gnome-@var{version})} module.

This special module alters guile's load path to include the path of the
specified API version of guile-gnome. For example:

@lisp
 (use-modules (gnome-2))

@end lisp

@item
Via invoking guile as guile-gnome-@var{version}.

This shell script is installed when building a particular version of
guile-gnome, and serves to automatically load the
@code{(gnome-@var{apiversion})} module. For example, to get a repl ready for
guile-gnome:

@example
 $ guile-gnome-2

@end example

To load a script with a particular version of guile-gnome:

@example
 $ guile-gnome-2 -s @var{script} @var{args...}
@end example

To specify the guile-gnome version in a script, you might begin the file with:

@example
 #! /bin/sh
 # -*- scheme -*-
 exec guile-gnome-2 -s $0
 !#
 ;; scheme code here...

@end example

@end enumerate

A program must select the guile-gnome version before importing any guile-gnome
modules. Indeed, one cannot even import @code{(gnome gobject)} before doing so.

For a further rationale on parallel installability, see
@uref{http://ometer.com/parallel.html}.

@section Usage
@node gnome gobject
@chapter (gnome gobject)
@section Overview
This is the Guile wrapper of @code{libgobject}, an implementation of a runtime,
dynamic type system for C. Besides providing an object system to C,
@code{libgobject}'s main design goal was to increase the ease with which C code
can be wrapped by interpreted languages, such as Guile or Perl.

This module, @code{(gnome gobject)}, just re-exports procedures from other
modules, so its documentation seems an opportune spot for a more tutorial-like
introduction. So open up a Guile session and let's begin.

First, if you haven't done it, load the appropriate version of Guile-GNOME:

@lisp
 guile> (use-modules (gnome-2))

@end lisp

@code{(gnome gobject)} is based heavily on GOOPS, Guile's object system, so go
ahead and load up that too:

@lisp
 guile> (use-modules (oop goops))

@end lisp

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

@lisp
 (+ 3 5)
 @result{} 8

@end lisp

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

You can make instances of these class with @code{make}:

@lisp
 (make <gboolean> #:value #f)
 @result{} #<gvalue <gboolean> 40529040 #f>

 (make <guint> #:value 85)
 @result{} #<gvalue <guint> 4054f040 85>

 (make <gfloat> #:value 3.1415)
 @result{} #<gvalue <gfloat> 40556af0 3.1414999961853>

 (make <gchararray> #:value "Hello World!")
 @result{} #<gvalue <gchararray> 4055af90 Hello World!>

@end lisp

You can get the normal Scheme values back with @code{gvalue->scm}:

@lisp
 (gvalue->scm (make <gchararray> #:value "Hello World!"))
 @result{} "Hello World!"

@end lisp

@section 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 @code{<genum>}:

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

@end lisp

Instances are created with @code{make}, just like with the other types:

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

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

@end lisp

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

@lisp
 (genum-class->value-table <foo>)
 @result{} #((hello "Hello World" 1) (test "Test" 2))

@end lisp

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.

@lisp
 (define foo (make <foo> #:value 'hello))
 (genum->symbol foo)
 @result{} hello
 (genum->name foo)
 @result{} "Hello World"
 (genum->value foo)
 @result{} 1

@end lisp

@section 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 @code{gtype-name->class}:

@lisp
 ;; Retrieve the type for the foo enum we made earlier in the tutorial
 (define copy-of-<foo> (gtype-name->class "Foo"))
 (eq? <foo> copy-of-<foo>)
 @result{} #t

 (make copy-of-<foo> #:value 2)
 @result{} #<gvalue <foo> 40535e50 (test Test 2)>

@end lisp

@section GObject
@code{<gobject>} (@code{GObject} in C) is the basic object type in
@code{libgobject}. @code{(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:

@lisp
 (use-modules (gnome gobject generics))

@end lisp

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

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

@end lisp

You can connect to signals on the new instance:

@lisp
 (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

@end lisp

And get and set properties...

@lisp
 (get window 'title)
 @result{} "Hello, World!"
 (set window 'resizable #f)

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

@end lisp

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

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

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

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

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

@end lisp

Adding a signal automatically defines the default method:

@lisp
 ;; 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!

@end lisp

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

@section Usage
@node gnome gobject gtype
@chapter (gnome gobject gtype)
@section Overview
Base support for the GLib type system.

The GLib runtime type system is broken into a number of modules, of which GType
is the base. A GType is a simply a named type. Some types are fundamental and
cannot be subclassed, such as integers. Others can form the root of complicated
object hierarchies, such as @code{<gobject>}.

One can obtain the class for a type if you know its name. For example,

@lisp
  (gtype-name->class "guint64") @result{} #<<gvalue-class> <guint64>>

@end lisp

A more detailed reference on the GLib type system may be had at
@uref{http://library.gnome.org/devel/gobject/stable/}.

@section Usage
@anchor{gnome gobject gtype <gtype-class>}@deftp Class <gtype-class>
The metaclass of all GType classes. Ensures that GType classes have a
@code{gtype} slot, which records the primitive GType information for this class.

@end deftp

@anchor{gnome gobject gtype <gtype-instance>}@deftp Class <gtype-instance>
The root class of all instantiatable GType classes. Adds a slot,
@code{gtype-instance}, to instances, which holds a pointer to the C value.

@end deftp

@anchor{gnome gobject gtype gtype-name->class}@deffn Primitive gtype-name->class name
Return the @code{<gtype-class>} associated with the GType, @var{name}.

@end deffn

@anchor{gnome gobject gtype class-name->gtype-name}@defun class-name->gtype-name class-name
Convert the name of a class into a suitable name for a GType. For example:

@lisp
 (class-name->gtype-name '<foo-bar>) @result{} "FooBar"
@end lisp

@end defun

@anchor{gnome gobject gtype gruntime-error}@defun gruntime-error format-string . args
Signal a runtime error. The error will be thrown to the key
@code{gruntime-error}.

@end defun

@anchor{gnome gobject gtype gtype-instance-destroy!}@deffn Primitive gtype-instance-destroy! instance
Release all references that the Scheme wrapper @var{instance} has on the
underlying C value, and release pointers associated with the C value that point
back to Scheme.

Normally, you don't need to call this function, because garbage collection will
take care of resource management. However some @code{<gtype-class>} instances
have semantics that require this function. The canonical example is that when a
@code{<gtk-object>} emits the @code{destroy} signal, all code should drop their
references to the object. This is, of course, handled internally in the
@code{(gnome gtk)} module.

@end deffn

@node gnome gobject gvalue
@chapter (gnome gobject gvalue)
@section Overview
GLib supports generic typed values via its GValue module. These values are
wrapped in Scheme as instances of @code{<gvalue-class>} classes, such as
@code{<gint>}, @code{<gfloat>}, etc.

In most cases, use of @code{<gvalue>} is transparent to the Scheme user. Values
which can be represented directly as Scheme values are normally given to the
user in their Scheme form, e.g. @code{#\a} instead of @code{#<gvalue <gchar>
3020c708 a>}. However, when dealing with low-level routines it is sometimes
necessary to have values in @code{<gvalue>} form. The conversion between the two
is performed via the @code{scm->gvalue} and @code{gvalue->scm} functions.

The other set of useful procedures exported by this module are those dealing
with enumerated values and flags. These objects are normally represented on the
C side with integers, but they have symbolic representations registered in the
GLib type system.

On the Scheme side, enumerated and flags values are canonically expressed as
@code{<gvalue>} objects. They can be converted to integers or symbols using the
conversion procedures exported by this module. It is conventional for Scheme
procedures that take enumerated values to accept any form for the values, which
can be canonicalized using @code{(make <your-enum-type> #:value @var{value})},
where @var{value} can be an integer, a symbol (or symbol list in the case of
flags), or the string ``nickname'' (or string list) of the enumerated/flags
value.

@section Usage
@anchor{gnome gobject gvalue <gvalue>}@deftp Class <gvalue>
@end deftp

@anchor{gnome gobject gvalue <gboolean>}@deftp Class <gboolean>
A @code{<gvalue>} class for boolean values.

@end deftp

@anchor{gnome gobject gvalue <gchar>}@deftp Class <gchar>
A @code{<gvalue>} class for signed 8-bit values.

@end deftp

@anchor{gnome gobject gvalue <guchar>}@deftp Class <guchar>
A @code{<gvalue>} class for unsigned 8-bit values.

@end deftp

@anchor{gnome gobject gvalue <gint>}@deftp Class <gint>
A @code{<gvalue>} class for signed 32-bit values.

@end deftp

@anchor{gnome gobject gvalue <guint>}@deftp Class <guint>
A @code{<gvalue>} class for unsigned 32-bit values.

@end deftp

@anchor{gnome gobject gvalue <glong>}@deftp Class <glong>
A @code{<gvalue>} class for signed ``long'' (32- or 64-bit) values.

@end deftp

@anchor{gnome gobject gvalue <gulong>}@deftp Class <gulong>
A @code{<gvalue>} class for unsigned ``long'' (32- or 64-bit) values.

@end deftp

@anchor{gnome gobject gvalue <gint64>}@deftp Class <gint64>
A @code{<gvalue>} class for signed 64-bit values.

@end deftp

@anchor{gnome gobject gvalue <guint64>}@deftp Class <guint64>
A @code{<gvalue>} class for unsigned 64-bit values.

@end deftp

@anchor{gnome gobject gvalue <gfloat>}@deftp Class <gfloat>
A @code{<gvalue>} class for 32-bit floating-point values.

@end deftp

@anchor{gnome gobject gvalue <gdouble>}@deftp Class <gdouble>
A @code{<gvalue>} class for 64-bit floating-point values.

@end deftp

@anchor{gnome gobject gvalue <gchararray>}@deftp Class <gchararray>
A @code{<gvalue>} class for arrays of 8-bit values (C strings).

@end deftp

@anchor{gnome gobject gvalue <gboxed>}@deftp Class <gboxed>
A @code{<gvalue>} class for ``boxed'' types, a way of wrapping generic C
structures. You won't see instances of this class, only of its subclasses.

@end deftp

@anchor{gnome gobject gvalue <gboxed-scm>}@deftp Class <gboxed-scm>
A @code{<gboxed>} class for holding arbitrary Scheme objects.

@end deftp

@anchor{gnome gobject gvalue <gvalue-array>}@deftp Class <gvalue-array>
A @code{<gvalue>} class for arrays of @code{<gvalue>}.

@end deftp

@anchor{gnome gobject gvalue <gpointer>}@deftp Class <gpointer>
A @code{<gvalue>} class for opaque pointers.

@end deftp

@anchor{gnome gobject gvalue <genum>}@deftp Class <genum>
A @code{<gvalue>} base class for enumerated values. Users may define new
enumerated value types via subclssing from @code{<genum>}, passing
@code{#:vtable @var{table}} as an initarg, where @var{table} should be in a
format suitable for passing to @code{genum-register-static}.

@end deftp

@anchor{gnome gobject gvalue <gflags>}@deftp Class <gflags>
A @code{<gvalue>} base class for flag values. Users may define new flag value
types via subclssing from @code{<gflags>}, passing @code{#:vtable @var{table}}
as an initarg, where @var{table} should be in a format suitable for passing to
@code{gflags-register-static}.

@end deftp

@anchor{gnome gobject gvalue genum-register-static}@deffn Primitive genum-register-static name vtable
Creates and registers a new enumerated type with name @var{name} with the C
runtime. There must be no type with name @var{name} when this function is
called.

The new type can be accessed by using @code{gtype-name->class}.

@var{vtable} is a vector describing the new enum type. Each vector element
describes one enum element and must be a list of 3 elements: the element's nick
name as a symbol, its name as a string, and its integer value.

@lisp
(genum-register-static "Test"
  #((foo "Foo" 1) (bar "Bar" 2) (baz "Long name of baz" 4)))
@end lisp

@end deffn

@anchor{gnome gobject gvalue gflags-register-static}@deffn Primitive gflags-register-static name vtable
Creates and registers a new flags @code{<gtype-class>} with name @var{name} with
the C runtime.

The @var{vtable} should be in the format described in the documentation for
@code{genum-register-static}.

@end deffn

@anchor{gnome gobject gvalue genum-class->value-table}@deffn Primitive genum-class->value-table class
Return a table of the values supported by the enumerated @code{<gtype-class>}
@var{class}. The return value will be in the format described in
@code{genum-register-static}.

@end deffn

@anchor{gnome gobject gvalue gflags-class->value-table}@deffn Primitive gflags-class->value-table class
Return a table of the values supported by the flag @code{<gtype-class>}
@var{class}. The return value will be in the format described in
@code{gflags-register-static}.

@end deffn

@anchor{gnome gobject gvalue scm->gvalue}@deffn Primitive scm->gvalue class scm
Convert a Scheme value into a @code{<gvalue>} of type @var{class}. If the
conversion is not possible, raise a @code{gruntime-error}.

@end deffn

@anchor{gnome gobject gvalue gvalue->scm}@deffn Primitive gvalue->scm value
Convert a @code{<gvalue>} into it normal scheme representation, for example
unboxing characters into Scheme characters. Note that the Scheme form for some
values is the @code{<gvalue>} form, for example with boxed or enumerated values.

@end deffn

@anchor{gnome gobject gvalue genum->symbol}@defun genum->symbol obj
Convert the enumerated value @var{obj} from a @code{<gvalue>} to its symbol
representation (its ``nickname'').

@end defun

@anchor{gnome gobject gvalue genum->name}@defun genum->name obj
Convert the enumerated value @var{obj} from a @code{<gvalue>} to its
representation as a string (its ``name'').

@end defun

@anchor{gnome gobject gvalue genum->value}@deffn Primitive genum->value value
Convert the enumerated value @var{obj} from a @code{<gvalue>} to its
representation as an integer.

@end deffn

@anchor{gnome gobject gvalue gflags->value}@deffn Primitive gflags->value value
Convert the flags value @var{obj} from a @code{<gvalue>} to its representation
as an integer.

@end deffn

@anchor{gnome gobject gvalue gflags->symbol-list}@defun gflags->symbol-list obj
Convert the flags value @var{obj} from a @code{<gvalue>} to a list of the
symbols that it represents.

@end defun

@anchor{gnome gobject gvalue gflags->name-list}@defun gflags->name-list obj
Convert the flags value @var{obj} from a @code{<gvalue>} to a list of strings,
the names of the values it represents.

@end defun

@anchor{gnome gobject gvalue gflags->value-list}@defun gflags->value-list obj
Convert the flags value @var{obj} from a @code{<gvalue>} to a list of integers,
which when @code{logand}'d together yield the flags' value.

@end defun

@node gnome gobject gparameter
@chapter (gnome gobject gparameter)
@section Overview
Parameters are constraints for values, both in type and in range. This module
wraps the parameters code of the GLib type system, allowing parameters to be
manipulated and created from Scheme.

There is a parameter class for each type of parameter: @code{<gparam-int>},
@code{<gparam-object>}, etc.

@section Usage
@anchor{gnome gobject gparameter <gparam>}@deftp Class <gparam>
The base class for GLib parameter objects. (Doc slots)

@end deftp

@anchor{gnome gobject gparameter <gparam-char>}@deftp Class <gparam-char>
Parameter for @code{<gchar>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-uchar>}@deftp Class <gparam-uchar>
Parameter for @code{<guchar>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-boolean>}@deftp Class <gparam-boolean>
Parameter for @code{<gboolean>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-int>}@deftp Class <gparam-int>
Parameter for @code{<gint>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-uint>}@deftp Class <gparam-uint>
Parameter for @code{<guint>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-long>}@deftp Class <gparam-long>
Parameter for @code{<glong>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-ulong>}@deftp Class <gparam-ulong>
Parameter for @code{<gulong>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-int64>}@deftp Class <gparam-int64>
Parameter for @code{<gint64>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-uint64>}@deftp Class <gparam-uint64>
Parameter for @code{<guint64>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-float>}@deftp Class <gparam-float>
Parameter for @code{<gfloat>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-double>}@deftp Class <gparam-double>
Parameter for @code{<gdouble>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-unichar>}@deftp Class <gparam-unichar>
Parameter for Unicode codepoints, represented as @code{<guint>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-pointer>}@deftp Class <gparam-pointer>
Parameter for @code{<gpointer>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-string>}@deftp Class <gparam-string>
Parameter for @code{<gchararray>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-boxed>}@deftp Class <gparam-boxed>
Parameter for @code{<gboxed>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-enum>}@deftp Class <gparam-enum>
Parameter for @code{<genum>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-flags>}@deftp Class <gparam-flags>
Parameter for @code{<gflags>} values.

@end deftp

@anchor{gnome gobject gparameter <gparam-spec-flags>}@deftp Class <gparam-spec-flags>
A @code{<gflags>} type for the flags allowable on a @code{<gparam>}:
@code{read}, @code{write}, @code{construct}, @code{construct-only}, and
@code{lax-validation}.

@end deftp

@anchor{gnome gobject gparameter gparameter:uint-max}@defvar gparameter:uint-max
@end defvar

@anchor{gnome gobject gparameter gparameter:int-min}@defvar gparameter:int-min
@end defvar

@anchor{gnome gobject gparameter gparameter:int-max}@defvar gparameter:int-max
@end defvar

@anchor{gnome gobject gparameter gparameter:ulong-max}@defvar gparameter:ulong-max
@end defvar

@anchor{gnome gobject gparameter gparameter:long-min}@defvar gparameter:long-min
@end defvar

@anchor{gnome gobject gparameter gparameter:long-max}@defvar gparameter:long-max
@end defvar

@anchor{gnome gobject gparameter gparameter:uint64-max}@defvar gparameter:uint64-max
@end defvar

@anchor{gnome gobject gparameter gparameter:int64-min}@defvar gparameter:int64-min
@end defvar

@anchor{gnome gobject gparameter gparameter:int64-max}@defvar gparameter:int64-max
@end defvar

@anchor{gnome gobject gparameter gparameter:float-max}@defvar gparameter:float-max
@end defvar

@anchor{gnome gobject gparameter gparameter:float-min}@defvar gparameter:float-min
@end defvar

@anchor{gnome gobject gparameter gparameter:double-max}@defvar gparameter:double-max
@end defvar

@anchor{gnome gobject gparameter gparameter:double-min}@defvar gparameter:double-min
@end defvar

@anchor{gnome gobject gparameter gparameter:byte-order}@defvar gparameter:byte-order
@end defvar

@node gnome gobject gclosure
@chapter (gnome gobject gclosure)
@section Overview
The GLib type system supports the creation and invocation of ``closures'',
objects which can be invoked like procedures. Its infrastructure allows one to
pass a Scheme function to C, and have C call into Scheme, and vice versa. In
Scheme, @code{<gclosure>} holds a Scheme procedure, the @code{<gtype>} of its
return value, and a list of the @code{<gtype>}'s of its arguments. Closures can
be invoked with @code{gclosure-invoke}.

However since on the C level, closures do not carry a description of their
argument and return types, when we invoke a closure we have to be very explicit
about the types involved. For example:

@lisp
 (gclosure-invoke (make <gclosure>
                   #:return-type <gint>
                   #:param-types (list <gulong>)
                   #:func (lambda (x) (* x x)))
                  <gulong>
                  (scm->gvalue <gulong> 10))
 @result{} 100

@end lisp

@section Usage
@anchor{gnome gobject gclosure <gclosure>}@deftp Class <gclosure>
The Scheme representation of a GLib closure: a typed procedure object that can
be passed to other languages.

@end deftp

@anchor{gnome gobject gclosure gclosure-invoke}@deffn Primitive gclosure-invoke closure return_type args
Invoke a closure.

A @code{<gclosure>} in GLib's abstraction for a callable object. This
abstraction carries no type information, so the caller must supply all arguments
as typed <gvalue> instances, which may be obtained by the scheme procedure,
@code{scm->gvalue}.

As you can see, this is a low-level function. In fact, it is not used internally
by the @code{guile-gobject} bindings.

@end deffn

@node gnome gobject gsignal
@chapter (gnome gobject gsignal)
@section Overview
GSignal is a mechanism by which code, normally written in C, may expose
extension points to which closures can be connected, much like Guile's hooks.
Instantiatable types can have signals associated with them; for example,
@code{<gtk-widget>} has an @code{expose} signal that will be ``fired'' at
certain well-documented points.

Signals are typed. They specify the types of their return value, and the types
of their arguments.

This module defines routines for introspecting, emitting, connecting to,
disconnecting from, blocking, and unblocking signals. Additionally it defines
routines to define new signal types on instantiatable types.

@section Usage
@anchor{gnome gobject gsignal <gsignal>}@deftp Class <gsignal>
A @code{<gsignal>} describes a signal on a @code{<gtype-instance>}: its name,
and how it should be called.

@end deftp

@anchor{gnome gobject gsignal gtype-class-get-signals}@deffn Primitive gtype-class-get-signals class tail
Returns a list of signals belonging to @var{class} and all parent types.

@end deffn

@anchor{gnome gobject gsignal gtype-class-get-signal-names}@defun gtype-class-get-signal-names class
Returns a vector of signal names belonging to @var{class} and all parent
classes.

@end defun

@anchor{gnome gobject gsignal gtype-instance-signal-emit}@deffn Primitive gtype-instance-signal-emit object name args
@end deffn

@anchor{gnome gobject gsignal gtype-instance-signal-connect}@defun gtype-instance-signal-connect object name func . after?
Connects @var{func} as handler for the @code{<gtype-instance>} @var{object}'s
signal @var{name}.

@var{name} should be a symbol. @var{after} is boolean specifying whether the
handler is run before (@code{#f}) or after (@code{#t}) the signal's default
handler.

Returns an integer number which can be used as arugment of
@code{gsignal-handler-block}, @code{gsignal-handler-unblock},
@code{gsignal-handler-disconnect} and @code{gsignal-handler-connected?}.

@end defun

@anchor{gnome gobject gsignal gtype-instance-signal-connect-after}@defun gtype-instance-signal-connect-after object name func
Convenience function for calling @code{gtype-instance-signal-connect} with
@var{after} = @code{#t}.

@end defun

@anchor{gnome gobject gsignal gsignal-handler-block}@deffn Primitive gsignal-handler-block instance handler_id
@end deffn

@anchor{gnome gobject gsignal gsignal-handler-unblock}@deffn Primitive gsignal-handler-unblock instance handler_id
@end deffn

@anchor{gnome gobject gsignal gsignal-handler-disconnect}@deffn Primitive gsignal-handler-disconnect instance handler_id
@end deffn

@anchor{gnome gobject gsignal gsignal-handler-connected?}@deffn Primitive gsignal-handler-connected? instance handler_id
@end deffn

@anchor{gnome gobject gsignal gtype-class-create-signal}@defun gtype-class-create-signal class name return-type param-types
Create a new signal associated with the @code{<gtype-class>} @var{class}.

@var{name} should be a symbol, the name of the signal. @var{return-type} should
be a @code{<gtype-class>} object. @var{param-types} should be a list of
@code{<gtype-class>} objects.

In a bit of an odd interface, this function will return a new generic function,
which will be run as the signal's default handler, whose default method will
silently return an unspecified value. The user may define new methods on this
generic to provide alternative default handler implementations.

@end defun

@node gnome gobject gobject
@chapter (gnome gobject gobject)
@section Overview
GObject is what is commonly understood as @emph{the} object system for GLib.
This is not strictly true. GObject is @emph{one} implementation of an object
system, built on the other modules: GType, GValue, GParameter, GClosure, and
GSignal.

Similarly, this Guile module provides integration with the GObject object
system, built on the Guile modules that support GType, GValue, GParameter,
GClosure, and GSignal.

The main class exported by this module is @code{<gobject>}. @code{<gobject>}
classes can be subclassed by the user, which will register new subtypes with the
GType runtime type system. @code{<gobject>} classes are are also created as
needed when wrapping GObjects that come from C, for example from a function's
return value.

Besides supporting derivation, and signals like other @code{<gtype-instance>}
implementations, @code{<gobject>} has the concept of @dfn{properties}, which are
@code{<gvalue>}'s associated with the object. The values are constrained by
@code{<gparam>}'s, which are associated with the object's class. This module
exports the necessary routines to query, get, and set @code{<gobject>}
properties.

In addition, this module defines the @code{<ginterface>} base class, whose
subclasses may be present as mixins of @code{<gobject>} classes. For example:

@lisp
 (use-modules (gnome gtk) (oop goops))
 (class-direct-supers <gtk-widget>) @result{}
    (#<<gobject-class> <atk-implementor-iface> 3033bad0>
     #<<gobject-class> <gtk-object> 3034bc90>)

@end lisp

In this example, we see that @code{<gtk-widget>} has two superclasses,
@code{<gtk-object>} and @code{<atk-implementor-iface>}. The second is an
interface implemented by the @code{<gtk-widget>} class. See
@code{gtype-interfaces} for more details.

@section Usage
@anchor{gnome gobject gobject <gobject>}@deftp Class <gobject>
The base class for GLib's default object system.

@code{<gobject>}'s metaclass understands a new slot option, @code{#:gparam},
which will export a slot as a @code{<gobject>} property. The default
implementation will set and access the value from the slot, but you can
customize this by writing your own methods for @code{gobject:set-property} and
@code{gobject:get-property}.

In addition, the metaclass also understands @code{#:gsignal} arguments, which
define signals on the class, and define the generics for the default signal
handler. See @code{gtype-class-define-signal} for more information.

For example:

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

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

  ;; likewise, using non-default parameter settings
  (foo-data #:gparam (list <gparam-long> #:name 'foo
                           #:minimum -3 #:maximum 1000
                           #:default-value 42))

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

  ;; a signal with arguments and a return value
  #:gsignal (list 'frobate <gboolean> <gint> <glong>))

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

@code{<gobject>} classes also expose a slot for each GObject property defined on
the class, if such a slot is not already defined.

@end deftp

@anchor{gnome gobject gobject <ginterface>}@deftp Class <ginterface>
The base class for GLib's interface types. Not derivable in Scheme.

@end deftp

@anchor{gnome gobject gobject <gparam-object>}@deftp Class <gparam-object>
Parameter for @code{<gobject>} values.

@end deftp

@anchor{gnome gobject gobject gtype-register-static}@deffn Primitive gtype-register-static name parent_class
Derive a new type named @var{name} from @var{parent_class}. Returns the new
@code{<gtype-class>}. This function is called when deriving from
@code{<gobject>}; users do not normally call this function directly.

@end deffn

@anchor{gnome gobject gobject gobject:get-property}@deffn Generic gobject:get-property
Called to get a gobject property. Only properties directly belonging to the
object's class will come through this function; superclasses handle their own
properties.

Takes two arguments: the object and the property name.

Call @code{(next-method)} in your methods to invoke the default handler

@end deffn

@deffn Method gobject:get-property  (@var{object} @code{<gobject>}) (@var{name} @code{<symbol>})
The default implementation of @code{gobject:get-property}, which calls
@code{(slot-ref obj name)}.

@end deffn

@anchor{gnome gobject gobject gobject:set-property}@deffn Generic gobject:set-property
Called to set a gobject property. Only properties directly belonging to the
object's class will come through this function; superclasses handle their own
properties.

Takes three arguments: the object, the property name, and the value.

Call @code{(next-method)} in your methods to invoke the default handler.

@end deffn

@deffn Method gobject:set-property  (@var{object} @code{<gobject>}) (@var{name} @code{<symbol>}) (@var{value} @code{<top>})
The default implementation of @code{gobject:set-property}, which sets slots on
the object.

@end deffn

@anchor{gnome gobject gobject gobject-class-get-properties}@deffn Primitive gobject-class-get-properties class
@end deffn

@anchor{gnome gobject gobject gobject-class-find-property}@defun gobject-class-find-property class name
Returns a property named @var{name} (a symbol), belonging to @var{class} or one
of its parent classes, or @code{#f} if not found.

@end defun

@anchor{gnome gobject gobject gobject-class-get-property-names}@deffn Primitive gobject-class-get-property-names class
@end deffn

@anchor{gnome gobject gobject gobject-get-property}@deffn Primitive gobject-get-property object name
Gets a the property named @var{name} (a symbol) from @var{object}.

@end deffn

@anchor{gnome gobject gobject gobject-set-property}@deffn Primitive gobject-set-property object name value
Sets the property named @var{name} (a symbol) on @var{object} to
@var{init-value}.

@end deffn

@node gnome gobject generics
@chapter (gnome gobject generics)
@section Overview
Generic functions for procedures in the @code{(gnome gobject)} module.

@subsection Mapping class libraries to Scheme
Guile-GNOME exists to wrap a C library, @code{libgobject}, its types, and the
set of libraries that based themselves on the GLib types.

Procedure invocation feels very similar in Scheme and in C. For example, the C
@code{gtk_widget_show (widget)} transliterates almost exactly to the Scheme
@code{(gtk-widget-show widget)}.

GLib-based libraries are not random collections of functions, however.
GLib-based libraries also implement classes and methods, insofar that it is
possible in C. For example, in the above example, @code{show} may be seen to be
a method on instances of the @code{<gtk-widget>} class.

Indeed, other object-oriented languages such as Python express this pattern
directly, translating the @code{show} operation as the pleasantly brief
@code{widget.show()}. However this representation of methods as being bound to
instances, while common, has a number of drawbacks.

The largest drawback is that the method itself is not bound to a generic
operation. For example, mapping the @code{show} operation across a set of
widgets cannot be done with the straightforward @code{map(show, set)}, because
there is no object for the @code{show} operation. Instead the user must locally
bind each widget to a variable in order to access a method of the abstract
@code{show} operation: @code{map(lambda widget: widget.show(), set)}.

Additionally, most languages which express methods as bound to instances only
select the method via the type of the first (implicit) argument. The rule for
these lanugages is, ``@code{gtk-widget-show} is an applicable method of the
@code{show} operation when the first argument to @code{show} is a
@code{<gtk-widget>}.'' Note the lack of specification for other arguments; the
same object cannot have two applicable methods of the @code{show} operation. A
more complete specification would be, ``@code{gtk-widget-show} is an applicable
method of the @code{show} operation when applied to one argument, a
@code{<gtk-widget>}.'' It is a fine difference, but sometimes important.

For these and other reasons, the conventional way to implement generic
operations in Lisp has been to define @dfn{generic functions}, and then
associate specific methods with those functions. For example, one would write
the following:

@lisp
 ;; defining a generic function, and one method implementation
 (define-generic show)
 (define-method (show (widget <gtk-widget>))
   (gtk-widget-show widget))

 ;; invoking the generic function
 (show my-widget)

@end lisp

One benefit of this approach is that method definitions can be made far away in
space and time from type definitions. This leads to a more dynamic environment,
in which methods can be added to existing types at runtime, which then can apply
to existing instances.

@subsection The semantics of generic functions in Guile-GNOME
Naturally, there is an impedance mismatch between the conventions used in the C
libraries and their Scheme equivalents. Operations in GLib-based libraries do
not form a coherent whole, in the sense that there is no place that defines the
meaning of an abstract @code{show} operation. For example,
@code{gtk-widget-set-state}, which can make a widget become uneditable, and
@code{gst-element-set-state}, which can start a video player, would both map to
the generic function @code{set-state}, even though they have nothing to do with
each other besides their name.

There is no conflict here; the methods apply on disjoint types. However there is
a problem of modularity, in that @emph{both methods must be defined on the same
generic function}, so that @code{(set-state foo bar)} picks the correct method,
depending on the types of @var{foo} and @var{bar}.

This point leads to the conclusion that @emph{generic functions in Guile-GNOME
have no abstract meaning, apart from their names}. Semantically, generics in
Guile-GNOME are abbreviations to save typing, not abstract operations with
defined meanings.

@subsection Practicalities
This module defines a number of ``abbreviations'', in the form of generic
functions, for operations on types defined in the @code{(gnome gobject)}
modules. Generic functions for generated bindings like @code{(gnome gtk)} are
defined in another module, @code{(gnome gw generics)}, which re-exports the
public bindings from this module.

@section Usage
@anchor{gnome gobject generics get}@deffn Generic get
@end deffn

@deffn Method get  (@var{object} @code{<gobject>}) (@var{name} @code{<symbol>})
A shorthand for @code{gobject-get-property}.

@end deffn

@anchor{gnome gobject generics set}@deffn Generic set
@end deffn

@deffn Method set  (@var{object} @code{<gobject>}) (@var{name} @code{<symbol>}) (@var{value} @code{<top>})
A shorthand for @code{gobject-set-property}.

@end deffn

@anchor{gnome gobject generics emit}@deffn Generic emit
@end deffn

@deffn Method emit  (@var{object} @code{<gtype-instance>}) (@var{name} @code{<symbol>}) (@var{args} @code{<top>})...
A shorthand for @code{gtype-instance-signal-emit}.

@end deffn

@anchor{gnome gobject generics connect}@deffn Generic connect
@end deffn

@deffn Method connect  (@var{object} @code{<gtype-instance>}) (@var{name} @code{<symbol>}) (@var{func} @code{<procedure>})
A shorthand for @code{gtype-instance-signal-connect}.

@end deffn

@deffn Method connect  (@var{args} @code{<top>})...
The core Guile implementation of the connect(2) POSIX call

@end deffn

@anchor{gnome gobject generics connect-after}@deffn Generic connect-after
@end deffn

@deffn Method connect-after  (@var{object} @code{<gtype-instance>}) (@var{name} @code{<symbol>}) (@var{func} @code{<procedure>})
A shorthand for @code{gtype-instance-signal-connect-after}.

@end deffn

@anchor{gnome gobject generics block}@deffn Generic block
@end deffn

@deffn Method block  (@var{object} @code{<gtype-instance>}) (@var{id} @code{<top>})
A shorthand for @code{gsignal-handler-block}.

@end deffn

@anchor{gnome gobject generics unblock}@deffn Generic unblock
@end deffn

@deffn Method unblock  (@var{object} @code{<gtype-instance>}) (@var{id} @code{<top>})
A shorthand for @code{gsignal-handler-unblock}.

@end deffn

@anchor{gnome gobject generics disconnect}@deffn Generic disconnect
@end deffn

@deffn Method disconnect  (@var{object} @code{<gtype-instance>}) (@var{id} @code{<top>})
A shorthand for @code{gsignal-handler-disconnect}.

@end deffn

@anchor{gnome gobject generics connected?}@deffn Generic connected?
@end deffn

@deffn Method connected?  (@var{object} @code{<gtype-instance>}) (@var{id} @code{<top>})
A shorthand for @code{gsignal-handler-connected?}.

@end deffn

@anchor{gnome gobject generics invoke}@deffn Generic invoke
@end deffn

@deffn Method invoke  (@var{closure} @code{<gclosure>}) (@var{args} @code{<top>})...
A shorthand for @code{gclosure-invoke}.

@end deffn

@anchor{gnome gobject generics create-signal}@deffn Generic create-signal
@end deffn

@deffn Method create-signal  (@var{class} @code{<gtype-class>}) (@var{name} @code{<symbol>}) (@var{return-type} @code{<top>}) (@var{param-types} @code{<top>})
A shorthand for @code{gtype-class-create-signal}.

@end deffn

@anchor{gnome gobject generics get-signals}@deffn Generic get-signals
@end deffn

@deffn Method get-signals  (@var{class} @code{<gtype-class>})
A shorthand for @code{gtype-class-get-signals}.

@end deffn

@anchor{gnome gobject generics get-properties}@deffn Generic get-properties
@end deffn

@deffn Method get-properties  (@var{class} @code{<gtype-class>})
A shorthand for @code{gobject-class-get-properties}.

@end deffn

@anchor{gnome gobject generics get-property-names}@deffn Generic get-property-names
@end deffn

@deffn Method get-property-names  (@var{class} @code{<gtype-class>})
A shorthand for @code{gobject-class-get-property-names}.

@end deffn

@anchor{gnome gobject generics find-property}@deffn Generic find-property
@end deffn

@deffn Method find-property  (@var{class} @code{<gtype-class>}) (@var{name} @code{<symbol>})
A shorthand for @code{gobject-class-find-property}.

@end deffn

@node gnome gobject utils
@chapter (gnome gobject utils)
@section Overview
@c
Common utility routines.

@section Usage
@anchor{gnome gobject utils GStudlyCapsExpand}@defun GStudlyCapsExpand nstr
Expand the StudlyCaps @var{nstr} to a more schemey-form, according to the
conventions of GLib libraries. For example:

@lisp
 (GStudlyCapsExpand "GSource") @result{} g-source
 (GStudlyCapsExpand "GtkIMContext") @result{} gtk-im-context
 (GStudlyCapsExpand "GtkHBox") @result{} gtk-hbox
@end lisp

@end defun

@anchor{gnome gobject utils gtype-name->scheme-name-alist}@defvar gtype-name->scheme-name-alist
An alist of exceptions to the name transformation algorithm implemented in
@code{GStudlyCapsExpand}.

@end defvar

@anchor{gnome gobject utils gtype-name->scheme-name}@defun gtype-name->scheme-name type-name
Transform a name of a @code{<gtype>}, such as "GtkWindow", to a scheme form,
such as @code{gtk-window}, taking into account the exceptions in
@code{gtype-name->scheme-name-alist}, and trimming trailing dashes if any.

@end defun

@anchor{gnome gobject utils gtype-name->class-name}@defun gtype-name->class-name type-name
Transform a name of a @code{<gtype>}, such as "GtkWindow", to a suitable name of
a Scheme class, such as @code{<gtk-window>}. Uses
@code{gtype-name->scheme-name}.

@end defun

@anchor{gnome gobject utils gtype-class-name->method-name}@defun gtype-class-name->method-name class-name name
Generate the name of a method given the name of a @code{<gtype>} and the name of
the operation. For example:

@lisp
 (gtype-name->method-name "GtkFoo" "bar") @result{} gtk-foo:bar
@end lisp

Uses @code{gtype-name->scheme-name}.

@end defun

@anchor{gnome gobject utils re-export-modules}@defspec re-export-modules  . args
Re-export the public interface of a module or modules. Invoked as
@code{(re-export-modules (mod1) (mod2)...)}.

@end defspec

@anchor{gnome gobject utils define-macro-with-docs}@defspec define-macro-with-docs form docs . body
@end defspec

@anchor{gnome gobject utils define-with-docs}@defspec define-with-docs name docs val
Define @var{name} as @var{val}, documenting the value with @var{docs}.

@end defspec

@anchor{gnome gobject utils define-generic-with-docs}@defspec define-generic-with-docs name documentation
Define a generic named @var{name}, with documentation @var{documentation}.

@end defspec

@anchor{gnome gobject utils define-class-with-docs}@defspec define-class-with-docs name supers docs . rest
Define a class named @var{name}, with superclasses @var{supers}, with
documentation @var{docs}.

@end defspec

@anchor{gnome gobject utils unless}@defspec unless test . body
@end defspec

@anchor{gnome gobject utils with-accessors}@defspec with-accessors names . body
@end defspec

@node gnome gw generics
@chapter (gnome gw generics)
@section Overview
This module exists so that all @code{(gnome gw)} modules have a common place to
put their generic functions. Whenever a wrapset is loaded, it adds method
definitions to generics defined in this module.

See the documentation for @code{(gnome gobject generics)} for more notes about
generic functions in Guile-GNOME. This module re-exports bindings from
@code{(gnome gobject generics)}, so there is no need to import them both.

@section Usage
@node gnome gw support gobject
@chapter (gnome gw support gobject)
@section Overview
@c
G-Wrap support for @code{(gnome gobject)} types. Code in this module is only
loaded when generating wrapsets; as such, it is not for end users.

@section Usage
@anchor{gnome gw support gobject <gobject-wrapset-base>}@deftp Class <gobject-wrapset-base>
The base class for G-Wrap wrapsets that use @code{<gobject>} types.

@end deftp

@anchor{gnome gw support gobject add-type-alias!}@deffn Generic add-type-alias!
@end deffn

@deffn Method add-type-alias!  (@var{wrapset} @code{<gobject-wrapset-base>}) (@var{alias} @code{<string>}) (@var{name} @code{<symbol>})
Add a type alias to @var{wrapset}, that the string @var{alias} is associated
with the type named @var{symbol}. For example, @code{"GtkWindow*"} might be
associated with a type named @code{<gtk-window>}. See
@code{lookup-type-by-alias}.

@end deffn

@anchor{gnome gw support gobject lookup-type-by-alias}@deffn Generic lookup-type-by-alias
@end deffn

@deffn Method lookup-type-by-alias  (@var{wrapset} @code{<gobject-wrapset-base>}) (@var{name} @code{<string>})
Lookup a type aliased @var{name} in @var{wrapset}, and all wrapsets on which
@var{wrapset} depends. This interface is used by @code{load-defs} to associate
G-Wrap types with the strings parsed out of the C header files.

@end deffn

@anchor{gnome gw support gobject add-type-rule!}@deffn Generic add-type-rule!
@end deffn

@deffn Method add-type-rule!  (@var{self} @code{<gobject-wrapset-base>}) (@var{param-type} @code{<string>}) (@var{typespec} @code{<top>})
Add a type rule to @var{wrapset}, that the string @var{param-type} maps directly
to the g-wrap typespec @var{typespec}. For example, @code{"int*"} might map to
the typespec @code{(int out)}. See @code{find-type-rule}.

@end deffn

@anchor{gnome gw support gobject find-type-rule}@deffn Generic find-type-rule
@end deffn

@deffn Method find-type-rule  (@var{self} @code{<gobject-wrapset-base>}) (@var{param-type} @code{<string>})
See if the parameter type @var{param-type} has a type rule present in
@var{wrapset} or in any wrapset on which @var{wrapset} depends. This interface
is used by @code{load-defs} to associate G-Wrap typespecs with the strings
parsed out of the C header files.

@end deffn

@anchor{gnome gw support gobject <gobject-type-base>}@deftp Class <gobject-type-base>
A base G-Wrap type class for GLib types.

@end deftp

@anchor{gnome gw support gobject <gobject-classed-type>}@deftp Class <gobject-classed-type>
A base G-Wrap type class for classed GLib types (see @code{gtype-classed?}).

@end deftp

@anchor{gnome gw support gobject gtype-id}@deffn Generic gtype-id
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-custom-gvalue-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-custom-boxed-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-class-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-flags-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-enum-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-interface-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-pointer-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-boxed-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-instance-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-classed-pointer-type>})
@end deffn

@deffn Method gtype-id  (@var{o} @code{<gobject-classed-type>})
@end deffn

@anchor{gnome gw support gobject <gobject-classed-pointer-type>}@deftp Class <gobject-classed-pointer-type>
A base G-Wrap type class for for classed GLib types whose values are pointers.

@end deftp

@anchor{gnome gw support gobject unwrap-null-checked}@deffn Generic unwrap-null-checked
@end deffn

@deffn Method unwrap-null-checked  (@var{value} @code{<gw-value>}) (@var{status-var} @code{<top>}) (@var{code} @code{<top>})
Unwrap a value into a C pointer, optionally unwrapping @code{#f} as @code{NULL}.

This function checks the typespec options on @var{value}, which should be a
@code{<gw-value>}. If the @code{null-ok} option is set (which is only the case
for value classes with @code{null-ok} in its @code{#:allowed-options}), this
function generates code that unwraps @code{#f} as @code{NULL}. If @code{null-ok}
is unset, or the value is not @code{#f}, @var{code} is run instead.

@end deffn

@anchor{gnome gw support gobject wrap-instance!}@deffn Generic wrap-instance!
@end deffn

@deffn Method wrap-instance!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for a specific instantiatable (@code{<gtype-instance>}-derived)
type in @var{ws}. Required keyword arguments are @code{#:ctype} and
@code{#:gtype-id}. For example,

@lisp
 (wrap-instance! ws #:ctype "GtkWidget"
                    #:gtype-id "GTK_TYPE_WIDGET")
@end lisp

Normally only called from @code{load-defs}.

@end deffn

@anchor{gnome gw support gobject wrap-boxed!}@deffn Generic wrap-boxed!
@end deffn

@deffn Method wrap-boxed!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for a specific boxed type in @var{ws}. Required keyword
arguments are @code{#:ctype} and @code{#:gtype-id}, as in @code{wrap-instance!}.

@end deffn

@anchor{gnome gw support gobject wrap-pointer!}@deffn Generic wrap-pointer!
@end deffn

@deffn Method wrap-pointer!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for a specific pointer type in @var{ws}. Required keyword
arguments are @code{#:ctype} and @code{#:gtype-id}, as in @code{wrap-instance!}.

@end deffn

@anchor{gnome gw support gobject wrap-opaque-pointer!}@defun wrap-opaque-pointer! ws ctype
Define a wrapper for an opaque pointer with the C type @var{ctype}. It will not
be possible to create these types from Scheme, but they can be received from a
library, and passed as arguments to other calls into the library.

@end defun

@anchor{gnome gw support gobject wrap-freeable-pointer!}@defun wrap-freeable-pointer! ws ctype free
foo

@end defun

@anchor{gnome gw support gobject wrap-refcounted-pointer!}@defun wrap-refcounted-pointer! ws ctype ref unref
foo

@end defun

@anchor{gnome gw support gobject wrap-structure!}@defun wrap-structure! ws ctype wrap unwrap
Define a wrapper for structure values of type @var{ctype}.

@var{wrap} and @var{unwrap} are the names of C functions to convert a C
structure to Scheme and vice versa, respectively. When in a function call,
parameters of this type of the form `@var{StructName}*' are interpreted as `out'
parameters, while `const-@var{StructName}*' are treated as `in' parameters.

Note that @var{ctype} should be the type of the structure, not a pointer to the
structure.

@end defun

@anchor{gnome gw support gobject wrap-interface!}@deffn Generic wrap-interface!
@end deffn

@deffn Method wrap-interface!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for an interface type in @var{ws}. Required keyword arguments
are @code{#:ctype} and @code{#:gtype-id}, as in @code{wrap-instance!}.

@end deffn

@anchor{gnome gw support gobject wrap-flags!}@deffn Generic wrap-flags!
@end deffn

@deffn Method wrap-flags!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for a flags type in @var{ws}. Required keyword arguments are
@code{#:ctype} and @code{#:gtype-id} or @code{#:values}, as in
@code{wrap-enum!}.

@end deffn

@anchor{gnome gw support gobject wrap-gobject-class!}@deffn Generic wrap-gobject-class!
@end deffn

@deffn Method wrap-gobject-class!  (@var{ws} @code{<gobject-wrapset-base>}) (@var{args} @code{<top>})...
Define a wrapper for GObject class values @var{ws}. Required keyword arguments
are @code{#:ctype} and @code{#:gtype-id}, as in @code{wrap-instance!}.

@code{#:ctype} should refer to the type of the class and not the instance; e.g.
@code{"GtkWidgetClass"} and not @code{"GtkWidget"}. This function will not be
called by @code{load-defs}, and should be invoked manually in a wrapset as
needed.

@end deffn

@anchor{gnome gw support gobject wrap-custom-boxed!}@defspec wrap-custom-boxed! ctype gtype wrap unwrap
Wrap a boxed type using custom wrappers and unwrappers.

FIXME: missing a wrapset argument!

@var{ctype} and @var{gtype} are as @code{#:ctype} and @code{#:gtype-id} in
@code{wrap-instance!}. @var{wrap} and @var{unwrap} are G-Wrap forms in which
@code{scm-var} and @code{c-var} will be bound to the names of the SCM and C
values, respectively. For example:

@lisp
  (wrap-custom-boxed!
   "GdkRectangle" "GDK_TYPE_RECTANGLE"
   (list scm-var " = "
         c-var " ?  scm_gdk_rectangle_to_scm (" c-var ")"
         " : SCM_BOOL_F;")
   (list c-var " = scm_scm_to_gdk_rectangle (" scm-var ");"))
@end lisp

@end defspec

@anchor{gnome gw support gobject wrap-custom-gvalue!}@defspec wrap-custom-gvalue! ctype gtype wrap-func unwrap-func
Wrap a GValue type using custom wrap and unwrap functions.

FIXME: missing a wrapset argument!

@var{ctype} and @var{gtype} are as @code{#:ctype} and @code{#:gtype-id} in
@code{wrap-instance!}. @var{wrap-func} and @var{unwrap-func} are names of
functions to convert to and from Scheme values, respectively. For example:

@lisp
 (wrap-custom-gvalue! "GstFraction" "GST_TYPE_FRACTION"
                      "scm_from_gst_fraction"
                      "scm_to_gst_fraction")
@end lisp

@end defspec

@node gnome gw support defs
@chapter (gnome gw support defs)
@section Overview
This module serves as a way to automatically populate G-Wrap wrapsets using
information parsed out of C header files.

First, the C header files are parsed into S-expression API description forms and
written into @code{.defs} files. These files are typically included in the
distribution, and regenerated infrequently. Then, the binding author includes a
call to @code{load-defs} in their G-Wrap wrapset definition, which loads those
API definitions into the wrapset.

The @code{.defs} files are usually produced using the API scanner script,
@code{h2defs.py}, included in the Guile-GNOME source distribution.

Code in this module is only loaded when generating wrapsets; as such, it is not
for end users.

As an example, ATK is wrapped with the following code, from
@code{atk/gnome/gw/atk-spec.scm}:

@example
 (define-module (gnome gw atk-spec)
   #:use-module (oop goops)
   #:use-module (gnome gw support g-wrap)
   #:use-module (gnome gw gobject-spec)
   #:use-module (gnome gw support gobject)
   #:use-module (gnome gw support defs))

 (define-class <atk-wrapset> (<gobject-wrapset-base>)
   #:id 'gnome-atk
   #:dependencies '(standard gnome-glib gnome-gobject))

 (define-method (global-declarations-cg (self <atk-wrapset>))
   (list
    (next-method)
    "#include <atk/atk.h>\n"
    "#include <atk/atk-enum-types.h>\n"))

 (define-method (initialize (ws <atk-wrapset>) initargs)
   (next-method ws (append '(#:module (gnome gw atk)) initargs))
   ;; manually wrap AtkState as a 64 bit uint
   (add-type-alias! ws "AtkState" 'unsigned-int64)
   (load-defs-with-overrides ws "gnome/defs/atk.defs"))

@end example

The wrapper-specifiction modules are actually installed, along with the .defs
files, so that other wrappers which use ATK's types, such as GTK+, can have them
available.

A full discussion of the Makefile mechanics of how to generate and compile the C
file, or how to interact with the wrapset objects, is probably prone to bitrot
here. Your best bet is to poke at Guile-GNOME's source, or especially the source
of a module distributed independently of @code{guile-gnome-platform}, such as
@code{guile-gnome-libwnck}.

Further details about the procedural API available for use e.g. within the
wrapset's @code{initialize} function can be found in the documentation for
@code{(gnome gw support gobject)}, and in G-Wrap's documentation.

@section Usage
@anchor{gnome gw support defs load-defs}@defun load-defs ws file [overrides = #f]
Load G-Wrap type and function information from @var{file} into the G-Wrap
wrapset @var{ws}.

@var{file} should be a relative path, which will be searched in the vicinity of
Guile's @code{%load-path}. @code{include} directives in the file will be
searched relative to the absolute path of the file.

The following forms are understood: @code{define-enum}, @code{define-flags},
@code{define-object}, @code{define-interface}, @code{define-pointer},
@code{define-boxed}, @code{define-function}, @code{define-method},
@code{ignore}, @code{ignore-glob}, and @code{ignore-types}.

The optional argument, @var{overrides}, specifies the location of an overrides
file that will be spliced into the @code{.defs} file at the point of an
@code{(include overrides)} form.

@end defun

@anchor{gnome gw support defs load-defs-with-overrides}@defun load-defs-with-overrides ws defs
Equivalent to:

@lisp
  (load-defs ws defs
             (string-append "gnome/overrides/"
                            (basename defs)))
@end lisp

@end defun

@node gnome gw support gtk-doc
@chapter (gnome gw support gtk-doc)
@section Overview
This module exports two high-level procedures to transform the Docbook files
generated by GTK-Doc into texinfo.

@uref{http://www.gtk.org/gtk-doc/,GTK-Doc} is commonly used to document
GObject-based libraries, such as those that Guile-GNOME wraps. In a typical
build setup, GTK-Doc generates a reference manual with one XML file per section.
The routines in this module attempt to recreate those sections, but in Texinfo
instead of Docbook, and which document the Scheme modules instead of the
upstream C libraries.

The tricky part of translating GTK-Doc's documentation is not the vocabulary
(Docbook), but that it documents C functions which have different calling
conventions than Scheme. For example, a C function might take four
@code{double*} arguments, but in Scheme the function would return four rational
values. Given only the C prototype, the code in this module will make an attempt
to determine what the Scheme function's arguments will be based on some
heuristics.

In most cases, however, we can do better than heuristics, because we have the
G-Wrap information that describes the relationship between the C function and
the Scheme wrapper. In that way we can know exactly what the input and output
arguments are for a particular function.

The @code{gtk-doc->texi-stubs} function is straightforward. It extracts the
"header" in a set of GTK-Doc files, translates them into texinfo, writing them
out one by one to files named @samp{section-@var{foo}.texi}, where @var{foo} is
the name of the XML file. It is unclear whether it is best to continously
generate these sections when updating the manuals, or whether this "stub"
generation should be run only once when the documentation is initially
generated, and thereafter maintained by hand. Your call!

@code{gtk-doc->texi-defuns} is slightly more complicated, because you have the
choice as to whether to use heuristics or the g-wrap method for determining the
arguments. See its documentation for more information.

Both of these functions are designed to be directly callable from the shell.
Here is a makefile snippet suitable for using the heuristics method for defuns
generation:

@example
 GTK_DOC_TO_TEXI_STUBS = \
   '((@@ (gnome gw support gtk-doc) gtk-doc->texi-stubs) \
   (cdr (program-arguments)))'
 GTK_DOC_DEFUN_METHOD = heuristics
 GTK_DOC_DEFUN_ARGS = (your-module-here)
 GTK_DOC_TO_TEXI_DEFUNS = "(apply (@@ (gnome gw support gtk-doc) \
    gtk-doc->texi-defuns) (cadr (program-arguments)) \
    '$(GTK_DOC_DEFUN_METHOD) '($(GTK_DOC_DEFUN_ARGS)) \
    (cddr (program-arguments)))"
 GUILE = $(top_builddir)/dev-environ guile

 generate-stubs:
      $(GUILE) $(GUILE_FLAGS) -c $(GTK_DOC_TO_TEXI_STUBS) \
         $(docbook_xml_files)

 generate-defuns:
 	$(GUILE) $(GUILE_FLAGS) -c $(GTK_DOC_TO_TEXI_DEFUNS) \
         ./overrides.texi $(docbook_xml_files)

@end example

To make the above snippet work, you will have to define
@code{$(docbook_xml_files)} as the set of docbook XML files to transform. To use
the G-Wrap method, try the following:

@example
 wrapset_module = (gnome gw $(wrapset_stem)-spec)
 wrapset_name = gnome-$(wrapset_stem)
 GTK_DOC_DEFUN_METHOD = g-wrap
 GTK_DOC_DEFUN_ARGS = $(wrapset_module) $(wrapset_name)

@end example

Set @code{$(wrapset_stem)} to the stem of the wrapset name, e.g. @code{pango},
and there you are.

@section Usage
@anchor{gnome gw support gtk-doc gtk-doc->texi-stubs}@defun gtk-doc->texi-stubs files
Generate a section overview texinfo file for each docbook XML file in
@var{files}.

The files will be created in the current directory, as described in the
documentation for @code{(gnome gw support gtk-doc)}. They will include a file
named @code{defuns-@var{file}.texi}, which should probably be created using
@code{gtk-doc->texi-defuns}.

@end defun

@anchor{gnome gw support gtk-doc gtk-doc->texi-defuns}@defun gtk-doc->texi-defuns overrides method args . files
Generate documentation for the types and functions defined in a set of docbook
files genearted by GTK-Doc.

@var{overrides} should be a path to a texinfo file from which @code{@@deffn}
overrides will be taken. @var{method} should be either @code{g-wrap} or
@code{heuristics}, as discussed in the @code{(gnome gw support gtk-doc)}
documentation. @var{files} is the list of docbook XML files from which to pull
function documentation.

@var{args} should be a list, whose form depends on the @var{method}. For
@code{g-wrap}, it should be two elements, the first the name of a module that,
when loaded, will load the necessary wrapset into the g-wrap runtime. For
example, @code{(gnome gw glib-spec)}. The second argument should be the name of
the wrapset, e.g. @code{gnome-glib}.

If @var{method} is @code{heuristics}, @var{args} should have only one element,
the name of the module to load to check the existence of procedures, e.g.
@code{(cairo)}.

@end defun

@anchor{gnome gw support gtk-doc check-documentation-coverage}@defun check-documentation-coverage modules texi
Check the coverage of generated documentation.

@var{modules} is a list of module names, and @var{texi} is a path to a texinfo
file. The set of exports of @var{modules} is checked against the set of
procedures defined in @var{texi}, resulting in a calculation of documentation
coverage, and the output of any missing documentation to the current output
port.

@end defun

@anchor{gnome gw support gtk-doc generate-undocumented-texi}@defun generate-undocumented-texi modules texi
Verify the bindings exported by @var{modules} against the documentation in
@var{texi}, writing documentation for any undocumented symbol to
@code{undocumented.texi}.

@var{modules} is a list of module names, and @var{texi} is a path to a texinfo
file.

@end defun

@node gnome gw support modules
@chapter (gnome gw support modules)
@section Overview
@c
Support routines for automatically-generated scheme G-Wrap modules.

@section Usage
@anchor{gnome gw support modules export-all-lazy!}@defun export-all-lazy! symbols
Export the @var{symbols} from the current module.

Most generic functions and classes that G-Wrap defines are bound lazily, as
needed in evaluation. This is done by placing module binder procedures on the
generated modules. However, if we export all symbols by name, this will force
the binding eagerly for all values, which is slow.

This procedure exports all bindings named in @var{symbols} that are already
bound in the current module, and then installs a module binder procedure on the
public interface, which allows lazy binding to work.

@end defun

@anchor{gnome gw support modules re-export-modules}@defspec re-export-modules  . args
Re-export the public interface of a module; used like @code{use-modules}.

@end defspec

@node Type Index
@unnumbered Type Index
@printindex tp
@node Function Index
@unnumbered Function Index
@printindex fn
@bye