D 2016-06-03T13:26:51.108
L (system\sglib)
P f08b2498a8d7a4b48895029811a7f193a6bfcabd
U murphy
W 9339
<h1>GLib Bindings</h1>
<h2>Synopsis</h2>
<code>(import (system glib))</code>
Bindings to some functionality of the [https://developer.gnome.org/glib/stable/|GLib] library.
<h2>Native Memory</h2>
When the library body runs, <tt>glib-alloc</tt> and <tt>glib-free</tt> are registered as the current <tt>heap-allocator</tt> for <tt>[(system heap)]</tt>.
<h3>procedure: <code>(glib-alloc <i>n</i>)</code></h3>
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 <tt>glib-alloc</tt> are filled with zero bytes.
<h3>procedure: <code>(glib-free <i>address</i>)</code></h3>
Frees the memory located at the specified address, which was previously allocated using <tt>glib-alloc</tt>.
<h2>Quarks</h2>
<h3>procecure: <code>(symbol->quark <i>symbol</i>)</code></h3>
Converts a symbol into a GQuark integer, registering the symbol's name as a new quark, if necessary.
<h3>procedure: <code>(quark->symbol <i>integer</i>)</code></h3>
Converts a GQuark integer into a symbol with the same name. Returns <tt>#f</tt> if the given number is not a registered quark.
<h2>Conditions</h2>
<h3>condition: <code>&gerror</code></h3>
<h3>procedure: <code>(gerror-condition? <i>any</i>)</code></h3>
<h3>procedure: <code>(make-gerror-condition <i>message</i> <i>domain</i> <i>code</i>)</code></h3>
<h3>procedure: <code>(condition-domain <i>condition</i>)</code></h3>
<h3>procedure: <code>(condition-code <i>condition</i>)</code></h3>
The <tt>&gerror</tt> condition type is derived from <tt>&message</tt> and stores the error category and error code together with a human-readable message.
<h3>procedure: <code>(call-with-gerror <i>who</i> <i>proc</i>)</code></h3>
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 <tt>&error</tt>, <tt>&who</tt> and <tt>&gerror</tt>. If there was no error, <tt>call-with-gerror</tt> returns whatever <tt>proc</tt> returns.
<h3>procedure: <code>(with-gerror-guard <i>address</i> <i>thunk</i>)</code></h3>
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, <tt>with-gerror-guard</tt> returns <tt>#f</tt>, otherwise it returns whatever <tt>thunk</tt> returns.
<h3>procedure: <code>(log-condition <i>v</i>)</code></h3>
<h3>procedure: <code>(log-condition <i>v</i> <i>domain</i>)</code></h3>
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 <tt>G_LOG_LEVEL_WARNING</tt> and the procedure returns <tt>#t</tt>, otherwise it will be logged at <tt>G_LOG_LEVEL_CRITICAL</tt> and the procedure returns <tt>#f</tt>.
<h2>Closures</h2>
<h3>procedure: <code>(closure-alloc <i>proc</i>)</code></h3>
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.
<h3>procedure: <code>(closure-free <i>address</i>)</code></h3>
Decrements the reference count of the native closure at the given address. Once the closure is destroyed, the backing Scheme procedure is unlocked.
<h2>Main Loops</h2>
<h3>parameter: <code>main-loop-context</code></h3>
The parameter holds the native address of the main loop context to use and is initialized to the default GMainContext.
<h3>procedure: <code>(main-loop)</code></h3>
Runs a main loop for the <tt>main-loop-context</tt>.
<h3>procedure: <code>(main-loop-running?)</code></h3>
Returns a boolean indicating whether a main loop is currently running.
<h3>procedure: <code>(main-loop-quit!)</code></h3>
Stops the innermost main loop currently running for the <tt>main-loop-context</tt>, if any.
<h3>procedure: <code>(main-loop-remove! <i>integer</i>)</code></h3>
Removes the source with the given identifier from the <tt>main-loop-context</tt>. Returns a boolean indicating whether the operation was successful.
<h3>procedure: <code>(main-loop-timeout <i>interval</i> <i>thunk</i>)</code></h3>
Creates a timeout source that runs the given procedure at regular intervals in the <tt>main-loop-context</tt>. 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 <tt>#f</tt>, the source removes itself from its main context. The procedure returns the identifier of the new source.
<h2>Object Management</h2>
<h3>ftype: <code>object</code></h3>
<h3>procedure: <code>(wrap-object <i>address</i> <i>retain?</i>)</code></h3>
GObject instance references are represented as foreign pointer objects. The reference count of the object is incremented by <tt>wrap-object</tt> if its second argument is true. <tt>object-collect</tt> 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 <tt>object-collect</tt>.
<h3>procedure: <code>(object-collect)</code></h3>
Decrements the reference count of all objects whose pointer wrappers have gone out of scope.
<h3>procedure: <code>(object? <i>any</i>)</code></h3>
<h3>procedure: <code>(object? <i>any</i> <i>type</i>)</code></h3>
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.
<h3>procedure: <code>(check-object <i>who</i> <i>any</i> <i>type</i>)</code></h3>
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 <tt>&who</tt> condition with the given location specification.
<h3>procedure: <code>(make-object <i>type</i> {<i>name</i> <i>type</i> <i>v</i>} ...)</code></h3>
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:
* <tt>integer-8</tt>, <tt>gchar</tt>: Signed 8-bit integer
* <tt>unsigned-8</tt>, <tt>guchar</tt>: Unsigned 8-bit integer
* <tt>boolean</tt>, <tt>gboolean</tt>: Boolean
* <tt>int</tt>, <tt>gint</tt>: Signed native integer
* <tt>unsigned-int</tt>, <tt>unsigned</tt>, <tt>guint</tt>: Unsigned native integer
* <tt>long</tt>, <tt>glong</tt>: Signed native long integer
* <tt>unsigned-long</tt>, <tt>gulong</tt>: Unsigned native long integer
* <tt>integer-64</tt>, <tt>gint64</tt>: Signed 64-bit integer
* <tt>unsigned-64</tt>, <tt>guint64</tt>: Unsigned 64-bit integer
* <tt>float</tt>, <tt>gfloat</tt>: 32-bit floating point number
* <tt>double</tt>, <tt>gdouble</tt>: 64-bit floating point number
* <tt>utf-8</tt>, <tt>string</tt>, <tt>gchar*</tt>, <tt>gchararray</tt>: UTF-8 encoded string
* <tt>void*</tt>, <tt>uptr</tt>, <tt>gpointer</tt>: Unsigned native memory address
* <tt>object</tt>, <tt>GObject</tt>: Wrapped GObject instance
* <tt>type</tt>, <tt>GType</tt>: GType code
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 <tt>make-object</tt> have to be released using <tt>object-release!</tt>.
<h3>procedure: <code>(object-type <i>obj</i>)</code></h3>
Retrieves the GType code for the class of the given object instance.
<h3>procedure: <code>(object-ref <i>obj</i> <i>name</i> <i>type</i>)</code></h3>
<h3>procedure: <code>(object-ref <i>obj</i> <i>name</i> <i>type</i> <i>convert</i>)</code></h3>
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 <tt>object-ref</tt> returns.
Object instances returned by <tt>object-ref</tt> have to be released using <tt>object-release!</tt>.
<h3>procedure: <code>(object-set! <i>obj</i> <i>name</i> <i>type</i> <i>v</i>)</code></h3>
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 <tt>object-ref</tt>.
<h3>procedure: <code>(signal-handler <i>obj</i> <i>signal</i> <i>proc</i>)</code></h3>
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.
<h3>procedure: <code>(signal-disconnect! <i>obj</i> <i>integer</i>)</code></h3>
Disconnects the handler with the given numeric identifier from its signal.
Z a0cef7504cc2901804c786356c5b4c12