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 * Creating GObjects classes 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.
141 The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.
143 Please bear in mind that this is the documentation for a work-in-progress library and is a snapshot of current situation. API and functionality may (and will) change. Largely unfinished parts are working with GBoxed types, subclassing GObjects and implementing GInterfaces.
145 CL-GTK2-GObject is logically split into several layers:
147 @item FFI code. FFI (foreign functions interface) layer is a glue between Lisp code and @code{libglib}, @code{libgobject}, @code{libgthread}. This code includes basic wrapper around GType designator (it is used everywhere and should be defined first) and definitions of foreign structures and imports foreign functions.
148 @item Low-level GObject integration. These are facilities provided by GObject that capture specific aspects of type system, object system and cross-language runtime. This includes types information, GValues (generic containers for value of any type supported by GObject type system), closures, means to create and use objects. This layer also includes some non-GObject facilities: stable pointers.
149 @item High-level GObject integration. This layer includes support for interoperability between CLOS and GObject and automatic generation of corresponding definitions.
152 Naturally, users of CL-GTK2-GObject should use the high-level GObject integration, but occasionaly it may be necessary to use lower-level functionality.
155 @chapter Installation
157 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}.
159 To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.
161 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.
163 @node GType designator
164 @chapter GType designator
173 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.
175 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
177 Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
179 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
180 @item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
181 @item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
182 @item @code{+g-type-char+} ("gchar"). 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}.
183 @item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
184 @item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
185 @item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
186 @item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
187 @item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
188 @item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
189 @item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
190 @item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
191 @item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
192 @item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
193 @item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
194 @item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
195 @item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
196 @item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
197 @item @code{+g-type-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived.
198 @item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived.
199 @item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
202 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.
204 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
207 (g-type-numeric "GObject") @result{} 80
208 (g-type-numeric 80) @result{} 80
209 (g-type-string "GObject") @result{} "GObject"
210 (g-type-string 80) @result{} "GObject"
211 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
215 @section g-type-string
218 (g-type-string g-type-designator) @result{} name
222 @item @var{g-type-designator}
223 The GType designator for the GType
228 Returns the name of GType.
231 @section g-type-numeric
234 (g-type-numeric g-type-designator) @result{} GType
238 @item @var{g-type-designator}.
239 The GType designator for the GType.
241 The numeric identifier of GType
244 Returns the numeric identifier of GType
250 (g-type= type-1 type-2) @result{} eq
259 A boolean that is true if @code{type-1} and @code{type-2} designate the same type.
266 (g-type/= type-1 type-2) @result{} eq
275 A boolean that is true if @code{type-1} and @code{type-2} designate different types.
278 @node Type hierarchy and type relations
279 @chapter Type hierarchy and type relations
284 * g-type-fundamental::
289 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.
291 There are functions to query some specific information:
293 @item @code{g-type-fundamental} retrieves the fundamental type for given type
294 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
295 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
298 @node g-type-children
299 @section g-type-children
302 (g-type-children type) @result{} children
309 A list of GType designators
312 Returns the list of descendent types.
316 (g-type-children "GtkButton")
318 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
322 @section g-type-parent
325 (g-type-parent type) @result{} parent
335 Returns the parent of @code{type}.
339 (g-type-parent "GtkToggleButton")
344 @node g-type-fundamental
345 @section g-type-fundamental
348 (g-type-fundamental type) @result{} fundamental-type
354 @item @var{fundamental-type}
355 A GType designator for one of the fundamental types
358 Returns the fundamental type that is the ancestor of @code{type}.
362 (g-type-fundamental "GtkButton") @result{} "GObject"
364 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
366 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
370 @section g-type-depth
373 (g-type-depth type) @result{} depth
383 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.
387 (g-type-depth "GObject") @result{} 1
388 (g-type-depth "GInitiallyUnowned") @result{} 2
391 @node g-type-next-base
392 @section g-type-next-base
395 (g-type-next-base leaf-type root-type) @result{} base-type
399 @item @var{leaf-type}
401 @item @var{root-type}
403 @item @var{base-type}
407 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
424 the following will be returned:
427 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
428 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
429 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
430 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
431 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
434 @node Object types information
435 @chapter Object types information
437 * g-class-property-definition::
439 * class-property-info::
440 * interface-properties::
443 * parse-signal-name::
444 * query-signal-info::
445 * g-type-interfaces::
446 * g-type-interface-prerequisites::
449 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.
451 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.
453 @node g-class-property-definition
454 @section g-class-property-definition
457 (defstruct g-class-property-definition
469 A string that names the property
471 A GType designator. Identifies the type of the property
473 A boolean. Identifies whether the property can be read
475 A boolean. Identifies whether the property can be assigned
476 @item @var{constructor}
477 A boolean. Identifies whether constructor of object accepts this property
478 @item @var{constructor-only}
479 A boolean. Identifies whether this property may only be set in constructor, not in property setter
480 @item @var{owner-type}
481 A GType designator. Identifies the type on which the property was defined.
484 This structure identifies a single property. Its field specify attributes of a property.
486 Structures of this type have shortened print syntax:
488 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
491 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
493 This syntax specifies:
495 @item type of property
496 @item the owner type of property
497 @item name of property
498 @item additional flags of property
501 @node class-properties
502 @section class-properties
505 (class-properties type) @result{} properties
510 A GType designator. Specifies the object type (class)
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 class @code{type}.
519 (class-properties "GtkWidget")
521 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
522 #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
523 #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
524 #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
525 #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
526 #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
527 #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
528 #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
529 #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
530 #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
531 #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
532 #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
533 #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
534 #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
535 #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
536 #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
537 #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
538 #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
539 #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
540 #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
541 #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
542 #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
543 #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
546 @node class-property-info
547 @section class-property-info
549 (class-property-info type property-name) @result{} property
555 @item @var{property-name}
556 A string naming the property
558 An instance of @code{g-property-definition} structure
561 Returns the property information for a single property.
565 (class-property-info "GtkButton" "label")
567 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
570 @node interface-properties
571 @section interface-properties
574 (interface-properties type) @result{} properties
580 @item @var{properties}
581 A list of @code{g-property-definition} structures
584 This function returns the list of properties that are available in interface @code{type}.
588 (interface-properties "GtkFileChooser")
590 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
591 #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
592 #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
593 #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
594 #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
595 #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
596 #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
597 #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
598 #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
599 #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
600 #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
607 (defstruct signal-info
619 An integer - the identifier of a signal
622 @item @var{owner-type}
623 A GType designator identifying the type on which the signal was defined
625 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
626 @item @var{return-type}
627 The return type of a signal (and signal handlers)
628 @item @var{param-types}
629 A list of GType designators that specify the types of signal parameters
631 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
634 When @code{*print-readably*} is nil, the following print syntax is used:
636 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
637 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
638 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
639 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
642 This syntax specifies:
645 @item signal return type
649 @item list of types of parameters
654 @section type-signals
656 (type-signals type &key (include-inherited t)) @result{} signals
662 A list of @code{signal-info} structures
663 @item @var{include-inherited}
664 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
667 Returns the list of signals that are available in type @code{type}.
671 (type-signals "GtkLabel" :include-inherited nil)
673 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
674 #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
675 #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
678 @node parse-signal-name
679 @section parse-signal-name
682 (parse-signal-name type signal-name) @result{} signal
687 A GType designator that has the signal.
688 @item @var{signal-name}
689 A string that identifies the signal.
691 A list @code{signal-info} structures.
694 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
698 (parse-signal-name "GObject" "notify::label")
700 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
703 @node query-signal-info
704 @section query-signal-info
706 (query-signal-info signal-id) @result{} signal
709 @item @var{signal-id}
710 An integer identifying the signal
712 An instance of @code{signal-info} structure
715 Retrieves the signal information by its id.
719 (query-signal-info 73)
721 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
724 @node g-type-interfaces
725 @section g-type-interfaces
728 (g-type-interfaces type) @result{} interfaces
734 @item @var{interfaces}
735 A list of GType designators
738 Returns the list of interfaces that @code{type} implements.
742 (g-type-interfaces "GtkButton")
744 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
747 @node g-type-interface-prerequisites
748 @section g-type-interface-prerequisites
751 (g-type-interface-prerequisites type) @result{} types
756 A GType designator of interface
758 A list of GType designators specifying the interface prerequisites
761 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
765 (g-type-interface-prerequisites "GtkCellEditable")
767 ("GtkObject" "GtkWidget")
770 @node Enum types information
771 @chapter Enum types information
779 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.
781 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.
792 A string - name of enum item
794 An integer - numeric value of enum item
796 A string - short name of an enum item
799 Structure @code{enum-item} represents a single item of an enumeration type.
803 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
809 (defstruct flags-item
815 A string - name of flags item
817 An integer - numeric value of flags item
819 A string - short name of an flags item
822 Structure @code{flags-item} represents a single item of an flags type.
827 :NAME "GDK_POINTER_MOTION_HINT_MASK"
829 :NICK "pointer-motion-hint-mask")
833 @section get-enum-items
836 (get-enum-items type) @result{} items
841 A GType designator of an enum type
843 A list of @code{enum-item} structures
846 Returns a list of items in an enumeration
850 (get-enum-items "GtkScrollType")
852 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
853 #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
854 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
855 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
856 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
857 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
858 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
859 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
860 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
861 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
862 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
863 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
864 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
865 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
866 #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
867 #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
870 @node get-flags-items
871 @section get-flags-items
874 (get-flags-items type) @result{} items
879 A GType designator of an flags type
881 A list of @code{flags-item} structures
884 Returns a list of items in an flags type
888 (get-flags-items "GtkAttachOptions")
890 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
891 #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
892 #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
896 @chapter Using GValues
903 * Registering types::
906 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
908 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.
910 GValue is used whenever a value of unkown type should be passed. It is used in:
912 @item Closure marshal functions
913 @item Property get and set functions
918 (cffi:with-foreign-object (gval 'g-value)
919 (set-g-value gval "Hello" "gchararray" :zero-g-value t)
920 (format t "~S~%" (parse-g-value gval))
921 (g-value-unset gval))
927 @section g-value-zero
929 (g-value-zero g-value)
933 A foreign pointer to GValue structure.
936 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
938 GValue value = @{ 0 @};
941 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).
944 @section g-value-init
947 (g-value-init value type)
951 A foreign pointer to GValue structure
956 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).
959 @section g-value-unset
961 (g-value-unset value)
965 A foreign pointer to GValue structure.
968 Unsets the GValue. This frees all resources associated with GValue.
971 @section parse-g-value
973 (parse-g-value value) @result{} object
977 A foreign pointer to GValue structure
982 Retrieves the object from GValue structure.
987 (set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))
992 A foreign pointer to GValue structure
994 An object that is to be assigned to @code{gvalue}
996 A GType designator specifying what GType should be set
997 @item @var{unset-g-value}
998 A boolean specifying whether to call @code{g-value-unset} before assigment.
999 @item @var{zero-g-value}
1000 A boolean specifying whether to call @code{g-value-zero} before assignment
1001 @item @var{g-value-init}
1002 A boolean specifying whether to call @code{g-value-init} before assignment
1005 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
1007 @node Registering types
1008 @section Registering types
1010 In order to be able to parse GValues and set them, it is necessary for GValue binding to know type mapping between GObject types and Lisp types. Type registration serves to this purpose.
1012 GEnum and GFlags are mapped to CFFI @code{defcenum} and @code{defbitfield} types. Functions @code{register-enum-type} and @code{register-flags-type} add the type to the mapping.
1015 @code{(register-enum-type name type)}
1018 A string naming the GEnum type
1020 A symbol - name of CFFI foreign enum type
1023 Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
1027 (defcenum text-direction
1029 (register-enum-type "GtkTextDirection" 'text-direction)
1033 @code{(register-flags-type name type)}
1036 A string naming the GFlags type
1038 A symbol - name of CFFI foreign flags type
1041 Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
1045 (defcenum state-type
1046 :normal :active :prelight :selected :insensitive)
1047 (register-enum-type "GtkStateType" 'state-type)
1050 @node Stable pointers
1051 @chapter Stable pointers
1053 * allocate-stable-pointer::
1054 * free-stable-pointer::
1055 * stable-pointer-value::
1056 * with-stable-pointer::
1059 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.
1061 @node allocate-stable-pointer
1062 @section allocate-stable-pointer
1065 (allocate-stable-pointer thing) @result{} stable-pointer
1070 An arbitrary Lisp object
1071 @item @var{stable-pointer}
1075 Allocates a stable pointer to @code{thing}.
1077 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
1081 (allocate-stable-pointer (lambda (x) (+ x 10)))
1083 #.(SB-SYS:INT-SAP #X00000002)
1085 (stable-pointer-value *)
1087 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1089 (free-stable-pointer **)
1094 @node free-stable-pointer
1095 @section free-stable-pointer
1098 (free-stable-pointer stable-pointer)
1102 @item @var{stable-pointer}
1103 A foreign pointer that was created with @code{allocate-stable-pointer}.
1106 Frees the stable pointer, enabling the garbage collector to reclaim the object.
1110 (allocate-stable-pointer (lambda (x) (+ x 10)))
1112 #.(SB-SYS:INT-SAP #X00000002)
1114 (stable-pointer-value *)
1116 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1118 (free-stable-pointer **)
1123 @node stable-pointer-value
1124 @section stable-pointer-value
1127 (stable-pointer-value stable-pointer) @result{} thing
1128 (setf (stable-pointer-value stable-pointer) thing)
1132 @item @var{stable-pointer}
1133 A foreign pointer created by @code{allocate-stable-pointer}
1138 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.
1140 @node with-stable-pointer
1141 @section with-stable-pointer
1144 (with-stable-pointer (ptr expr) &body body)
1149 A variable that will be bound to the stable pointer
1151 An expression that will be evaluated once and its value will be bound to stable pointer's value
1154 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1158 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1159 (print (stable-pointer-value ptr)))
1161 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1167 Closure are anonymous functions that capture their lexical environment.
1169 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).
1171 @section create-g-closure
1172 @code{(create-g-closure fn) @result{} closure}
1176 A function that will be called by closure invokation
1178 A foreign pointer to allocated closure
1181 Allocates the closure. The closure is destroyed automatically by GObject.
1185 (create-g-closure (lambda (x) (+ x 10)))
1187 #.(SB-SYS:INT-SAP #X006D7B20)
1190 Example of usage from GObject binding code:
1192 (defun connect-signal (object signal handler &key after)
1193 (g-signal-connect-closure (ensure-object-pointer object)
1195 (create-g-closure handler)
1199 (TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
1201 @node GObject low-level
1202 @chapter GObject low-level
1204 * g-object-call-constructor::
1205 * g-type-from-object::
1206 * g-object-call-get-property::
1207 * g-object-call-set-property::
1210 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.
1212 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.
1214 @node g-object-call-constructor
1215 @section g-object-call-constructor
1218 (g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr
1222 @item @var{object-type}
1223 A GType designator that specifies the object type that is to be created
1224 @item @var{args-names}
1225 A list of strings naming the arguments to constructor
1226 @item @var{args-value}
1227 A list of arguments values (in the same order as args-names)
1228 @item @var{args-types}
1229 Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
1230 @item @var{object-ptr}
1231 A foreign pointer to newly created instance
1234 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}.
1238 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1240 #.(SB-SYS:INT-SAP #X006D8900)
1242 (g-object-call-get-property * "label")
1246 (g-object-call-get-property ** "use-underline")
1251 @node g-type-from-object
1252 @section g-type-from-object
1255 (g-type-from-object object-ptr) @result{} type
1259 @item @var{object-ptr}
1260 A foreign pointer to a GObject instance
1265 Returns the type of an object by a pointer to its instance
1269 (g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
1274 @node g-object-call-get-property
1275 @section g-object-call-get-property
1278 (g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value
1282 @item @var{object-ptr}
1283 A foreign pointer to a GObject instance
1284 @item @var{property-name}
1285 A string naming the property
1286 @item @var{property-type}
1287 Optional GType designator specifying the type of a property
1288 @item @var{property-value}
1289 The value of a property
1292 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.
1296 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1298 #.(SB-SYS:INT-SAP #X006D8900)
1300 (g-object-call-get-property * "label")
1304 (g-object-call-get-property ** "use-underline")
1309 @node g-object-call-set-property
1310 @section g-object-call-set-property
1313 (g-object-call-set-property object-ptr property-name new-value &optional property-type)
1317 @item @var{object-ptr}
1318 A foreign pointer to a GObject instance
1319 @item @var{property-name}
1320 A string naming the property
1321 @item @var{new-value}
1322 A new value of a property
1323 @item @var{property-type}
1324 Optional GType designator specifying the type of a property
1327 Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
1331 (g-object-call-constructor "GtkButton" nil nil)
1333 #.(SB-SYS:INT-SAP #X006D8B40)
1335 (g-object-call-set-property * "label" "Hello")
1339 (g-object-call-get-property ** "label")
1344 @node GObject high-level
1345 @chapter GObject high-level
1347 * GObject metaclass::
1350 * GObject foreign class::
1353 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):
1355 @item objects are created with @code{make-instance}
1356 @item properties are used as regular slots
1359 GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
1361 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.
1363 Example GObject class of definition:
1365 (defclass dialog (gtk-window atk-implementor-iface buildable)
1366 ((has-separator :accessor dialog-has-separator
1367 :initarg :has-separator
1368 :allocation :gobject-property
1369 :g-property-type "gboolean"
1370 :g-property-name "has-separator"))
1371 (:metaclass gobject-class)
1372 (:g-type-name . "GtkDialog")
1373 (:g-type-initializer . "gtk_dialog_get_type"))
1376 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.
1378 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.
1380 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).
1382 @node GObject metaclass
1383 @section GObject metaclass
1385 See MOP for information what metaclass is and why is it useful.
1387 GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
1389 Classes that correspond to GObject classes are instances of this class.
1391 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}.
1393 This class has the following slots:
1395 @item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
1397 Specifies the name of GObject class
1398 @item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
1400 Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
1401 @item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
1403 A boolean specifying whether this CLOS class corresponds to GInterface.
1406 This metaclass defines the GObject classes.
1408 Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
1410 @item @var{:g-property-type}
1412 A string naming GType of property
1413 @item @var{:g-property-name}
1415 A name of a property
1418 Slots which have @code{:allocation} of @code{:gobject-fn} are mapped to a pair of accessor functions (usually named @code{class_get_property} and @code{class_set_property}). This is included because some properties are not exposed as GObject properties. Such slots have following attributes:
1420 @item @var{:g-property-type}
1421 A CFFI foreign type of property
1422 @item @var{:g-getter}
1423 A string naming foreign getter function of a property or a symbol designating Lisp getter function. Foreign getter function should have signature @code{type class_get_property(object *)}. Lisp function should be of type @code{(function (class) type)}.
1424 @item @var{:g-setter}
1425 A string naming foreign setter function of a property or a symbol designating Lisp setter function. Foreign setter function should have signature @code{void class_set_property(object *, type)}. Lisp function should be of type @code{(function (class type))}.
1428 Initargs of a slot are used to construct the GObject class.
1432 (defclass container (widget atk-implementor-iface buildable)
1433 ((border-width :allocation :gobject-property
1434 :g-property-type "guint"
1435 :accessor container-border-width
1436 :initarg :border-width
1437 :g-property-name "border-width")
1438 (resize-mode :allocation :gobject-property
1439 :g-property-type "GtkResizeMode"
1440 :accessor container-resize-mode
1441 :initarg :resize-mode
1442 :g-property-name "resize-mode")
1443 (child :allocation :gobject-property
1444 :g-property-type "GtkWidget"
1445 :accessor container-child
1447 :g-property-name "child")
1448 (focus-child :allocation :gobject-fn
1449 :g-property-type g-object
1450 :accessor container-focus-child
1451 :initarg :focus-child
1452 :g-getter "gtk_container_get_focus_child"
1453 :g-setter "gtk_container_set_focus_child")
1454 (focus-vadjustment :allocation :gobject-fn
1455 :g-property-type (g-object adjustment)
1456 :accessor container-focus-vadjustment
1457 :initarg :focus-vadjustment
1458 :g-getter "gtk_container_get_focus_vadjustment"
1459 :g-setter "gtk_container_set_focus_vadjustment")
1460 (focus-hadjustment :allocation :gobject-fn
1461 :g-property-type (g-object adjustment)
1462 :accessor container-focus-hadjustment
1463 :initarg :focus-hadjustment
1464 :g-getter "gtk_container_get_focus_hadjustment"
1465 :g-setter "gtk_container_set_focus_hadjustment"))
1466 (:metaclass gobject-class)
1467 (:g-type-name . "GtkContainer")
1468 (:g-type-initializer . "gtk_container_get_type"))
1470 (note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)
1473 @section Using objects
1474 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.
1478 (make-instance 'gtk:dialog :has-separator t)
1480 #<GTK:DIALOG @{10036C5A71@}>
1482 (defvar *d* (make-instance 'gtk:dialog :has-separator t))
1486 (gtk:dialog-has-separator *d*)
1490 (setf (gtk:dialog-has-separator *d*) nil)
1494 (gtk:dialog-has-separator *d*)
1502 To connect handler to a signal, @code{connect-signal} function is used.
1504 @code{(connect-signal object signal handler &key after)}
1508 An instance of GObject object
1514 A boolean specifying whether the handler should be called after the default handler
1517 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.
1521 (defvar *d* (make-instance 'gtk:dialog))
1527 #<GTK:DIALOG @{1002D866F1@}>
1529 (parse-signal-name "GtkDialog" "response")
1531 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1533 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1535 (emit-signal *d* "response" 14)
1538 #<GTK:DIALOG @{1002D866F1@}>
1542 Function @code{emit-signal} is used to emit signals on objects.
1544 @code{(emit-signal object signal-name &rest args) @result{} return-value}
1548 An object on which the signal should be emitted
1549 @item @var{signal-name}
1550 A string naming the signal
1552 Arguments for a signal
1553 @item @var{return-value}
1554 Return value of a signal
1557 Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
1561 (defvar *d* (make-instance 'gtk:dialog))
1567 #<GTK:DIALOG @{1002D866F1@}>
1569 (parse-signal-name "GtkDialog" "response")
1571 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1573 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1575 (emit-signal *d* "response" 14)
1578 #<GTK:DIALOG @{1002D866F1@}>
1582 @node GObject foreign class
1583 @section GObject foreign class
1585 To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
1587 This type has the following syntax:
1588 @code{(g-object &optional type)} or @code{g-object}.
1590 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.
1592 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.
1594 This defines the function that may be called with instances of types @code{container} and @code{widget}:
1596 (defcfun (container-add "gtk_container_add") :void
1597 (container (g-object container))
1598 (widget (g-object widget)))
1600 (let ((window (make-instance 'gtk-window))
1601 (widget (make-instance 'button)))
1602 (container-add window widget))
1604 (@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
1606 This defines the function that returns an instance of GObject class:
1608 (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
1609 (bin (g-object bin)))
1611 (let ((window (make-instance 'gtk-window))
1612 (widget (make-instance 'button)))
1613 (container-add window widget)
1616 #<GTK:BUTTON @{1002DE74B1@}>
1619 @node Creating GObjects classes and implementing GInterfaces
1620 @chapter Creating GObjects classes and implementing GInterfaces
1624 * register-object-type-implementation::
1627 Creating GObject classes from Lisp is the most complex part of GObject binding.
1629 GObject binding at the moment provides only limited scenarios of creating GObject classes. It lets register GObject class (as a subclass of another class or of GObject), specify its properties and implemented interfaces. Each property is associated with Lisp getter and setter functions. Each interface is associated wth vtable (table of virtual function pointers, see @uref{http://en.wikipedia.org/wiki/Vtable}) that specifies a list of methods and their signatures. If class is ever created from GObject side (not from Lisp side, must be constructable with no parameters).
1631 Each virtual function is mapped to a generic function for which class should provide a specialized method. This function should not be called by user. Rather, user code should call corresponding foreign function.
1633 Practically speaking, creating GObject class requires defining CLOS class that correspond to GObject class and calling @code{register-object-type-implementation} with information about the class (its GType name, superclass, interfaces and properties).
1635 Interface that is implemented by a class should have its vtable defined by @code{define-vtable}. Vtable definitions consists of a list of functions's names and signatures and their locations in vtable.
1637 Unfortunately, GObject does not provide information about vtables, and does not support using GClosures to implement virtual functions. Therefore, implementation for all interface's functions are defined as CFFI foreign callbacks. These callbacks in turn call corresponding generic functions that should be specialized on required objects.
1640 @section define-vtable
1643 (define-vtable (type-name cstruct-name)
1646 item ::= (name callback-name return-type &rest arg*)
1647 item ::= (:skip cffi-structure-item)
1648 arg ::= (arg-name arg-type)
1652 @item @var{type-name}
1653 A string naming the GObject type of interface
1654 @item @var{cstruct-name}
1655 A name for a generated CFFI foreign structure
1657 A name for implementation generic function
1658 @item @var{callback-name}
1659 A name for generated callback function
1660 @item @var{return-type}
1661 A CFFI specifier for foreign function return type
1662 @item @var{arg-name}
1663 A symbol naming the argument of interface method
1664 @item @var{arg-type}
1665 A CFFI specifier for foreign function argument type
1668 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.
1672 (define-vtable ("GtkTreeModel" c-gtk-tree-model)
1673 (:skip parent-instance g-type-interface)
1675 (:skip tree-model-row-changed :pointer)
1676 (:skip tree-model-row-inserted :pointer)
1677 (:skip tree-model-row-has-child-toggled :pointer)
1678 (:skip tree-model-row-deleted :pointer)
1679 (:skip tree-model-rows-reordered :pointer)
1681 (tree-model-get-flags-impl tree-model-get-flags-cb
1682 tree-model-flags (tree-model g-object))
1683 (tree-model-get-n-columns-impl tree-model-get-n-columns-cb
1684 :int (tree-model g-object))
1685 (tree-model-get-column-type-impl tree-model-get-column-type-cb
1686 g-type (tree-model g-object) (index :int))
1687 (tree-model-get-iter-impl tree-model-get-iter-cb
1688 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)) (path (g-boxed-ref tree-path)))
1689 (tree-model-get-path-impl tree-model-get-path-cb
1690 (g-boxed-ref tree-path) (tree-model g-object) (iter (g-boxed-ref tree-iter)))
1691 (tree-model-get-value-impl tree-model-get-value-cb
1692 :void (tree-model g-object) (iter (g-boxed-ref tree-iter)) (n :int) (value (:pointer g-value)))
1693 (tree-model-iter-next-impl tree-model-iter-next-cb
1694 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)))
1695 (tree-model-iter-children-impl tree-model-iter-children-cb
1696 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)) (parent (g-boxed-ref tree-iter)))
1697 (tree-model-iter-has-child-impl tree-model-iter-has-child-cb
1698 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)))
1699 (tree-model-iter-n-children-impl tree-model-iter-n-children-cb
1700 :int (tree-model g-object) (iter (g-boxed-ref tree-iter)))
1701 (tree-model-iter-nth-child-impl tree-model-iter-nth-child-cb
1702 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)) (parent (g-boxed-ref tree-iter)) (n :int))
1703 (tree-model-iter-parent-impl tree-model-iter-parent-cb
1704 :boolean (tree-model g-object) (iter (g-boxed-ref tree-iter)) (child (g-boxed-ref tree-iter)))
1705 (tree-model-ref-node-impl tree-model-ref-node-cb
1706 :void (tree-model g-object) (iter (g-boxed-ref tree-iter)))
1707 (tree-model-unref-node-impl tree-model-unref-node-cb
1708 :void (tree-model g-object) (iter (g-boxed-ref tree-iter))))
1711 @node register-object-type-implementation
1712 @section register-object-type-implementation
1715 (register-object-type-implementation name class parent interfaces properties)
1720 A string naming the new GObject class.
1722 A class name of corresponding CLOS class. It should be inherited from @code{g-object} or its descendants.
1724 A string naming the GObject superclass
1725 @item @var{interfaces}
1726 A list of names of interfaces that this class implements.
1727 @item @var{properties}
1728 A list of properties that this class provides.
1729 Each property is defined as
1731 property ::= (property-name property-type accessor property-get-fn property-set-fn)
1735 A macro that creates a new GObject type and registers the Lisp implementation for it.
1739 (register-object-type-implementation "LispArrayListStore" array-list-store "GObject" ("GtkTreeModel") nil)
1745 * define-g-boxed-class::
1746 * define-g-boxed-ref::
1749 GObject manual defines this type in the following way:
1751 ``GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.
1753 Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries.''
1755 Naturally, it is quite hard to provide support for such structures. At the moment, support for GBoxed is pretty bad.
1757 Basically, two use cases of GBoxed structures are provided:
1759 @item structure is mapped to Lisp structure defined with @code{defstruct}. This is complex scenario and it supports inheritance between structure. Its main use is to define the @code{GdkEvent} structure wrapper. Macro @code{define-g-boxed-class} supports this use case.
1760 @item structure is mapped to Lisp wrapper that contains pointer to structure and provides accessor functions (by calling foreign function or calling Lisp function). Macro @code{define-g-boxed-ref} supports this use case.
1763 In both scenarios, foreign functions and GValue type registrations are provided that provide wrapping and unwrapping behaivour (it yet remains to be proven that the behaviour is correct in all cases with regard to issues of memory management, ownership, lifetime). In both cases it is possible to pass the structure by reference, allowing the foreign function (or the callback code) to change the contents of GBoxed.
1765 It is expected that the support for GBoxed structures will be improved.
1767 @node define-g-boxed-class
1768 @section define-g-boxed-class
1771 (define-g-boxed-class g-name-and-c-name name (&optional superclass-and-dispatch (export t))
1774 g-name-and-c-name ::= nil
1775 g-name-and-c-name ::= (g-name c-name)
1776 superclass-and-dispatch ::= (&optional superclass dispatch-slot dispatch-values)
1777 slot ::= slot-name slot-type &key initform parser unparser
1782 A string naming the type of this GBoxed; for inherited classes, it should be @code{NIL}
1784 A symbol naming the generated CFFI foreign structure definition corresponding to this GBoxed. This name should not conflict with other CFFI types.
1786 A symbol naming the Lisp structure that will be generated
1787 @item @var{superclass}
1788 A symbol naming the structure defined with @code{define-g-boxed-class} that is the superclass of this structure
1789 @item @var{dispatch-slot}
1790 A slot of the superclass structure that identifies the specific type of structure (``discriminator'')
1791 @item @var{dispatch-values}
1792 A value or a list of values of the @code{dispatch-slot} that correspond to this GBoxed class
1793 @item @var{slot-name}
1795 @item @var{slot-type}
1796 CFFI foreign type of a slot
1797 @item @var{initform}
1798 An optional initform for @code{defstruct} slot
1800 An optional parser function designator for slot. Parser function is called to get the value for slot when the GBoxed is passed to Lisp with the following arguments: @code{(name pointer)} where the @code{name} is the name of a structure being defined and the @code{pointer} is a foreign pointer to the C structure.
1801 @item @var{unparser}
1802 An optional unparser function designator for a slot. Unparser function is called to write the slot value to GBoxed structure. It is called with arguments @code{(name pointer object)} where @code{name} is the name of a structure being defined, @code{pointer} is the pointer to the C structure and the @code{object} is object whose slot value should be written to structure.
1805 Defines the @code{defstruct} wrapper for GBoxed type. Various parameters control how the structure is converted between C and Lisp representations.
1807 @code{define-g-boxed-class} supports basic single inheritance. This is provided to support ``generic'' C structures like @code{GdkEvent} that contain a ``type'' field and a @code{union} of other substructures. The natural mapping of such structure to Lisp is not one, but several structures that are inherited one from another. This supports e.g. method dispatching on @code{GdkEvent} types (if it is ever necessary).
1809 The only use of @code{define-g-boxed-class} that involves inheritance is the @code{GdkEvent} structure. It is defined as follows.
1811 (define-g-boxed-class ("GdkEvent" event-struct) event ()
1813 (window (g-object gdk-window))
1814 (send-event (:boolean :int8)))
1816 (define-g-boxed-class nil event-key ((event type (:key-press :key-release)))
1818 (state modifier-type)
1821 (string (:string :free-from-foreign nil :free-to-foreign nil))
1822 (hardware-keycode :uint16)
1824 (is-modifier :uint))
1826 (define-g-boxed-class nil event-button ((event type (:button-press :2button-press :3button-press :button-release)))
1830 (axes (fixed-array :double 2))
1833 (device (g-object device))
1838 Some simpler uses include following examples:
1840 (define-g-boxed-class "GdkFont" font ()
1841 (type font-type :initform :font)
1842 (ascent :int :initform 0)
1843 (descent :int :initform 0))
1845 (define-g-boxed-class "GdkColor" color ()
1846 (pixel :uint32 :initform 0)
1847 (red :uint16 :initform 0)
1848 (green :uint16 :initform 0)
1849 (blue :uint16 :initform 0))
1851 (define-g-boxed-class "GdkGeometry" geometry ()
1852 (min-width :int :initform 0)
1853 (min-height :int :initform 0)
1854 (max-width :int :initform 0)
1855 (max-height :int :initform 0)
1856 (base-width :int :initform 0)
1857 (base-height :int :initform 0)
1858 (width-increment :int :initform 0)
1859 (height-increment :int :initform 0)
1860 (min-aspect :double :initform 0.0d0)
1861 (max-aspect :double :initform 0.0d0)
1862 (gravity gravity :initform :north-west))
1865 @node define-g-boxed-ref
1866 @section define-g-boxed-ref
1868 @code{g-boxed-ref} class is defined:
1870 (defclass g-boxed-ref ()
1871 ((pointer :accessor pointer :initarg :pointer)))
1874 This class holds the pointer to structure. GBoxed-ref types are subclasses of this class.
1877 (define-g-boxed-ref g-name name
1880 property ::= (:free-function free-function)
1881 property ::= (:alloc-function alloc-function)
1882 property ::= (:slots &rest slot*)
1883 slot ::= (slot-name &key reader writer type (accessor slot-name))
1888 A string that names the GBoxed type
1890 A symbol that is the name for generated class
1891 @item @var{free-function}
1892 Mandatory designator for a function that frees the allocated object. This function accepts a single argument - CFFI foreign pointer.
1893 @item @var{alloc-function}
1894 Mandatory designator for a function that allocates the object. This function accepts zero arguments and returns CFFI foreign pointer to fresh object.
1895 @item @var{slot-name}
1896 A symbol naming the slot
1898 A CFFI foreign type of a slot
1900 @code{NIL} or a string or a function designator. If it is @code{NIL} the the slot is not readable. If it is a string then it names the C function that accepts the pointer to structure and returns the value of a slot of specified CFFI type. If it is a function designator that it designates a function that accepts the Lisp object and returns its slot value.
1902 @code{NIL} or string or a function designator. If it is a @code{NIL} then the slot is not writable. If it is a string then it names the C function that accepts the pointer to C structure and a value (of specified CFFI type) and assigns it to the slot of a structure. If it is a function designator then it specifies a function that accepts the new slot value and a Lisp object and assigns it to the slot.
1903 @item @var{accessor}
1904 A symbol namin the accessor function for slot.
1907 Defines a class corresponding to GBoxed type that is passed by reference (e.g., @code{GtkTextIter}). Class is made a subclass of @code{g-boxed-ref}.
1909 The memory occupied by this class is managed automatically: after the GC collects the Lisp instance, @code{free-function} is used to free the structure (if the instance was created by lisp code).
1913 (defcstruct tree-iter
1915 (user-data :pointer)
1916 (user-data-2 :pointer)
1917 (user-data-3 :pointer))
1919 (defun tree-iter-get-stamp (i) (foreign-slot-value (pointer i) 'tree-iter 'stamp))
1920 (defun tree-iter-set-stamp (value i) (setf (foreign-slot-value (pointer i) 'tree-iter 'stamp) value))
1921 (defun tree-iter-get-user-data (i) (pointer-address (foreign-slot-value (pointer i) 'tree-iter 'user-data)))
1922 (defun tree-iter-set-user-data (value i) (setf (foreign-slot-value (pointer i) 'tree-iter 'user-data) (make-pointer value)))
1924 (defun tree-iter-alloc () (glib:g-malloc (foreign-type-size 'tree-iter)))
1925 (defun tree-iter-free (v) (glib:g-free v))
1927 (define-g-boxed-ref "GtkTreeIter" tree-iter
1928 (:slots (stamp :reader tree-iter-get-stamp :writer tree-iter-set-stamp :accessor tree-iter-stamp)
1929 (user-data :reader tree-iter-get-user-data :writer tree-iter-set-user-data :accessor tree-iter-user-data))
1930 (:alloc-function tree-iter-alloc)
1931 (:free-function tree-iter-free))
1936 (define-foreign-type unichar ()
1938 (:actual-type :uint32)
1939 (:simple-parser unichar))
1941 (defmethod translate-from-foreign (value (type unichar))
1944 (defmethod translate-to-foreign (value (type unichar))
1947 (define-g-boxed-ref "GtkTextIter" text-iter
1948 (:free-function gtk-text-iter-free)
1949 (:alloc-function gtk-text-iter-alloc)
1950 (:slots (text-iter-buffer :reader "gtk_text_iter_get_buffer" :type (g-object text-buffer))
1951 (text-iter-offset :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
1952 (text-iter-line :reader "gtk_text_iter_get_line" :writer "gtk_text_iter_set_line" :type :int)
1953 (text-iter-line-offset :reader "gtk_text_iter_get_line_offset" :writer "gtk_text_iter_set_line_offset" :type :int)
1954 (text-iter-visible-line-offset :reader "gtk_text_iter_get_visible_line_offset" :writer "gtk_text_iter_set_visible_line_offset" :type :int)
1955 (text-iter-char :reader "gtk_text_iter_get_char" :type unichar)
1956 (text-iter-pixbuf :reader "gtk_text_iter_get_pixbuf" :type (g-object pixbuf))
1957 (text-iter-marks :reader "gtk_text_iter_get_marks" :type (gslist (g-object text-mark) :free-from-foreign t))
1958 (text-iter-child-anchor :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))
1959 (text-iter-tags :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))
1960 (text-iter-chars-in-line :reader "gtk_text_iter_get_chars_in_line" :type :int)
1961 (text-iter-language :reader "gtk_text_iter_get_language" :type :pointer)
1962 (text-iter-is-end :reader "gtk_text_iter_is_end" :type :boolean)
1963 (text-iter-is-start :reader "gtk_text_iter_is_start" :type :boolean)
1964 (text-iter-can-insert :reader "gtk_text_iter_can_insert" :type :boolean)
1965 (text-iter-starts-word :reader "gtk_text_iter_starts_word" :type :boolean)
1966 (text-iter-ends-word :reader "gtk_text_iter_ends_word" :type :boolean)
1967 (text-iter-inside-word :reader "gtk_text_iter_inside_word" :type :boolean)
1968 (text-iter-starts-line :reader "gtk_text_iter_starts_line" :type :boolean)
1969 (text-iter-ends-line :reader "gtk_text_iter_ends_line" :type :boolean)
1970 (text-iter-starts-sentence :reader "gtk_text_iter_starts_sentence" :type :boolean)
1971 (text-iter-ends-sentence :reader "gtk_text_iter_ends_sentence" :type :boolean)
1972 (text-iter-inside-sentence :reader "gtk_text_iter_inside_sentence" :type :boolean)
1973 (text-iter-is-cursor-position :reader "gtk_text_iter_is_cursor_position" :type :boolean)))
1975 (defcstruct %text-iter
1991 (defcfun gtk-text-iter-copy :pointer
1994 (defcfun gtk-text-iter-free :void
1997 (defun gtk-text-iter-alloc ()
1998 (with-foreign-object (iter '%text-iter)
1999 (gtk-text-iter-copy iter)))
2002 @node Generating type definitions by introspection
2003 @chapter Generating type definitions by introspection
2005 * define-g-object-class::
2006 * define-g-interface::
2009 * get-g-enum-definition::
2010 * get-g-flags-definition::
2011 * get-g-interface-definition::
2012 * get-g-class-definition::
2013 * Specifying additional properties for CLOS classes::
2014 * Generating names for CLOS classes and accessors::
2015 * generate-types-hierarchy-to-file::
2018 CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.
2020 @node define-g-object-class
2021 @section define-g-object-class
2024 (define-g-object-class g-type-name name
2025 (&key (superclass 'g-object) (export t) interfaces type-initializer)
2028 property ::= (name accessor gname type readable writable)
2029 property ::= (:cffi name acessor type reader writer)
2032 Parameters of @code{define-g-object-class}
2034 @item @var{superclass}
2035 A symbol naming the superclass of this class
2037 Whether to export the name of the class and names of autogenerated properties names from the current package.
2038 @item @var{interfaces}
2039 A list of interfaces the this class implements
2040 @item @var{type-initializer}
2041 A string naming the type initiliazer function. It is usually named @code{class_get_type}.
2042 @item @var{properties}
2043 A list of slots of a class
2046 Parameters of @code{property}:
2049 A symbol naming the slot
2050 @item @var{accessor}
2051 A symbol naming the accessor function for this slot
2053 A string naming the property of GObject
2055 A string naming the type of property of GObject (for GObject properties); or a symbol naming CFFI foreign type (for slots mapped to foreign accessors)
2056 @item @var{readable}
2057 A boolean specifying whether the slot can be read
2058 @item @var{writable}
2059 A boolean specifying whether the slot can be assigned to
2061 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2063 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2066 Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.
2070 (define-g-object-class "GtkContainer" container
2071 (:superclass widget :export t :interfaces
2072 ("AtkImplementorIface" "GtkBuildable")
2073 :type-initializer "gtk_container_get_type")
2074 ((border-width container-border-width "border-width" "guint" t t)
2075 (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
2076 (child container-child "child" "GtkWidget" nil t)
2077 (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
2078 (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
2079 (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
2082 @node define-g-interface
2083 @section define-g-interface
2086 (define-g-interface g-type-name name (&key (export t) type-initializer)
2089 property ::= (name accessor gname type readable writable)
2090 property ::= (:cffi name acessor type reader writer)
2093 Parameters of @code{define-g-interface}
2096 Whether to export the name of the interface and names of autogenerated properties names from the current package.
2097 @item @var{type-initializer}
2098 A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
2099 @item @var{properties}
2100 A list of slots of a interface
2103 Parameters of @code{property}:
2106 A symbol naming the slot
2107 @item @var{accessor}
2108 A symbol naming the accessor function for this slot
2110 A string naming the property of GObject
2112 A string naming the type of property of GObject (for GObject properties); or a symbol naming CFFI foreign type (for slots mapped to foreign accessors)
2113 @item @var{readable}
2114 A boolean specifying whether the slot can be read
2115 @item @var{writable}
2116 A boolean specifying whether the slot can be assigned to
2118 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2120 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2123 Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.
2127 (define-g-interface "GtkFileChooser" file-chooser
2128 (:export t :type-initializer "gtk_file_chooser_get_type")
2129 (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
2130 (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
2131 (filter file-chooser-filter "filter" "GtkFileFilter" t t)
2132 (local-only file-chooser-local-only "local-only" "gboolean" t t)
2133 (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
2134 (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
2135 (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
2136 (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
2137 (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
2138 (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
2139 (action file-chooser-action "action" "GtkFileChooserAction" t t)
2140 (:cffi current-name file-chooser-current-name
2141 (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
2142 (:cffi filename file-chooser-filename
2143 (g-string :free-from-foreign t :free-to-foreign t)
2144 "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
2145 (:cffi current-folder file-chooser-current-folder
2146 (g-string :free-from-foreign t :free-to-foreign t)
2147 "gtk_file_chooser_get_current_folder"
2148 "gtk_file_chooser_set_current_folder")
2149 (:cffi uri file-chooser-uri
2150 (g-string :free-from-foreign t :free-to-foreign t)
2151 "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
2152 (:cffi current-folder-uri file-chooser-current-folder-uri
2153 (g-string :free-from-foreign t :free-to-foreign t)
2154 "gtk_file_chooser_get_current_folder_uri"
2155 "gtk_file_chooser_set_current_folder_uri")
2156 (:cffi preview-filename file-chooser-preview-filename
2157 (g-string :free-from-foreign t :free-to-foreign t)
2158 "gtk_file_chooser_get_preview_filename" nil)
2159 (:cffi preview-uri file-chooser-preview-uri
2160 (g-string :free-from-foreign t :free-to-foreign t)
2161 "gtk_file_chooser_get_preview_uri" nil))
2165 @section define-g-enum
2168 (define-g-enum g-name name (&key (export t) type-initializer) &body value*)
2171 value ::= (:keyword integer)
2176 A string naming the GEnum type
2178 A symbol naming the CFFI enumeration type
2180 A boolean indicating whether to export @code{name}
2181 @item @var{type-initializer}
2182 A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
2185 Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
2189 (define-g-enum "GtkTextDirection" text-direction
2190 (:export t :type-initializer "gtk_text_direction_get_type")
2191 (:none 0) (:ltr 1) (:rtl 2))
2193 (define-g-enum "GtkSizeGroupMode" size-group-mode
2194 (:export t :type-initializer "gtk_size_group_mode_get_type")
2195 :none :horizontal :vertical :both)
2198 @node define-g-flags
2199 @section define-g-flags
2202 (define-g-flags g-name name (&key (export t) type-initializer) &body value*)
2205 value ::= (:keyword integer)
2210 A string naming the GFlags type
2212 A symbol naming the CFFI flags type
2214 A boolean indicating whether to export @code{name}
2215 @item @var{type-initializer}
2216 A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
2219 Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
2223 (define-g-flags "GtkAttachOptions" attach-options
2224 (:export t :type-initializer "gtk_attach_options_get_type")
2225 (:expand 1) (:shrink 2) (:fill 4))
2227 (define-g-flags "GtkButtonAction" button-action
2228 (:export t :type-initializer "gtk_button_action_get_type")
2229 :ignored :selects :drags :expands)
2232 @node get-g-enum-definition
2233 @section get-g-enum-definition
2236 (get-g-enum-definition type &optional lisp-name-package) @result{} definition
2241 A string naming the GEnum type
2242 @item @var{lisp-name-package}
2243 A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
2244 @item @var{definition}
2245 A Lisp form that when evaluated defines the GEnum.
2248 Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.
2250 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2254 (get-g-enum-definition "GtkDirectionType")
2256 (DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
2257 (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
2258 (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
2262 @node get-g-flags-definition
2263 @section get-g-flags-definition
2266 (get-g-flags-definition type &optional lisp-name-package) @result{} definition
2271 A string naming the GFlags type
2272 @item @var{lisp-name-package}
2273 A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
2274 @item @var{definition}
2275 A Lisp form that when evaluated defines the GFlags.
2278 Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.
2280 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2284 (get-g-flags-definition "GtkCalendarDisplayOptions")
2286 (DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
2287 (:EXPORT T :TYPE-INITIALIZER
2288 "gtk_calendar_display_options_get_type")
2289 (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
2290 (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
2294 @node get-g-interface-definition
2295 @section get-g-interface-definition
2298 get-g-interface-definition type &optional lisp-name-package) @result{} definition
2303 A string naming the GInterface type
2304 @item @var{lisp-name-package}
2305 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*}
2306 @item @var{definition}
2307 A Lisp form that when evaluated defines the GInterface.
2310 Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.
2312 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2316 (get-g-interface-definition "GtkActivatable")
2318 (DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
2319 (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
2320 (USE-ACTION-APPEARANCE
2321 GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
2322 "use-action-appearance" "gboolean" T T)
2323 (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
2324 "related-action" "GtkAction" T T))
2327 @node get-g-class-definition
2328 @section get-g-class-definition
2332 get-g-class-definition type &optional lisp-name-package) @result{} definition
2337 A string naming the GObject type
2338 @item @var{lisp-name-package}
2339 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*}
2340 @item @var{definition}
2341 A Lisp form that when evaluated defines the GObject.
2344 Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.
2346 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2350 (get-g-class-definition "GtkButton")
2352 (DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
2353 (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
2354 ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
2355 :TYPE-INITIALIZER "gtk_button_get_type")
2356 ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
2357 (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
2358 (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
2360 (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
2362 (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
2364 (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
2365 "focus-on-click" "gboolean" T T)
2366 (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
2367 (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
2368 (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
2369 "image-position" "GtkPositionType" T T)))
2372 @node Specifying additional properties for CLOS classes
2373 @section Specifying additional properties for CLOS classes
2375 Some properties are not exposed through GObject introspection facilities, but are rather present as a pair of functions (@code{class_get_property}, @code{class_set_property}). @code{gobject-class} metaclass supports such properties. For these properties to be included in automatically generated class definitions, they should be made known to the generator.
2377 Definitions generator uses variable @code{*additional-properties*} to get this information.
2379 Variable @code{*additional-properties*} contains a plist that maps GType names to a list of properties definitions (See @ref{define-g-object-class} for syntax of properties definitions).
2381 To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
2385 (("GtkTreeViewColumn"
2386 (:cffi gtk::tree-view
2387 gtk::tree-view-column-tree-view
2388 g-object "gtk_tree_view_column_get_tree_view" nil)
2389 (:cffi gtk::sort-column-id
2390 gtk::tree-view-column-sort-column-id
2391 :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
2392 (:cffi gtk::cell-renderers
2393 gtk::tree-view-column-cell-renderers
2394 (glist g-object :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
2397 gtk::tree-selection-mode
2398 gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
2399 (:cffi gtk::select-function
2400 gtk::tree-selection-select-function
2401 nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
2404 @node Generating names for CLOS classes and accessors
2405 @section Generating names for CLOS classes and accessors
2407 Names of types are generated by mapping @code{CamelCaseNames} to @code{dash-separated-names} and interning them in specified package. Additionally, prefix from beginning of the name may be stripped (@code{"GtkWidget"} has prefix @code{"Gtk"}, after stripping it maps to @code{widget}). Some names may require special processing (e.g., @code{"GObject"}, @code{"GInitiallyUnowned"} should map to class names in @code{gobject} package; @code{"GtkWindow"} and @code{"GdkWindow"} should receive different @code{symbol-name}s so that they can both be imported in one package).
2409 Accessors for slots are generated by concatenating class name, dash and slot name, producing names like @code{class-slot}: @code{container-child}, @code{button-label}, etc.
2411 Name generation affected by following variables:
2413 @item @var{*strip-prefix*}
2414 A string variable specifying the prefix that should to be stripped from the names to generate symbols (e.g., if @code{(equal "Gtk" *strip-prefix*)}, then type named @code{"GtkWidget"} will map to class named @code{widget}.
2415 @item @var{*lisp-name-exceptions*}
2416 A plist mapping from strings (type names) to symbols (class names) that have special name processing.
2419 `(("GObject" gobject:g-object)
2420 ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2421 ("GInitiallyUnowned" gobject::g-initially-unowned)
2422 ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2423 ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2424 ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2428 @node generate-types-hierarchy-to-file
2429 @section generate-types-hierarchy-to-file
2432 (generate-types-hierarchy-to-file file
2434 &key include-referenced
2444 additional-properties)
2449 A string or pathname naming the file, or a stream.
2450 @item @var{root-type}
2451 A GType designator for a root type. All types that inherit from this type will be defined.
2452 @item @var{&key include-referenced}
2453 A boolean. Specifies whether referenced types should be included. Type is referenced if it is an interface or a type of property of type included in generation
2455 A string naming the prefix that should be removed from the beginning of names
2457 A package which will contain generated names of types, slots and accessors. It will also be the current package when the definitions are written to file
2458 @item @var{exceptions}
2459 A plist that maps GType names to their Lisp names.
2460 See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
2461 @item @var{prologue}
2462 A string that will be included verbatim in generated code file
2463 @item @var{interfaces}
2464 Additional list of interfaces that will also be included in generation
2466 Additional list of enums that will also be included in generation
2468 Additional list of flags that will also be included in generation
2470 Additional list of object types that will also be included in generation
2471 @item @var{exclusions}
2472 A list of GType names that will be excluded from generation
2473 @item @var{additional-properties}
2474 A plist of properties definitions that will be added to generated classes.
2475 See @ref{Specifying additional properties for CLOS classes} for more information.
2478 Generates definitions for all types in a type hierarchy. Recursively scan types hierarchy (starting from @code{root} and @code{objects} and @code{interfaces}) (except types that were specifically excluded) and generate defintion for every mentioned type. Parameters control various aspects of definition generation.
2482 (generate-types-hierarchy-to-file
2483 "gtk.generated-classes.lisp"
2485 :include-referenced t
2487 :package (or (find-package :gtk) (make-package :gtk))
2488 :exceptions `(("GObject" gobject:g-object)
2489 ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2490 ("GInitiallyUnowned" gobject::g-initially-unowned)
2491 ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2492 ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2493 ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2494 :prologue (format nil "(in-package :gtk)")
2495 :interfaces '("GtkBuildable" "GtkCellEditable" ...)
2496 :objects '("GtkSettings" "GtkRcStyle" ...)
2497 :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
2498 :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
2499 :exclusions '("PangoStretch" "PangoVariant" ...)
2500 :additional-properties
2501 '(("GtkTreeViewColumn"
2504 gtk::tree-view-column-tree-view
2506 "gtk_tree_view_column_get_tree_view"