@chapter GType designator
@menu
-* g-type-string::
-* g-type-numeric::
-* g-type=::
-* g-type/=::
+* gtype-id::
+* gtype-name::
+* gtype::
@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.
+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 designator structures. GType designator is a structure identifying a particular GType; it contains its name and integer value.
-An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
+GType designators are singleton structures meaning that for every GType, there may be only one GType designator structure for it; this means that two GType designators are equal (with respect to the @code{COMMON-LISP:EQ} function) if and only if their corresponding GTypes are the same.
+
+GType designators remain the same (with respect to the @code{COMMON-LISP:EQ} function) even after dumping and restarting Lisp memory image.
+
+GType designators are obtained with @ref{gtype} function, and corresponding numeric and string values are accessed via @ref{gtype-id} and @ref{gtype-name} functions (you must not access @code{gtype} structure directly). If an attempt is made to obtain an invalid GType, then a warning is signalled but GType designator is still returned (which may become valid at some later time due to e.g. library being initialized).
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-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=} and @ref{g-type/=} check types for equality.
-
-Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
-
@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
+(gtype "GObject") @result{} #S(GTYPE :NAME "GObject" :%ID 80)
+(gtype-id (gtype "GObject")) @result{} 80
+(gtype-name (gtype "GObject")) @result{} "GObject"
+(gtype "GtkWidget") @result{} #S(GTYPE :NAME "GtkWidget" :%ID 6963568)
@end lisp
-@node g-type-string
-@section g-type-string
+@node gtype-name
+@section gtype-name
-@Function g-type-string
+@Function gtype-name
@lisp
-(g-type-string g-type-designator) @result{} name
+(gtype-name gtype) @result{} name
@end lisp
@table @var
The name of GType
@end table
-Returns the name of GType.
+Returns the name of GType. If the GType is invalid, signals warning and may return @code{NIL}.
+
+@lisp
+(gtype-name (gtype "gint")) @result{} "gint"
+@end lisp
-@node g-type-numeric
-@section g-type-numeric
+@node gtype-id
+@section gtype-id
-@Function g-type-numeric
+@Function gtype-id
@lisp
-(g-type-numeric g-type-designator) @result{} GType
+(gtype-id gtype) @result{} GType
@end lisp
@table @var
The numeric identifier of GType
@end table
-Returns the numeric identifier of GType
-
-@node g-type=
-@section g-type=
-
-@Function g-type=
-@lisp
-(g-type= type-1 type-2) @result{} eq
-@end lisp
-
-@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
+Returns the numeric identifier of GType. If the GType designator is invalid, signals warning and returns 0.
-@node g-type/=
-@section g-type/=
+@node gtype
+@section gtype
-@Function g-type/=
+@Function gtype
@lisp
-(g-type/= type-1 type-2) @result{} eq
+(gtype thing) @result GType designator
@end lisp
-@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
+Returns the GType designator for @var{thing}. @var{thing} may be:
+@itemize
+@item A string. @code{gtype} treats this as a GType name. If no GType with name is registered in GObject then warning is signalled and invalid GType designator is returned (which will become valid once GType will be registered).
+@item An integer. @code{gtype} treats this as a GType numeric value. If no GType with this valud is registered in GObject then warning is signalled and invalid GType designator is returned (which will become valid once GType will be registered).
+@item A GType designator. @var{thing} is returned.
+@end itemize
@node Type hierarchy and type relations
@chapter Type hierarchy and type relations
@node Closures
@chapter Closures
+@menu
+* create-signal-handler-closure::
+* Object-bound foreign functions::
+@end menu
Closure are anonymous functions that capture their lexical environment.
-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).
+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-signal-handler-closure} create closure from lisp function that can be used a signal handler. The GClosure is finalized automatically when GObject no longer needs it (e.g., when GClosure is disconnected from signal).
-@section create-g-closure
-@Function create-g-closure
+(TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
+
+@node create-signal-handler-closure
+@section create-signal-handler-closure
+@Function create-signal-handler-closure
@lisp
-(create-g-closure fn) @result{} closure
+(create-signal-handler-closure object fn) @result{} closure
@end lisp
@table @var
+@item @var{object}
+An object for which the closure is created
@item @var{fn}
A function that will be called by closure invokation
@item @var{closure}
Example:
@lisp
-(create-g-closure (lambda (x) (+ x 10)))
+(create-signal-handler-closure obj (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X006D7B20)
@end lisp
(defun connect-signal (object signal handler &key after)
(g-signal-connect-closure (ensure-object-pointer object)
signal
- (create-g-closure handler)
+ (create-signal-handler-closure object handler)
after))
@end lisp
-(TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
+@node Object-bound foreign functions
+@section Object-bound foreign functions
+
+A common idiom for Gtk+ for passing user-defined function is as follows. Callback function has (besides its 'useful' arguments) an additional argument at the end - the 'data' pointer. This 'data' pointer, along with the pointer to 'destroy-notify' function is specified when passing the function. Destroy-notify function allows to free the function object (the Lisp closure) when it is not used by an object.
+
+@RMacro define-cb-methods
+@lisp
+(define-cb-methods name return-type ((arg-1 type-1) ... (arg-n type-n)))
+@end lisp
+
+Defines two CFFI callbacks assosiated with the callback function type @var{name}. Creates @var{name}-cb - a callback to be passed as an function and create @var{name}-destroy-notify - a callback to be passed as 'destroy-notify' function. These callbacks are intended to work together with @ref{create-fn-ref}.
+
+Arguments and return-type are the same as CFFI arguments and return-type for callbacks. Arguments do not include the last 'data' pointer.
+
+@RFunction create-fn-ref
+@lisp
+(create-fn-ref object function) @result{} foreign-pointer
+@end lisp
+
+This function creates a foreign structure containing the data neccesary for callbacks defined by @ref{define-cb-methods} to call and dispose of the @var{function}. The @var{function} is bound to the @var{object}. This is neccesary for correct work of garbage collector. The created structure is freed by 'destroy-notify' function.
+
+Example:
+@lisp
+(defcfun gtk-assistant-set-forward-page-func :void
+ (assistant (g-object assistant))
+ (page-func :pointer)
+ (data :pointer)
+ (destroy-notify :pointer))
+
+(define-cb-methods assistant-page-func :int ((current-page :int)))
+
+(defun set-assistant-forward-page-function (assistant function)
+ (if function
+ (gtk-assistant-set-forward-page-func assistant
+ (callback assistant-page-func-cb)
+ (create-fn-ref assistant function)
+ (callback assistant-page-func-destroy-notify))
+ (gtk-assistant-set-forward-page-func assistant (null-pointer) (null-pointer) (null-pointer))))
+@end lisp
@node GObject low-level
@chapter GObject low-level
An accessor that accesses the foreign pointer to object.
+@Function release
+@lisp
+(release object)
+@end lisp
+
+Releases the @var{object} by dropping the reference from it in advance before GC reclaims it. Use this function as an optimization measure when you know that some object will not be needed. All access to the object's properties will be invalid after this function is called.
+
+@Macro using
+@lisp
+(using (object expr) &body body)
+@end lisp
+
+Evaluates and returns the result of evaluation of the @var{body} with @var{object} being bound to the result of evaluating @var{expr}. Ensures that @code{release} is called on @var{object} after the @var{body} is evaluated.
+
+@Macro using
+@lisp
+(using ((var1 expr1) (var2 expr2) ... (varn exprn)) &body body)
+@end lisp
+
+Evaluates and returns the result of evaluation of the @var{body} with @var{var}s being bound to the results of evaluating @var{expr}s. Ensures that @code{release} is called on every @var{var} after the @var{body} is evaluated.
+
@node g-initially-unowned
@section g-initially-unowned
@node Signals
@section Signals
-To connect handler to a signal, @code{connect-signal} function is used.
+To connect handler to a signal, @code{connect-signal} function is used. Function @code{disconnect-signal} removes the connected signal.
-@Function connect-signals
+@Function connect-signal
@lisp
-(connect-signal object signal handler &key after)
+(connect-signal object signal handler &key after) @result{} handler-id
@end lisp
@table @var
A function
@item @var{after}
A boolean specifying whether the handler should be called after the default handler
+@item @var{handler-id}
+An integer - identifier of signal handler; can be used to disconnect the signal handler with @code{disconnect-signal}
@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.
+@Function disconnect-signal
+@lisp
+(disconnect-signal object handler-id)
+@end lisp
+
+Disconnects the signal handler identified by @var{handler-id} from the corresponding signal for @var{object}. @var{handler-id} is the integer identifying the signal handler; @code{connect-signal} returns handler identifiers.
+
Example:
@lisp
(defvar *d* (make-instance 'gtk:dialog))
Function @code{emit-signal} is used to emit signals on objects.
+@RFunction emit-signal
@code{(emit-signal object signal-name &rest args) @result{} return-value}
@table @var
@Macro define-vtable
@lisp
-(define-vtable (type-name cstruct-name)
+(define-vtable (g-type-name type-name)
&body item*)
-item ::= (name callback-name return-type &rest arg*)
item ::= (:skip cffi-structure-item)
+item ::= (method-name (return-type &rest arg*) &key impl-call)
arg ::= (arg-name arg-type)
+impl-call ::= ((arg-name*) &body call-code)
@end lisp
@table @var
-@item @var{type-name}
+@item @var{g-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}
+@item @var{cffi-structure-item}
+A structure item that is inserted verbatim into foreign structure definition of vtable and is not used as a pointer to method
+@item @var{method-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
+@item @var{call-code}
+A body of code that is used to convert arguments and return values between interface signature and desired implementor generic function signature
@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.
+Macro that specifies the vtable for an interface. Vtable for an interface is a structure that contains pointer to implementations of interface methods. Vtable is used to dispach method calls to corresponding method implementations. In cl-gtk2-gobject, vtables are needed to create classes that implement GObject interfaces.
+
+GObject interfaces are implemented in the following way. For every method, an implementor generic function is defined. This generic function is called by interface method callback, and CLOS classes specialize on this generic function to implement an interface. The generic function has the same signature as the interface's function, but signatures may differ.
+
+This macro defines generic functions (named by concatenatinag @var{type-name}, @var{name} and @code{impl}; e.g., @code{get-flags} method of class @code{tree-model} will have generic function named @code{tree-model-get-flags-impl}) 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.
+
+In some cases, the signature of interface method is not very lispy: it may pass @code{void*} pointers, pointers to places where return values should be stored. To conceal such unlispy things, you specify your own code that will call the generic function and translate arguments for implementor generic function. This is implemented by specifying @var{impl-call} method option. @var{impl-call} specifies the signature of implementor function and code that calls the generic function and returns its result. The code is put in return position of callback, and it has access to the arguments of callback and its return value becomes the return value of callback.
Example:
@lisp
-(define-vtable ("GtkTreeModel" c-gtk-tree-model)
+(define-vtable ("GtkTreeModel" tree-model)
(:skip parent-instance g-type-interface)
;;some signals
(:skip tree-model-row-changed :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))))
+ (get-flags (tree-model-flags (tree-model g-object)))
+ (get-value (:void
+ (tree-model g-object)
+ (iter (g-boxed-foreign tree-iter))
+ (n :int)
+ (value (:pointer g-value)))
+ :impl-call
+ ((tree-model iter n)
+ (multiple-value-bind (v type) (tree-model-get-value-impl tree-model iter n)
+ (set-g-value value v type)))))
+
+(defmethod tree-model-get-flags-impl ((model array-list-store))
+ '(:list-only))
+
+(defmethod tree-model-get-value-impl ((model array-list-store) iter n)
+ (let ((n-row (tree-iter-user-data iter)))
+ (values (funcall (aref (store-getters model) n)
+ (aref (store-items model) n-row))
+ (aref (store-types model) n))))
@end lisp
@node register-object-type-implementation
* define-boxed-opaque-accessor::
* boxed-related-symbols::
* GBoxed foreign type::
+* copy-boxed-slots-to-foreign::
+* with-boxed-foreign-array::
@end menu
GObject manual defines this type in the following way:
A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
@end table
-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.
+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. This also defines the @var{name}-cstruct CFFI structure definition with equivalent structure.
Example of usage:
@lisp
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).
+This also defines the @var{name}-cstruct, @var{structure-name}-cstruct, @var{structure-name}-cunion CFFI structures definitions with equivalent structures (unions).
+
For example, for these structures this assumption holds:
@example
union GdkEvent
(limit (g-boxed-foreign text-iter)))
@end lisp
+
+@node copy-boxed-slots-to-foreign
+@section copy-boxed-slots-to-foreign
+
+@Function copy-boxed-slots-to-foreign
+@lisp
+(copy-boxed-slots-to-foreign structure native-ptr &optional (type (and structure (type-of structure))))
+@end lisp
+
+@table @var
+@item @var{structure}
+A Lisp structure corresponding to some GBoxed type
+@item @var{native-ptr}
+A foreign pointer
+@item @code{type}
+Name of the GBoxed type. It is optional but may be included for optimization purposes
+@end table
+
+Copies the contents of @var{structure} to C structure pointed to by @var{native-ptr}. @var{type} is used to determine which slots and which cstruct definition should be used.
+
+Examples:
+@lisp
+(cffi:with-foreign-object (point-ptr 'gdk::point-cstruct)
+ (gobject:copy-boxed-slots-to-foreign (gdk:make-point :x 10 :y 10) point-ptr 'gdk:point))
+@end lisp
+
+@node with-boxed-foreign-array
+@section with-boxed-foreign-array
+
+@Macro with-boxed-foreign-array
+@lisp
+(with-foreign-boxed-array (n-var array-var type values-seq) &body body)
+@end lisp
+
+@table @var
+@item @var{n-var}
+A variable that will contain the count of items in @var{values-seq}
+@item @var{array-var}
+A variable that will contain the pointer to array of C structures
+@item @var{type}
+A symbol that specifies the type of GBoxed structure
+@item @var{values-seq}
+An expression that returns the sequence of structures (list or array)
+@end table
+
+Evaluates the @var{body} within the scope and extent of foreign array that contains copies of structures that are returned by @var{values-seq}. Binds @var{n-var} to the length of @var{values-seq}, @var{array-var} to the pointer to array of structures.
+
+Examples:
+@lisp
+(defcfun gdk-region-polygon (g-boxed-foreign region :return)
+ (points :pointer)
+ (n-points :int)
+ (fill-rule gdk-fill-rule))
+
+(defun region-from-polygon (points fill-rule)
+ (with-foreign-boxed-array (n pts point points)
+ (gdk-region-polygon pts n fill-rule)))
+@end lisp
+
@node Generating type definitions by introspection
@chapter Generating type definitions by introspection
@menu
* get-g-flags-definition::
* get-g-interface-definition::
* get-g-class-definition::
+* get-g-type-definition::
* Specifying additional properties for CLOS classes::
* Generating names for CLOS classes and accessors::
* generate-types-hierarchy-to-file::
"image-position" "GtkPositionType" T T)))
@end lisp
+@node get-g-type-definition
+@section get-g-type-definition
+
+@Function get-g-type-definition
+@lisp
+(get-g-class-definition type &optional lisp-name-package) @result{} definition
+@end lisp
+
+@table @var
+@item @var{type}
+A string naming the GEnum, GFlags, GInterface or 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 corresponding Lisp type.
+@end table
+
+Depending on a kind of @var{type}, calls @ref{get-g-enum-definition} or @ref{get-g-flags-definition} or @ref{get-g-interface-definition} or @ref{get-g-class-definition}.
+
@node Specifying additional properties for CLOS classes
@section Specifying additional properties for CLOS classes
projects / cl-gtk2.git / blobdiff