glib/gobject.package.lisp

   1 (defpackage :gobject
   2   (:use :cl :glib :cffi :tg :bordeaux-threads :iter :closer-mop :gobject.ffi :gobject.type-info)
   3   (:export #:+g-type-invalid+
   4            #:+g-type-void+
   5            #:+g-type-interface+
   6            #:+g-type-char+
   7            #:+g-type-uchar+
   8            #:+g-type-boolean+
   9            #:+g-type-int+
  10            #:+g-type-uint+
  11            #:+g-type-long+
  12            #:+g-type-ulong+
  13            #:+g-type-int64+
  14            #:+g-type-uint64+
  15            #:+g-type-enum+
  16            #:+g-type-flags+
  17            #:+g-type-float+
  18            #:+g-type-double+
  19            #:+g-type-string+
  20            #:+g-type-pointer+
  21            #:+g-type-boxed+
  22            #:+g-type-param+
  23            #:+g-type-object+
  24            #:g-object
  25            #:pointer
  26            #:g-type-from-object
  27            #:g-type-name
  28            #:g-type-from-name
  29            #:g-signal-connect
  30            #:define-g-object-class
  31            #:g-initially-unowned
  32            #:define-g-enum
  33            #:*lisp-name-package*
  34            #:define-g-boxed-class
  35            #:define-g-flags
  36            #:fixed-array
  37            #:g-boxed-inline
  38            #:g-boxed-ptr
  39            #:define-g-interface
  40            #:release
  41            #:using
  42            #:using*
  43            #:define-g-boxed-ref
  44            #:g-boxed-ref
  45            #:allocate-stable-pointer
  46            #:free-stable-pointer
  47            #:get-stable-pointer-value
  48            #:with-stable-pointer
  49            #:release*
  50            #:disown-boxed-ref
  51            #:g-type-interface
  52            #:g-value
  53            #:register-object-type-implementation
  54            #:ensure-g-type
  55            #:define-vtable
  56            #:g-type
  57            #:set-g-value
  58            #:parse-gvalue
  59            #:emit-signal
  60            #:g-value-unset
  61            #:g-value-zero
  62            #:g-value-init
  63            #:g-type-class-ref
  64            #:g-object-class
  65            #:gobject-class
  66            #:g-param-spec
  67            #:type-instance
  68            #:g-type-class-unref
  69            #:registered-object-type-by-name
  70            #:g-type-children
  71            #:g-signal-lookup
  72            #:g-type-parent
  73            #:connect-signal
  74            #:boxed-c-structure-name
  75            #:g-type-designator
  76            #:g-type-fundamental
  77            #:g-type-depth
  78            #:g-type-next-base
  79            #:g-type-is-a
  80            #:g-type-interfaces
  81            #:g-type-interface-prerequisites
  82            #:g-type-name
  83            #:g-type-from-name
  84            #:g-type
  85            #:g-type-children
  86            #:g-type-parent
  87            #:g-type-designator
  88            #:g-type-fundamental
  89            #:g-type-depth
  90            #:g-type-next-base
  91            #:g-type-is-a
  92            #:g-type-interfaces
  93            #:g-type-interface-prerequisites
  94            #:g-strv-get-type
  95            #:g-closure-get-type
  96            #:g-class-property-definition
  97            #:g-class-property-definition-name
  98            #:g-class-property-definition-type
  99            #:g-class-property-definition-readable
 100            #:g-class-property-definition-writable
 101            #:g-class-property-definition-constructor
 102            #:g-class-property-definition-constructor-only
 103            #:g-class-property-definition-owner-type
 104            #:parse-g-param-spec
 105            #:class-properties
 106            #:interface-properties
 107            #:enum-item
 108            #:enum-item-name
 109            #:enum-item-value
 110            #:enum-item-nick
 111            #:get-enum-items
 112            #:flags-item
 113            #:flags-item-name
 114            #:flags-item-value
 115            #:flags-item-nick
 116            #:get-flags-items)
 117   (:documentation
 118    "CL-GTK2-GOBJECT is a binding to GObject type system.
 119 For information on GObject, see its @a[http://library.gnome.org/devel/gobject/stable/]{documentation}.
 120
 121 CL-GTK2-GOBJECT is structured as follows:
 122 @itemize{
 123 @item{Binding to GObject API, providing low-level means to use functionality of GObject. This includes introspection facilities and means to invoke functionality of GObject.}
 124 @item{GObject wrapper that bridges Lisp language with GObject API.}
 125 }
 126
 127 @begin[GObject instrospection API]{section}
 128 The base of GObject type system is GType. GType is a numerical value that is the unique identifier of a registered type.
 129 Each GType has a name that is retrieved with @fun{g-type-name}. Conversely, GType can be retrieved from its name via @fun{g-type-from-name}.
 130
 131 There are several predefined GType values that correspond to fundamental or base types.
 132 @begin{itemize}
 133 @item{@variable{+g-type-invalid+}}
 134 @item{@variable{+g-type-void+}}
 135 @item{@variable{+g-type-interface+}}
 136 @item{@variable{+g-type-char+}}
 137 @item{@variable{+g-type-uchar+}}
 138 @item{@variable{+g-type-boolean+}}
 139 @item{@variable{+g-type-int+}}
 140 @item{@variable{+g-type-uint+}}
 141 @item{@variable{+g-type-long+}}
 142 @item{@variable{+g-type-ulong+}}
 143 @item{@variable{+g-type-int64+}}
 144 @item{@variable{+g-type-uint64+}}
 145 @item{@variable{+g-type-enum+}}
 146 @item{@variable{+g-type-flags+}}
 147 @item{@variable{+g-type-float+}}
 148 @item{@variable{+g-type-double+}}
 149 @item{@variable{+g-type-string+}}
 150 @item{@variable{+g-type-pointer+}}
 151 @item{@variable{+g-type-boxed+}}
 152 @item{@variable{+g-type-param+}}
 153 @item{@variable{+g-type-object+}}
 154 @end{itemize}
 155
 156 GType values form type hierarchies via signle inheritance. Functions @fun{g-type-parent} and @fun{g-type-children} enable to traverse through the type hierarchy.
 157
 158 For some types, additional information is available. Functions @fun{class-properties} and @fun{interface-properties} return properties of classes and interfaces. Functions @fun{get-enum-items} and @fun{get-flags-items} return members of enum and flags types.
 159
 160 //TODO: document and refactor signals
 161
 162 @end{section}
 163
 164 @begin[GValue]{section}
 165 GObject uses GValues as a generic way to pass values. It is used when calling closures, emitting signals, setting and getting properties' values, passing values to object constructors. @class{g-value} foreign structure is used for holding GValue. It used like all foreign structures: either with @code{cffi:foreign-alloc} or with @code{cffi:with-foreign-object}. Before first use, @class{g-value} should be zeroed with @fun{g-value-zero}. Zeroed @class{g-value} may be configured to hold a GValue of a given type with @fun{g-value-init}. @fun{parse-g-value} retrieves the Lisp object corresponding to the value stored in GValue. @fun{set-g-value} sets the GValue from Lisp object.
 166 @end{section}"))
 167
 168 (in-package :gobject)
 169
 170 (defvar *gobject-debug* nil)
 171
 172 (defun debugf (&rest args)
 173   (when *gobject-debug*
 174     (apply 'format t args)))