chez-libs

(system glib)
Login

GLib Bindings

Synopsis

(import (system glib))

Bindings to some functionality of the GLib library.

Native Memory

When the library body runs, glib-alloc and glib-free are registered as the current heap-allocator for (system heap).

procedure: (glib-alloc n)

Allocates the requested number of bytes of foreign memory and returns the address. If zero bytes are requested a null pointer is returned.

Memory blocks returned by glib-alloc are filled with zero bytes.

procedure: (glib-free address)

Frees the memory located at the specified address, which was previously allocated using glib-alloc.

Quarks

procecure: (symbol->quark symbol)

Converts a symbol into a GQuark integer, registering the symbol's name as a new quark, if necessary.

procedure: (quark->symbol integer)

Converts a GQuark integer into a symbol with the same name. Returns #f if the given number is not a registered quark.

Conditions

condition: &gerror

procedure: (gerror-condition? any)

procedure: (make-gerror-condition message domain code)

procedure: (condition-domain condition)

procedure: (condition-code condition)

The &gerror condition type is derived from &message and stores the error category and error code together with a human-readable message.

procedure: (call-with-gerror who proc)

Allocates a memory location that may hold a GError pointer and passes its address to the given procedure. Once the procedure returns, the error location is examined: If it contains a GError instance, it is cleared and the error is raised as a condition with types &error, &who and &gerror. If there was no error, call-with-gerror returns whatever proc returns.

procedure: (with-gerror-guard address thunk)

Runs the given proceedure without arguments and converts any condition raised by it into a GError, which is stored at the given memory address. If a condition was raised, with-gerror-guard returns #f, otherwise it returns whatever thunk returns.

procedure: (log-condition v)

procedure: (log-condition v domain)

Formats the given value in an error message and passes it to the GLib logging system, optionally with the given logging domain. If the value is a warning condition, the message will be logged at G_LOG_LEVEL_WARNING and the procedure returns #t, otherwise it will be logged at G_LOG_LEVEL_CRITICAL and the procedure returns #f.

Closures

procedure: (closure-alloc proc)

Creates a native GClosure object that calls the given Scheme procedure when invoked. Locks the procedure in memory. Returns the memory address of the closure.

procedure: (closure-free address)

Decrements the reference count of the native closure at the given address. Once the closure is destroyed, the backing Scheme procedure is unlocked.

Main Loops

parameter: main-loop-context

The parameter holds the native address of the main loop context to use and is initialized to the default GMainContext.

procedure: (main-loop)

Runs a main loop for the main-loop-context.

procedure: (main-loop-running?)

Returns a boolean indicating whether a main loop is currently running.

procedure: (main-loop-quit!)

Stops the innermost main loop currently running for the main-loop-context, if any.

procedure: (main-loop-remove! integer)

Removes the source with the given identifier from the main-loop-context. Returns a boolean indicating whether the operation was successful.

procedure: (main-loop-timeout interval thunk)

Creates a timeout source that runs the given procedure at regular intervals in the main-loop-context. The interval is specified in seconds. If the interval is an exact integer, the source will have second granularity, otherwise it will have millisecond granularity. The source keeps invoking the callback in regular intervals as long as the main loop keeps running and the callback keeps returning true values. Once the callback returns #f, the source removes itself from its main context. The procedure returns the identifier of the new source.

Object Management

ftype: object

procedure: (wrap-object address retain?)

GObject instance references are represented as foreign pointer objects. The reference count of the object is incremented by wrap-object if its second argument is true. object-collect is then called to decrement the reference count of all objects that have gone out of scope. Finally, the new pointer is registered with the guardian used by object-collect.

procedure: (object-collect)

Decrements the reference count of all objects whose pointer wrappers have gone out of scope.

procedure: (object? any)

procedure: (object? any type)

Checks whether the given value is a valid object pointer. Optionally also check whether the object is of the given type, represented by a GType integer code.

procedure: (check-object who any type)

Checks whether the given object is a valid GObject instance of the given GType. In case of success, the object is returned. If the check fails, an error is raised, which includes a &who condition with the given location specification.

procedure: (make-object type {name type v} ...)

Creates an instance of the given GObject type with the given construction properties. Each property is specified as a three arguments, indicating its name, type and value.

The type of each construction property is indicated by a symbol:

In addition, the type may be a GType code representing one of the above types or a subtype of GObject or GBoxed.

Object instances returned by make-object have to be released using object-release!.

procedure: (object-type obj)

Retrieves the GType code for the class of the given object instance.

procedure: (object-ref obj name type)

procedure: (object-ref obj name type convert)

Retrieves the value of a named property of the given object. Optionally, the value is converted using the specified procedure before it is returned. This is particularly useful for instances of boxed values that become invalid before object-ref returns.

Object instances returned by object-ref have to be released using object-release!.

procedure: (object-set! obj name type v)

Sets the value of a named property of the given object. The type of the value to set is indicated by a symbol, the same as for object-ref.

procedure: (signal-handler obj signal proc)

Connects a handler to a signal and returns a numeric identifier. The signal is specified as a string, which includes the signal name and optional details. The callback procedure will be locked in memory as long as the signal connection is maintained.

procedure: (signal-disconnect! obj integer)

Disconnects the handler with the given numeric identifier from its signal.