4.10.6 GObject foreign class

To enable passing GObject instance between Lisp code and foreign code, g-object foreign type is introduced.

This type has the following syntax: (g-object [type] [:already-referenced]) or g-object. (Brackets indicate optional arguments)

When the g-object foreign type is specified as a return type of a function, the value is converted to instance of corresponding CLOS class. If type is specified then it is checked that object is of this type. If :already-referenced is included then it is assumed that the function returns already referenced object (so that it is not needed to call g-object-ref on returned object).

When the g-object foreign type is specified as a type of function's argument, the value is converted to pointer to GObject. If type is specified then it is checked that the object is of this type.

This defines the function that may be called with instances of types container and widget:

     (defcfun (container-add "gtk_container_add") :void
       (container (g-object container))
       (widget (g-object widget)))
     
     (let ((window (make-instance 'gtk-window))
           (widget (make-instance 'button)))
       (container-add window widget))

(gtk-window is a subclass of container; button is a subclass of widget)

This defines the function that returns an instance of GObject class:

     (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
       (bin (g-object bin)))
     
     (let ((window (make-instance 'gtk-window))
           (widget (make-instance 'button)))
       (container-add window widget)
       (bin-child window))
     =>
     #<GTK:BUTTON {1002DE74B1}>

This example shows the use of :already-referenced option:

     (defcfun (widget-create-pango-layout "gtk_widget_create_pango_layout") (g-object gdk::pango-layout :already-referenced)
       (widget (g-object widget))
       (text :string))
     
     (defcfun gdk-gc-new (g-object graphics-context :already-referenced)
       (drawable (g-object drawable)))