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+
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
986 (stable-pointer-value stable-pointer) @result{} thing
987 (setf (stable-pointer-value stable-pointer) thing)
991 @item @var{stable-pointer}
992 A foreign pointer created by @code{allocate-stable-pointer}
997 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.
999 @node with-stable-pointer
1000 @section with-stable-pointer
1002 @code{(with-stable-pointer (ptr expr) &body body)}
1006 A variable that will be bound to the stable pointer
1008 An expression that will be evaluated once and its value will be bound to stable pointer's value
1011 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1015 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1016 (print (stable-pointer-value ptr)))
1018 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1024 Closure are anonymous functions that capture their lexical environment.
1026 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).
1028 @section create-g-closure
1029 @code{(create-g-closure fn) @result{} closure}
1033 A function that will be called by closure invokation
1035 A foreign pointer to allocated closure
1038 Allocates the closure. The closure is destroyed automatically by GObject.
1042 (create-g-closure (lambda (x) (+ x 10)))
1044 #.(SB-SYS:INT-SAP #X006D7B20)
1047 Example of usage from GObject binding code:
1049 (defun connect-signal (object signal handler &key after)
1050 (g-signal-connect-closure (ensure-object-pointer object)
1052 (create-g-closure handler)
1056 (TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
1058 @node GObject low-level
1059 @chapter GObject low-level
1061 * g-object-call-constructor::
1062 * g-type-from-object::
1063 * g-object-call-get-property::
1064 * g-object-call-set-property::
1067 GObject low-level support includes facilities for working with objects as foreign pointers and using explicit function to get and set properties. This low-level support does not deal with integration of GObject with CLOS; GObject high-level support does that.
1069 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.
1071 @node g-object-call-constructor
1072 @section g-object-call-constructor
1074 @code{(g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr}
1077 @item @var{object-type}
1078 A GType designator that specifies the object type that is to be created
1079 @item @var{args-names}
1080 A list of strings naming the arguments to constructor
1081 @item @var{args-value}
1082 A list of arguments values (in the same order as args-names)
1083 @item @var{args-types}
1084 Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
1085 @item @var{object-ptr}
1086 A foreign pointer to newly created instance
1089 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}.
1093 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1095 #.(SB-SYS:INT-SAP #X006D8900)
1097 (g-object-call-get-property * "label")
1101 (g-object-call-get-property ** "use-underline")
1106 @node g-type-from-object
1107 @section g-type-from-object
1109 @code{(g-type-from-object object-ptr) @result{} type}
1112 @item @var{object-ptr}
1113 A foreign pointer to a GObject instance
1118 Returns the type of an object by a pointer to its instance
1122 (g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
1127 @node g-object-call-get-property
1128 @section g-object-call-get-property
1130 @code{(g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value}
1133 @item @var{object-ptr}
1134 A foreign pointer to a GObject instance
1135 @item @var{property-name}
1136 A string naming the property
1137 @item @var{property-type}
1138 Optional GType designator specifying the type of a property
1139 @item @var{property-value}
1140 The value of a property
1143 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.
1147 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1149 #.(SB-SYS:INT-SAP #X006D8900)
1151 (g-object-call-get-property * "label")
1155 (g-object-call-get-property ** "use-underline")
1160 @node g-object-call-set-property
1161 @section g-object-call-set-property
1163 @code{(g-object-call-set-property object-ptr property-name new-value &optional property-type)}
1166 @item @var{object-ptr}
1167 A foreign pointer to a GObject instance
1168 @item @var{property-name}
1169 A string naming the property
1170 @item @var{new-value}
1171 A new value of a property
1172 @item @var{property-type}
1173 Optional GType designator specifying the type of a property
1176 Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
1180 (g-object-call-constructor "GtkButton" nil nil)
1182 #.(SB-SYS:INT-SAP #X006D8B40)
1184 (g-object-call-set-property * "label" "Hello")
1188 (g-object-call-get-property ** "label")
1193 @node GObject high-level
1194 @chapter GObject high-level
1196 * GObject metaclass::
1199 * GObject foreign class::
1202 GObject high-level support includes integration of GObject and CLOS systems. This enables to use GObjects classes as CLOS classes (with support from @code{gobject-class} metaclass):
1204 @item objects are created with @code{make-instance}
1205 @item properties are used as regular slots
1208 GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
1210 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.
1212 Example GObject class of definition:
1214 (defclass dialog (gtk-window atk-implementor-iface buildable)
1215 ((has-separator :accessor dialog-has-separator
1216 :initarg :has-separator
1217 :allocation :gobject-property
1218 :g-property-type "gboolean"
1219 :g-property-name "has-separator"))
1220 (:metaclass gobject-class)
1221 (:g-type-name . "GtkDialog")
1222 (:g-type-initializer . "gtk_dialog_get_type"))
1225 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.
1227 GObject does not expose objects methods. Because of this, methods are not automatically mapped to CLOS generic functions and methods. Methods should be manually wrapped with CFFI as foreign functions. Foreign type @code{g-object} aids in it. This type automatically wraps (and unwraps) the GObject class instances and handles the reference counting.
1229 GObject high-level support enables connect signals to signal handlers. Any function may be connected as a signal handler, and GObject will release the reference on signal handler whenever it become unneded (e.g., when object is destroyed or handler is disconnected).
1231 @node GObject metaclass
1232 @section GObject metaclass
1234 See MOP for information what metaclass is and why is it useful.
1236 GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
1238 Classes that correspond to GObject classes are instances of this class.
1240 This class has the following slots:
1242 @item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
1244 Specifies the name of GObject class
1245 @item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
1247 Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
1248 @item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
1251 This metaclass defines the GObject classes.
1253 Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. This metaclass defines the following attributes for slots:
1255 @item @var{:g-property-type}
1257 A name of a type of property
1258 @item @var{:g-property-name}
1260 A name of a property
1263 Initargs of a slot are used to construct the GObject class.
1267 (defclass dialog (gtk-window atk-implementor-iface buildable)
1268 ((has-separator :accessor dialog-has-separator
1269 :initarg :has-separator
1270 :allocation :gobject-property
1271 :g-property-type "gboolean"
1272 :g-property-name "has-separator"))
1273 (:metaclass gobject-class)
1274 (:g-type-name . "GtkDialog")
1275 (:g-type-initializer . "gtk_dialog_get_type"))
1277 (note the dot in @code{(:g-type-name . "GtkDialog")} and in @code{(:g-type-initializer . "gtk_dialog_get_type")}. It should be present)
1280 @section Using objects
1281 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.
1285 (make-instance 'gtk:dialog :has-separator t)
1287 #<GTK:DIALOG @{10036C5A71@}>
1289 (defvar *d* (make-instance 'gtk:dialog :has-separator t))
1293 (gtk:dialog-has-separator *d*)
1297 (setf (gtk:dialog-has-separator *d*) nil)
1301 (gtk:dialog-has-separator *d*)
1309 To connect handler to a signal, @code{connect-signal} function is used.
1311 @code{(connect-signal object signal handler &key after)}
1315 An instance of GObject object
1321 A boolean specifying whether the handler should be called after the default handler
1324 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.
1328 (defvar *d* (make-instance 'gtk:dialog))
1334 #<GTK:DIALOG @{1002D866F1@}>
1336 (parse-signal-name "GtkDialog" "response")
1338 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1340 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1342 (emit-signal *d* "response" 14)
1345 #<GTK:DIALOG @{1002D866F1@}>
1349 Function @code{emit-signal} is used to emit signals on objects.
1351 @code{(emit-signal object signal-name &rest args) @result{} return-value}
1355 An object on which the signal should be emitted
1356 @item @var{signal-name}
1357 A string naming the signal
1359 Arguments for a signal
1360 @item @var{return-value}
1361 Return value of a signal
1364 Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
1368 (defvar *d* (make-instance 'gtk:dialog))
1374 #<GTK:DIALOG @{1002D866F1@}>
1376 (parse-signal-name "GtkDialog" "response")
1378 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1380 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1382 (emit-signal *d* "response" 14)
1385 #<GTK:DIALOG @{1002D866F1@}>
1389 @node GObject foreign class
1390 @section GObject foreign class
1392 To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
1394 This type has the following syntax:
1395 @code{(g-object &optional type)} or @code{g-object}.
1397 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.
1399 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.
1401 This defines the function that may be called with instances of types @code{container} and @code{widget}:
1403 (defcfun (container-add "gtk_container_add") :void
1404 (container (g-object container))
1405 (widget (g-object widget)))
1407 (let ((window (make-instance 'gtk-window))
1408 (widget (make-instance 'button)))
1409 (container-add window widget))
1411 (@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
1413 This defines the function that returns an instance of GObject class:
1415 (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
1416 (bin (g-object bin)))
1418 (let ((window (make-instance 'gtk-window))
1419 (widget (make-instance 'button)))
1420 (container-add window widget)
1423 #<GTK:BUTTON @{1002DE74B1@}>
1426 @node Subclassing GObjects and implementing GInterfaces
1427 @chapter Subclassing GObjects and implementing GInterfaces
1432 @node Generating type definitions by introspection
1433 @chapter Generating type definitions by introspection