glib/gobject.package.lisp

   1 (defpackage :gobject
   2   (:use :cl :glib :cffi :tg :bordeaux-threads :iter :closer-mop :gobject.ffi)
   3   #+(or clozure-common-lisp openmcl) (:shadowing-import-from :closer-mop #:defgeneric #:ensure-generic-function #:standard-generic-function)
   4   (:export #:g-type
   5            #:g-type-string
   6            #:g-type-numeric
   7            #:g-type-children
   8            #:g-type-parent
   9            #:g-type-designator
  10            #:g-type-fundamental
  11            #:g-type-depth
  12            #:g-type-next-base
  13            #:g-type-is-a
  14            #:g-type-interfaces
  15            #:g-type-interface-prerequisites
  16            #:g-strv-get-type
  17            #:g-closure-get-type
  18            #:g-class-property-definition
  19            #:g-class-property-definition-name
  20            #:g-class-property-definition-type
  21            #:g-class-property-definition-readable
  22            #:g-class-property-definition-writable
  23            #:g-class-property-definition-constructor
  24            #:g-class-property-definition-constructor-only
  25            #:g-class-property-definition-owner-type
  26            #:parse-g-param-spec
  27            #:class-properties
  28            #:interface-properties
  29            #:enum-item
  30            #:enum-item-name
  31            #:enum-item-value
  32            #:enum-item-nick
  33            #:get-enum-items
  34            #:flags-item
  35            #:flags-item-name
  36            #:flags-item-value
  37            #:flags-item-nick
  38            #:get-flags-items
  39            #:signal-info
  40            #:signal-info-id
  41            #:signal-info-name
  42            #:signal-info-owner-type
  43            #:signal-info-flags
  44            #:signal-info-return-type
  45            #:signal-info-param-types
  46            #:signal-info-detail
  47            #:query-signal-info
  48            #:type-signals
  49            #:parse-signal-name
  50            #:class-property-info
  51            #:+g-type-invalid+
  52            #:+g-type-void+
  53            #:+g-type-interface+
  54            #:+g-type-char+
  55            #:+g-type-uchar+
  56            #:+g-type-boolean+
  57            #:+g-type-int+
  58            #:+g-type-uint+
  59            #:+g-type-long+
  60            #:+g-type-ulong+
  61            #:+g-type-int64+
  62            #:+g-type-uint64+
  63            #:+g-type-enum+
  64            #:+g-type-flags+
  65            #:+g-type-float+
  66            #:+g-type-double+
  67            #:+g-type-string+
  68            #:+g-type-pointer+
  69            #:+g-type-boxed+
  70            #:+g-type-param+
  71            #:+g-type-object+
  72            #:g-object
  73            #:pointer
  74            #:g-type-from-object
  75            #:g-type-name
  76            #:g-type-from-name
  77            #:g-signal-connect
  78            #:define-g-object-class
  79            #:g-initially-unowned
  80            #:define-g-enum
  81            #:*lisp-name-package*
  82            #:define-g-flags
  83            #:fixed-array
  84            #:g-boxed-inline
  85            #:g-boxed-ptr
  86            #:define-g-interface
  87            #:release
  88            #:using
  89            #:using*
  90            #:g-boxed-ref
  91            #:allocate-stable-pointer
  92            #:free-stable-pointer
  93            #:get-stable-pointer-value
  94            #:with-stable-pointer
  95            #:release*
  96            #:disown-boxed-ref
  97            #:g-type-interface
  98            #:g-value
  99            #:register-object-type-implementation
 100            #:ensure-g-type
 101            #:define-vtable
 102            #:g-type
 103            #:set-g-value
 104            #:parse-g-value
 105            #:emit-signal
 106            #:g-value-unset
 107            #:g-value-zero
 108            #:g-value-init
 109            #:g-type-class-ref
 110            #:g-object-class
 111            #:gobject-class
 112            #:g-param-spec
 113            #:type-instance
 114            #:g-type-class-unref
 115            #:registered-object-type-by-name
 116            #:g-type-children
 117            #:g-signal-lookup
 118            #:g-type-parent
 119            #:connect-signal
 120            #:boxed-c-structure-name
 121            #:g-type-designator
 122            #:g-type-fundamental
 123            #:g-type-depth
 124            #:g-type-next-base
 125            #:g-type-is-a
 126            #:g-type-interfaces
 127            #:g-type-interface-prerequisites
 128            #:g-type-name
 129            #:g-type-from-name
 130            #:g-type
 131            #:g-type-children
 132            #:g-type-parent
 133            #:g-type-designator
 134            #:g-type-fundamental
 135            #:g-type-depth
 136            #:g-type-next-base
 137            #:g-type-is-a
 138            #:g-type-interfaces
 139            #:g-type-interface-prerequisites
 140            #:g-strv-get-type
 141            #:g-closure-get-type
 142            #:g-class-property-definition
 143            #:g-class-property-definition-name
 144            #:g-class-property-definition-type
 145            #:g-class-property-definition-readable
 146            #:g-class-property-definition-writable
 147            #:g-class-property-definition-constructor
 148            #:g-class-property-definition-constructor-only
 149            #:g-class-property-definition-owner-type
 150            #:parse-g-param-spec
 151            #:class-properties
 152            #:interface-properties
 153            #:enum-item
 154            #:enum-item-name
 155            #:enum-item-value
 156            #:enum-item-nick
 157            #:get-enum-items
 158            #:flags-item
 159            #:flags-item-name
 160            #:flags-item-value
 161            #:flags-item-nick
 162            #:get-flags-items
 163            #:stable-pointer-value
 164            #:g-value-type
 165            #:g-object-call-constructor
 166            #:g-object-call-get-property
 167            #:g-object-call-set-property
 168            #:register-enum-type
 169            #:register-flags-type
 170            #:register-object-type
 171            #:generate-types-hierarchy-to-file
 172            #:get-g-flags-definition
 173            #:get-g-enum-definition
 174            #:get-g-interface-definition
 175            #:get-g-class-definition
 176            #:*strip-prefix*
 177            #:*lisp-name-exceptions*
 178            #:*additional-properties*
 179            #:g-type=
 180            #:g-type/=
 181            #:define-g-boxed-cstruct
 182            #:define-g-boxed-opaque
 183            #:g-boxed-opaque
 184            #:g-boxed-opaque-pointer
 185            #:define-g-boxed-variant-cstruct
 186            #:g-boxed-foreign
 187            #:boxed-related-symbols
 188            #:define-boxed-opaque-accessor
 189            #:glib-defcallback
 190            #:create-signal-handler-closure
 191            #:save-handler-to-object
 192            #:retrieve-handler-from-object
 193            #:delete-handler-from-object
 194            #:disconnect-signal
 195            #:define-cb-methods
 196            #:create-fn-ref)
 197   (:documentation
 198    "CL-GTK2-GOBJECT is a binding to GObject type system.
 199 For information on GObject, see its @a[http://library.gnome.org/devel/gobject/stable/]{documentation}.
 200
 201 CL-GTK2-GOBJECT is structured as follows:
 202 @itemize{
 203 @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.}
 204 @item{GObject wrapper that bridges Lisp language with GObject API.}
 205 }
 206
 207 @begin[GObject instrospection API]{section}
 208 The base of GObject type system is GType. GType is a numerical value that is the unique identifier of a registered type.
 209 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}.
 210
 211 There are several predefined GType values that correspond to fundamental or base types.
 212 @begin{itemize}
 213 @item{@variable{+g-type-invalid+}}
 214 @item{@variable{+g-type-void+}}
 215 @item{@variable{+g-type-interface+}}
 216 @item{@variable{+g-type-char+}}
 217 @item{@variable{+g-type-uchar+}}
 218 @item{@variable{+g-type-boolean+}}
 219 @item{@variable{+g-type-int+}}
 220 @item{@variable{+g-type-uint+}}
 221 @item{@variable{+g-type-long+}}
 222 @item{@variable{+g-type-ulong+}}
 223 @item{@variable{+g-type-int64+}}
 224 @item{@variable{+g-type-uint64+}}
 225 @item{@variable{+g-type-enum+}}
 226 @item{@variable{+g-type-flags+}}
 227 @item{@variable{+g-type-float+}}
 228 @item{@variable{+g-type-double+}}
 229 @item{@variable{+g-type-string+}}
 230 @item{@variable{+g-type-pointer+}}
 231 @item{@variable{+g-type-boxed+}}
 232 @item{@variable{+g-type-param+}}
 233 @item{@variable{+g-type-object+}}
 234 @end{itemize}
 235
 236 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.
 237
 238 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.
 239
 240 //TODO: document and refactor signals
 241
 242 @end{section}
 243
 244 @begin[GValue]{section}
 245 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.
 246 @end{section}"))
 247
 248 (in-package :gobject)
 249
 250 (defvar *gobject-debug* nil)
 251
 252 (defvar *debug-gc* nil)
 253 (defvar *debug-subclass* nil)
 254
 255 (defvar *debug-stream* t)
 256
 257 (defmacro log-for (categories control-string &rest args)
 258   (let ((vars (iter (for sym in (if (listp categories) categories (list categories)))
 259                     (collect (intern (format nil "*DEBUG-~A*" (symbol-name sym)) (find-package :gobject))))))
 260     `(progn
 261        (when (or ,@vars)
 262          (format *debug-stream* ,control-string ,@args))
 263        nil)))