@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).
+
+(TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
-@section create-g-closure
-@Function create-g-closure
+@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
@chapter GObject high-level
@menu
* g-object::
+* g-initially-unowned::
* GObject metaclass::
* Using objects::
* Signals::
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
+
+@Class g-initially-unowned
+
+Superclass: @ref{g-object}
+
+A base class for all GObject classes whose initial reference is floating.
+
@node GObject metaclass
@section GObject metaclass
GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
-Classes that correspond to GObject classes are instances of this class.
+Classes that correspond to GObject classes are instances of this class. Each CLOS class of @code{gobject-class} metaclass is mapped to one GObject class. Two or more CLOS classes may map into one GObject class. GObject and CLOS inheritance must be consistent: if class @code{X} is a subclass or the same class as @code{Y} in CLOS, then this relation must hold for @code{X'} and @code{Y'}, where @code{X'} is a GObject class to which @code{X} class maps to.
+
+For each instance of GObject-related CLOS class there is a corresponding instance of GObject class (of a GObject class to which the CLOS class maps). Whenever the GObject class instance reference enters the Lisp memory (by creating instance with @code{make-instance}, as the return value of foreign function or as a slot value of GObject class instance), an instance of CLOS class is created.
Defining the class with metaclass @code{gobject-class} registers the type @code{:g-type-name} for conversions using GValue and CFFI foreign type @code{g-object}.
@itemize
@item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
-Specifies the name of GObject class
+Specifies the name of corresponding GObject class. String or NIL is allowed. If the name is NIL, then the same GObject class as its parent. Only one class may have specified a given @code{:g-type-name}.
@item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
-Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
+Name of foreign type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}. String or NIL is allowed.
@item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
-A boolean specifying whether this CLOS class corresponds to GInterface.
+A boolean specifying whether this CLOS class corresponds to GInterface. It is NIL by default.
@end itemize
This metaclass defines the GObject classes.
@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
To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
This type has the following syntax:
-@code{(g-object &optional type)} or @code{g-object}.
+@code{(g-object [type] [:already-referenced])} or @code{g-object}. (Brackets indicate optional arguments)
-When the @code{g-object} foreign type is specified as a return type of a function, the value is converted to instance of corresponding CLOS class. If @code{type} is specified then it is checked that object is of this type.
+When the @code{g-object} foreign type is specified as a return type of a function, the value is converted to instance of corresponding CLOS class. If @code{type} is specified then it is checked that object is of this type. If @code{:already-referenced} is included then it is assumed that the function returns already referenced object (so that it is not needed to call @code{g-object-ref} on returned object).
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.
#<GTK:BUTTON @{1002DE74B1@}>
@end lisp
+This example shows the use of @code{:already-referenced} option:
+@lisp
+(defcfun (widget-create-pango-layout "gtk_widget_create_pango_layout") (g-object gdk::pango-layout :already-referenced)
+ (widget (g-object widget))
+ (text :string))
+
+(defcfun gdk-gc-new (g-object graphics-context :already-referenced)
+ (drawable (g-object drawable)))
+@end lisp
+
@node Creating GObjects classes and implementing GInterfaces
@chapter Creating GObjects classes and implementing GInterfaces
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
projects / cl-gtk2.git / blobdiff