@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}.
-@node g-type-numeric
-@section g-type-numeric
+@lisp
+(gtype-name (gtype "gint")) @result{} "gint"
+@end lisp
+
+@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
+Returns the numeric identifier of GType. If the GType designator is invalid, signals warning and returns 0.
-@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/=
+@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
@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