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
20 @deftp {Structure} \args\
29 @macro Accessor {args}
30 @deffn {Accessor} \args\
34 @macro GenericFunction {args}
35 @deffn {Generic Function} \args\
39 @macro ForeignType {args}
40 @deftp {Foreign Type} \args\
44 @macro Variable {args}
45 @defvr {Special Variable} \args\
49 @macro Condition {args}
50 @deftp {Condition Type} \args\
60 @strong{Implementor's note:} @emph{\text\}
64 @c Info "requires" that x-refs end in a period or comma, or ) in the
65 @c case of @pxref. So the following implements that requirement for
66 @c the "See also" subheadings that permeate this manual, but only in
78 @c Typeset comments in roman font for the TeX output.
86 @c My copy of makeinfo is not generating any HTML for @result{} for
87 @c some odd reason. (It certainly used to...)
94 @c Similar macro to @result. Its purpose is to work around the fact
95 @c that ⇒ does not work properly inside @lisp.
108 @c ============================= Macros =============================
111 @c Show types, functions, and concepts in the same index.
117 @subtitle A Common Lisp binding for Gtk+
119 @author Dmitry Kalyanov
133 * Type hierarchy and type relations::
134 * Object types information::
135 * Enum types information::
139 * GObject low-level::
140 * GObject high-level::
141 * Creating GObjects classes and implementing GInterfaces::
143 * Generating type definitions by introspection::
147 @chapter Introduction
149 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.
151 The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.
153 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.
155 CL-GTK2-GObject is logically split into several layers:
157 @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.
158 @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.
159 @item High-level GObject integration. This layer includes support for interoperability between CLOS and GObject and automatic generation of corresponding definitions.
162 Naturally, users of CL-GTK2-GObject should use the high-level GObject integration, but occasionaly it may be necessary to use lower-level functionality.
165 @chapter Installation
167 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}.
169 To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.
171 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.
173 @node GType designator
174 @chapter GType designator
183 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.
185 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
187 Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
189 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
190 @item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
191 @item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
192 @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}.
193 @item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
194 @item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
195 @item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
196 @item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
197 @item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
198 @item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
199 @item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
200 @item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
201 @item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
202 @item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
203 @item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
204 @item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
205 @item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
206 @item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
207 @item @code{+g-type-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived. Values of this type correspond to by-value structures.
208 @item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived. Values of this type correspond to instances of structure @code{g-class-property-definition}.
209 @item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
212 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.
214 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
217 (g-type-numeric "GObject") @result{} 80
218 (g-type-numeric 80) @result{} 80
219 (g-type-string "GObject") @result{} "GObject"
220 (g-type-string 80) @result{} "GObject"
221 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
225 @section g-type-string
227 @Function g-type-string
229 (g-type-string g-type-designator) @result{} name
233 @item @var{g-type-designator}
234 The GType designator for the GType
239 Returns the name of GType.
242 @section g-type-numeric
244 @Function g-type-numeric
246 (g-type-numeric g-type-designator) @result{} GType
250 @item @var{g-type-designator}.
251 The GType designator for the GType.
253 The numeric identifier of GType
256 Returns the numeric identifier of GType
263 (g-type= type-1 type-2) @result{} eq
272 A boolean that is true if @code{type-1} and @code{type-2} designate the same type.
280 (g-type/= type-1 type-2) @result{} eq
289 A boolean that is true if @code{type-1} and @code{type-2} designate different types.
292 @node Type hierarchy and type relations
293 @chapter Type hierarchy and type relations
298 * g-type-fundamental::
303 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.
305 There are functions to query some specific information:
307 @item @code{g-type-fundamental} retrieves the fundamental type for given type
308 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
309 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
312 @node g-type-children
313 @section g-type-children
315 @Function g-type-children
317 (g-type-children type) @result{} children
324 A list of GType designators
327 Returns the list of descendent types.
331 (g-type-children "GtkButton")
333 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
337 @section g-type-parent
339 @Function g-type-parent
341 (g-type-parent type) @result{} parent
351 Returns the parent of @code{type}.
355 (g-type-parent "GtkToggleButton")
360 @node g-type-fundamental
361 @section g-type-fundamental
363 @Function g-type-fundamental
365 (g-type-fundamental type) @result{} fundamental-type
371 @item @var{fundamental-type}
372 A GType designator for one of the fundamental types
375 Returns the fundamental type that is the ancestor of @code{type}.
379 (g-type-fundamental "GtkButton") @result{} "GObject"
381 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
383 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
387 @section g-type-depth
389 @Function g-type-depth
391 (g-type-depth type) @result{} depth
401 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.
405 (g-type-depth "GObject") @result{} 1
406 (g-type-depth "GInitiallyUnowned") @result{} 2
409 @node g-type-next-base
410 @section g-type-next-base
412 @Function g-type-next-base
414 (g-type-next-base leaf-type root-type) @result{} base-type
418 @item @var{leaf-type}
420 @item @var{root-type}
422 @item @var{base-type}
426 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
443 the following will be returned:
446 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
447 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
448 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
449 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
450 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
453 @node Object types information
454 @chapter Object types information
456 * g-class-property-definition::
458 * class-property-info::
459 * interface-properties::
462 * parse-signal-name::
463 * query-signal-info::
464 * g-type-interfaces::
465 * g-type-interface-prerequisites::
468 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.
470 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.
472 @node g-class-property-definition
473 @section g-class-property-definition
475 @Struct g-class-property-definition
477 (defstruct g-class-property-definition
489 A string that names the property
491 A GType designator. Identifies the type of the property
493 A boolean. Identifies whether the property can be read
495 A boolean. Identifies whether the property can be assigned
496 @item @var{constructor}
497 A boolean. Identifies whether constructor of object accepts this property
498 @item @var{constructor-only}
499 A boolean. Identifies whether this property may only be set in constructor, not in property setter
500 @item @var{owner-type}
501 A GType designator. Identifies the type on which the property was defined.
504 This structure identifies a single property. Its field specify attributes of a property.
506 Structures of this type have shortened print syntax:
508 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
511 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
513 This syntax specifies:
515 @item type of property
516 @item the owner type of property
517 @item name of property
518 @item additional flags of property
521 @node class-properties
522 @section class-properties
524 @Function class-properties
526 (class-properties type) @result{} properties
531 A GType designator. Specifies the object type (class)
532 @item @var{properties}
533 A list of @code{g-property-definition} structures.
536 This function returns the list of properties that are available in class @code{type}.
540 (class-properties "GtkWidget")
542 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
543 #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
544 #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
545 #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
546 #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
547 #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
548 #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
549 #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
550 #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
551 #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
552 #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
553 #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
554 #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
555 #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
556 #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
557 #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
558 #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
559 #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
560 #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
561 #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
562 #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
563 #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
564 #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
567 @node class-property-info
568 @section class-property-info
569 @Function class-property-info
571 (class-property-info type property-name) @result{} property
577 @item @var{property-name}
578 A string naming the property
580 An instance of @code{g-property-definition} structure
583 Returns the property information for a single property.
587 (class-property-info "GtkButton" "label")
589 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
592 @node interface-properties
593 @section interface-properties
595 @Function interface-properties
597 (interface-properties type) @result{} properties
603 @item @var{properties}
604 A list of @code{g-property-definition} structures
607 This function returns the list of properties that are available in interface @code{type}.
611 (interface-properties "GtkFileChooser")
613 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
614 #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
615 #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
616 #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
617 #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
618 #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
619 #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
620 #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
621 #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
622 #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
623 #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
631 (defstruct signal-info
643 An integer - the identifier of a signal
646 @item @var{owner-type}
647 A GType designator identifying the type on which the signal was defined
649 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
650 @item @var{return-type}
651 The return type of a signal (and signal handlers)
652 @item @var{param-types}
653 A list of GType designators that specify the types of signal parameters
655 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
658 When @code{*print-readably*} is nil, the following print syntax is used:
660 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
661 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
662 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
663 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
666 This syntax specifies:
669 @item signal return type
673 @item list of types of parameters
678 @section type-signals
679 @Function type-signals
681 (type-signals type &key (include-inherited t)) @result{} signals
687 A list of @code{signal-info} structures
688 @item @var{include-inherited}
689 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
692 Returns the list of signals that are available in type @code{type}.
696 (type-signals "GtkLabel" :include-inherited nil)
698 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
699 #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
700 #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
703 @node parse-signal-name
704 @section parse-signal-name
706 @Function parse-signal-name
708 (parse-signal-name type signal-name) @result{} signal
713 A GType designator that has the signal.
714 @item @var{signal-name}
715 A string that identifies the signal.
717 A list @code{signal-info} structures.
720 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
724 (parse-signal-name "GObject" "notify::label")
726 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
729 @node query-signal-info
730 @section query-signal-info
731 @Function query-signal-info
733 (query-signal-info signal-id) @result{} signal
736 @item @var{signal-id}
737 An integer identifying the signal
739 An instance of @code{signal-info} structure
742 Retrieves the signal information by its id.
746 (query-signal-info 73)
748 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
751 @node g-type-interfaces
752 @section g-type-interfaces
754 @Function g-type-interfaces
756 (g-type-interfaces type) @result{} interfaces
762 @item @var{interfaces}
763 A list of GType designators
766 Returns the list of interfaces that @code{type} implements.
770 (g-type-interfaces "GtkButton")
772 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
775 @node g-type-interface-prerequisites
776 @section g-type-interface-prerequisites
778 @Function g-type-interface-prerequisites
780 (g-type-interface-prerequisites type) @result{} types
785 A GType designator of interface
787 A list of GType designators specifying the interface prerequisites
790 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
794 (g-type-interface-prerequisites "GtkCellEditable")
796 ("GtkObject" "GtkWidget")
799 @node Enum types information
800 @chapter Enum types information
808 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.
810 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.
822 A string - name of enum item
824 An integer - numeric value of enum item
826 A string - short name of an enum item
829 Structure @code{enum-item} represents a single item of an enumeration type.
833 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
840 (defstruct flags-item
846 A string - name of flags item
848 An integer - numeric value of flags item
850 A string - short name of an flags item
853 Structure @code{flags-item} represents a single item of an flags type.
858 :NAME "GDK_POINTER_MOTION_HINT_MASK"
860 :NICK "pointer-motion-hint-mask")
864 @section get-enum-items
866 @Function get-enum-items
868 (get-enum-items type) @result{} items
873 A GType designator of an enum type
875 A list of @code{enum-item} structures
878 Returns a list of items in an enumeration
882 (get-enum-items "GtkScrollType")
884 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
885 #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
886 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
887 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
888 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
889 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
890 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
891 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
892 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
893 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
894 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
895 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
896 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
897 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
898 #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
899 #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
902 @node get-flags-items
903 @section get-flags-items
905 @Function get-flags-items
907 (get-flags-items type) @result{} items
912 A GType designator of an flags type
914 A list of @code{flags-item} structures
917 Returns a list of items in an flags type
921 (get-flags-items "GtkAttachOptions")
923 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
924 #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
925 #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
929 @chapter Using GValues
936 * Registering types::
939 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
941 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.
943 GValue is used whenever a value of unkown type should be passed. It is used in:
945 @item Closure marshal functions
946 @item Property get and set functions
951 (cffi:with-foreign-object (gval 'g-value)
952 (set-g-value gval "Hello" "gchararray" :zero-g-value t)
953 (format t "~S~%" (parse-g-value gval))
954 (g-value-unset gval))
960 @section g-value-zero
961 @Function g-value-zero
963 (g-value-zero g-value)
967 A foreign pointer to GValue structure.
970 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
972 GValue value = @{ 0 @};
975 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).
978 @section g-value-init
980 @Function g-value-init
982 (g-value-init value type)
986 A foreign pointer to GValue structure
991 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).
994 @section g-value-unset
995 @Function g-value-unset
997 (g-value-unset value)
1001 A foreign pointer to GValue structure.
1004 Unsets the GValue. This frees all resources associated with GValue.
1007 @section parse-g-value
1008 @Function parse-g-value
1010 (parse-g-value value) @result{} object
1014 A foreign pointer to GValue structure
1019 Retrieves the object from GValue structure.
1022 @section set-g-value
1023 @Function set-g-value
1025 (set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))
1030 A foreign pointer to GValue structure
1032 An object that is to be assigned to @code{gvalue}
1034 A GType designator specifying what GType should be set
1035 @item @var{unset-g-value}
1036 A boolean specifying whether to call @code{g-value-unset} before assigment.
1037 @item @var{zero-g-value}
1038 A boolean specifying whether to call @code{g-value-zero} before assignment
1039 @item @var{g-value-init}
1040 A boolean specifying whether to call @code{g-value-init} before assignment
1043 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
1045 @node Registering types
1046 @section Registering types
1048 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.
1050 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.
1052 @subsection register-enum-type
1053 @Function register-enum-type
1055 (register-enum-type name type)
1059 A string naming the GEnum type
1061 A symbol - name of CFFI foreign enum type
1064 Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
1068 (defcenum text-direction
1070 (register-enum-type "GtkTextDirection" 'text-direction)
1073 @subsection register-flags-type
1074 @Function register-flags-type
1076 (register-flags-type name type)
1080 A string naming the GFlags type
1082 A symbol - name of CFFI foreign flags type
1085 Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
1089 (defcenum state-type
1090 :normal :active :prelight :selected :insensitive)
1091 (register-enum-type "GtkStateType" 'state-type)
1094 @node Stable pointers
1095 @chapter Stable pointers
1097 * allocate-stable-pointer::
1098 * free-stable-pointer::
1099 * stable-pointer-value::
1100 * with-stable-pointer::
1103 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.
1105 @node allocate-stable-pointer
1106 @section allocate-stable-pointer
1108 @Function allocate-stable-pointer
1110 (allocate-stable-pointer thing) @result{} stable-pointer
1115 An arbitrary Lisp object
1116 @item @var{stable-pointer}
1120 Allocates a stable pointer to @code{thing}.
1122 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
1126 (allocate-stable-pointer (lambda (x) (+ x 10)))
1128 #.(SB-SYS:INT-SAP #X00000002)
1130 (stable-pointer-value *)
1132 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1134 (free-stable-pointer **)
1139 @node free-stable-pointer
1140 @section free-stable-pointer
1142 @Function free-stable-pointer
1144 (free-stable-pointer stable-pointer)
1148 @item @var{stable-pointer}
1149 A foreign pointer that was created with @code{allocate-stable-pointer}.
1152 Frees the stable pointer, enabling the garbage collector to reclaim the object.
1156 (allocate-stable-pointer (lambda (x) (+ x 10)))
1158 #.(SB-SYS:INT-SAP #X00000002)
1160 (stable-pointer-value *)
1162 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1164 (free-stable-pointer **)
1169 @node stable-pointer-value
1170 @section stable-pointer-value
1172 @Accessor stable-pointer-value
1174 (stable-pointer-value stable-pointer) @result{} thing
1175 (setf (stable-pointer-value stable-pointer) thing)
1179 @item @var{stable-pointer}
1180 A foreign pointer created by @code{allocate-stable-pointer}
1185 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.
1187 @node with-stable-pointer
1188 @section with-stable-pointer
1190 @Macro with-stable-pointer
1192 (with-stable-pointer (ptr expr) &body body)
1197 A variable that will be bound to the stable pointer
1199 An expression that will be evaluated once and its value will be bound to stable pointer's value
1202 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1206 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1207 (print (stable-pointer-value ptr)))
1209 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1215 Closure are anonymous functions that capture their lexical environment.
1217 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).
1219 @section create-g-closure
1220 @Function create-g-closure
1222 (create-g-closure fn) @result{} closure
1227 A function that will be called by closure invokation
1229 A foreign pointer to allocated closure
1232 Allocates the closure. The closure is destroyed automatically by GObject.
1236 (create-g-closure (lambda (x) (+ x 10)))
1238 #.(SB-SYS:INT-SAP #X006D7B20)
1241 Example of usage from GObject binding code:
1243 (defun connect-signal (object signal handler &key after)
1244 (g-signal-connect-closure (ensure-object-pointer object)
1246 (create-g-closure handler)
1250 (TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
1252 @node GObject low-level
1253 @chapter GObject low-level
1255 * g-object-call-constructor::
1256 * g-type-from-object::
1257 * g-object-call-get-property::
1258 * g-object-call-set-property::
1261 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.
1263 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.
1265 @node g-object-call-constructor
1266 @section g-object-call-constructor
1268 @Function g-object-call-constructor
1270 (g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr
1274 @item @var{object-type}
1275 A GType designator that specifies the object type that is to be created
1276 @item @var{args-names}
1277 A list of strings naming the arguments to constructor
1278 @item @var{args-value}
1279 A list of arguments values (in the same order as args-names)
1280 @item @var{args-types}
1281 Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
1282 @item @var{object-ptr}
1283 A foreign pointer to newly created instance
1286 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}.
1290 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1292 #.(SB-SYS:INT-SAP #X006D8900)
1294 (g-object-call-get-property * "label")
1298 (g-object-call-get-property ** "use-underline")
1303 @node g-type-from-object
1304 @section g-type-from-object
1306 @Function g-type-from-object
1308 (g-type-from-object object-ptr) @result{} type
1312 @item @var{object-ptr}
1313 A foreign pointer to a GObject instance
1318 Returns the type of an object by a pointer to its instance
1322 (g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
1327 @node g-object-call-get-property
1328 @section g-object-call-get-property
1330 @Function g-object-call-get-property
1332 (g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value
1336 @item @var{object-ptr}
1337 A foreign pointer to a GObject instance
1338 @item @var{property-name}
1339 A string naming the property
1340 @item @var{property-type}
1341 Optional GType designator specifying the type of a property
1342 @item @var{property-value}
1343 The value of a property
1346 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.
1350 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1352 #.(SB-SYS:INT-SAP #X006D8900)
1354 (g-object-call-get-property * "label")
1358 (g-object-call-get-property ** "use-underline")
1363 @node g-object-call-set-property
1364 @section g-object-call-set-property
1366 @Function g-object-call-set-property
1368 (g-object-call-set-property object-ptr property-name new-value &optional property-type)
1372 @item @var{object-ptr}
1373 A foreign pointer to a GObject instance
1374 @item @var{property-name}
1375 A string naming the property
1376 @item @var{new-value}
1377 A new value of a property
1378 @item @var{property-type}
1379 Optional GType designator specifying the type of a property
1382 Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
1386 (g-object-call-constructor "GtkButton" nil nil)
1388 #.(SB-SYS:INT-SAP #X006D8B40)
1390 (g-object-call-set-property * "label" "Hello")
1394 (g-object-call-get-property ** "label")
1399 @node GObject high-level
1400 @chapter GObject high-level
1402 * GObject metaclass::
1405 * GObject foreign class::
1408 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):
1410 @item objects are created with @code{make-instance}
1411 @item properties are used as regular slots
1414 GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
1416 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.
1418 Example GObject class of definition:
1420 (defclass dialog (gtk-window atk-implementor-iface buildable)
1421 ((has-separator :accessor dialog-has-separator
1422 :initarg :has-separator
1423 :allocation :gobject-property
1424 :g-property-type "gboolean"
1425 :g-property-name "has-separator"))
1426 (:metaclass gobject-class)
1427 (:g-type-name . "GtkDialog")
1428 (:g-type-initializer . "gtk_dialog_get_type"))
1431 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.
1433 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.
1435 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).
1437 @node GObject metaclass
1438 @section GObject metaclass
1440 See MOP for information what metaclass is and why is it useful.
1442 GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
1444 Classes that correspond to GObject classes are instances of this class.
1446 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}.
1448 This class has the following slots:
1450 @item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
1452 Specifies the name of GObject class
1453 @item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
1455 Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
1456 @item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
1458 A boolean specifying whether this CLOS class corresponds to GInterface.
1461 This metaclass defines the GObject classes.
1463 Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
1465 @item @var{:g-property-type}
1467 A string naming GType of property
1468 @item @var{:g-property-name}
1470 A name of a property
1473 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:
1475 @item @var{:g-property-type}
1476 A CFFI foreign type of property
1477 @item @var{:g-getter}
1478 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)}.
1479 @item @var{:g-setter}
1480 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))}.
1483 Initargs of a slot are used to construct the GObject class.
1487 (defclass container (widget atk-implementor-iface buildable)
1488 ((border-width :allocation :gobject-property
1489 :g-property-type "guint"
1490 :accessor container-border-width
1491 :initarg :border-width
1492 :g-property-name "border-width")
1493 (resize-mode :allocation :gobject-property
1494 :g-property-type "GtkResizeMode"
1495 :accessor container-resize-mode
1496 :initarg :resize-mode
1497 :g-property-name "resize-mode")
1498 (child :allocation :gobject-property
1499 :g-property-type "GtkWidget"
1500 :accessor container-child
1502 :g-property-name "child")
1503 (focus-child :allocation :gobject-fn
1504 :g-property-type g-object
1505 :accessor container-focus-child
1506 :initarg :focus-child
1507 :g-getter "gtk_container_get_focus_child"
1508 :g-setter "gtk_container_set_focus_child")
1509 (focus-vadjustment :allocation :gobject-fn
1510 :g-property-type (g-object adjustment)
1511 :accessor container-focus-vadjustment
1512 :initarg :focus-vadjustment
1513 :g-getter "gtk_container_get_focus_vadjustment"
1514 :g-setter "gtk_container_set_focus_vadjustment")
1515 (focus-hadjustment :allocation :gobject-fn
1516 :g-property-type (g-object adjustment)
1517 :accessor container-focus-hadjustment
1518 :initarg :focus-hadjustment
1519 :g-getter "gtk_container_get_focus_hadjustment"
1520 :g-setter "gtk_container_set_focus_hadjustment"))
1521 (:metaclass gobject-class)
1522 (:g-type-name . "GtkContainer")
1523 (:g-type-initializer . "gtk_container_get_type"))
1525 (note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)
1528 @section Using objects
1529 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.
1533 (make-instance 'gtk:dialog :has-separator t)
1535 #<GTK:DIALOG @{10036C5A71@}>
1537 (defvar *d* (make-instance 'gtk:dialog :has-separator t))
1541 (gtk:dialog-has-separator *d*)
1545 (setf (gtk:dialog-has-separator *d*) nil)
1549 (gtk:dialog-has-separator *d*)
1557 To connect handler to a signal, @code{connect-signal} function is used.
1559 @Function connect-signals
1561 (connect-signal object signal handler &key after)
1566 An instance of GObject object
1572 A boolean specifying whether the handler should be called after the default handler
1575 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.
1579 (defvar *d* (make-instance 'gtk:dialog))
1585 #<GTK:DIALOG @{1002D866F1@}>
1587 (parse-signal-name "GtkDialog" "response")
1589 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1591 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1593 (emit-signal *d* "response" 14)
1596 #<GTK:DIALOG @{1002D866F1@}>
1600 Function @code{emit-signal} is used to emit signals on objects.
1602 @code{(emit-signal object signal-name &rest args) @result{} return-value}
1606 An object on which the signal should be emitted
1607 @item @var{signal-name}
1608 A string naming the signal
1610 Arguments for a signal
1611 @item @var{return-value}
1612 Return value of a signal
1615 Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
1619 (defvar *d* (make-instance 'gtk:dialog))
1625 #<GTK:DIALOG @{1002D866F1@}>
1627 (parse-signal-name "GtkDialog" "response")
1629 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1631 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1633 (emit-signal *d* "response" 14)
1636 #<GTK:DIALOG @{1002D866F1@}>
1640 @node GObject foreign class
1641 @section GObject foreign class
1643 To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
1645 This type has the following syntax:
1646 @code{(g-object &optional type)} or @code{g-object}.
1648 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.
1650 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.
1652 This defines the function that may be called with instances of types @code{container} and @code{widget}:
1654 (defcfun (container-add "gtk_container_add") :void
1655 (container (g-object container))
1656 (widget (g-object widget)))
1658 (let ((window (make-instance 'gtk-window))
1659 (widget (make-instance 'button)))
1660 (container-add window widget))
1662 (@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
1664 This defines the function that returns an instance of GObject class:
1666 (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
1667 (bin (g-object bin)))
1669 (let ((window (make-instance 'gtk-window))
1670 (widget (make-instance 'button)))
1671 (container-add window widget)
1674 #<GTK:BUTTON @{1002DE74B1@}>
1677 @node Creating GObjects classes and implementing GInterfaces
1678 @chapter Creating GObjects classes and implementing GInterfaces
1682 * register-object-type-implementation::
1685 Creating GObject classes from Lisp is the most complex part of GObject binding.
1687 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).
1689 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.
1691 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).
1693 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.
1695 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.
1698 @section define-vtable
1700 @Macro define-vtable
1702 (define-vtable (type-name cstruct-name)
1705 item ::= (name callback-name return-type &rest arg*)
1706 item ::= (:skip cffi-structure-item)
1707 arg ::= (arg-name arg-type)
1711 @item @var{type-name}
1712 A string naming the GObject type of interface
1713 @item @var{cstruct-name}
1714 A name for a generated CFFI foreign structure
1716 A name for implementation generic function
1717 @item @var{callback-name}
1718 A name for generated callback function
1719 @item @var{return-type}
1720 A CFFI specifier for foreign function return type
1721 @item @var{arg-name}
1722 A symbol naming the argument of interface method
1723 @item @var{arg-type}
1724 A CFFI specifier for foreign function argument type
1727 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.
1731 (define-vtable ("GtkTreeModel" c-gtk-tree-model)
1732 (:skip parent-instance g-type-interface)
1734 (:skip tree-model-row-changed :pointer)
1735 (:skip tree-model-row-inserted :pointer)
1736 (:skip tree-model-row-has-child-toggled :pointer)
1737 (:skip tree-model-row-deleted :pointer)
1738 (:skip tree-model-rows-reordered :pointer)
1740 (tree-model-get-flags-impl tree-model-get-flags-cb
1742 (tree-model g-object))
1743 (tree-model-get-n-columns-impl tree-model-get-n-columns-cb
1745 (tree-model g-object))
1746 (tree-model-get-column-type-impl tree-model-get-column-type-cb
1748 (tree-model g-object) (index :int))
1749 (tree-model-get-iter-impl tree-model-get-iter-cb
1751 (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (path (g-boxed-foreign tree-path)))
1752 (tree-model-get-path-impl tree-model-get-path-cb
1753 (g-boxed-foreign tree-path :return)
1754 (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1755 (tree-model-get-value-impl tree-model-get-value-cb
1757 (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
1758 (tree-model-iter-next-impl tree-model-iter-next-cb
1760 (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1761 (tree-model-iter-children-impl tree-model-iter-children-cb
1763 (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)))
1764 (tree-model-iter-has-child-impl tree-model-iter-has-child-cb
1766 (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1767 (tree-model-iter-n-children-impl tree-model-iter-n-children-cb
1769 (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1770 (tree-model-iter-nth-child-impl tree-model-iter-nth-child-cb
1772 (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)) (n :int))
1773 (tree-model-iter-parent-impl tree-model-iter-parent-cb
1775 (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (child (g-boxed-foreign tree-iter)))
1776 (tree-model-ref-node-impl tree-model-ref-node-cb
1778 (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1779 (tree-model-unref-node-impl tree-model-unref-node-cb
1781 (tree-model g-object) (iter (g-boxed-foreign tree-iter))))
1784 @node register-object-type-implementation
1785 @section register-object-type-implementation
1787 @Macro register-object-type-implementation
1789 (register-object-type-implementation name class parent interfaces properties)
1794 A string naming the new GObject class.
1796 A class name of corresponding CLOS class. It should be inherited from @code{g-object} or its descendants.
1798 A string naming the GObject superclass
1799 @item @var{interfaces}
1800 A list of names of interfaces that this class implements.
1801 @item @var{properties}
1802 A list of properties that this class provides.
1803 Each property is defined as
1805 property ::= (property-name property-type accessor property-get-fn property-set-fn)
1809 A macro that creates a new GObject type and registers the Lisp implementation for it.
1813 (register-object-type-implementation "LispArrayListStore" array-list-store "GObject" ("GtkTreeModel") nil)
1819 * define-g-boxed-cstruct::
1820 * define-g-boxed-variant-cstruct::
1821 * define-g-boxed-opaque::
1823 * define-boxed-opaque-accessor::
1824 * boxed-related-symbols::
1825 * GBoxed foreign type::
1828 GObject manual defines this type in the following way:
1830 ``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.
1832 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.''
1834 Naturally, it is hard to provide support for ``arbitrary C structures''. We support a few useful use cases of GBoxed types:
1836 @item Simple C structures. A Lisp structure is a one-to-one correspondence to C structure and is passes to and from foreign code by copying the data it contains. Examples of simple structures are GdkPoint, GdkRectangle.
1837 @item ``Variant'' C structures. A one common idiom of C is to define a union of structures sharing the same parts in order to implement the polymorphism of structures. These structures are mapped to a hierarchy of Lisp structures (where one structure subclasses another via the @code{:include} @code{defstruct} option).
1839 For example, Gdk has structure GdkEvent which is a union of GdkEventAny, GdkEventExpose and other structures. These structures have common slots: ``type'', ``window'', ``send_event''. By dispatching on ``type'', user or GdkEvent structure knows which of GdkEvent* structures it has and can access other fields.
1840 @item Opaque C structures. A C structure the has ``hidden'' fields and should only created/destroyed with specific functions and be accessed only with specific accessors. Example of such structures is GtkTreePath.
1843 @node define-g-boxed-cstruct
1844 @section define-g-boxed-cstruct
1845 @Macro define-g-boxed-cstruct
1847 (define-g-boxed-cstruct name g-type-name
1850 slot ::= (slot-name slot-type &key count initform inline)
1855 A symbol naming the type being defined
1856 @item @var{g-type-name}
1857 A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
1858 @item @var{slot-name}
1859 A symbol naming the slot of a structure
1860 @item @var{slot-type}
1861 A foreign type of a slot
1863 An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
1864 @item @var{initform}
1865 A form that is the initform of Lisp structure slot
1867 A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
1870 Defines the ``simple'' GBoxed structure corresponding to C structure. The slot specification is analogous to CFFI @code{defstruct} slot specification with the addition of @code{inline} option.
1874 (define-g-boxed-cstruct rectangle "GdkRectangle"
1875 (left :int :initform 0)
1876 (top :int :initform 0)
1877 (width :int :initform 0)
1878 (height :int :initform 0))
1880 (define-g-boxed-cstruct point nil
1881 (x :int :initform 0)
1882 (y :int :initform 0))
1884 (define-g-boxed-cstruct vector4 nil
1885 (coords :double :count 4 :initform (vector 0d0 0d0 0d0 0d0)))
1887 (define-g-boxed-cstruct segment nil
1888 (a point :inline t :initform (make-point))
1889 (b point :inline t :initform (make-point)))
1892 @node define-g-boxed-variant-cstruct
1893 @section define-g-boxed-variant-cstruct
1895 @Macro define-g-boxed-variant-cstruct
1897 (define-g-boxed-variant-cstruct name g-type-name
1898 &body slot-or-variant-specification*)
1900 slot ::= (slot-name slot-type &key count initform inline)
1901 variant-specification ::= (:variant dispatching-slot-name structure-variant*)
1902 structure-variant ::= (dispatching-slot-values structure-name &body slot-or-variant-specification*)
1907 A symbol naming the type being defined
1908 @item @var{g-type-name}
1909 A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
1910 @item @var{slot-name}
1911 A symbol naming the slot of a structure
1912 @item @var{slot-type}
1913 A foreign type of a slot
1915 An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
1916 @item @var{initform}
1917 A form that is the initform of Lisp structure slot
1919 A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
1920 @item @var{dispatching-slot-name}
1921 A name of the dispatching slot
1922 @item @var{dispatching-slot-values}
1923 A single value or a list of values.
1924 @item @var{structure-name}
1925 A symbol naming the structure
1928 Defines the variant GBoxed structure. Slots of variant structures are defined the same way as the slots of ``simple'' cstructs. After the last slot, @code{variant-specification} may be used to specify the variants of the structure. For this, dispatching slot is specified. The value of this slot specifies which variant of structure is used. Each variant is specified by values of the dispatching slot, by its slots and its variants.
1930 Variant structure is represented in Lisp via a hierarchy on structures. For example, @code{GdkEvent} structure has variants @code{GdkEventAny}, @code{GdkEventButton}, @code{GdkEventMotion}. In Lisp, @code{event} structure is defined with all common fields of these structures and @code{event-button}, @code{event-motion} structures inherit from @code{event} structure.
1932 It is assumed that the variant of structures can be represented as C structures with fields of their ``parent'' structures prepended to them. This assumption breaks when structures include their ``parent'' structure as a first field (this changes the memory alignment and changes offsets of fields).
1934 For example, for these structures this assumption holds:
1940 GdkEventButton button;
1943 struct GdkEventKey @{
1944 GdkEventType type; //
1945 GdkWindow *window; // These fields are common
1946 gint8 send_event; //
1953 struct GdkEventButton @{
1954 GdkEventType type; //
1955 GdkWindow *window; // These fields are common
1956 gint8 send_event; //
1966 (define-g-boxed-variant-cstruct event "GdkEvent"
1968 (window (g-object gdk-window))
1969 (send-event (:boolean :int8))
1971 ((:key-press :key-release) event-key
1973 (state modifier-type)
1976 (string (:string :free-from-foreign nil
1977 :free-to-foreign nil))
1978 (hardware-keycode :uint16)
1980 (is-modifier :uint))
1981 ((:button-press :2button-press :3button-press
1982 :button-release) event-button
1986 (axes (fixed-array :double 2))
1989 (device (g-object device))
1995 This code defines following structures:
1998 type window send-event)
2000 (defstruct (event-key (:include event))
2001 time state keyval length string
2002 hardware-keycode group is-modifier)
2004 (defstruct (event-button (:include event))
2005 time x y axes state button device x-root y-root)
2008 @node define-g-boxed-opaque
2009 @section define-g-boxed-opaque
2011 @Macro define-g-boxed-opaque
2013 (define-g-boxed-opaque name g-type-name &key alloc)
2018 A name of boxed type
2019 @item @var{g-type-name}
2020 A string; the name of GType
2022 A form that when evaluated produces a pointer to newly allocated structure. This pointer should be copiable with @code{g_boxed_copy} and freeable with @code{g_boxed_free} function.
2025 Defines a opaque boxed structure. A class named @var{name} is defined as a subclass of @code{g-boxed-opaque} class. Instances of this class contain pointers to corresponding structures. An @code{:after} method for @code{initialize-instance} generic function is defined that speciales on class @var{name}. This method either accepts a @code{:pointer} initarg or evaluates @var{alloc} form if @code{:pointer} is not specified; the resulting pointer is saved in instance; finalizer is registered to free the pointer when the garbage collectors deletes this object.
2029 (defcfun gtk-tree-path-new :pointer)
2031 (define-g-boxed-opaque tree-path "GtkTreePath"
2032 :alloc (gtk-tree-path-new))
2034 @node g-boxed-opaque
2035 @section g-boxed-opaque
2036 @Class g-boxed-opaque
2038 (defclass g-boxed-opaque ()
2039 ((pointer :initarg :pointer
2041 :accessor g-boxed-opaque-pointer)))
2044 A class that is the base class for wrappers of opaque structures. Contains a pointer to the wrapped opaque structure.
2046 Accessor function @code{g-boxed-opaque-pointer} is used to access the pointer. Pointer should not be modified directly, only read.
2047 @node define-boxed-opaque-accessor
2048 @section define-boxed-opaque-accessor
2049 @Macro define-boxed-opaque-accessor
2051 (define-boxed-opaque-accessor
2052 boxed-name accessor-name &key type reader writer)
2056 @item @var{boxed-name}
2057 A symbol naming the opaque structure type for which the accessor is being defined
2058 @item @var{accessor-name}
2059 A symbol naming the accessor
2061 A CFFI foreign type of the property for which the accessor is being defined
2063 A @code{NIL} or a string or a function designator for the reader function
2065 A @code{NIL} or a string or a function designator for the writer function
2068 Defines the accessor named @var{accessor-name} for property of opaque structure named @var{boxed-name} of type specified by CFFI foreign-type @var{type}.
2070 @var{reader} is a string naming a foreign function of one argument of CFFI foreign-type @code{(g-boxed-foreign @var{boxed-name})} that returns a value of CFFI foreign-type @var{type}; or a function designator for a function that accepts a single argument - an instance of @code{g-boxed-opaque} class and returns the value of a property; or a @code{NIL} if the property is not readable.
2072 @var{writer} is a string naming a foreign function of two arguments: of types @var{type} and @code{(g-boxed-foreign @var{boxed-name})} (with the first argument being the new value and the second being the object); or a function designator for a function of two arguments: a new value and an instance of @code{g-boxed-opaque} class; or a @code{NIL} if the property is not writable.
2076 (define-boxed-opaque-accessor text-iter text-iter-child-anchor
2077 :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))
2079 (define-boxed-opaque-accessor text-iter text-iter-tags
2080 :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))
2082 (define-boxed-opaque-accessor text-iter text-iter-chars-in-line
2083 :reader "gtk_text_iter_get_chars_in_line" :type :int)
2085 (define-boxed-opaque-accessor text-iter text-iter-offset
2086 :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
2089 @node boxed-related-symbols
2090 @section boxed-related-symbols
2092 @Function boxed-related-symbols
2094 (boxed-related-symbols name) @result{} symbols
2099 A symbol naming the boxed type
2104 This function returns the list of symbols that are related to GBoxed type @var{name}. These symbols are returned:
2106 @item name of boxed type
2107 @item name of all accessors of cstruct and variant-cstruct boxed types
2108 @item names of all variants of variant-cstruct boxed types
2109 @item names of constructors and copiers of cstruct and variant-cstruct boxed-types
2112 Typical usage of this function is to export the symbols related to given boxed type.
2116 (define-g-boxed-cstruct rectangle "GdkRectangle"
2117 (x :int :initform 0)
2118 (y :int :initform 0)
2119 (width :int :initform 0)
2120 (height :int :initform 0))
2122 (boxed-related-symbols 'rectangle)
2124 (RECTANGLE MAKE-RECTANGLE COPY-RECTANGLE RECTANGLE-X RECTANGLE-Y
2125 RECTANGLE-WIDTH RECTANGLE-HEIGHT)
2128 @node GBoxed foreign type
2129 @section GBoxed foreign type
2131 @ForeignType g-boxed-foreign
2133 (g-boxed-foreign name &rest option*)
2142 Option of foreign type
2143 @item @code{:return}
2144 An option that identifies the foreign type which is used at return position (as foreign function return type or as a callback return type)
2147 @code{g-boxed-foreign} type deals with marshaling data between Lisp code and foreign code. The marshaling follows the following principles:
2149 @item All operations on Lisp objects corresponding to GBoxed types are type-safe and should never lead to any form of memory corruption (if some operation is impossible due to e.g., pointer in opaque pointer wrapper being invalidated, error should be signalled)
2150 @item Lisp objects should not be manually managed and are properly reclaimed by garbage collector, leaving no memory leaks
2151 @item Foreign code can change objects that are passed to them as arguments. This is required for functions that operate by modifying their arguments
2152 @item Lisp code in callbacks can change objects that are passed as arguments. This is required to be able to implement interfaces that have functions that operate by modifying their arguments
2155 The @code{:return} option is required to be able to properly manage memory of opaque pointer wrappers and propagate changes to foreign and lisp structures.
2157 In order to be able to correctly use @code{g-boxed-foreign} foreign type in callbacks, you should use @code{glib-defcallback}. This macro is a thin wrapper around @code{cffi:defcallback} that adds proper handling of @code{g-boxed-foreign} foreign types.
2161 (define-vtable ("GtkTreeModel" c-gtk-tree-model)
2163 (tree-model-get-path-impl tree-model-get-path-cb
2164 (g-boxed-foreign tree-path :return) (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
2165 (tree-model-get-value-impl tree-model-get-value-cb
2166 :void (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
2167 (tree-model-iter-next-impl tree-model-iter-next-cb
2168 :boolean (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
2171 (defcfun gtk-text-iter-forward-search :boolean
2172 (iter (g-boxed-foreign text-iter))
2173 (str (:string :free-to-foreign t))
2174 (flags text-search-flags)
2175 (match-start (g-boxed-foreign text-iter))
2176 (match-end (g-boxed-foreign text-iter))
2177 (limit (g-boxed-foreign text-iter)))
2180 @node Generating type definitions by introspection
2181 @chapter Generating type definitions by introspection
2183 * define-g-object-class::
2184 * define-g-interface::
2187 * get-g-enum-definition::
2188 * get-g-flags-definition::
2189 * get-g-interface-definition::
2190 * get-g-class-definition::
2191 * Specifying additional properties for CLOS classes::
2192 * Generating names for CLOS classes and accessors::
2193 * generate-types-hierarchy-to-file::
2196 CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.
2198 @node define-g-object-class
2199 @section define-g-object-class
2201 @Macro define-g-object-class
2203 (define-g-object-class g-type-name name
2204 (&key (superclass 'g-object) (export t) interfaces type-initializer)
2207 property ::= (name accessor gname type readable writable)
2208 property ::= (:cffi name acessor type reader writer)
2211 Parameters of @code{define-g-object-class}
2213 @item @var{superclass}
2214 A symbol naming the superclass of this class
2216 Whether to export the name of the class and names of autogenerated properties names from the current package.
2217 @item @var{interfaces}
2218 A list of interfaces the this class implements
2219 @item @var{type-initializer}
2220 A string naming the type initiliazer function. It is usually named @code{class_get_type}.
2221 @item @var{properties}
2222 A list of slots of a class
2225 Parameters of @code{property}:
2228 A symbol naming the slot
2229 @item @var{accessor}
2230 A symbol naming the accessor function for this slot
2232 A string naming the property of GObject
2234 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)
2235 @item @var{readable}
2236 A boolean specifying whether the slot can be read
2237 @item @var{writable}
2238 A boolean specifying whether the slot can be assigned to
2240 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2242 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2245 Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.
2249 (define-g-object-class "GtkContainer" container
2250 (:superclass widget :export t :interfaces
2251 ("AtkImplementorIface" "GtkBuildable")
2252 :type-initializer "gtk_container_get_type")
2253 ((border-width container-border-width "border-width" "guint" t t)
2254 (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
2255 (child container-child "child" "GtkWidget" nil t)
2256 (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
2257 (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
2258 (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
2261 @node define-g-interface
2262 @section define-g-interface
2264 @Macro define-g-interface
2266 (define-g-interface g-type-name name (&key (export t) type-initializer)
2269 property ::= (name accessor gname type readable writable)
2270 property ::= (:cffi name acessor type reader writer)
2273 Parameters of @code{define-g-interface}
2276 Whether to export the name of the interface and names of autogenerated properties names from the current package.
2277 @item @var{type-initializer}
2278 A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
2279 @item @var{properties}
2280 A list of slots of a interface
2283 Parameters of @code{property}:
2286 A symbol naming the slot
2287 @item @var{accessor}
2288 A symbol naming the accessor function for this slot
2290 A string naming the property of GObject
2292 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)
2293 @item @var{readable}
2294 A boolean specifying whether the slot can be read
2295 @item @var{writable}
2296 A boolean specifying whether the slot can be assigned to
2298 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2300 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2303 Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.
2307 (define-g-interface "GtkFileChooser" file-chooser
2308 (:export t :type-initializer "gtk_file_chooser_get_type")
2309 (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
2310 (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
2311 (filter file-chooser-filter "filter" "GtkFileFilter" t t)
2312 (local-only file-chooser-local-only "local-only" "gboolean" t t)
2313 (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
2314 (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
2315 (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
2316 (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
2317 (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
2318 (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
2319 (action file-chooser-action "action" "GtkFileChooserAction" t t)
2320 (:cffi current-name file-chooser-current-name
2321 (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
2322 (:cffi filename file-chooser-filename
2323 (g-string :free-from-foreign t :free-to-foreign t)
2324 "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
2325 (:cffi current-folder file-chooser-current-folder
2326 (g-string :free-from-foreign t :free-to-foreign t)
2327 "gtk_file_chooser_get_current_folder"
2328 "gtk_file_chooser_set_current_folder")
2329 (:cffi uri file-chooser-uri
2330 (g-string :free-from-foreign t :free-to-foreign t)
2331 "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
2332 (:cffi current-folder-uri file-chooser-current-folder-uri
2333 (g-string :free-from-foreign t :free-to-foreign t)
2334 "gtk_file_chooser_get_current_folder_uri"
2335 "gtk_file_chooser_set_current_folder_uri")
2336 (:cffi preview-filename file-chooser-preview-filename
2337 (g-string :free-from-foreign t :free-to-foreign t)
2338 "gtk_file_chooser_get_preview_filename" nil)
2339 (:cffi preview-uri file-chooser-preview-uri
2340 (g-string :free-from-foreign t :free-to-foreign t)
2341 "gtk_file_chooser_get_preview_uri" nil))
2345 @section define-g-enum
2347 @Macro define-g-enum
2349 (define-g-enum g-name name (&key (export t) type-initializer) &body value*)
2352 value ::= (:keyword integer)
2357 A string naming the GEnum type
2359 A symbol naming the CFFI enumeration type
2361 A boolean indicating whether to export @code{name}
2362 @item @var{type-initializer}
2363 A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
2366 Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
2370 (define-g-enum "GtkTextDirection" text-direction
2371 (:export t :type-initializer "gtk_text_direction_get_type")
2372 (:none 0) (:ltr 1) (:rtl 2))
2374 (define-g-enum "GtkSizeGroupMode" size-group-mode
2375 (:export t :type-initializer "gtk_size_group_mode_get_type")
2376 :none :horizontal :vertical :both)
2379 @node define-g-flags
2380 @section define-g-flags
2382 @Macro define-g-flags
2384 (define-g-flags g-name name (&key (export t) type-initializer) &body value*)
2387 value ::= (:keyword integer)
2392 A string naming the GFlags type
2394 A symbol naming the CFFI flags type
2396 A boolean indicating whether to export @code{name}
2397 @item @var{type-initializer}
2398 A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
2401 Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
2405 (define-g-flags "GtkAttachOptions" attach-options
2406 (:export t :type-initializer "gtk_attach_options_get_type")
2407 (:expand 1) (:shrink 2) (:fill 4))
2409 (define-g-flags "GtkButtonAction" button-action
2410 (:export t :type-initializer "gtk_button_action_get_type")
2411 :ignored :selects :drags :expands)
2414 @node get-g-enum-definition
2415 @section get-g-enum-definition
2417 @Function get-g-enum-definition
2419 (get-g-enum-definition type &optional lisp-name-package) @result{} definition
2424 A string naming the GEnum type
2425 @item @var{lisp-name-package}
2426 A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
2427 @item @var{definition}
2428 A Lisp form that when evaluated defines the GEnum.
2431 Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.
2433 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2437 (get-g-enum-definition "GtkDirectionType")
2439 (DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
2440 (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
2441 (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
2445 @node get-g-flags-definition
2446 @section get-g-flags-definition
2448 @Function get-g-flags-definition
2450 (get-g-flags-definition type &optional lisp-name-package) @result{} definition
2455 A string naming the GFlags type
2456 @item @var{lisp-name-package}
2457 A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
2458 @item @var{definition}
2459 A Lisp form that when evaluated defines the GFlags.
2462 Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.
2464 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2468 (get-g-flags-definition "GtkCalendarDisplayOptions")
2470 (DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
2471 (:EXPORT T :TYPE-INITIALIZER
2472 "gtk_calendar_display_options_get_type")
2473 (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
2474 (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
2478 @node get-g-interface-definition
2479 @section get-g-interface-definition
2481 @Function get-g-interface-definition
2483 get-g-interface-definition type &optional lisp-name-package) @result{} definition
2488 A string naming the GInterface type
2489 @item @var{lisp-name-package}
2490 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*}
2491 @item @var{definition}
2492 A Lisp form that when evaluated defines the GInterface.
2495 Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.
2497 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2501 (get-g-interface-definition "GtkActivatable")
2503 (DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
2504 (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
2505 (USE-ACTION-APPEARANCE
2506 GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
2507 "use-action-appearance" "gboolean" T T)
2508 (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
2509 "related-action" "GtkAction" T T))
2512 @node get-g-class-definition
2513 @section get-g-class-definition
2515 @Function get-g-class-definition
2517 (get-g-class-definition type &optional lisp-name-package) @result{} definition
2522 A string naming the GObject type
2523 @item @var{lisp-name-package}
2524 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*}
2525 @item @var{definition}
2526 A Lisp form that when evaluated defines the GObject.
2529 Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.
2531 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2535 (get-g-class-definition "GtkButton")
2537 (DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
2538 (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
2539 ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
2540 :TYPE-INITIALIZER "gtk_button_get_type")
2541 ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
2542 (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
2543 (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
2545 (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
2547 (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
2549 (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
2550 "focus-on-click" "gboolean" T T)
2551 (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
2552 (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
2553 (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
2554 "image-position" "GtkPositionType" T T)))
2557 @node Specifying additional properties for CLOS classes
2558 @section Specifying additional properties for CLOS classes
2560 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.
2562 Definitions generator uses variable @code{*additional-properties*} to get this information.
2564 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).
2566 To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
2570 (("GtkTreeViewColumn"
2571 (:cffi gtk::tree-view
2572 gtk::tree-view-column-tree-view
2573 g-object "gtk_tree_view_column_get_tree_view" nil)
2574 (:cffi gtk::sort-column-id
2575 gtk::tree-view-column-sort-column-id
2576 :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
2577 (:cffi gtk::cell-renderers
2578 gtk::tree-view-column-cell-renderers
2579 (glist g-object :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
2582 gtk::tree-selection-mode
2583 gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
2584 (:cffi gtk::select-function
2585 gtk::tree-selection-select-function
2586 nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
2589 @node Generating names for CLOS classes and accessors
2590 @section Generating names for CLOS classes and accessors
2592 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).
2594 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.
2596 Name generation affected by following variables:
2598 @item @var{*strip-prefix*}
2599 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}.
2600 @item @var{*lisp-name-exceptions*}
2601 A plist mapping from strings (type names) to symbols (class names) that have special name processing.
2604 `(("GObject" gobject:g-object)
2605 ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2606 ("GInitiallyUnowned" gobject::g-initially-unowned)
2607 ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2608 ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2609 ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2613 @node generate-types-hierarchy-to-file
2614 @section generate-types-hierarchy-to-file
2616 @Function generate-types-hierarchy-to-file
2618 (generate-types-hierarchy-to-file file
2620 &key include-referenced
2630 additional-properties)
2635 A string or pathname naming the file, or a stream.
2636 @item @var{root-type}
2637 A GType designator for a root type. All types that inherit from this type will be defined.
2638 @item @var{&key include-referenced}
2639 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
2641 A string naming the prefix that should be removed from the beginning of names
2643 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
2644 @item @var{exceptions}
2645 A plist that maps GType names to their Lisp names.
2646 See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
2647 @item @var{prologue}
2648 A string that will be included verbatim in generated code file
2649 @item @var{interfaces}
2650 Additional list of interfaces that will also be included in generation
2652 Additional list of enums that will also be included in generation
2654 Additional list of flags that will also be included in generation
2656 Additional list of object types that will also be included in generation
2657 @item @var{exclusions}
2658 A list of GType names that will be excluded from generation
2659 @item @var{additional-properties}
2660 A plist of properties definitions that will be added to generated classes.
2661 See @ref{Specifying additional properties for CLOS classes} for more information.
2664 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.
2668 (generate-types-hierarchy-to-file
2669 "gtk.generated-classes.lisp"
2671 :include-referenced t
2673 :package (or (find-package :gtk) (make-package :gtk))
2674 :exceptions `(("GObject" gobject:g-object)
2675 ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2676 ("GInitiallyUnowned" gobject::g-initially-unowned)
2677 ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2678 ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2679 ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2680 :prologue (format nil "(in-package :gtk)")
2681 :interfaces '("GtkBuildable" "GtkCellEditable" ...)
2682 :objects '("GtkSettings" "GtkRcStyle" ...)
2683 :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
2684 :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
2685 :exclusions '("PangoStretch" "PangoVariant" ...)
2686 :additional-properties
2687 '(("GtkTreeViewColumn"
2690 gtk::tree-view-column-tree-view
2692 "gtk_tree_view_column_get_tree_view"