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


8 (gnome gobject gobject)

8.1 Overview

GObject is what is commonly understood as the object system for GLib. This is not strictly true. GObject is 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 <gobject>. <gobject> classes can be subclassed by the user, which will register new subtypes with the GType runtime type system. <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 <gtype-instance> implementations, <gobject> has the concept of properties, which are <gvalue>'s associated with the object. The values are constrained by <gparam>'s, which are associated with the object's class. This module exports the necessary routines to query, get, and set <gobject> properties.

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

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

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

8.2 Usage

— Class: <gobject>

The base class for GLib's default object system.

<gobject>'s metaclass understands a new slot option, #:gparam, which will export a slot as a <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 gobject:set-property and gobject:get-property.

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

For example:

           ;; 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>))

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

— Class: <ginterface>

The base class for GLib's interface types. Not derivable in Scheme.

— Class: <gparam-object>

Parameter for <gobject> values.

— Primitive: gtype-register-static name parent_class

Derive a new type named name from parent_class. Returns the new <gtype-class>. This function is called when deriving from <gobject>; users do not normally call this function directly.

— 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 (next-method) in your methods to invoke the default handler

— Method: gobject:get-property (object <gobject>) (name <symbol>)

The default implementation of gobject:get-property, which calls (slot-ref obj name).

— 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 (next-method) in your methods to invoke the default handler.

— Method: gobject:set-property (object <gobject>) (name <symbol>) (value <top>)

The default implementation of gobject:set-property, which sets slots on the object.

— Primitive: gobject-class-get-properties class

— Function: gobject-class-find-property class name

Returns a property named name (a symbol), belonging to class or one of its parent classes, or #f if not found.

— Primitive: gobject-class-get-property-names class

— Primitive: gobject-get-property object name

Gets a the property named name (a symbol) from object.

— Primitive: gobject-set-property object name value

Sets the property named name (a symbol) on object to init-value.