@titlepage
@title CL-GTK2
@subtitle A Common Lisp binding for Gtk+
-@subtitle GObject bindings
+@subtitle GObject
@author Dmitry Kalyanov
@end titlepage
GObject is a part of GLib library that implements the type system. The CL-GTK2-GObject is a Common Lisp binding for relevant parts of GObject.
+The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.
+
+Please bear in mind that this is the documentation for a work-in-progress library and is a snapshot of current situation. API and functionality may (and will) change. Largely unfinished parts are working with GBoxed types, subclassing GObjects and implementing GInterfaces.
+
+CL-GTK2-GObject is logically split into several layers:
+@itemize
+@item FFI code. FFI (foreign functions interface) layer is a glue between Lisp code and @code{libglib}, @code{libgobject}, @code{libgthread}. This code includes basic wrapper around GType designator (it is used everywhere and should be defined first) and definitions of foreign structures and imports foreign functions.
+@item Low-level GObject integration. These are facilities provided by GObject that capture specific aspects of type system, object system and cross-language runtime. This includes types information, GValues (generic containers for value of any type supported by GObject type system), closures, means to create and use objects. This layer also includes some non-GObject facilities: stable pointers.
+@item High-level GObject integration. This layer includes support for interoperability between CLOS and GObject and automatic generation of corresponding definitions.
+@end itemize
+
+Naturally, users of CL-GTK2-GObject should use the high-level GObject integration, but occasionaly it may be necessary to use lower-level functionality.
+
@node Installation
@chapter Installation
@menu
* g-type-string::
* g-type-numeric::
+* g-type=::
+* g-type/=::
@end menu
GObject is an object system based on GType type system. Types in it are identified by an integer value of type @code{GType}. In @code{cl-gtk2-gobject}, types are identified by GType designators. GType designator is an integer (equal to corresponding GType identifier) or a string (equal to the name of corresponding type). The important difference between GType and GType designator is that GType values may change between program runs (all GTypes except fundamental GTypes will change values), but string GType designators do not change (because names of types do not change). As such, if ever GType must be saved in a code, string GType designator should be preferred.
An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
-Some of the types are fundamental and have constant integer values. They are identified by constants:
+Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
@itemize
@item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
-@item @code{+g-type-void+}. A fundamental type which is used as a replacement for the C @code{void} return type.
-@item @code{+g-type-interface+}. The fundamental type from which all interfaces are derived.
-@item @code{+g-type-char+}. The fundamental type corresponding to gchar. The type designated by @code{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.
-@item @code{+g-type-uchar+}. The fundamental type corresponding to @code{guchar}.
-@item @code{+g-type-boolean+}. The fundamental type corresponding to @code{gboolean}.
-@item @code{+g-type-int+}. The fundamental type corresponding to @code{gint}.
-@item @code{+g-type-uint+}. The fundamental type corresponding to @code{guint}.
-@item @code{+g-type-long+}. The fundamental type corresponding to @code{glong}.
-@item @code{+g-type-ulong+}. The fundamental type corresponding to @code{gulong}.
-@item @code{+g-type-int64+}. The fundamental type corresponding to @code{gint64}.
-@item @code{+g-type-uint64+}. The fundamental type corresponding to @code{guint64}.
-@item @code{+g-type-enum+}. The fundamental type from which all enumeration types are derived.
-@item @code{+g-type-flags+}. The fundamental type from which all flags types are derived.
-@item @code{+g-type-float+}. The fundamental type corresponding to @code{gfloat}.
-@item @code{+g-type-double+}. The fundamental type corresponding to @code{gdouble}.
-@item @code{+g-type-string+}. The fundamental type corresponding to null-terminated C strings.
-@item @code{+g-type-pointer+}. The fundamental type corresponding to @code{gpointer}.
-@item @code{+g-type-boxed+}. The fundamental type from which all boxed types are derived.
-@item @code{+g-type-param+}. The fundamental type from which all GParamSpec types are derived.
-@item @code{+g-type-object+}. The fundamental type for GObject.
+@item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
+@item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
+@item @code{+g-type-char+} ("gchar"). The fundamental type corresponding to gchar. The type designated by @code{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.
+@item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
+@item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
+@item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
+@item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
+@item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
+@item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
+@item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
+@item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
+@item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
+@item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
+@item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
+@item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
+@item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
+@item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
+@item @code{+g-type-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived.
+@item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived.
+@item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
@end itemize
-Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them).
+Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them). Functions @ref{g-type=} and @ref{g-type/=} check types for equality.
Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
Returns the numeric identifier of GType
+@node g-type=
+@section g-type=
+
+@code{(g-type= type-1 type-2) @result{} eq}
+
+@table @var
+@item @var{type-1}
+A GType designator
+@item @var{type-2}
+A GType designator
+@item @var{eq}
+A boolean that is true if @code{type-1} and @code{type-2} designate the same type.
+@end table
+
+@node g-type/=
+@section g-type/=
+
+@code{(g-type/= type-1 type-2) @result{} eq}
+
+@table @var
+@item @var{type-1}
+A GType designator
+@item @var{type-2}
+A GType designator
+@item @var{eq}
+A boolean that is true if @code{type-1} and @code{type-2} designate different types.
+@end table
+
@node Type hierarchy and type relations
@chapter Type hierarchy and type relations
* g-value-unset::
* parse-g-value::
* set-g-value::
+* Registering types::
@end menu
GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
+@node Registering types
+@section Registering types
+
+In order to be able to parse GValues and set them, it is necessary for GValue binding to know type mapping between GObject types and Lisp types. Type registration serves to this purpose.
+
+GEnum and GFlags are mapped to CFFI @code{defcenum} and @code{defbitfield} types. Functions @code{register-enum-type} and @code{register-flags-type} add the type to the mapping.
+
+@subsection
+@code{(register-enum-type name type)}
+@table @var
+@item @var{name}
+A string naming the GEnum type
+@item @var{type}
+A symbol - name of CFFI foreign enum type
+@end table
+
+Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
+
+Example:
+@example
+(defcenum text-direction
+ :none :ltr :rtl)
+(register-enum-type "GtkTextDirection" 'text-direction)
+@end example
+
+@subsection
+@code{(register-flags-type name type)}
+@table @var
+@item @var{name}
+A string naming the GFlags type
+@item @var{type}
+A symbol - name of CFFI foreign flags type
+@end table
+
+Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
+
+Example:
+@example
+(defcenum state-type
+ :normal :active :prelight :selected :insensitive)
+(register-enum-type "GtkStateType" 'state-type)
+@end example
+
@node Stable pointers
@chapter Stable pointers
@menu
@node stable-pointer-value
@section stable-pointer-value
-@code{(stable-pointer-value stable-pointer) @result{} thing}
-
-@code{(setf (stable-pointer-value stable-pointer) thing)}
+@example
+(stable-pointer-value stable-pointer) @result{} thing
+(setf (stable-pointer-value stable-pointer) thing)
+@end example
@table @var
@item @var{stable-pointer}
@node GObject high-level
@chapter GObject high-level
+@menu
+* GObject metaclass::
+* Using objects::
+* Signals::
+* GObject foreign class::
+@end menu
+
+GObject high-level support includes integration of GObject and CLOS systems. This enables to use GObjects classes as CLOS classes (with support from @code{gobject-class} metaclass):
+@itemize
+@item objects are created with @code{make-instance}
+@item properties are used as regular slots
+@end itemize
+
+GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
+
+To be able to use particular GObject class with CLOS, it should be defined and registered. This is accomplished by @code{defclass}'ing it with @code{gobject-class} metaclass. After GObject class is defined, it may be used as CLOS class.
+
+Example GObject class of definition:
+@example
+(defclass dialog (gtk-window atk-implementor-iface buildable)
+ ((has-separator :accessor dialog-has-separator
+ :initarg :has-separator
+ :allocation :gobject-property
+ :g-property-type "gboolean"
+ :g-property-name "has-separator"))
+ (:metaclass gobject-class)
+ (:g-type-name . "GtkDialog")
+ (:g-type-initializer . "gtk_dialog_get_type"))
+@end example
+
+This example defines the CLOS class @code{dialog} that corresponds to GObject class @code{GtkDialog}. Whenever object of GObject type @code{GtkDialog} are to be received from foreign functions or passed to foreign functions, it will be mapped to CLOS class @code{dialog}. Properties that have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties, and reading or writing this slot reads or writes corresponding GObject class property.
+
+GObject does not expose objects methods. Because of this, methods are not automatically mapped to CLOS generic functions and methods. Methods should be manually wrapped with CFFI as foreign functions. Foreign type @code{g-object} aids in it. This type automatically wraps (and unwraps) the GObject class instances and handles the reference counting.
+
+GObject high-level support enables connect signals to signal handlers. Any function may be connected as a signal handler, and GObject will release the reference on signal handler whenever it become unneded (e.g., when object is destroyed or handler is disconnected).
+
+@node GObject metaclass
+@section GObject metaclass
+
+See MOP for information what metaclass is and why is it useful.
+
+GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
+
+Classes that correspond to GObject classes are instances of this class.
+
+Defining the class with metaclass @code{gobject-class} registers the type @code{:g-type-name} for conversions using GValue and CFFI foreign type @code{g-object}.
+
+This class has the following slots:
+@itemize
+@item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
+
+Specifies the name of GObject class
+@item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
+
+Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
+@item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
+
+A boolean specifying whether this CLOS class corresponds to GInterface.
+@end itemize
+
+This metaclass defines the GObject classes.
+
+Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
+@itemize
+@item @var{:g-property-type}
+
+A string naming GType of property
+@item @var{:g-property-name}
+
+A name of a property
+@end itemize
+
+Slots which have @code{:allocation} of @code{:gobject-fn} are mapped to a pair of accessor functions (usually named @code{class_get_property} and @code{class_set_property}). This is included because some properties are not exposed as GObject properties. Such slots have following attributes:
+@itemize
+@item @var{:g-property-type}
+A CFFI foreign type of property
+@item @var{:g-getter}
+A string naming foreign getter function of a property or a symbol designating Lisp getter function. Foreign getter function should have signature @code{type class_get_property(object *)}. Lisp function should be of type @code{(function (class) type)}.
+@item @var{:g-setter}
+A string naming foreign setter function of a property or a symbol designating Lisp setter function. Foreign setter function should have signature @code{void class_set_property(object *, type)}. Lisp function should be of type @code{(function (class type))}.
+@end itemize
+
+Initargs of a slot are used to construct the GObject class.
+
+Example:
+@example
+(defclass container (widget atk-implementor-iface buildable)
+ ((border-width :allocation :gobject-property
+ :g-property-type "guint"
+ :accessor container-border-width
+ :initarg :border-width
+ :g-property-name "border-width")
+ (resize-mode :allocation :gobject-property
+ :g-property-type "GtkResizeMode"
+ :accessor container-resize-mode
+ :initarg :resize-mode
+ :g-property-name "resize-mode")
+ (child :allocation :gobject-property
+ :g-property-type "GtkWidget"
+ :accessor container-child
+ :initarg :child
+ :g-property-name "child")
+ (focus-child :allocation :gobject-fn
+ :g-property-type g-object
+ :accessor container-focus-child
+ :initarg :focus-child
+ :g-getter "gtk_container_get_focus_child"
+ :g-setter "gtk_container_set_focus_child")
+ (focus-vadjustment :allocation :gobject-fn
+ :g-property-type (g-object adjustment)
+ :accessor container-focus-vadjustment
+ :initarg :focus-vadjustment
+ :g-getter "gtk_container_get_focus_vadjustment"
+ :g-setter "gtk_container_set_focus_vadjustment")
+ (focus-hadjustment :allocation :gobject-fn
+ :g-property-type (g-object adjustment)
+ :accessor container-focus-hadjustment
+ :initarg :focus-hadjustment
+ :g-getter "gtk_container_get_focus_hadjustment"
+ :g-setter "gtk_container_set_focus_hadjustment"))
+ (:metaclass gobject-class)
+ (:g-type-name . "GtkContainer")
+ (:g-type-initializer . "gtk_container_get_type"))
+@end example
+(note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)
+
+@node Using objects
+@section Using objects
+Instances are created with @code{make-instance}. If initargs of GObject properties are supplied, they are passed to constructor. Some slots (properties) may only be set at construction time (e.g., @code{type} property of @code{GtkWindow}). Properties may be accessed (read or assigned) with defined @code{:accessor}, @code{:reader} or @code{:writer} functions.
+
+Example:
+@example
+(make-instance 'gtk:dialog :has-separator t)
+@result{}
+#<GTK:DIALOG @{10036C5A71@}>
+
+(defvar *d* (make-instance 'gtk:dialog :has-separator t))
+@result{}
+*D*
+
+(gtk:dialog-has-separator *d*)
+@result{}
+T
+
+(setf (gtk:dialog-has-separator *d*) nil)
+@result{}
+NIL
+
+(gtk:dialog-has-separator *d*)
+@result{}
+NIL
+@end example
+
+@node Signals
+@section Signals
+
+To connect handler to a signal, @code{connect-signal} function is used.
+
+@code{(connect-signal object signal handler &key after)}
+
+@table @var
+@item @var{object}
+An instance of GObject object
+@item @var{signal}
+A signal name
+@item @var{handler}
+A function
+@item @var{after}
+A boolean specifying whether the handler should be called after the default handler
+@end table
+
+Connects the @code{handler} to signal @code{signal} on object @code{object}. Signature of @code{handler} should comply with signature of a signal. @code{handler} will be called with arguments of type specified by signal with the object (on which the signal was emitted) prepended to them and it should return the value of the signal's return type.
+
+Example:
+@example
+(defvar *d* (make-instance 'gtk:dialog))
+@result{}
+*D*
+
+*d*
+@result{}
+#<GTK:DIALOG @{1002D866F1@}>
+
+(parse-signal-name "GtkDialog" "response")
+@result{}
+#<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
+
+(connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
+
+(emit-signal *d* "response" 14)
+@result{}
+;; Prints:
+#<GTK:DIALOG @{1002D866F1@}>
+14
+@end example
+
+Function @code{emit-signal} is used to emit signals on objects.
+
+@code{(emit-signal object signal-name &rest args) @result{} return-value}
+
+@table @var
+@item @var{object}
+An object on which the signal should be emitted
+@item @var{signal-name}
+A string naming the signal
+@item @var{args}
+Arguments for a signal
+@item @var{return-value}
+Return value of a signal
+@end table
+
+Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
+
+Example:
+@example
+(defvar *d* (make-instance 'gtk:dialog))
+@result{}
+*D*
+
+*d*
+@result{}
+#<GTK:DIALOG @{1002D866F1@}>
+
+(parse-signal-name "GtkDialog" "response")
+@result{}
+#<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
+
+(connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
+
+(emit-signal *d* "response" 14)
+@result{}
+;; Prints:
+#<GTK:DIALOG @{1002D866F1@}>
+14
+@end example
+
+@node GObject foreign class
+@section GObject foreign class
+
+To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
+
+This type has the following syntax:
+@code{(g-object &optional type)} or @code{g-object}.
+
+When the @code{g-object} foreign type is specified as a return type of a function, the value is converted to instance of corresponding CLOS class. If @code{type} is specified then it is checked that object is of this type.
+
+When the @code{g-object} foreign type is specified as a type of function's argument, the value is converted to pointer to GObject. If @code{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 @code{container} and @code{widget}:
+@example
+(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))
+@end example
+(@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
+
+This defines the function that returns an instance of GObject class:
+@example
+(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))
+@result{}
+#<GTK:BUTTON @{1002DE74B1@}>
+@end example
@node Subclassing GObjects and implementing GInterfaces
@chapter Subclassing GObjects and implementing GInterfaces
@node GBoxed
@chapter GBoxed
+@menu
+* define-g-boxed-class::
+* define-g-boxed-ref::
+@end menu
+
+GObject manual defines this type in the following way:
+
+``GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.
+
+Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries.''
+
+Naturally, it is quite hard to provide support for such structures. At the moment, support for GBoxed is pretty bad.
+
+Basically, two use cases of GBoxed structures are provided:
+@itemize
+@item structure is mapped to Lisp structure defined with @code{defstruct}. This is complex scenario and it supports inheritance between structure. Its main use is to define the @code{GdkEvent} structure wrapper. Macro @code{define-g-boxed-class} supports this use case.
+@item structure is mapped to Lisp wrapper that contains pointer to structure and provides accessor functions (by calling foreign function or calling Lisp function). Macro @code{define-g-boxed-ref} supports this use case.
+@end itemize
+
+In both scenarios, foreign functions and GValue type registrations are provided that provide wrapping and unwrapping behaivour (it yet remains to be proven that the behaviour is correct in all cases with regard to issues of memory management, ownership, lifetime). In both cases it is possible to pass the structure by reference, allowing the foreign function (or the callback code) to change the contents of GBoxed.
+
+It is expected that the support for GBoxed structures will be improved.
+
+@node define-g-boxed-class
+@section define-g-boxed-class
+
+@example
+(define-g-boxed-class g-name-and-c-name name (&optional superclass-and-dispatch (export t))
+ &body slot*)
+
+g-name-and-c-name ::= nil
+g-name-and-c-name ::= (g-name c-name)
+superclass-and-dispatch ::= (&optional superclass dispatch-slot dispatch-values)
+slot ::= slot-name slot-type &key initform parser unparser
+@end example
+
+@table @var
+@item @var{g-name}
+A string naming the type of this GBoxed; for inherited classes, it should be @code{NIL}
+@item @var{c-name}
+A symbol naming the generated CFFI foreign structure definition corresponding to this GBoxed. This name should not conflict with other CFFI types.
+@item @var{name}
+A symbol naming the Lisp structure that will be generated
+@item @var{superclass}
+A symbol naming the structure defined with @code{define-g-boxed-class} that is the superclass of this structure
+@item @var{dispatch-slot}
+A slot of the superclass structure that identifies the specific type of structure (``discriminator'')
+@item @var{dispatch-values}
+A value or a list of values of the @code{dispatch-slot} that correspond to this GBoxed class
+@item @var{slot-name}
+Name of a slot
+@item @var{slot-type}
+CFFI foreign type of a slot
+@item @var{initform}
+An optional initform for @code{defstruct} slot
+@item @var{parser}
+An optional parser function designator for slot. Parser function is called to get the value for slot when the GBoxed is passed to Lisp with the following arguments: @code{(name pointer)} where the @code{name} is the name of a structure being defined and the @code{pointer} is a foreign pointer to the C structure.
+@item @var{unparser}
+An optional unparser function designator for a slot. Unparser function is called to write the slot value to GBoxed structure. It is called with arguments @code{(name pointer object)} where @code{name} is the name of a structure being defined, @code{pointer} is the pointer to the C structure and the @code{object} is object whose slot value should be written to structure.
+@end table
+
+Defines the @code{defstruct} wrapper for GBoxed type. Various parameters control how the structure is converted between C and Lisp representations.
+
+@code{define-g-boxed-class} supports basic single inheritance. This is provided to support ``generic'' C structures like @code{GdkEvent} that contain a ``type'' field and a @code{union} of other substructures. The natural mapping of such structure to Lisp is not one, but several structures that are inherited one from another. This supports e.g. method dispatching on @code{GdkEvent} types (if it is ever necessary).
+
+The only use of @code{define-g-boxed-class} that involves inheritance is the @code{GdkEvent} structure. It is defined as follows.
+@example
+(define-g-boxed-class ("GdkEvent" event-struct) event ()
+ (type event-type)
+ (window (g-object gdk-window))
+ (send-event (:boolean :int8)))
+
+(define-g-boxed-class nil event-key ((event type (:key-press :key-release)))
+ (time :uint32)
+ (state modifier-type)
+ (keyval :uint)
+ (length :int)
+ (string (:string :free-from-foreign nil :free-to-foreign nil))
+ (hardware-keycode :uint16)
+ (group :uint8)
+ (is-modifier :uint))
+
+(define-g-boxed-class nil event-button ((event type (:button-press :2button-press :3button-press :button-release)))
+ (time :uint32)
+ (x :double)
+ (y :double)
+ (axes (fixed-array :double 2))
+ (state :uint)
+ (button :uint)
+ (device (g-object device))
+ (x-root :double)
+ (y-root :double))
+@end example
+
+Some simpler uses include following examples:
+@example
+(define-g-boxed-class "GdkFont" font ()
+ (type font-type :initform :font)
+ (ascent :int :initform 0)
+ (descent :int :initform 0))
+
+(define-g-boxed-class "GdkColor" color ()
+ (pixel :uint32 :initform 0)
+ (red :uint16 :initform 0)
+ (green :uint16 :initform 0)
+ (blue :uint16 :initform 0))
+
+(define-g-boxed-class "GdkGeometry" geometry ()
+ (min-width :int :initform 0)
+ (min-height :int :initform 0)
+ (max-width :int :initform 0)
+ (max-height :int :initform 0)
+ (base-width :int :initform 0)
+ (base-height :int :initform 0)
+ (width-increment :int :initform 0)
+ (height-increment :int :initform 0)
+ (min-aspect :double :initform 0.0d0)
+ (max-aspect :double :initform 0.0d0)
+ (gravity gravity :initform :north-west))
+@end example
+
+@node define-g-boxed-ref
+@section define-g-boxed-ref
+
+@code{g-boxed-ref} class is defined:
+@example
+(defclass g-boxed-ref ()
+ ((pointer :accessor pointer :initarg :pointer)))
+@end example
+
+This class holds the pointer to structure. GBoxed-ref types are subclasses of this class.
+
+@example
+(define-g-boxed-ref g-name name
+ &rest property*)
+
+property ::= (:free-function free-function)
+property ::= (:alloc-function alloc-function)
+property ::= (:slots &rest slot*)
+slot ::= (slot-name &key reader writer type (accessor slot-name))
+@end example
+
+@table @var
+@item @var{g-name}
+A string that names the GBoxed type
+@item @var{name}
+A symbol that is the name for generated class
+@item @var{free-function}
+Mandatory designator for a function that frees the allocated object. This function accepts a single argument - CFFI foreign pointer.
+@item @var{alloc-function}
+Mandatory designator for a function that allocates the object. This function accepts zero arguments and returns CFFI foreign pointer to fresh object.
+@item @var{slot-name}
+A symbol naming the slot
+@item @var{type}
+A CFFI foreign type of a slot
+@item @var{reader}
+@code{NIL} or a string or a function designator. If it is @code{NIL} the the slot is not readable. If it is a string then it names the C function that accepts the pointer to structure and returns the value of a slot of specified CFFI type. If it is a function designator that it designates a function that accepts the Lisp object and returns its slot value.
+@item @var{writer}
+@code{NIL} or string or a function designator. If it is a @code{NIL} then the slot is not writable. If it is a string then it names the C function that accepts the pointer to C structure and a value (of specified CFFI type) and assigns it to the slot of a structure. If it is a function designator then it specifies a function that accepts the new slot value and a Lisp object and assigns it to the slot.
+@item @var{accessor}
+A symbol namin the accessor function for slot.
+@end table
+
+Defines a class corresponding to GBoxed type that is passed by reference (e.g., @code{GtkTextIter}). Class is made a subclass of @code{g-boxed-ref}.
+
+The memory occupied by this class is managed automatically: after the GC collects the Lisp instance, @code{free-function} is used to free the structure (if the instance was created by lisp code).
+
+Example:
+@example
+(defcstruct tree-iter
+ (stamp :int)
+ (user-data :pointer)
+ (user-data-2 :pointer)
+ (user-data-3 :pointer))
+
+(defun tree-iter-get-stamp (i) (foreign-slot-value (pointer i) 'tree-iter 'stamp))
+(defun tree-iter-set-stamp (value i) (setf (foreign-slot-value (pointer i) 'tree-iter 'stamp) value))
+(defun tree-iter-get-user-data (i) (pointer-address (foreign-slot-value (pointer i) 'tree-iter 'user-data)))
+(defun tree-iter-set-user-data (value i) (setf (foreign-slot-value (pointer i) 'tree-iter 'user-data) (make-pointer value)))
+
+(defun tree-iter-alloc () (glib:g-malloc (foreign-type-size 'tree-iter)))
+(defun tree-iter-free (v) (glib:g-free v))
+
+(define-g-boxed-ref "GtkTreeIter" tree-iter
+ (:slots (stamp :reader tree-iter-get-stamp :writer tree-iter-set-stamp :accessor tree-iter-stamp)
+ (user-data :reader tree-iter-get-user-data :writer tree-iter-set-user-data :accessor tree-iter-user-data))
+ (:alloc-function tree-iter-alloc)
+ (:free-function tree-iter-free))
+@end example
+
+Another example:
+@example
+(define-foreign-type unichar ()
+ ()
+ (:actual-type :uint32)
+ (:simple-parser unichar))
+
+(defmethod translate-from-foreign (value (type unichar))
+ (code-char value))
+
+(defmethod translate-to-foreign (value (type unichar))
+ (char-code value))
+
+(define-g-boxed-ref "GtkTextIter" text-iter
+ (:free-function gtk-text-iter-free)
+ (:alloc-function gtk-text-iter-alloc)
+ (:slots (text-iter-buffer :reader "gtk_text_iter_get_buffer" :type (g-object text-buffer))
+ (text-iter-offset :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
+ (text-iter-line :reader "gtk_text_iter_get_line" :writer "gtk_text_iter_set_line" :type :int)
+ (text-iter-line-offset :reader "gtk_text_iter_get_line_offset" :writer "gtk_text_iter_set_line_offset" :type :int)
+ (text-iter-visible-line-offset :reader "gtk_text_iter_get_visible_line_offset" :writer "gtk_text_iter_set_visible_line_offset" :type :int)
+ (text-iter-char :reader "gtk_text_iter_get_char" :type unichar)
+ (text-iter-pixbuf :reader "gtk_text_iter_get_pixbuf" :type (g-object pixbuf))
+ (text-iter-marks :reader "gtk_text_iter_get_marks" :type (gslist (g-object text-mark) :free-from-foreign t))
+ (text-iter-child-anchor :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))
+ (text-iter-tags :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))
+ (text-iter-chars-in-line :reader "gtk_text_iter_get_chars_in_line" :type :int)
+ (text-iter-language :reader "gtk_text_iter_get_language" :type :pointer)
+ (text-iter-is-end :reader "gtk_text_iter_is_end" :type :boolean)
+ (text-iter-is-start :reader "gtk_text_iter_is_start" :type :boolean)
+ (text-iter-can-insert :reader "gtk_text_iter_can_insert" :type :boolean)
+ (text-iter-starts-word :reader "gtk_text_iter_starts_word" :type :boolean)
+ (text-iter-ends-word :reader "gtk_text_iter_ends_word" :type :boolean)
+ (text-iter-inside-word :reader "gtk_text_iter_inside_word" :type :boolean)
+ (text-iter-starts-line :reader "gtk_text_iter_starts_line" :type :boolean)
+ (text-iter-ends-line :reader "gtk_text_iter_ends_line" :type :boolean)
+ (text-iter-starts-sentence :reader "gtk_text_iter_starts_sentence" :type :boolean)
+ (text-iter-ends-sentence :reader "gtk_text_iter_ends_sentence" :type :boolean)
+ (text-iter-inside-sentence :reader "gtk_text_iter_inside_sentence" :type :boolean)
+ (text-iter-is-cursor-position :reader "gtk_text_iter_is_cursor_position" :type :boolean)))
+
+(defcstruct %text-iter
+ (dummy1 :pointer)
+ (dummy2 :pointer)
+ (dummy3 :int)
+ (dummy4 :int)
+ (dummy5 :int)
+ (dummy6 :int)
+ (dummy7 :int)
+ (dummy8 :int)
+ (dummy9 :pointer)
+ (dummy10 :pointer)
+ (dummy11 :int)
+ (dummy12 :int)
+ (dummy13 :int)
+ (dummy14 :pointer))
+
+(defcfun gtk-text-iter-copy :pointer
+ (iter :pointer))
+
+(defcfun gtk-text-iter-free :void
+ (iter :pointer))
+
+(defun gtk-text-iter-alloc ()
+ (with-foreign-object (iter '%text-iter)
+ (gtk-text-iter-copy iter)))
+@end example
@node Generating type definitions by introspection
@chapter Generating type definitions by introspection
+@menu
+* define-g-object-class::
+* define-g-interface::
+* define-g-enum::
+* define-g-flags::
+* get-g-enum-definition::
+* get-g-flags-definition::
+* get-g-interface-definition::
+* get-g-class-definition::
+* Specifying additional properties for CLOS classes::
+* Generating names for CLOS classes and accessors::
+* generate-types-hierarchy-to-file::
+@end menu
+
+CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.
+
+@node define-g-object-class
+@section define-g-object-class
+
+@example
+(define-g-object-class g-type-name name
+ (&key (superclass 'g-object) (export t) interfaces type-initializer)
+ (&rest property*))
+
+property ::= (name accessor gname type readable writable)
+property ::= (:cffi name acessor type reader writer)
+@end example
+
+Parameters of @code{define-g-object-class}
+@table @var
+@item @var{superclass}
+A symbol naming the superclass of this class
+@item @var{export}
+Whether to export the name of the class and names of autogenerated properties names from the current package.
+@item @var{interfaces}
+A list of interfaces the this class implements
+@item @var{type-initializer}
+A string naming the type initiliazer function. It is usually named @code{class_get_type}.
+@item @var{properties}
+A list of slots of a class
+@end table
+
+Parameters of @code{property}:
+@table @var
+@item @var{name}
+A symbol naming the slot
+@item @var{accessor}
+A symbol naming the accessor function for this slot
+@item @var{gname}
+A string naming the property of GObject
+@item @var{type}
+A string naming the type of property of GObject (for GObject properties); or a symbol naming CFFI foreign type (for slots mapped to foreign accessors)
+@item @var{readable}
+A boolean specifying whether the slot can be read
+@item @var{writable}
+A boolean specifying whether the slot can be assigned to
+@item @var{reader}
+A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
+@item @var{writter}
+A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
+@end table
+
+Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.
+
+Example:
+@example
+(define-g-object-class "GtkContainer" container
+ (:superclass widget :export t :interfaces
+ ("AtkImplementorIface" "GtkBuildable")
+ :type-initializer "gtk_container_get_type")
+ ((border-width container-border-width "border-width" "guint" t t)
+ (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
+ (child container-child "child" "GtkWidget" nil t)
+ (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
+ (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
+ (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
+@end example
+
+@node define-g-interface
+@section define-g-interface
+
+@example
+(define-g-interface g-type-name name (&key (export t) type-initializer)
+ &body property*)
+
+property ::= (name accessor gname type readable writable)
+property ::= (:cffi name acessor type reader writer)
+@end example
+
+Parameters of @code{define-g-interface}
+@table @var
+@item @var{export}
+Whether to export the name of the interface and names of autogenerated properties names from the current package.
+@item @var{type-initializer}
+A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
+@item @var{properties}
+A list of slots of a interface
+@end table
+
+Parameters of @code{property}:
+@table @var
+@item @var{name}
+A symbol naming the slot
+@item @var{accessor}
+A symbol naming the accessor function for this slot
+@item @var{gname}
+A string naming the property of GObject
+@item @var{type}
+A string naming the type of property of GObject (for GObject properties); or a symbol naming CFFI foreign type (for slots mapped to foreign accessors)
+@item @var{readable}
+A boolean specifying whether the slot can be read
+@item @var{writable}
+A boolean specifying whether the slot can be assigned to
+@item @var{reader}
+A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
+@item @var{writter}
+A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
+@end table
+
+Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.
+
+Example:
+@example
+(define-g-interface "GtkFileChooser" file-chooser
+ (:export t :type-initializer "gtk_file_chooser_get_type")
+ (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
+ (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
+ (filter file-chooser-filter "filter" "GtkFileFilter" t t)
+ (local-only file-chooser-local-only "local-only" "gboolean" t t)
+ (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
+ (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
+ (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
+ (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
+ (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
+ (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
+ (action file-chooser-action "action" "GtkFileChooserAction" t t)
+ (:cffi current-name file-chooser-current-name
+ (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
+ (:cffi filename file-chooser-filename
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
+ (:cffi current-folder file-chooser-current-folder
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_current_folder"
+ "gtk_file_chooser_set_current_folder")
+ (:cffi uri file-chooser-uri
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
+ (:cffi current-folder-uri file-chooser-current-folder-uri
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_current_folder_uri"
+ "gtk_file_chooser_set_current_folder_uri")
+ (:cffi preview-filename file-chooser-preview-filename
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_preview_filename" nil)
+ (:cffi preview-uri file-chooser-preview-uri
+ (g-string :free-from-foreign t :free-to-foreign t)
+ "gtk_file_chooser_get_preview_uri" nil))
+@end example
+
+@node define-g-enum
+@section define-g-enum
+
+@example
+(define-g-enum g-name name (&key (export t) type-initializer) &body value*)
+
+value ::= :keyword
+value ::= (:keyword integer)
+@end example
+
+@table @var
+@item @var{g-name}
+A string naming the GEnum type
+@item @var{name}
+A symbol naming the CFFI enumeration type
+@item @var{export}
+A boolean indicating whether to export @code{name}
+@item @var{type-initializer}
+A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
+@end table
+
+Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
+
+Example:
+@example
+(define-g-enum "GtkTextDirection" text-direction
+ (:export t :type-initializer "gtk_text_direction_get_type")
+ (:none 0) (:ltr 1) (:rtl 2))
+
+(define-g-enum "GtkSizeGroupMode" size-group-mode
+ (:export t :type-initializer "gtk_size_group_mode_get_type")
+ :none :horizontal :vertical :both)
+@end example
+
+@node define-g-flags
+@section define-g-flags
+
+@example
+(define-g-flags g-name name (&key (export t) type-initializer) &body value*)
+
+value ::= :keyword
+value ::= (:keyword integer)
+@end example
+
+@table @var
+@item @var{g-name}
+A string naming the GFlags type
+@item @var{name}
+A symbol naming the CFFI flags type
+@item @var{export}
+A boolean indicating whether to export @code{name}
+@item @var{type-initializer}
+A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
+@end table
+
+Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
+
+Example:
+@example
+(define-g-flags "GtkAttachOptions" attach-options
+ (:export t :type-initializer "gtk_attach_options_get_type")
+ (:expand 1) (:shrink 2) (:fill 4))
+
+(define-g-flags "GtkButtonAction" button-action
+ (:export t :type-initializer "gtk_button_action_get_type")
+ :ignored :selects :drags :expands)
+@end example
+
+@node get-g-enum-definition
+@section get-g-enum-definition
+
+@code{(get-g-enum-definition type &optional lisp-name-package) @result{} definition}
+
+@table @var
+@item @var{type}
+A string naming the GEnum type
+@item @var{lisp-name-package}
+A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
+@item @var{definition}
+A Lisp form that when evaluated defines the GEnum.
+@end table
+
+Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.
+
+See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
+
+Example:
+@example
+(get-g-enum-definition "GtkDirectionType")
+@result{}
+(DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
+ (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
+ (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
+ (:RIGHT 5))
+@end example
+
+@node get-g-flags-definition
+@section get-g-flags-definition
+
+@code{(get-g-flags-definition type &optional lisp-name-package) @result{} definition}
+
+@table @var
+@item @var{type}
+A string naming the GFlags type
+@item @var{lisp-name-package}
+A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
+@item @var{definition}
+A Lisp form that when evaluated defines the GFlags.
+@end table
+
+Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.
+
+See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
+
+Example:
+@example
+(get-g-flags-definition "GtkCalendarDisplayOptions")
+@result{}
+(DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
+ (:EXPORT T :TYPE-INITIALIZER
+ "gtk_calendar_display_options_get_type")
+ (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
+ (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
+ (:SHOW-DETAILS 32))
+@end example
+
+@node get-g-interface-definition
+@section get-g-interface-definition
+
+@code{get-g-interface-definition type &optional lisp-name-package) @result{} definition}
+
+@table @var
+@item @var{type}
+A string naming the GInterface type
+@item @var{lisp-name-package}
+A package that will be used as a package for generated symbols (type name, accessor names). If not specified, symbols are interned in @code{*package*}
+@item @var{definition}
+A Lisp form that when evaluated defines the GInterface.
+@end table
+
+Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.
+
+See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
+
+Example:
+@example
+(get-g-interface-definition "GtkActivatable")
+@result{}
+(DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
+ (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
+ (USE-ACTION-APPEARANCE
+ GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
+ "use-action-appearance" "gboolean" T T)
+ (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
+ "related-action" "GtkAction" T T))
+@end example
+@node get-g-class-definition
+@section get-g-class-definition
+
+
+@code{get-g-class-definition type &optional lisp-name-package) @result{} definition}
+
+@table @var
+@item @var{type}
+A string naming the GObject type
+@item @var{lisp-name-package}
+A package that will be used as a package for generated symbols (type name, accessor names). If not specified, symbols are interned in @code{*package*}
+@item @var{definition}
+A Lisp form that when evaluated defines the GObject.
+@end table
+
+Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.
+
+See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
+
+Example:
+@example
+(get-g-class-definition "GtkButton")
+@result{}
+(DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
+ (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
+ ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
+ :TYPE-INITIALIZER "gtk_button_get_type")
+ ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
+ (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
+ (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
+ T)
+ (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
+ "gboolean" T T)
+ (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
+ T T)
+ (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
+ "focus-on-click" "gboolean" T T)
+ (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
+ (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
+ (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
+ "image-position" "GtkPositionType" T T)))
+@end example
+
+@node Specifying additional properties for CLOS classes
+@section Specifying additional properties for CLOS classes
+
+Some properties are not exposed through GObject introspection facilities, but are rather present as a pair of functions (@code{class_get_property}, @code{class_set_property}). @code{gobject-class} metaclass supports such properties. For these properties to be included in automatically generated class definitions, they should be made known to the generator.
+
+Definitions generator uses variable @code{*additional-properties*} to get this information.
+
+Variable @code{*additional-properties*} contains a plist that maps GType names to a list of properties definitions (See @ref{define-g-object-class} for syntax of properties definitions).
+
+To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
+
+Example:
+@example
+(("GtkTreeViewColumn"
+ (:cffi gtk::tree-view
+ gtk::tree-view-column-tree-view
+ g-object "gtk_tree_view_column_get_tree_view" nil)
+ (:cffi gtk::sort-column-id
+ gtk::tree-view-column-sort-column-id
+ :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
+ (:cffi gtk::cell-renderers
+ gtk::tree-view-column-cell-renderers
+ (glist g-object :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
+ ("GtkTreeSelection"
+ (:cffi gtk::mode
+ gtk::tree-selection-mode
+ gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
+ (:cffi gtk::select-function
+ gtk::tree-selection-select-function
+ nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
+@end example
+
+@node Generating names for CLOS classes and accessors
+@section Generating names for CLOS classes and accessors
+
+Names of types are generated by mapping @code{CamelCaseNames} to @code{dash-separated-names} and interning them in specified package. Additionally, prefix from beginning of the name may be stripped (@code{"GtkWidget"} has prefix @code{"Gtk"}, after stripping it maps to @code{widget}). Some names may require special processing (e.g., @code{"GObject"}, @code{"GInitiallyUnowned"} should map to class names in @code{gobject} package; @code{"GtkWindow"} and @code{"GdkWindow"} should receive different @code{symbol-name}s so that they can both be imported in one package).
+
+Accessors for slots are generated by concatenating class name, dash and slot name, producing names like @code{class-slot}: @code{container-child}, @code{button-label}, etc.
+
+Name generation affected by following variables:
+@itemize
+@item @var{*strip-prefix*}
+A string variable specifying the prefix that should to be stripped from the names to generate symbols (e.g., if @code{(equal "Gtk" *strip-prefix*)}, then type named @code{"GtkWidget"} will map to class named @code{widget}.
+@item @var{*lisp-name-exceptions*}
+A plist mapping from strings (type names) to symbols (class names) that have special name processing.
+Example:
+@example
+`(("GObject" gobject:g-object)
+ ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
+ ("GInitiallyUnowned" gobject::g-initially-unowned)
+ ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
+ ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
+ ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
+@end example
+@end itemize
+
+@node generate-types-hierarchy-to-file
+@section generate-types-hierarchy-to-file
+
+@example
+(generate-types-hierarchy-to-file file
+ root-type
+ &key include-referenced
+ prefix
+ package
+ exceptions
+ prologue
+ interfaces
+ enums
+ flags
+ objects
+ exclusions
+ additional-properties)
+@end example
+
+@table @var
+@item @var{file}
+A string or pathname naming the file, or a stream.
+@item @var{root-type}
+A GType designator for a root type. All types that inherit from this type will be defined.
+@item @var{&key include-referenced}
+A boolean. Specifies whether referenced types should be included. Type is referenced if it is an interface or a type of property of type included in generation
+@item @var{prefix}
+A string naming the prefix that should be removed from the beginning of names
+@item @var{package}
+A package which will contain generated names of types, slots and accessors. It will also be the current package when the definitions are written to file
+@item @var{exceptions}
+A plist that maps GType names to their Lisp names.
+See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
+@item @var{prologue}
+A string that will be included verbatim in generated code file
+@item @var{interfaces}
+Additional list of interfaces that will also be included in generation
+@item @var{enums}
+Additional list of enums that will also be included in generation
+@item @var{flags}
+Additional list of flags that will also be included in generation
+@item @var{objects}
+Additional list of object types that will also be included in generation
+@item @var{exclusions}
+A list of GType names that will be excluded from generation
+@item @var{additional-properties}
+A plist of properties definitions that will be added to generated classes.
+See @ref{Specifying additional properties for CLOS classes} for more information.
+@end table
+
+Generates definitions for all types in a type hierarchy. Recursively scan types hierarchy (starting from @code{root} and @code{objects} and @code{interfaces}) (except types that were specifically excluded) and generate defintion for every mentioned type. Parameters control various aspects of definition generation.
+
+Example of usage:
+@example
+(generate-types-hierarchy-to-file
+ "gtk.generated-classes.lisp"
+ "GtkObject"
+ :include-referenced t
+ :prefix "Gtk"
+ :package (or (find-package :gtk) (make-package :gtk))
+ :exceptions `(("GObject" gobject:g-object)
+ ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
+ ("GInitiallyUnowned" gobject::g-initially-unowned)
+ ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
+ ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
+ ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
+ :prologue (format nil "(in-package :gtk)")
+ :interfaces '("GtkBuildable" "GtkCellEditable" ...)
+ :objects '("GtkSettings" "GtkRcStyle" ...)
+ :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
+ :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
+ :exclusions '("PangoStretch" "PangoVariant" ...)
+ :additional-properties
+ '(("GtkTreeViewColumn"
+ (:cffi
+ gtk::tree-view
+ gtk::tree-view-column-tree-view
+ g-object
+ "gtk_tree_view_column_get_tree_view"
+ nil)
+ ...)
+ ...))
+@end example
@bye
projects / cl-gtk2.git / blobdiff