Chapter 2. Extension modules

Table of Contents
2.1. Glib/GObject 2.0 binding
2.2. GTK+ 2.0 binding
2.3. G+, a higher-level GTK+ interface
2.4. GdkEvent binding
2.5. Libglade 2.0 binding

2.1. Glib/GObject 2.0 binding

(require 'gobject)
The gobject extension module provides a wrapping for a subset of the features offered by GLib version 2.0. Currently it exposes a partial API for manipulating GType, GBoxed, GEnum, GFlags, GValue, GClosure, GObject and GSignal types and values.

2.1.1. Initialization and glib miscellany

procedure: (g-warning args ...)

Delegates to the C function g_warning to produce a warning message using the GLib logging facility.

2.1.2. GType

GType is the GLib Runtime type identification and management system. Most of the datatypes used in GLib (and GDK/GTK+ etc) are registered with the GType system.

A certain amount of introspection over the GType system is possible. GType itself does not provide information about methods on objects, but does allow enumeration of object properties, signals, superclasses and subclasses, and also provides information on the allowable values of enumerations (GEnum) and flags (GFlags).

The combination of the following procedures and variables ought to allow access to much of the available metainformation:


   (gtype-name t)                     ; query type name
   gtype:fundamental-types            ; list of root types
   (gtype-parent t)                   ; retrieve supertype
   (gtype-children t)                 ; retrieve subtypes
   (gobject-type o)                   ; extract GType from GObject
   (gobject-class-properties t)       ; list properties of class
   (gobject:methods-on-class t)       ; list methods on a class
   (gobject:methods-in-gf gfname)     ; list methods in a generic function
   (gsignal-list t)                   ; list signals in a class
   (gsignal-list-complete t)          ; list signals in a class and parents
 

Since GType does not collect the information returned by gobject:methods-on-class or gobject:methods-in-gf itself, explicit calls to gobject:register-method! are required to fill in the associated datastructures.

Much of the introspection API is described in the sections devoted to each major grouping of GType instances.

record: (make-gtype number)

Represents a GType instance - a representation of a type known to the GLib system. The number is the unsigned-long GType value as used in C.

procedure: (gtype-name t)

Given a gtype record, returns the name associated with the GType as a string.

procedure: (wrap-gtype num)

Wraps a GType number in a gtype record. If num is zero (the invalid GType), #f is returned.

procedure: (gtype-from-name name)

Looks up a GType by name, wrapping it in a gtype record. Returns #f if the type name is not found.

procedure: (raw-gtype->fundamental num)

Given a GType number (not a record!), returns the GType number of its ultimate parent type - the root of the inheritance tree for the passed-in GType.

procedure: (gtype->fundamental t)

As for raw-gtype->fundamental, but takes and returns a gtype record instead of a raw GType number.

procedure: (wrap-gtype-fundamental num)

Produces a gtype record from a fundamental type number, using the C macro G_TYPE_MAKE_FUNDAMENTAL.

procedure: (raw-unmake-gtype-fundamental num)

Converts a GType number to its raw fundamental-GType number by shifting right by G_TYPE_FUNDAMENTAL_SHIFT.

procedure: (unwrap-gtype-fundamental t)

As for raw-unmake-gtype-fundamental, but takes a record instead of a GType number.

variable: gtype:...

The gtype:... variables correspond to the fundamental types defined in gtype.h as G_TYPE_....


     G_TYPE_INVALID       gtype:invalid           
     G_TYPE_NONE          gtype:none              
     G_TYPE_INTERFACE     gtype:interface         
     G_TYPE_CHAR          gtype:char              
     G_TYPE_UCHAR         gtype:uchar             
     G_TYPE_BOOLEAN       gtype:boolean           
     G_TYPE_INT           gtype:int               
     G_TYPE_UINT          gtype:uint              
     G_TYPE_LONG          gtype:long              
     G_TYPE_ULONG         gtype:ulong             
     G_TYPE_INT64         gtype:int64             
     G_TYPE_UINT64        gtype:uint64            
     G_TYPE_ENUM          gtype:enum              
     G_TYPE_FLAGS         gtype:flags             
     G_TYPE_FLOAT         gtype:float             
     G_TYPE_DOUBLE        gtype:double            
     G_TYPE_STRING        gtype:string            
     G_TYPE_POINTER       gtype:pointer           
     G_TYPE_BOXED         gtype:boxed             
     G_TYPE_PARAM         gtype:param             
     G_TYPE_OBJECT        gtype:object            
 

variable: gtype:fundamental-types

Collects all the fundamental (root) types together in a list.

procedure: (gtype-...? t)

Predicates for examining attributes of GType records.


     gtype-fundamental?       G_TYPE_IS_FUNDAMENTAL
     gtype-derived?           G_TYPE_IS_DERIVED
     gtype-interface?         G_TYPE_IS_INTERFACE
     gtype-classed?           G_TYPE_IS_CLASSED
     gtype-instantiatable?    G_TYPE_IS_INSTANTIATABLE
     gtype-derivable?         G_TYPE_IS_DERIVABLE
     gtype-deep-derivable?    G_TYPE_IS_DEEP_DERIVABLE
     gtype-abstract?          G_TYPE_IS_ABSTRACT
     gtype-value-abstract?    G_TYPE_IS_VALUE_ABSTRACT
     gtype-has-value-table?   G_TYPE_IS_HAS_VALUE_TABLE
 

procedure: (gtype-parent t)

Returns the parent type of the passed-in gtype record.

procedure: (gtype-depth t)

Returns the depth in the inheritance tree of the passed-in gtype record. A fundamental (root) type has depth 1, its child types have depth 2, and so forth.

procedure: (gtype-next-base leaf-t root-t)

Given a leaf-t and a root-t which is contained in its ancestry, return the type that root-t is the immediate parent of. In other words, this function determines the type that is derived directly from root-t which is also a base class of leaf-t. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type[1].

procedure: (gtype-isa? t is-a-t)

Returns #t if t is equal to, or a subtype of, is-a-t; otherwise returns #f.

procedure: (gtype-children t)

Returns a list of child types of the passed-in gtype record.

procedure: (gtype-interfaces t)

Returns a list of the interfaces supported by the passed-in gtype record.

2.1.3. GBoxed

Boxed types are non-reference-counted, explicitly allocated, copied and freed structures. Each boxed type has a pair of associated copy and free routines, which are called automatically when pointers to GBoxed instances are put under the control of wrap-gboxed.

record: (make-gboxed type pointer)

Represents a wrapped instance of a GBoxed type. type is the gtype record that is the type of the boxed value; pointer is the C pointer pointing to the boxed value. Do not call make-gboxed directly - usually, wrap-gboxed is more appropriate (as it arranges for reference-counting/finalization where make-gboxed does not).

procedure: (gboxed-copy-hook (#:optional new-value))

Gets (or sets, if the optional argument is supplied) the current value of the hook function called when a GBoxed instance is to be copied. The default hook is the C function g_boxed_copy. The hook function should take an unsigned long (GType) and a c-pointer, and should return a c-pointer.

procedure: (gboxed-finalizer-hook (#:optional new-value))

Gets (or sets, if the optional argument is supplied) the current value of the hook function called when a GBoxed instance is to be destroyed. The default hook does nothing. The hook function should accept an unsigned long (GType) and a c-pointer.

procedure: (wrap-gboxed type ptr (#:optional copy?))

If ptr is non-#f and non-NULL, calls g_boxed_copy on it, wraps it in a gboxed record, and arranges for g_boxed_free to be called on the copied pointer when the gboxed record is garbage collected. type is required to decide which copying/freeing procedures to use.

The optional copy? parameter defaults to #t: it controls whether the pointer is to be copied before being wrapped. If #f, the passed-in pointer is wrapped without being copied first. Use this only if you know what you are doing, otherwise you can introduce "double-free" problems to your program.

copy? does not control finalization: all records returned by wrap-gboxed are finalized with g_boxed_free when they are garbage collected, whether they were copied originally or not.

procedure: (null-gboxed)

Returns the GBoxed equivalent of the null pointer.

2.1.4. GEnum and GFlags

The GType API provides information about enumeration and flags types registered with the system. The associated wrappers provide convenience functions for introspection and translation between enumeration/flag nicknames and numbers.

procedure: (genum-info t)

Retrieves a list of information about the values in the enumeration GType record passed in.

procedure: (make-genum-number->nick t)

Returns a procedure that when given a number returns the associated nickname from the enumeration GType record passed in.


 ((make-genum-number->nick (gtype-from-name "GtkJustification"))
  3)
 ==> fill
 

procedure: (make-genum-nick->number t)

Returns a procedure that when given a symbol returns the associated number from the enumeration GType record passed in.


 ((make-genum-nick->number (gtype-from-name "GtkJustification"))
  'fill)
 ==> 3
 

procedure: (gflags-info t)

Retrieves a list of information about the available values in the flags GType record passed in.

procedure: (make-gflags->number t)

Returns a procedure that when given a list of symbols returns the bitwise or of the associated numbers from the flags GType record passed in.


 ((make-gflags->number (gtype-from-name "GdkWindowState"))
  '(iconified sticky))
 ==> 10
 

procedure: (make-number->gflags t)

Returns a procedure that when given a number returns the list of symbols making up that number, from the flags GType record passed in.


 ((make-number->gflags (gtype-from-name "GdkWindowState"))
  10)
 ==> (sticky iconified)
 

2.1.5. GValue

GValue is a subtype of GBoxed which is a polymorphic value cell - it can hold any of the fundamental types and their subclasses. The wrapper provides conversion routines between Scheme objects and GValue instances.

procedure: (raw-gvalue-type gvalue-pointer)

Given a C pointer to a GValue object, returns the GType number associated with the GValue.

procedure: (gvalue-type gv)

Given a properly boxed GValue, returns the gtype record associated with the GValue.

procedure: (gvalue->object gv)

Extracts a Scheme object from the passed-in boxed GValue. (Also accepts a raw pointer to a GValue object, instead of a properly boxed GValue, for internal implementation use.)

procedure: (gvalue-empty! gv)

Empties a boxed GValue, without altering the type associated with it.

procedure: (make-gvalue (#:optional gtype-record))

Returns a newly-allocated, boxed GValue, with its type set to the passed in GType record. If gtype-record is omitted, returns a completely blank GValue object, ready for filling in with any type (by, for instance, gtk-tree-model-get-value).

procedure: (raw-gvalue-fill! gvalue-ptr scheme-object)

Fills a pointer to a GValue object with a value taken from the passed-in Scheme object. If the type of scheme-object is not compatible with the type of gvalue-ptr, returns #f; if the fill operation was otherwise successful, returns #t.

procedure: (gvalue-fill! gv o)

Fills a properly boxed GValue object with the value of the passed-in scheme object, as for raw-gvalue-fill!.

procedure: (object->gvalue t o)

Allocates a new boxed GValue of type t using make-gvalue, fills it using gvalue-fill!, and returns it. If the fill operation failed, an error is signalled.

2.1.6. GClosure

Only basic support for GClosures is implemented, using a custom marshalling function (cg_gclosure_marshaller). Scheme functions wrapped in GClosure instances are properly collected - when the GClosure object is destroyed, a finalizer function (cg_gclosure_finalizer) causes the handle on the scheme function to be released.

GClosures are not usually manipulated explicitly in Scheme code. Usually a function like gsignal-connect (a.k.a. gtk-signal-connect) is used, which transparently manages GClosure instances.

procedure: (make-gclosure fn)

Wrap a scheme function in a GClosure, and return a C pointer to the new GClosure structure. See gsignal-connect.

2.1.7. GObject

GObject is the base type for all reference-counted objects in the GType hierarchy.

record: (make-gobject pointer)

Represents a GObject instance. pointer is the C pointer to the GObject instance. Do not call make-gobject directly - use wrap-gobject instead.

procedure: (gobject-type o)

Returns the gtype record representing the type of the passed-in GObject.

procedure: (gobject-ref-hook (#:optional new-value))

Gets (or sets, if the optional argument is supplied) the current value of the hook function called when a GObject instance is to be referenced. The default hook is the C function g_object_ref. The hook function should take a c-pointer and return a c-pointer.

procedure: (gobject-finalizer-hook (#:optional new-value))

Gets (or sets, if the optional argument is supplied) the current value of the hook function called when a GObject instance is to be unreferenced. The default hook does nothing. The hook function should accept a c-pointer.

procedure: (wrap-gobject p)

Given a C pointer to a GObject instance, calls g_object_ref on it, constructs a gobject record for it, and registers g_object_unref as the finalizer for the new record. If p is #f or the null pointer, #f is returned; otherwise the newly-allocated gobject record is returned.

procedure: (null-gobject)

Returns the GObject equivalent of the null pointer. Useful with functions like gtk-scrolled-window-new.

procedure: (gobject-class-properties t)

Returns a list of the properties supported by instances of the GObject GType record passed in.

procedure: (gobject-class-find-property t pname)

Returns a property specification for the named property on instances of the GObject GType record passed in, or #f if no property by that name is found on that class.

procedure: (make-gobject-property-getter t pname-symbol-or-string)

Produces a getter function for the passed-in GType and property name.

procedure: (gobject-get-property o pname)

Retrieves the value of the named property on the GObject instance passed in.

procedure: (make-gobject-property-setter t pname-symbol-or-string)

Produces a setter function for the passed-in GType and property name.

procedure: (gobject-set-property! o pname newval)

Updates the value of the named property on the GObject instance passed in.

record: (make-gobject-method name gf class function)

Represents a method associated with a GObject class. name is the name of the method; gf is the name of the generic function; class is the GType record for the class; and function is the method function itself.

procedure: (gobject:methods-on-class g)

Retrieve a list of all methods supported by the GObject GType passed in.

procedure: (gobject:methods-in-gf gfname)

Retrieve a list of all methods in the named generic function.

procedure: (gobject:register-method! classname gfname methodname function)

Registers a method on a particular class with the system. This procedure is called by the generated code for the GTK+ wrapper.

2.1.8. GSignal

Only a partial interface to the GSignal system is supported. In particular, there is no support for signal emission.

procedure: (gsignal-connect o sigdetail fn (#:optional after))

(also known as gtk-signal-connect within the gtk module) Connects fn to the signal (string or symbol) sigdetail on GObject instance o. When the signal is emitted, fn will be called with an argument list appropriate to the particular signal. Returns a number representing the connection which can then be passed into gsignal-handler-disconnect.

procedure: (gsignal-disconnect o handlerid)

Given an object and a handler connection number as returned by gsignal-connect, disconnects the handler so it will no longer fire when the signal is emitted.

procedure: (gsignal-lookup name t)

Look up a signal in a class by name; returns zero if the signal is not found for some reason.

procedure: (gsignal-query sigid)

Returns a list containing information about the signal identified by the signal identifier number passed in.

procedure: (gsignal-list t)

Returns a list of information about the signals that can be emitted by objects of the passed-in GType record, but not signals that can be emitted by its supertypes.

procedure: (gsignal-list-complete t)

Returns a list of information about the signals that can be emitted by objects of the passed-in GType record, including the signals that can be emitted by its supertypes.

Notes

[1]

Documentation nicked outright from the GLib GType documentation.