1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header (This is for running texinfo on a region.)
3 @setfilename gobject.info
4 @settitle CL-Gtk2-GObject
5 @c %**end of header (This is for running texinfo on a region.)
7 @c @documentencoding utf-8
19 @macro Accessor {args}
20 @deffn {Accessor} \args\
24 @macro GenericFunction {args}
25 @deffn {Generic Function} \args\
29 @macro ForeignType {args}
30 @deftp {Foreign Type} \args\
34 @macro Variable {args}
35 @defvr {Special Variable} \args\
39 @macro Condition {args}
40 @deftp {Condition Type} \args\
50 @strong{Implementor's note:} @emph{\text\}
54 @c Info "requires" that x-refs end in a period or comma, or ) in the
55 @c case of @pxref. So the following implements that requirement for
56 @c the "See also" subheadings that permeate this manual, but only in
68 @c Typeset comments in roman font for the TeX output.
76 @c My copy of makeinfo is not generating any HTML for @result{} for
77 @c some odd reason. (It certainly used to...)
84 @c Similar macro to @result. Its purpose is to work around the fact
85 @c that ⇒ does not work properly inside @lisp.
98 @c ============================= Macros =============================
101 @c Show types, functions, and concepts in the same index.
107 @subtitle A Common Lisp binding for Gtk+
108 @subtitle GObject bindings
109 @author Dmitry Kalyanov
123 * Type hierarchy and type relations::
124 * Object types information::
125 * Enum types information::
129 * GObject low-level::
130 * GObject high-level::
131 * Subclassing GObjects and implementing GInterfaces::
133 * Generating type definitions by introspection::
137 @chapter Introduction
139 GObject is a part of GLib library that implements the type system. The CL-GTK2-GObject is a Common Lisp binding for relevant parts of GObject.
142 @chapter Installation
144 CL-GTK2-GObject comes as a part of CL-GTK2 bindings that are avaiable at its @uref{http://common-lisp.net/project/cl-gtk2/,,website}.
146 To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.
148 CL-GTK2-GObject defines two packages: @code{gobject} and @code{gobject.ffi}. The @code{gobject.ffi} package contains definitions for low-level CFFI imports. The @code{gobject} package contains symbols for external API of this GObject binding.
150 @node GType designator
151 @chapter GType designator
158 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.
160 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
162 Some of the types are fundamental and have constant integer values. They are identified by constants:
164 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
165 @item @code{+g-type-void+}. A fundamental type which is used as a replacement for the C @code{void} return type.
166 @item @code{+g-type-interface+}. The fundamental type from which all interfaces are derived.
167 @item @code{+g-type-char+}. The fundamental type corresponding to gchar. The type designated by @code{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.
168 @item @code{+g-type-uchar+}. The fundamental type corresponding to @code{guchar}.
169 @item @code{+g-type-boolean+}. The fundamental type corresponding to @code{gboolean}.
170 @item @code{+g-type-int+}. The fundamental type corresponding to @code{gint}.
171 @item @code{+g-type-uint+}. The fundamental type corresponding to @code{guint}.
172 @item @code{+g-type-long+}. The fundamental type corresponding to @code{glong}.
173 @item @code{+g-type-ulong+}. The fundamental type corresponding to @code{gulong}.
174 @item @code{+g-type-int64+}. The fundamental type corresponding to @code{gint64}.
175 @item @code{+g-type-uint64+}. The fundamental type corresponding to @code{guint64}.
176 @item @code{+g-type-enum+}. The fundamental type from which all enumeration types are derived.
177 @item @code{+g-type-flags+}. The fundamental type from which all flags types are derived.
178 @item @code{+g-type-float+}. The fundamental type corresponding to @code{gfloat}.
179 @item @code{+g-type-double+}. The fundamental type corresponding to @code{gdouble}.
180 @item @code{+g-type-string+}. The fundamental type corresponding to null-terminated C strings.
181 @item @code{+g-type-pointer+}. The fundamental type corresponding to @code{gpointer}.
182 @item @code{+g-type-boxed+}. The fundamental type from which all boxed types are derived.
183 @item @code{+g-type-param+}. The fundamental type from which all GParamSpec types are derived.
184 @item @code{+g-type-object+}. The fundamental type for GObject.
187 Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them).
189 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
192 (g-type-numeric "GObject") @result{} 80
193 (g-type-numeric 80) @result{} 80
194 (g-type-string "GObject") @result{} "GObject"
195 (g-type-string 80) @result{} "GObject"
196 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
200 @section g-type-string
202 @code{(g-type-string g-type-designator) @result{} name}
205 @item @var{g-type-designator}
206 The GType designator for the GType
211 Returns the name of GType.
214 @section g-type-numeric
216 @code{(g-type-numeric g-type-designator) @result{} GType}
219 @item @var{g-type-designator}.
220 The GType designator for the GType.
222 The numeric identifier of GType
225 Returns the numeric identifier of GType
227 @node Type hierarchy and type relations
228 @chapter Type hierarchy and type relations
233 * g-type-fundamental::
238 GTypes are organized into hierarchy. Each GType (except fundamental types) has a parent type and zero or more children types. Parent of GType identified by @code{g-type-parent} function and its children are identified by @code{g-type-children} function.
240 There are functions to query some specific information:
242 @item @code{g-type-fundamental} retrieves the fundamental type for given type
243 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
244 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
247 @node g-type-children
248 @section g-type-children
250 @code{(g-type-children type) @result{} children}
255 A list of GType designators
258 Returns the list of descendent types.
262 (g-type-children "GtkButton")
264 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
268 @section g-type-parent
270 @code{(g-type-parent type) @result{} parent}
279 Returns the parent of @code{type}.
283 (g-type-parent "GtkToggleButton")
287 @node g-type-fundamental
288 @section g-type-fundamental
290 @code{(g-type-fundamental type) @result{} fundamental-type}
295 @item @var{fundamental-type}
296 A GType designator for one of the fundamental types
299 Returns the fundamental type that is the ancestor of @code{type}.
303 (g-type-fundamental "GtkButton") @result{} "GObject"
305 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
307 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
311 @section g-type-depth
313 @code{(g-type-depth type) @result{} depth}
322 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.
326 (g-type-depth "GObject") @result{} 1
327 (g-type-depth "GInitiallyUnowned") @result{} 2
330 @node g-type-next-base
331 @section g-type-next-base
333 @code{(g-type-next-base leaf-type root-type) @result{} base-type}
336 @item @var{leaf-type}
338 @item @var{root-type}
340 @item @var{base-type}
344 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
361 the following will be returned:
364 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
365 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
366 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
367 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
368 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
371 @node Object types information
372 @chapter Object types information
374 * g-class-property-definition::
376 * class-property-info::
377 * interface-properties::
380 * parse-signal-name::
381 * query-signal-info::
382 * g-type-interfaces::
383 * g-type-interface-prerequisites::
386 GObject classes and interfaces have properties that can be queried with @code{class-properties}, @code{class-property-info} and @code{interface-properties}. These functions represent information about properties with instances of @code{g-class-property-definition} structure.
388 Information about signals can be queries with @code{type-signals}, @code{parse-signal-name} and @code{query-signal-info} functions. Information is returned within instances of @code{signal-info} structures.
390 @node g-class-property-definition
391 @section g-class-property-definition
394 (defstruct g-class-property-definition
406 A string that names the property
408 A GType designator. Identifies the type of the property
410 A boolean. Identifies whether the property can be read
412 A boolean. Identifies whether the property can be assigned
413 @item @var{constructor}
414 A boolean. Identifies whether constructor of object accepts this property
415 @item @var{constructor-only}
416 A boolean. Identifies whether this property may only be set in constructor, not in property setter
417 @item @var{owner-type}
418 A GType designator. Identifies the type on which the property was defined.
421 This structure identifies a single property. Its field specify attributes of a property.
423 Structures of this type have shortened print syntax:
425 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
428 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
430 This syntax specifies:
432 @item type of property
433 @item the owner type of property
434 @item name of property
435 @item additional flags of property
438 @node class-properties
439 @section class-properties
441 @code{(class-properties type) @result{} properties}
445 A GType designator. Specifies the object type (class)
446 @item @var{properties}
447 A list of @code{g-property-definition} structures.
450 This function returns the list of properties that are available in class @code{type}.
454 (class-properties "GtkWidget")
456 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
457 #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
458 #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
459 #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
460 #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
461 #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
462 #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
463 #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
464 #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
465 #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
466 #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
467 #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
468 #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
469 #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
470 #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
471 #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
472 #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
473 #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
474 #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
475 #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
476 #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
477 #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
478 #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
481 @node class-property-info
482 @section class-property-info
483 @code{(class-property-info type property-name) @result{} property}
488 @item @var{property-name}
489 A string naming the property
491 An instance of @code{g-property-definition} structure
494 Returns the property information for a single property.
498 (class-property-info "GtkButton" "label")
500 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
503 @node interface-properties
504 @section interface-properties
506 @code{(interface-properties type) @result{} properties}
511 @item @var{properties}
512 A list of @code{g-property-definition} structures
515 This function returns the list of properties that are available in interface @code{type}.
519 (interface-properties "GtkFileChooser")
521 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
522 #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
523 #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
524 #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
525 #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
526 #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
527 #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
528 #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
529 #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
530 #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
531 #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
538 (defstruct signal-info
550 An integer - the identifier of a signal
553 @item @var{owner-type}
554 A GType designator identifying the type on which the signal was defined
556 A list of keywords of type @code{'(member :run-first :run-last :run-cleanup :no-recurse :detailed :action :no-hooks)}. Specifies the attributes of a signals
557 @item @var{return-type}
558 The return type of a signal (and signal handlers)
559 @item @var{param-types}
560 A list of GType designators that specify the types of signal parameters
562 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
565 When @code{*print-readably*} is nil, the following print syntax is used:
567 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
568 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
569 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
570 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
573 This syntax specifies:
576 @item signal return type
580 @item list of types of parameters
585 @section type-signals
586 @code{(type-signals type &key (include-inherited t)) @result{} signals}
591 A list of @code{signal-info} structures
592 @item @var{include-inherited}
593 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
596 Returns the list of signals that are available in type @code{type}.
600 (type-signals "GtkLabel" :include-inherited nil)
602 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
603 #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
604 #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
607 @node parse-signal-name
608 @section parse-signal-name
610 @code{(parse-signal-name type signal-name) @result{} signal}
614 A GType designator that has the signal.
615 @item @var{signal-name}
616 A string that identifies the signal.
618 A list @code{signal-info} structures.
621 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
625 (parse-signal-name "GObject" "notify::label")
627 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
630 @node query-signal-info
631 @section query-signal-info
632 @code{(query-signal-info signal-id) @result{} signal}
634 @item @var{signal-id}
635 An integer identifying the signal
637 An instance of @code{signal-info} structure
640 Retrieves the signal information by its id.
644 (query-signal-info 73)
646 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
649 @node g-type-interfaces
650 @section g-type-interfaces
652 @code{(g-type-interfaces type) @result{} interfaces}
657 @item @var{interfaces}
658 A list of GType designators
661 Returns the list of interfaces that @code{type} implements.
665 (g-type-interfaces "GtkButton")
667 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
670 @node g-type-interface-prerequisites
671 @section g-type-interface-prerequisites
673 @code{(g-type-interface-prerequisites type) @result{} types}
677 A GType designator of interface
679 A list of GType designators specifying the interface prerequisites
682 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
686 (g-type-interface-prerequisites "GtkCellEditable")
688 ("GtkObject" "GtkWidget")
691 @node Enum types information
692 @chapter Enum types information
700 Enum types have items that can be listed with @code{get-enum-items} function. This information is exposed within instances of @code{enum-item} structure.
702 Flags types (flags is a kind of enum whose values can be combined) have items that can be queried with @code{get-flags-items} function. This information is exposed within instances of @code{flags-item} structure.
713 A string - name of enum item
715 An integer - numeric value of enum item
717 A string - short name of an enum item
720 Structure @code{enum-item} represents a single item of an enumeration type.
724 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
730 (defstruct flags-item
736 A string - name of flags item
738 An integer - numeric value of flags item
740 A string - short name of an flags item
743 Structure @code{flags-item} represents a single item of an flags type.
748 :NAME "GDK_POINTER_MOTION_HINT_MASK"
750 :NICK "pointer-motion-hint-mask")
754 @section get-enum-items
756 @code{(get-enum-items type) @result{} items}
760 A GType designator of an enum type
762 A list of @code{enum-item} structures
765 Returns a list of items in an enumeration
769 (get-enum-items "GtkScrollType")
771 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
772 #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
773 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
774 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
775 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
776 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
777 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
778 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
779 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
780 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
781 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
782 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
783 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
784 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
785 #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
786 #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
789 @node get-flags-items
790 @section get-flags-items
792 @code{(get-flags-items type) @result{} items}
796 A GType designator of an flags type
798 A list of @code{flags-item} structures
801 Returns a list of items in an flags type
805 (get-flags-items "GtkAttachOptions")
807 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
808 #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
809 #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
813 @chapter Using GValues
822 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
824 CL-GTK2-GOBJECT works with GValue as a foreign type @code{g-value}. Functions @code{g-value-zero}, @code{g-value-type}, @code{g-value-init}, @code{parse-g-value}, @code{set-g-value} are used to inspect and assign GValues. @code{g-value} is a CFFI foreign type that is used by all these functions. Pointer to foreign instance of this type is passed to them.
826 GValue is used whenever a value of unkown type should be passed. It is used in:
828 @item Closure marshal functions
829 @item Property get and set functions
834 (cffi:with-foreign-object (gval 'g-value)
835 (set-g-value gval "Hello" "gchararray" :zero-g-value t)
836 (format t "~S~%" (parse-g-value gval))
837 (g-value-unset gval))
843 @section g-value-zero
844 @code{(g-value-zero g-value)}
847 A foreign pointer to GValue structure.
850 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
852 GValue value = @{ 0 @};
855 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).
858 @section g-value-init
860 @code{(g-value-init value type)}
863 A foreign pointer to GValue structure
868 Initializes the GValue to store instances of type @code{type}. Must be called before other functions operate on GValue (except @code{g-value-zero} and @code{set-g-value} with keyword argument @code{:g-value-init} set to true).
871 @section g-value-unset
872 @code{(g-value-unset value)}
875 A foreign pointer to GValue structure.
878 Unsets the GValue. This frees all resources associated with GValue.
881 @section parse-g-value
882 @code{(parse-g-value value) @result{} object}
885 A foreign pointer to GValue structure
890 Retrieves the object from GValue structure.
894 @code{(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))}
898 A foreign pointer to GValue structure
900 An object that is to be assigned to @code{gvalue}
902 A GType designator specifying what GType should be set
903 @item @var{unset-g-value}
904 A boolean specifying whether to call @code{g-value-unset} before assigment.
905 @item @var{zero-g-value}
906 A boolean specifying whether to call @code{g-value-zero} before assignment
907 @item @var{g-value-init}
908 A boolean specifying whether to call @code{g-value-init} before assignment
911 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
913 @node Stable pointers
914 @chapter Stable pointers
916 * allocate-stable-pointer::
917 * free-stable-pointer::
918 * stable-pointer-value::
919 * with-stable-pointer::
922 Sometimes it is necessary to pass arbitrary Lisp object to C code and then receive it back. Stable pointer serve to this purpose. Stable pointer is an integer (that is passed to C code as a @code{void*} pointer) that is created on Lisp side by call to @code{allocate-stable-pointer} and can be dereferenced by Lisp side at any time by calling @code{stable-pointer-value}. Stable pointer exists and does not change its value until explicitly freed by calling @code{free-stable-poitner}. Convenience macro @code{with-stable-pointer} binds the stable pointer for the duration of its body.
924 @node allocate-stable-pointer
925 @section allocate-stable-pointer
927 @code{(allocate-stable-pointer thing) @result{} stable-pointer}
931 An arbitrary Lisp object
932 @item @var{stable-pointer}
936 Allocates a stable pointer to @code{thing}.
938 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
942 (allocate-stable-pointer (lambda (x) (+ x 10)))
944 #.(SB-SYS:INT-SAP #X00000002)
946 (stable-pointer-value *)
948 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
950 (free-stable-pointer **)
955 @node free-stable-pointer
956 @section free-stable-pointer
958 @code{(free-stable-pointer stable-pointer)}
961 @item @var{stable-pointer}
962 A foreign pointer that was created with @code{allocate-stable-pointer}.
965 Frees the stable pointer, enabling the garbage collector to reclaim the object.
969 (allocate-stable-pointer (lambda (x) (+ x 10)))
971 #.(SB-SYS:INT-SAP #X00000002)
973 (stable-pointer-value *)
975 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
977 (free-stable-pointer **)
982 @node stable-pointer-value
983 @section stable-pointer-value
985 @code{(stable-pointer-value stable-pointer) @result{} thing}
987 @code{(setf (stable-pointer-value stable-pointer) thing)}
990 @item @var{stable-pointer}
991 A foreign pointer created by @code{allocate-stable-pointer}
996 Dereferences a @code{stable-pointer}, returning the stable pointer value. @code{stable-pointer-value} is a SETFable form, SETFing it sets the stable pointer's value to new value.
998 @node with-stable-pointer
999 @section with-stable-pointer
1001 @code{(with-stable-pointer (ptr expr) &body body)}
1005 A variable that will be bound to the stable pointer
1007 An expression that will be evaluated once and its value will be bound to stable pointer's value
1010 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1014 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1015 (print (stable-pointer-value ptr)))
1017 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1023 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).
1025 @section create-g-closure
1027 @node GObject low-level
1028 @chapter GObject low-level
1030 GObject low-level support includes facilities for working with objects as foreign pointers and using explicit function to get and set properties.
1032 Function @code{g-type-from-object} identifies the type of the object. Function @code{g-object-call-get-property} retrieves the value of the property and function @code{g-object-call-set-property} sets the value of the property. Function @code{g-object-call-constructor} calls the constructor of the GObject type.
1034 @section g-type-from-object
1036 @section g-object-call-get-property
1038 @section g-object-call-set-property
1040 @section g-object-call-constructor
1042 @node GObject high-level
1043 @chapter GObject high-level
1045 @node Subclassing GObjects and implementing GInterfaces
1046 @chapter Subclassing GObjects and implementing GInterfaces
1051 @node Generating type definitions by introspection
1052 @chapter Generating type definitions by introspection