Next: , Previous: gnome gobject gtype, Up: Top


4 (gnome gobject gvalue)

4.1 Overview

GLib supports generic typed values via its GValue module. These values are wrapped in Scheme as instances of <gvalue-class> classes, such as <gint>, <gfloat>, etc.

In most cases, use of <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. #\a instead of #<gvalue <gchar> 3020c708 a>. However, when dealing with low-level routines it is sometimes necessary to have values in <gvalue> form. The conversion between the two is performed via the scm->gvalue and 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 <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 (make <your-enum-type> #:value value), where 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.

4.2 Usage

— Class: <gvalue>

— Class: <gboolean>

A <gvalue> class for boolean values.

— Class: <gchar>

A <gvalue> class for signed 8-bit values.

— Class: <guchar>

A <gvalue> class for unsigned 8-bit values.

— Class: <gint>

A <gvalue> class for signed 32-bit values.

— Class: <guint>

A <gvalue> class for unsigned 32-bit values.

— Class: <glong>

A <gvalue> class for signed “long” (32- or 64-bit) values.

— Class: <gulong>

A <gvalue> class for unsigned “long” (32- or 64-bit) values.

— Class: <gint64>

A <gvalue> class for signed 64-bit values.

— Class: <guint64>

A <gvalue> class for unsigned 64-bit values.

— Class: <gfloat>

A <gvalue> class for 32-bit floating-point values.

— Class: <gdouble>

A <gvalue> class for 64-bit floating-point values.

— Class: <gchararray>

A <gvalue> class for arrays of 8-bit values (C strings).

— Class: <gboxed>

A <gvalue> class for “boxed” types, a way of wrapping generic C structures. You won't see instances of this class, only of its subclasses.

— Class: <gboxed-scm>

A <gboxed> class for holding arbitrary Scheme objects.

— Class: <gvalue-array>

A <gvalue> class for arrays of <gvalue>.

— Class: <gpointer>

A <gvalue> class for opaque pointers.

— Class: <genum>

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

— Class: <gflags>

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

— Primitive: genum-register-static name vtable

Creates and registers a new enumerated type with name name with the C runtime. There must be no type with name name when this function is called.

The new type can be accessed by using gtype-name->class.

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.

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

— Primitive: gflags-register-static name vtable

Creates and registers a new flags <gtype-class> with name name with the C runtime.

The vtable should be in the format described in the documentation for genum-register-static.

— Primitive: genum-class->value-table class

Return a table of the values supported by the enumerated <gtype-class> class. The return value will be in the format described in genum-register-static.

— Primitive: gflags-class->value-table class

Return a table of the values supported by the flag <gtype-class> class. The return value will be in the format described in gflags-register-static.

— Primitive: scm->gvalue class scm

Convert a Scheme value into a <gvalue> of type class. If the conversion is not possible, raise a gruntime-error.

— Primitive: gvalue->scm value

Convert a <gvalue> into it normal scheme representation, for example unboxing characters into Scheme characters. Note that the Scheme form for some values is the <gvalue> form, for example with boxed or enumerated values.

— Function: genum->symbol obj

Convert the enumerated value obj from a <gvalue> to its symbol representation (its “nickname”).

— Function: genum->name obj

Convert the enumerated value obj from a <gvalue> to its representation as a string (its “name”).

— Primitive: genum->value value

Convert the enumerated value obj from a <gvalue> to its representation as an integer.

— Primitive: gflags->value value

Convert the flags value obj from a <gvalue> to its representation as an integer.

— Function: gflags->symbol-list obj

Convert the flags value obj from a <gvalue> to a list of the symbols that it represents.

— Function: gflags->name-list obj

Convert the flags value obj from a <gvalue> to a list of strings, the names of the values it represents.

— Function: gflags->value-list obj

Convert the flags value obj from a <gvalue> to a list of integers, which when logand'd together yield the flags' value.