@end defmac
@end macro
+@macro Struct {args}
+@deftp {Structure} \args\
+@end deftp
+@end macro
+
+@macro Class {args}
+@deftp {Class} \args\
+@end deftp
+@end macro
+
@macro Accessor {args}
@deffn {Accessor} \args\
@end deffn
* Closures::
* GObject low-level::
* GObject high-level::
-* Subclassing GObjects and implementing GInterfaces::
+* Creating GObjects classes and implementing GInterfaces::
* GBoxed::
* Generating type definitions by introspection::
@end menu
@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-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived. Values of this type correspond to by-value structures.
+@item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived. Values of this type correspond to instances of structure @code{g-class-property-definition}.
@item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
@end itemize
Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
-@example
+@lisp
(g-type-numeric "GObject") @result{} 80
(g-type-numeric 80) @result{} 80
(g-type-string "GObject") @result{} "GObject"
(g-type-string 80) @result{} "GObject"
(g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
-@end example
+@end lisp
@node g-type-string
@section g-type-string
-@code{(g-type-string g-type-designator) @result{} name}
+@Function g-type-string
+@lisp
+(g-type-string g-type-designator) @result{} name
+@end lisp
@table @var
@item @var{g-type-designator}
@node g-type-numeric
@section g-type-numeric
-@code{(g-type-numeric g-type-designator) @result{} GType}
+@Function g-type-numeric
+@lisp
+(g-type-numeric g-type-designator) @result{} GType
+@end lisp
@table @var
@item @var{g-type-designator}.
@node g-type=
@section g-type=
-@code{(g-type= type-1 type-2) @result{} eq}
+@Function g-type=
+@lisp
+(g-type= type-1 type-2) @result{} eq
+@end lisp
@table @var
@item @var{type-1}
@node g-type/=
@section g-type/=
-@code{(g-type/= type-1 type-2) @result{} eq}
+@Function g-type/=
+@lisp
+(g-type/= type-1 type-2) @result{} eq
+@end lisp
@table @var
@item @var{type-1}
@node g-type-children
@section g-type-children
-@code{(g-type-children type) @result{} children}
+@Function g-type-children
+@lisp
+(g-type-children type) @result{} children
+@end lisp
+
@table @var
@item @var{type}
A GType designator
Returns the list of descendent types.
Example:
-@example
+@lisp
(g-type-children "GtkButton")
@result{}
("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
-@end example
+@end lisp
@node g-type-parent
@section g-type-parent
-@code{(g-type-parent type) @result{} parent}
+@Function g-type-parent
+@lisp
+(g-type-parent type) @result{} parent
+@end lisp
@table @var
@item @var{type}
Returns the parent of @code{type}.
Example:
-@example
+@lisp
(g-type-parent "GtkToggleButton")
@result{}
"GtkButton"
-@end example
+@end lisp
+
@node g-type-fundamental
@section g-type-fundamental
-@code{(g-type-fundamental type) @result{} fundamental-type}
+@Function g-type-fundamental
+@lisp
+(g-type-fundamental type) @result{} fundamental-type
+@end lisp
@table @var
@item @var{type}
Returns the fundamental type that is the ancestor of @code{type}.
Example:
-@example
+@lisp
(g-type-fundamental "GtkButton") @result{} "GObject"
(g-type-fundamental "GtkWindowType") @result{} "GEnum"
(g-type-fundamental "GdkEvent") @result{} "GBoxed"
-@end example
+@end lisp
@node g-type-depth
@section g-type-depth
-@code{(g-type-depth type) @result{} depth}
+@Function g-type-depth
+@lisp
+(g-type-depth type) @result{} depth
+@end lisp
@table @var
@item @var{type}
Returns the depth of the @code{type}. Depth is the number of types between the @code{type} and its fundamental types (including both @code{type} and its fundamental type). Depth of a fundamental type equals to 1.
Example:
-@example
+@lisp
(g-type-depth "GObject") @result{} 1
(g-type-depth "GInitiallyUnowned") @result{} 2
-@end example
+@end lisp
@node g-type-next-base
@section g-type-next-base
-@code{(g-type-next-base leaf-type root-type) @result{} base-type}
+@Function g-type-next-base
+@lisp
+(g-type-next-base leaf-type root-type) @result{} base-type
+@end lisp
@table @var
@item @var{leaf-type}
@end table
Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
-@example
+@lisp
+ GObject
\
+ GInitiallyUnowned
+ GtkContainer
\
+ GtkTable
-@end example
+@end lisp
the following will be returned:
-@example
+@lisp
(g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
(g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
(g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
(g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
(g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
-@end example
+@end lisp
@node Object types information
@chapter Object types information
@node g-class-property-definition
@section g-class-property-definition
-@example
+@Struct g-class-property-definition
+@lisp
(defstruct g-class-property-definition
name
type
constructor
constructor-only
owner-type)
-@end example
+@end lisp
@table @var
@item @var{name}
This structure identifies a single property. Its field specify attributes of a property.
Structures of this type have shortened print syntax:
-@example
+@lisp
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
-@end example
+@end lisp
(When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
@node class-properties
@section class-properties
-@code{(class-properties type) @result{} properties}
+@Function class-properties
+@lisp
+(class-properties type) @result{} properties
+@end lisp
@table @var
@item @var{type}
This function returns the list of properties that are available in class @code{type}.
Example:
-@example
+@lisp
(class-properties "GtkWidget")
@result{}
(#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
#<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
#<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
#<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
-@end example
+@end lisp
@node class-property-info
@section class-property-info
-@code{(class-property-info type property-name) @result{} property}
+@Function class-property-info
+@lisp
+(class-property-info type property-name) @result{} property
+@end lisp
@table @var
@item @var{type}
Returns the property information for a single property.
Example:
-@example
+@lisp
(class-property-info "GtkButton" "label")
@result{}
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
-@end example
+@end lisp
@node interface-properties
@section interface-properties
-@code{(interface-properties type) @result{} properties}
+@Function interface-properties
+@lisp
+(interface-properties type) @result{} properties
+@end lisp
@table @var
@item @var{type}
This function returns the list of properties that are available in interface @code{type}.
Example:
-@example
+@lisp
(interface-properties "GtkFileChooser")
@result{}
(#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
#<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
#<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
#<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
-@end example
+@end lisp
@node signal-info
@section signal-info
-@example
+@Struct signal-info
+@lisp
(defstruct signal-info
id
name
return-type
param-types
detail)
-@end example
+@end lisp
@table @var
@item @var{id}
@end table
When @code{*print-readably*} is nil, the following print syntax is used:
-@example
+@lisp
#<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
#<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
#<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
#<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
-@end example
+@end lisp
This syntax specifies:
@itemize
@node type-signals
@section type-signals
-@code{(type-signals type &key (include-inherited t)) @result{} signals}
+@Function type-signals
+@lisp
+(type-signals type &key (include-inherited t)) @result{} signals
+@end lisp
@table @var
@item @var{type}
A GType designator
Returns the list of signals that are available in type @code{type}.
Example:
-@example
+@lisp
(type-signals "GtkLabel" :include-inherited nil)
@result{}
(#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
#<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
#<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
-@end example
+@end lisp
@node parse-signal-name
@section parse-signal-name
-@code{(parse-signal-name type signal-name) @result{} signal}
+@Function parse-signal-name
+@lisp
+(parse-signal-name type signal-name) @result{} signal
+@end lisp
@table @var
@item @var{type}
Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
Example:
-@example
+@lisp
(parse-signal-name "GObject" "notify::label")
@result{}
#<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
-@end example
+@end lisp
@node query-signal-info
@section query-signal-info
-@code{(query-signal-info signal-id) @result{} signal}
+@Function query-signal-info
+@lisp
+(query-signal-info signal-id) @result{} signal
+@end lisp
@table @var
@item @var{signal-id}
An integer identifying the signal
Retrieves the signal information by its id.
Example:
-@example
+@lisp
(query-signal-info 73)
@result{}
#<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
-@end example
+@end lisp
@node g-type-interfaces
@section g-type-interfaces
-@code{(g-type-interfaces type) @result{} interfaces}
+@Function g-type-interfaces
+@lisp
+(g-type-interfaces type) @result{} interfaces
+@end lisp
@table @var
@item @var{type}
Returns the list of interfaces that @code{type} implements.
Example:
-@example
+@lisp
(g-type-interfaces "GtkButton")
@result{}
("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
-@end example
+@end lisp
@node g-type-interface-prerequisites
@section g-type-interface-prerequisites
-@code{(g-type-interface-prerequisites type) @result{} types}
+@Function g-type-interface-prerequisites
+@lisp
+(g-type-interface-prerequisites type) @result{} types
+@end lisp
@table @var
@item @var{type}
Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
Example:
-@example
+@lisp
(g-type-interface-prerequisites "GtkCellEditable")
@result{}
("GtkObject" "GtkWidget")
-@end example
+@end lisp
@node Enum types information
@chapter Enum types information
@node enum-item
@section enum-item
-@example
+@Struct enum-item
+@lisp
(defstruct enum-item
name value nick)
-@end example
+@end lisp
@table @var
@item @var{name}
Structure @code{enum-item} represents a single item of an enumeration type.
Example:
-@example
+@lisp
#S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
-@end example
+@end lisp
@node flags-item
@section flags-item
-@example
+@Struct flags-item
+@lisp
(defstruct flags-item
name value nick)
-@end example
+@end lisp
@table @var
@item @var{name}
Structure @code{flags-item} represents a single item of an flags type.
Example:
-@example
+@lisp
#S(FLAGS-ITEM
:NAME "GDK_POINTER_MOTION_HINT_MASK"
:VALUE 8
:NICK "pointer-motion-hint-mask")
-@end example
+@end lisp
@node get-enum-items
@section get-enum-items
-@code{(get-enum-items type) @result{} items}
+@Function get-enum-items
+@lisp
+(get-enum-items type) @result{} items
+@end lisp
@table @var
@item @var{type}
Returns a list of items in an enumeration
Example:
-@example
+@lisp
(get-enum-items "GtkScrollType")
@result{}
(#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
#S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
#S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
#S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
-@end example
+@end lisp
@node get-flags-items
@section get-flags-items
-@code{(get-flags-items type) @result{} items}
+@Function get-flags-items
+@lisp
+(get-flags-items type) @result{} items
+@end lisp
@table @var
@item @var{type}
Returns a list of items in an flags type
Example:
-@example
+@lisp
(get-flags-items "GtkAttachOptions")
@result{}
(#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
#S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
#S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
-@end example
+@end lisp
@node Using GValues
@chapter Using GValues
@end itemize
Example of usage:
-@example
+@lisp
(cffi:with-foreign-object (gval 'g-value)
(set-g-value gval "Hello" "gchararray" :zero-g-value t)
(format t "~S~%" (parse-g-value gval))
(g-value-unset gval))
@result{}
"Hello"
-@end example
+@end lisp
@node g-value-zero
@section g-value-zero
-@code{(g-value-zero g-value)}
+@Function g-value-zero
+@lisp
+(g-value-zero g-value)
+@end lisp
@table @var
@item @var{g-value}
A foreign pointer to GValue structure.
@end table
Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
-@example
+@lisp
GValue value = @{ 0 @};
-@end example
+@end lisp
Must be called before other functions that work with GValue (except @code{set-g-value} with keyword argument @code{:zero-g-value} set to true).
@node g-value-init
@section g-value-init
-@code{(g-value-init value type)}
+@Function g-value-init
+@lisp
+(g-value-init value type)
+@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure
@node g-value-unset
@section g-value-unset
-@code{(g-value-unset value)}
+@Function g-value-unset
+@lisp
+(g-value-unset value)
+@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure.
@node parse-g-value
@section parse-g-value
-@code{(parse-g-value value) @result{} object}
+@Function parse-g-value
+@lisp
+(parse-g-value value) @result{} object
+@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure
@node set-g-value
@section set-g-value
-@code{(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))}
+@Function set-g-value
+@lisp
+(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))
+@end lisp
@table @var
@item @var{gvalue}
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)}
+@Function register-enum-type
+@lisp
+(register-enum-type name type)
+@end lisp
@table @var
@item @var{name}
A string naming the GEnum type
Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
Example:
-@example
+@lisp
(defcenum text-direction
:none :ltr :rtl)
(register-enum-type "GtkTextDirection" 'text-direction)
-@end example
+@end lisp
@subsection
-@code{(register-flags-type name type)}
+@Function register-flags-type
+@lisp
+(register-flags-type name type)
+@end lisp
@table @var
@item @var{name}
A string naming the GFlags type
Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
Example:
-@example
+@lisp
(defcenum state-type
:normal :active :prelight :selected :insensitive)
(register-enum-type "GtkStateType" 'state-type)
-@end example
+@end lisp
@node Stable pointers
@chapter Stable pointers
@node allocate-stable-pointer
@section allocate-stable-pointer
-@code{(allocate-stable-pointer thing) @result{} stable-pointer}
+@Function allocate-stable-pointer
+@lisp
+(allocate-stable-pointer thing) @result{} stable-pointer
+@end lisp
@table @var
@item @var{thing}
(Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
Example:
-@example
+@lisp
(allocate-stable-pointer (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X00000002)
(free-stable-pointer **)
@result{}
NIL
-@end example
+@end lisp
@node free-stable-pointer
@section free-stable-pointer
-@code{(free-stable-pointer stable-pointer)}
+@Function free-stable-pointer
+@lisp
+(free-stable-pointer stable-pointer)
+@end lisp
@table @var
@item @var{stable-pointer}
Frees the stable pointer, enabling the garbage collector to reclaim the object.
Example:
-@example
+@lisp
(allocate-stable-pointer (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X00000002)
(free-stable-pointer **)
@result{}
NIL
-@end example
+@end lisp
@node stable-pointer-value
@section stable-pointer-value
-@example
+@Accessor stable-pointer-value
+@lisp
(stable-pointer-value stable-pointer) @result{} thing
(setf (stable-pointer-value stable-pointer) thing)
-@end example
+@end lisp
@table @var
@item @var{stable-pointer}
@node with-stable-pointer
@section with-stable-pointer
-@code{(with-stable-pointer (ptr expr) &body body)}
+@Macro with-stable-pointer
+@lisp
+(with-stable-pointer (ptr expr) &body body)
+@end lisp
@table @var
@item @var{ptr}
Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
Example:
-@example
+@lisp
(with-stable-pointer (ptr (lambda (x) (+ x 10)))
(print (stable-pointer-value ptr)))
;;Prints:
#<FUNCTION (LAMBDA (X)) @{1004807E79@}>
-@end example
+@end lisp
@node Closures
@chapter Closures
GObject supports using closures (as instances of type GClosure) as signal handlers and in some other places where a function is expected. Function @code{create-g-closure} create closure from lisp function. The GClosure is finalized automatically when GObject no longer needs it (e.g., when GClosure is disconnected from signal).
@section create-g-closure
-@code{(create-g-closure fn) @result{} closure}
+@Function create-g-closure
+@lisp
+(create-g-closure fn) @result{} closure
+@end lisp
@table @var
@item @var{fn}
Allocates the closure. The closure is destroyed automatically by GObject.
Example:
-@example
+@lisp
(create-g-closure (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X006D7B20)
-@end example
+@end lisp
Example of usage from GObject binding code:
-@example
+@lisp
(defun connect-signal (object signal handler &key after)
(g-signal-connect-closure (ensure-object-pointer object)
signal
(create-g-closure handler)
after))
-@end example
+@end lisp
(TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
@node g-object-call-constructor
@section g-object-call-constructor
-@code{(g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr}
+@Function g-object-call-constructor
+@lisp
+(g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr
+@end lisp
@table @var
@item @var{object-type}
Creates the object of type @code{object-type} by calling its constructors with arguments specified by @code{args-names}, @code{args-values}, @code{args-types}.
Example:
-@example
+@lisp
(g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
@result{}
#.(SB-SYS:INT-SAP #X006D8900)
(g-object-call-get-property ** "use-underline")
@result{}
T
-@end example
+@end lisp
@node g-type-from-object
@section g-type-from-object
-@code{(g-type-from-object object-ptr) @result{} type}
+@Function g-type-from-object
+@lisp
+(g-type-from-object object-ptr) @result{} type
+@end lisp
@table @var
@item @var{object-ptr}
Returns the type of an object by a pointer to its instance
Example:
-@example
+@lisp
(g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
@result{}
"GtkButton"
-@end example
+@end lisp
@node g-object-call-get-property
@section g-object-call-get-property
-@code{(g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value}
+@Function g-object-call-get-property
+@lisp
+(g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value
+@end lisp
@table @var
@item @var{object-ptr}
Retrieves the value of a property @code{property-name} of object pointed to by @code{object-ptr}. @code{property-type} specifies the type of a property; it may be omitted.
Example:
-@example
+@lisp
(g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
@result{}
#.(SB-SYS:INT-SAP #X006D8900)
(g-object-call-get-property ** "use-underline")
@result{}
T
-@end example
+@end lisp
@node g-object-call-set-property
@section g-object-call-set-property
-@code{(g-object-call-set-property object-ptr property-name new-value &optional property-type)}
+@Function g-object-call-set-property
+@lisp
+(g-object-call-set-property object-ptr property-name new-value &optional property-type)
+@end lisp
@table @var
@item @var{object-ptr}
Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
Example:
-@example
+@lisp
(g-object-call-constructor "GtkButton" nil nil)
@result{}
#.(SB-SYS:INT-SAP #X006D8B40)
(g-object-call-get-property ** "label")
@result{}
"Hello"
-@end example
+@end lisp
@node GObject high-level
@chapter GObject high-level
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
+@lisp
(defclass dialog (gtk-window atk-implementor-iface buildable)
((has-separator :accessor dialog-has-separator
:initarg :has-separator
(:metaclass gobject-class)
(:g-type-name . "GtkDialog")
(:g-type-initializer . "gtk_dialog_get_type"))
-@end example
+@end lisp
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.
Initargs of a slot are used to construct the GObject class.
Example:
-@example
+@lisp
(defclass container (widget atk-implementor-iface buildable)
((border-width :allocation :gobject-property
:g-property-type "guint"
(:metaclass gobject-class)
(:g-type-name . "GtkContainer")
(:g-type-initializer . "gtk_container_get_type"))
-@end example
+@end lisp
(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
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
+@lisp
(make-instance 'gtk:dialog :has-separator t)
@result{}
#<GTK:DIALOG @{10036C5A71@}>
(gtk:dialog-has-separator *d*)
@result{}
NIL
-@end example
+@end lisp
@node Signals
@section Signals
To connect handler to a signal, @code{connect-signal} function is used.
-@code{(connect-signal object signal handler &key after)}
+@Function connect-signals
+@lisp
+(connect-signal object signal handler &key after)
+@end lisp
@table @var
@item @var{object}
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
+@lisp
(defvar *d* (make-instance 'gtk:dialog))
@result{}
*D*
;; Prints:
#<GTK:DIALOG @{1002D866F1@}>
14
-@end example
+@end lisp
Function @code{emit-signal} is used to emit signals on objects.
Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
Example:
-@example
+@lisp
(defvar *d* (make-instance 'gtk:dialog))
@result{}
*D*
;; Prints:
#<GTK:DIALOG @{1002D866F1@}>
14
-@end example
+@end lisp
@node GObject foreign class
@section GObject foreign class
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
+@lisp
(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
+@end lisp
(@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
+@lisp
(defcfun (bin-child "gtk_bin_get_child") (g-object widget)
(bin (g-object bin)))
(bin-child window))
@result{}
#<GTK:BUTTON @{1002DE74B1@}>
-@end example
+@end lisp
+
+@node Creating GObjects classes and implementing GInterfaces
+@chapter Creating GObjects classes and implementing GInterfaces
+
+@menu
+* define-vtable::
+* register-object-type-implementation::
+@end menu
+
+Creating GObject classes from Lisp is the most complex part of GObject binding.
+
+GObject binding at the moment provides only limited scenarios of creating GObject classes. It lets register GObject class (as a subclass of another class or of GObject), specify its properties and implemented interfaces. Each property is associated with Lisp getter and setter functions. Each interface is associated wth vtable (table of virtual function pointers, see @uref{http://en.wikipedia.org/wiki/Vtable}) that specifies a list of methods and their signatures. If class is ever created from GObject side (not from Lisp side, must be constructable with no parameters).
+
+Each virtual function is mapped to a generic function for which class should provide a specialized method. This function should not be called by user. Rather, user code should call corresponding foreign function.
+
+Practically speaking, creating GObject class requires defining CLOS class that correspond to GObject class and calling @code{register-object-type-implementation} with information about the class (its GType name, superclass, interfaces and properties).
+
+Interface that is implemented by a class should have its vtable defined by @code{define-vtable}. Vtable definitions consists of a list of functions's names and signatures and their locations in vtable.
+
+Unfortunately, GObject does not provide information about vtables, and does not support using GClosures to implement virtual functions. Therefore, implementation for all interface's functions are defined as CFFI foreign callbacks. These callbacks in turn call corresponding generic functions that should be specialized on required objects.
+
+@node define-vtable
+@section define-vtable
+
+@Macro define-vtable
+@lisp
+(define-vtable (type-name cstruct-name)
+ &body item*)
+
+item ::= (name callback-name return-type &rest arg*)
+item ::= (:skip cffi-structure-item)
+arg ::= (arg-name arg-type)
+@end lisp
+
+@table @var
+@item @var{type-name}
+A string naming the GObject type of interface
+@item @var{cstruct-name}
+A name for a generated CFFI foreign structure
+@item @var{name}
+A name for implementation generic function
+@item @var{callback-name}
+A name for generated callback function
+@item @var{return-type}
+A CFFI specifier for foreign function return type
+@item @var{arg-name}
+A symbol naming the argument of interface method
+@item @var{arg-type}
+A CFFI specifier for foreign function argument type
+@end table
+
+Macro that specifies the vtable for an interface. This macro defines generic functions (named by @code{name}) that correspond to methods of an interface. On these generic functions methods should be defined that implement the interface method. @code{item}s specify the CFFI foreign structure for vtable. Vtable contains not only function pointers, but other slots. Such slots should be specified here with @code{:skip} prepended to them. This is needed to be able to correctly calculate offsets to function pointers in vtable.
-@node Subclassing GObjects and implementing GInterfaces
-@chapter Subclassing GObjects and implementing GInterfaces
+Example:
+@lisp
+(define-vtable ("GtkTreeModel" c-gtk-tree-model)
+ (:skip parent-instance g-type-interface)
+ ;;some signals
+ (:skip tree-model-row-changed :pointer)
+ (:skip tree-model-row-inserted :pointer)
+ (:skip tree-model-row-has-child-toggled :pointer)
+ (:skip tree-model-row-deleted :pointer)
+ (:skip tree-model-rows-reordered :pointer)
+ ;;methods
+ (tree-model-get-flags-impl tree-model-get-flags-cb
+ tree-model-flags
+ (tree-model g-object))
+ (tree-model-get-n-columns-impl tree-model-get-n-columns-cb
+ :int
+ (tree-model g-object))
+ (tree-model-get-column-type-impl tree-model-get-column-type-cb
+ g-type-designator
+ (tree-model g-object) (index :int))
+ (tree-model-get-iter-impl tree-model-get-iter-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (path (g-boxed-foreign tree-path)))
+ (tree-model-get-path-impl tree-model-get-path-cb
+ (g-boxed-foreign tree-path :return)
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-get-value-impl tree-model-get-value-cb
+ :void
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
+ (tree-model-iter-next-impl tree-model-iter-next-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-iter-children-impl tree-model-iter-children-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)))
+ (tree-model-iter-has-child-impl tree-model-iter-has-child-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-iter-n-children-impl tree-model-iter-n-children-cb
+ :int
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-iter-nth-child-impl tree-model-iter-nth-child-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)) (n :int))
+ (tree-model-iter-parent-impl tree-model-iter-parent-cb
+ :boolean
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (child (g-boxed-foreign tree-iter)))
+ (tree-model-ref-node-impl tree-model-ref-node-cb
+ :void
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-unref-node-impl tree-model-unref-node-cb
+ :void
+ (tree-model g-object) (iter (g-boxed-foreign tree-iter))))
+@end lisp
+
+@node register-object-type-implementation
+@section register-object-type-implementation
+
+@Macro register-object-type-implementation
+@lisp
+(register-object-type-implementation name class parent interfaces properties)
+@end lisp
+
+@table @var
+@item @var{name}
+A string naming the new GObject class.
+@item @var{class}
+A class name of corresponding CLOS class. It should be inherited from @code{g-object} or its descendants.
+@item @var{parent}
+A string naming the GObject superclass
+@item @var{interfaces}
+A list of names of interfaces that this class implements.
+@item @var{properties}
+A list of properties that this class provides.
+Each property is defined as
+@lisp
+property ::= (property-name property-type accessor property-get-fn property-set-fn)
+@end lisp
+@end table
+
+A macro that creates a new GObject type and registers the Lisp implementation for it.
+
+Example:
+@lisp
+(register-object-type-implementation "LispArrayListStore" array-list-store "GObject" ("GtkTreeModel") nil)
+@end lisp
@node GBoxed
@chapter GBoxed
@menu
-* define-g-boxed-class::
-* define-g-boxed-ref::
+* define-g-boxed-cstruct::
+* define-g-boxed-variant-cstruct::
+* define-g-boxed-opaque::
+* g-boxed-opaque::
+* define-boxed-opaque-accessor::
+* boxed-related-symbols::
+* GBoxed foreign type::
@end menu
GObject manual defines this type in the following way:
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:
+Naturally, it is hard to provide support for ``arbitrary C structures''. We support a few useful use cases of GBoxed types:
@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.
+@item Simple C structures. A Lisp structure is a one-to-one correspondence to C structure and is passes to and from foreign code by copying the data it contains. Examples of simple structures are GdkPoint, GdkRectangle.
+@item ``Variant'' C structures. A one common idiom of C is to define a union of structures sharing the same parts in order to implement the polymorphism of structures. These structures are mapped to a hierarchy of Lisp structures (where one structure subclasses another via the @code{:include} @code{defstruct} option).
+
+For example, Gdk has structure GdkEvent which is a union of GdkEventAny, GdkEventExpose and other structures. These structures have common slots: ``type'', ``window'', ``send_event''. By dispatching on ``type'', user or GdkEvent structure knows which of GdkEvent* structures it has and can access other fields.
+@item Opaque C structures. A C structure the has ``hidden'' fields and should only created/destroyed with specific functions and be accessed only with specific accessors. Example of such structures is GtkTreePath.
@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.
+@node define-g-boxed-cstruct
+@section define-g-boxed-cstruct
+@Macro define-g-boxed-cstruct
+@lisp
+(define-g-boxed-cstruct name g-type-name
+ &body slot*)
-It is expected that the support for GBoxed structures will be improved.
+slot ::= (slot-name slot-type &key count initform inline)
+@end lisp
-@node define-g-boxed-class
-@section define-g-boxed-class
+@table @var
+@item @var{name}
+A symbol naming the type being defined
+@item @var{g-type-name}
+A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
+@item @var{slot-name}
+A symbol naming the slot of a structure
+@item @var{slot-type}
+A foreign type of a slot
+@item @var{count}
+An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
+@item @var{initform}
+A form that is the initform of Lisp structure slot
+@item @var{inline}
+A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
+@end table
-@example
-(define-g-boxed-class g-name-and-c-name name (&optional superclass-and-dispatch (export t))
- &body slot*)
+Defines the ``simple'' GBoxed structure corresponding to C structure. The slot specification is analogous to CFFI @code{defstruct} slot specification with the addition of @code{inline} option.
-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
+Example of usage:
+@lisp
+(define-g-boxed-cstruct rectangle "GdkRectangle"
+ (left :int :initform 0)
+ (top :int :initform 0)
+ (width :int :initform 0)
+ (height :int :initform 0))
+
+(define-g-boxed-cstruct point nil
+ (x :int :initform 0)
+ (y :int :initform 0))
+
+(define-g-boxed-cstruct vector4 nil
+ (coords :double :count 4 :initform (vector 0d0 0d0 0d0 0d0)))
+
+(define-g-boxed-cstruct segment nil
+ (a point :inline t :initform (make-point))
+ (b point :inline t :initform (make-point)))
+@end lisp
+
+@node define-g-boxed-variant-cstruct
+@section define-g-boxed-variant-cstruct
+
+@Macro define-g-boxed-variant-cstruct
+@lisp
+(define-g-boxed-variant-cstruct name g-type-name
+ &body slot-or-variant-specification*)
+
+slot ::= (slot-name slot-type &key count initform inline)
+variant-specification ::= (:variant dispatching-slot-name structure-variant*)
+structure-variant ::= (dispatching-slot-values structure-name &body slot-or-variant-specification*)
+@end lisp
@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
+A symbol naming the type being defined
+@item @var{g-type-name}
+A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
@item @var{slot-name}
-Name of a slot
+A symbol naming the slot of a structure
@item @var{slot-type}
-CFFI foreign type of a slot
+A foreign type of a slot
+@item @var{count}
+An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
@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.
+A form that is the initform of Lisp structure slot
+@item @var{inline}
+A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
+@item @var{dispatching-slot-name}
+A name of the dispatching slot
+@item @var{dispatching-slot-values}
+A single value or a list of values.
+@item @var{structure-name}
+A symbol naming the structure
@end table
-Defines the @code{defstruct} wrapper for GBoxed type. Various parameters control how the structure is converted between C and Lisp representations.
+Defines the variant GBoxed structure. Slots of variant structures are defined the same way as the slots of ``simple'' cstructs. After the last slot, @code{variant-specification} may be used to specify the variants of the structure. For this, dispatching slot is specified. The value of this slot specifies which variant of structure is used. Each variant is specified by values of the dispatching slot, by its slots and its variants.
-@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).
+Variant structure is represented in Lisp via a hierarchy on structures. For example, @code{GdkEvent} structure has variants @code{GdkEventAny}, @code{GdkEventButton}, @code{GdkEventMotion}. In Lisp, @code{event} structure is defined with all common fields of these structures and @code{event-button}, @code{event-motion} structures inherit from @code{event} structure.
-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
+It is assumed that the variant of structures can be represented as C structures with fields of their ``parent'' structures prepended to them. This assumption breaks when structures include their ``parent'' structure as a first field (this changes the memory alignment and changes offsets of fields).
-Some simpler uses include following examples:
+For example, for these structures this assumption holds:
@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
+union GdkEvent
+@{
+ GdkEventType type;
+ GdkEventKey key;
+ GdkEventButton button;
+@};
-@node define-g-boxed-ref
-@section define-g-boxed-ref
+struct GdkEventKey @{
+ GdkEventType type; //
+ GdkWindow *window; // These fields are common
+ gint8 send_event; //
+ guint32 time;
+ guint state;
+ guint keyval;
+ ...
+@};
-@code{g-boxed-ref} class is defined:
-@example
-(defclass g-boxed-ref ()
- ((pointer :accessor pointer :initarg :pointer)))
+struct GdkEventButton @{
+ GdkEventType type; //
+ GdkWindow *window; // These fields are common
+ gint8 send_event; //
+ guint32 time;
+ gdouble x;
+ gdouble y;
+ ...
+@};
@end example
-This class holds the pointer to structure. GBoxed-ref types are subclasses of this class.
+Example:
+@lisp
+(define-g-boxed-variant-cstruct event "GdkEvent"
+ (type event-type)
+ (window (g-object gdk-window))
+ (send-event (:boolean :int8))
+ (:variant type
+ ((:key-press :key-release) event-key
+ (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))
+ ((:button-press :2button-press :3button-press
+ :button-release) event-button
+ (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 lisp
+
+This code defines following structures:
+@lisp
+(defstruct event
+ type window send-event)
+
+(defstruct (event-key (:include event))
+ time state keyval length string
+ hardware-keycode group is-modifier)
+
+(defstruct (event-button (:include event))
+ time x y axes state button device x-root y-root)
+@end lisp
+
+@node define-g-boxed-opaque
+@section define-g-boxed-opaque
+
+@Macro define-g-boxed-opaque
+@lisp
+(define-g-boxed-opaque name g-type-name &key alloc)
+@end lisp
-@example
-(define-g-boxed-ref g-name name
- &rest property*)
+@table @var
+@item @var{name}
+A name of boxed type
+@item @var{g-type-name}
+A string; the name of GType
+@item @var{alloc}
+A form that when evaluated produces a pointer to newly allocated structure. This pointer should be copiable with @code{g_boxed_copy} and freeable with @code{g_boxed_free} function.
+@end table
-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
+Defines a opaque boxed structure. A class named @var{name} is defined as a subclass of @code{g-boxed-opaque} class. Instances of this class contain pointers to corresponding structures. An @code{:after} method for @code{initialize-instance} generic function is defined that speciales on class @var{name}. This method either accepts a @code{:pointer} initarg or evaluates @var{alloc} form if @code{:pointer} is not specified; the resulting pointer is saved in instance; finalizer is registered to free the pointer when the garbage collectors deletes this object.
+
+Example:
+@lisp
+(defcfun gtk-tree-path-new :pointer)
+
+(define-g-boxed-opaque tree-path "GtkTreePath"
+ :alloc (gtk-tree-path-new))
+@end lisp
+@node g-boxed-opaque
+@section g-boxed-opaque
+@Class g-boxed-opaque
+@lisp
+(defclass g-boxed-opaque ()
+ ((pointer :initarg :pointer
+ :initform nil
+ :accessor g-boxed-opaque-pointer)))
+@end lisp
+
+A class that is the base class for wrappers of opaque structures. Contains a pointer to the wrapped opaque structure.
+
+Accessor function @code{g-boxed-opaque-pointer} is used to access the pointer. Pointer should not be modified directly, only read.
+@node define-boxed-opaque-accessor
+@section define-boxed-opaque-accessor
+@Macro define-boxed-opaque-accessor
+@lisp
+(define-boxed-opaque-accessor
+ boxed-name accessor-name &key type reader writer)
+@end lisp
@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{boxed-name}
+A symbol naming the opaque structure type for which the accessor is being defined
+@item @var{accessor-name}
+A symbol naming the accessor
@item @var{type}
-A CFFI foreign type of a slot
+A CFFI foreign type of the property for which the accessor is being defined
@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.
+A @code{NIL} or a string or a function designator for the reader function
@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.
+A @code{NIL} or a string or a function designator for the writer function
@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}.
+Defines the accessor named @var{accessor-name} for property of opaque structure named @var{boxed-name} of type specified by CFFI foreign-type @var{type}.
-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).
+@var{reader} is a string naming a foreign function of one argument of CFFI foreign-type @code{(g-boxed-foreign @var{boxed-name})} that returns a value of CFFI foreign-type @var{type}; or a function designator for a function that accepts a single argument - an instance of @code{g-boxed-opaque} class and returns the value of a property; or a @code{NIL} if the property is not readable.
+
+@var{writer} is a string naming a foreign function of two arguments: of types @var{type} and @code{(g-boxed-foreign @var{boxed-name})} (with the first argument being the new value and the second being the object); or a function designator for a function of two arguments: a new value and an instance of @code{g-boxed-opaque} class; or a @code{NIL} if the property is not writable.
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
+@lisp
+(define-boxed-opaque-accessor text-iter text-iter-child-anchor
+ :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))
-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
+(define-boxed-opaque-accessor text-iter text-iter-tags
+ :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))
+
+(define-boxed-opaque-accessor text-iter text-iter-chars-in-line
+ :reader "gtk_text_iter_get_chars_in_line" :type :int)
+
+(define-boxed-opaque-accessor text-iter text-iter-offset
+ :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
+@end lisp
+
+@node boxed-related-symbols
+@section boxed-related-symbols
+
+@Function boxed-related-symbols
+@lisp
+(boxed-related-symbols name) @result{} symbols
+@end lisp
+
+@table @var
+@item @var{name}
+A symbol naming the boxed type
+@item @var{symbols}
+A list of symbols
+@end table
+
+This function returns the list of symbols that are related to GBoxed type @var{name}. These symbols are returned:
+@itemize
+@item name of boxed type
+@item name of all accessors of cstruct and variant-cstruct boxed types
+@item names of all variants of variant-cstruct boxed types
+@item names of constructors and copiers of cstruct and variant-cstruct boxed-types
+@end itemize
+
+Typical usage of this function is to export the symbols related to given boxed type.
+
+Example:
+@lisp
+(define-g-boxed-cstruct rectangle "GdkRectangle"
+ (x :int :initform 0)
+ (y :int :initform 0)
+ (width :int :initform 0)
+ (height :int :initform 0))
+
+(boxed-related-symbols 'rectangle)
+@result{}
+(RECTANGLE MAKE-RECTANGLE COPY-RECTANGLE RECTANGLE-X RECTANGLE-Y
+ RECTANGLE-WIDTH RECTANGLE-HEIGHT)
+@end lisp
+
+@node GBoxed foreign type
+@section GBoxed foreign type
+
+@ForeignType g-boxed-foreign
+@lisp
+(g-boxed-foreign name &rest option*)
+
+option ::= :return
+@end lisp
+
+@table @var
+@item @var{name}
+Name of GBoxed type
+@item @var{option}
+Option of foreign type
+@item @code{:return}
+An option that identifies the foreign type which is used at return position (as foreign function return type or as a callback return type)
+@end table
+
+@code{g-boxed-foreign} type deals with marshaling data between Lisp code and foreign code. The marshaling follows the following principles:
+@itemize
+@item All operations on Lisp objects corresponding to GBoxed types are type-safe and should never lead to any form of memory corruption (if some operation is impossible due to e.g., pointer in opaque pointer wrapper being invalidated, error should be signalled)
+@item Lisp objects should not be manually managed and are properly reclaimed by garbage collector, leaving no memory leaks
+@item Foreign code can change objects that are passed to them as arguments. This is required for functions that operate by modifying their arguments
+@item Lisp code in callbacks can change objects that are passed as arguments. This is required to be able to implement interfaces that have functions that operate by modifying their arguments
+@end itemize
+
+The @code{:return} option is required to be able to properly manage memory of opaque pointer wrappers and propagate changes to foreign and lisp structures.
+
+In order to be able to correctly use @code{g-boxed-foreign} foreign type in callbacks, you should use @code{glib-defcallback}. This macro is a thin wrapper around @code{cffi:defcallback} that adds proper handling of @code{g-boxed-foreign} foreign types.
+
+Examples of usage:
+@lisp
+(define-vtable ("GtkTreeModel" c-gtk-tree-model)
+ ...
+ (tree-model-get-path-impl tree-model-get-path-cb
+ (g-boxed-foreign tree-path :return) (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ (tree-model-get-value-impl tree-model-get-value-cb
+ :void (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
+ (tree-model-iter-next-impl tree-model-iter-next-cb
+ :boolean (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
+ ...)
+
+(defcfun gtk-text-iter-forward-search :boolean
+ (iter (g-boxed-foreign text-iter))
+ (str (:string :free-to-foreign t))
+ (flags text-search-flags)
+ (match-start (g-boxed-foreign text-iter))
+ (match-end (g-boxed-foreign text-iter))
+ (limit (g-boxed-foreign text-iter)))
+@end lisp
@node Generating type definitions by introspection
@chapter Generating type definitions by introspection
@node define-g-object-class
@section define-g-object-class
-@example
+@Macro define-g-object-class
+@lisp
(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
+@end lisp
Parameters of @code{define-g-object-class}
@table @var
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
+@lisp
(define-g-object-class "GtkContainer" container
(:superclass widget :export t :interfaces
("AtkImplementorIface" "GtkBuildable")
(: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
+@end lisp
@node define-g-interface
@section define-g-interface
-@example
+@Macro define-g-interface
+@lisp
(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
+@end lisp
Parameters of @code{define-g-interface}
@table @var
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
+@lisp
(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)
(: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
+@end lisp
@node define-g-enum
@section define-g-enum
-@example
+@Macro define-g-enum
+@lisp
(define-g-enum g-name name (&key (export t) type-initializer) &body value*)
value ::= :keyword
value ::= (:keyword integer)
-@end example
+@end lisp
@table @var
@item @var{g-name}
Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
Example:
-@example
+@lisp
(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
+@end lisp
@node define-g-flags
@section define-g-flags
-@example
+@Macro define-g-flags
+@lisp
(define-g-flags g-name name (&key (export t) type-initializer) &body value*)
value ::= :keyword
value ::= (:keyword integer)
-@end example
+@end lisp
@table @var
@item @var{g-name}
Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
Example:
-@example
+@lisp
(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
+@end lisp
@node get-g-enum-definition
@section get-g-enum-definition
-@code{(get-g-enum-definition type &optional lisp-name-package) @result{} definition}
+@Function get-g-enum-definition
+@lisp
+(get-g-enum-definition type &optional lisp-name-package) @result{} definition
+@end lisp
@table @var
@item @var{type}
See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
Example:
-@example
+@lisp
(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
+@end lisp
@node get-g-flags-definition
@section get-g-flags-definition
-@code{(get-g-flags-definition type &optional lisp-name-package) @result{} definition}
+@Function get-g-flags-definition
+@lisp
+(get-g-flags-definition type &optional lisp-name-package) @result{} definition
+@end lisp
@table @var
@item @var{type}
See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
Example:
-@example
+@lisp
(get-g-flags-definition "GtkCalendarDisplayOptions")
@result{}
(DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
(:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
(:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
(:SHOW-DETAILS 32))
-@end example
+@end lisp
@node get-g-interface-definition
@section get-g-interface-definition
-@code{get-g-interface-definition type &optional lisp-name-package) @result{} definition}
+@Function get-g-interface-definition
+@lisp
+get-g-interface-definition type &optional lisp-name-package) @result{} definition
+@end lisp
@table @var
@item @var{type}
See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
Example:
-@example
+@lisp
(get-g-interface-definition "GtkActivatable")
@result{}
(DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
"use-action-appearance" "gboolean" T T)
(RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
"related-action" "GtkAction" T T))
-@end example
+@end lisp
@node get-g-class-definition
@section get-g-class-definition
-
-@code{get-g-class-definition type &optional lisp-name-package) @result{} definition}
+@Function get-g-class-definition
+@lisp
+(get-g-class-definition type &optional lisp-name-package) @result{} definition
+@end lisp
@table @var
@item @var{type}
See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
Example:
-@example
+@lisp
(get-g-class-definition "GtkButton")
@result{}
(DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
(YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
(IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
"image-position" "GtkPositionType" T T)))
-@end example
+@end lisp
@node Specifying additional properties for CLOS classes
@section Specifying additional properties for CLOS classes
To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
Example:
-@example
+@lisp
(("GtkTreeViewColumn"
(:cffi gtk::tree-view
gtk::tree-view-column-tree-view
(:cffi gtk::select-function
gtk::tree-selection-select-function
nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
-@end example
+@end lisp
@node Generating names for CLOS classes and accessors
@section Generating names for CLOS classes and accessors
@item @var{*lisp-name-exceptions*}
A plist mapping from strings (type names) to symbols (class names) that have special name processing.
Example:
-@example
+@lisp
`(("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 lisp
@end itemize
@node generate-types-hierarchy-to-file
@section generate-types-hierarchy-to-file
-@example
+@Function generate-types-hierarchy-to-file
+@lisp
(generate-types-hierarchy-to-file file
root-type
&key include-referenced
objects
exclusions
additional-properties)
-@end example
+@end lisp
@table @var
@item @var{file}
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
+@lisp
(generate-types-hierarchy-to-file
"gtk.generated-classes.lisp"
"GtkObject"
nil)
...)
...))
-@end example
+@end lisp
@bye
projects / cl-gtk2.git / blobdiff