doc/gobject.texi

   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.)
   6
   7 @c @documentencoding utf-8
   8
   9 @macro Function {args}
  10 @defun \args\
  11 @end defun
  12 @end macro
  13
  14 @macro Macro {args}
  15 @defmac \args\
  16 @end defmac
  17 @end macro
  18
  19 @macro Accessor {args}
  20 @deffn {Accessor} \args\
  21 @end deffn
  22 @end macro
  23
  24 @macro GenericFunction {args}
  25 @deffn {Generic Function} \args\
  26 @end deffn
  27 @end macro
  28
  29 @macro ForeignType {args}
  30 @deftp {Foreign Type} \args\
  31 @end deftp
  32 @end macro
  33
  34 @macro Variable {args}
  35 @defvr {Special Variable} \args\
  36 @end defvr
  37 @end macro
  38
  39 @macro Condition {args}
  40 @deftp {Condition Type} \args\
  41 @end deftp
  42 @end macro
  43
  44 @macro cffi
  45 @acronym{CFFI}
  46 @end macro
  47
  48 @macro impnote {text}
  49 @quotation
  50 @strong{Implementor's note:} @emph{\text\}
  51 @end quotation
  52 @end macro
  53
  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
  57 @c Info mode.
  58 @ifinfo
  59 @macro seealso {name}
  60 @ref{\name\}.
  61 @end macro
  62 @end ifinfo
  63
  64 @ifnotinfo
  65 @alias seealso = ref
  66 @end ifnotinfo
  67
  68 @c Typeset comments in roman font for the TeX output.
  69 @iftex
  70 @alias lispcmt = r
  71 @end iftex
  72 @ifnottex
  73 @alias lispcmt = asis
  74 @end ifnottex
  75
  76 @c My copy of makeinfo is not generating any HTML for @result{} for
  77 @c some odd reason. (It certainly used to...)
  78 @ifhtml
  79 @macro result
  80 =>
  81 @end macro
  82 @end ifhtml
  83
  84 @c Similar macro to @result. Its purpose is to work around the fact
  85 @c that &rArr; does not work properly inside @lisp.
  86 @ifhtml
  87 @macro res
  88 @html
  89 &rArr;
  90 @end html
  91 @end macro
  92 @end ifhtml
  93
  94 @ifnothtml
  95 @alias res = result
  96 @end ifnothtml
  97
  98 @c ============================= Macros =============================
  99
 100
 101 @c Show types, functions, and concepts in the same index.
 102 @syncodeindex tp cp
 103 @syncodeindex fn cp
 104
 105 @titlepage
 106 @title CL-GTK2
 107 @subtitle A Common Lisp binding for Gtk+
 108 @subtitle GObject
 109 @author Dmitry Kalyanov
 110 @end titlepage
 111
 112 @contents
 113
 114 @ifnottex
 115 @node Top
 116 @top cl-gtk2-gobject
 117 @end ifnottex
 118
 119 @menu
 120 * Introduction::
 121 * Installation::
 122 * GType designator::
 123 * Type hierarchy and type relations::
 124 * Object types information::
 125 * Enum types information::
 126 * Using GValues::
 127 * Stable pointers::
 128 * Closures::
 129 * GObject low-level::
 130 * GObject high-level::
 131 * Subclassing GObjects and implementing GInterfaces::
 132 * GBoxed::
 133 * Generating type definitions by introspection::
 134 @end menu
 135
 136 @node Introduction
 137 @chapter Introduction
 138
 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.
 140
 141 The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.
 142
 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.
 144
 145 CL-GTK2-GObject is logically split into several layers:
 146 @itemize
 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.
 150 @end itemize
 151
 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.
 153
 154 @node Installation
 155 @chapter Installation
 156
 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}.
 158
 159 To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.
 160
 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.
 162
 163 @node GType designator
 164 @chapter GType designator
 165
 166 @menu
 167 * g-type-string::
 168 * g-type-numeric::
 169 @end menu
 170
 171 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.
 172
 173 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
 174
 175 Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
 176 @itemize
 177 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
 178 @item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
 179 @item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
 180 @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}.
 181 @item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
 182 @item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
 183 @item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
 184 @item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
 185 @item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
 186 @item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
 187 @item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
 188 @item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
 189 @item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
 190 @item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
 191 @item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
 192 @item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
 193 @item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
 194 @item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
 195 @item @code{+g-type-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived.
 196 @item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived.
 197 @item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
 198 @end itemize
 199
 200 Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them).
 201
 202 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
 203
 204 @example
 205 (g-type-numeric "GObject") @result{} 80
 206 (g-type-numeric 80) @result{} 80
 207 (g-type-string "GObject") @result{} "GObject"
 208 (g-type-string 80) @result{} "GObject"
 209 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
 210 @end example
 211
 212 @node g-type-string
 213 @section g-type-string
 214
 215 @code{(g-type-string g-type-designator) @result{} name}
 216
 217 @table @var
 218 @item @var{g-type-designator}
 219 The GType designator for the GType
 220 @item @var{name}
 221 The name of GType
 222 @end table
 223
 224 Returns the name of GType.
 225
 226 @node g-type-numeric
 227 @section g-type-numeric
 228
 229 @code{(g-type-numeric g-type-designator) @result{} GType}
 230
 231 @table @var
 232 @item @var{g-type-designator}.
 233 The GType designator for the GType.
 234 @item @var{GType}
 235 The numeric identifier of GType
 236 @end table
 237
 238 Returns the numeric identifier of GType
 239
 240 @node Type hierarchy and type relations
 241 @chapter Type hierarchy and type relations
 242
 243 @menu
 244 * g-type-children::
 245 * g-type-parent::
 246 * g-type-fundamental::
 247 * g-type-depth::
 248 * g-type-next-base::
 249 @end menu
 250
 251 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.
 252
 253 There are functions to query some specific information:
 254 @itemize
 255 @item @code{g-type-fundamental} retrieves the fundamental type for given type
 256 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
 257 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
 258 @end itemize
 259
 260 @node g-type-children
 261 @section g-type-children
 262
 263 @code{(g-type-children type) @result{} children}
 264 @table @var
 265 @item @var{type}
 266 A GType designator
 267 @item @var{children}
 268 A list of GType designators
 269 @end table
 270
 271 Returns the list of descendent types.
 272
 273 Example:
 274 @example
 275 (g-type-children "GtkButton")
 276 @result{}
 277 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
 278 @end example
 279
 280 @node g-type-parent
 281 @section g-type-parent
 282
 283 @code{(g-type-parent type) @result{} parent}
 284
 285 @table @var
 286 @item @var{type}
 287 A GType designator
 288 @item @var{parent}
 289 A GType designator
 290 @end table
 291
 292 Returns the parent of @code{type}.
 293
 294 Example:
 295 @example
 296 (g-type-parent "GtkToggleButton")
 297 @result{}
 298 "GtkButton"
 299 @end example
 300 @node g-type-fundamental
 301 @section g-type-fundamental
 302
 303 @code{(g-type-fundamental type) @result{} fundamental-type}
 304
 305 @table @var
 306 @item @var{type}
 307 A GType designator
 308 @item @var{fundamental-type}
 309 A GType designator for one of the fundamental types
 310 @end table
 311
 312 Returns the fundamental type that is the ancestor of @code{type}.
 313
 314 Example:
 315 @example
 316 (g-type-fundamental "GtkButton") @result{} "GObject"
 317
 318 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
 319
 320 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
 321 @end example
 322
 323 @node g-type-depth
 324 @section g-type-depth
 325
 326 @code{(g-type-depth type) @result{} depth}
 327
 328 @table @var
 329 @item @var{type}
 330 A GType designator
 331 @item @var{depth}
 332 An integer
 333 @end table
 334
 335 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.
 336
 337 Example:
 338 @example
 339 (g-type-depth "GObject") @result{} 1
 340 (g-type-depth "GInitiallyUnowned") @result{} 2
 341 @end example
 342
 343 @node g-type-next-base
 344 @section g-type-next-base
 345
 346 @code{(g-type-next-base leaf-type root-type) @result{} base-type}
 347
 348 @table @var
 349 @item @var{leaf-type}
 350 A GType designator
 351 @item @var{root-type}
 352 A GType designator
 353 @item @var{base-type}
 354 A GType designator
 355 @end table
 356
 357 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
 358 @example
 359 + GObject
 360  \
 361   + GInitiallyUnowned
 362    \
 363     + GtkObject
 364     |\
 365     | + GtkAdjustment
 366      \
 367       + GtkWidget
 368        \
 369         + GtkContainer
 370          \
 371           + GtkTable
 372 @end example
 373
 374 the following will be returned:
 375
 376 @example
 377 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
 378 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
 379 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
 380 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
 381 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
 382 @end example
 383
 384 @node Object types information
 385 @chapter Object types information
 386 @menu
 387 * g-class-property-definition::
 388 * class-properties::
 389 * class-property-info::
 390 * interface-properties::
 391 * signal-info::
 392 * type-signals::
 393 * parse-signal-name::
 394 * query-signal-info::
 395 * g-type-interfaces::
 396 * g-type-interface-prerequisites::
 397 @end menu
 398
 399 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.
 400
 401 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.
 402
 403 @node g-class-property-definition
 404 @section g-class-property-definition
 405
 406 @example
 407 (defstruct g-class-property-definition
 408   name
 409   type
 410   readable
 411   writable
 412   constructor
 413   constructor-only
 414   owner-type)
 415 @end example
 416
 417 @table @var
 418 @item @var{name}
 419 A string that names the property
 420 @item @var{type}
 421 A GType designator. Identifies the type of the property
 422 @item @var{readable}
 423 A boolean. Identifies whether the property can be read
 424 @item @var{writable}
 425 A boolean. Identifies whether the property can be assigned
 426 @item @var{constructor}
 427 A boolean. Identifies whether constructor of object accepts this property
 428 @item @var{constructor-only}
 429 A boolean. Identifies whether this property may only be set in constructor, not in property setter
 430 @item @var{owner-type}
 431 A GType designator. Identifies the type on which the property was defined.
 432 @end table
 433
 434 This structure identifies a single property. Its field specify attributes of a property.
 435
 436 Structures of this type have shortened print syntax:
 437 @example
 438 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 439 @end example
 440
 441 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
 442
 443 This syntax specifies:
 444 @itemize
 445 @item type of property
 446 @item the owner type of property
 447 @item name of property
 448 @item additional flags of property
 449 @end itemize
 450
 451 @node class-properties
 452 @section class-properties
 453
 454 @code{(class-properties type) @result{} properties}
 455
 456 @table @var
 457 @item @var{type}
 458 A GType designator. Specifies the object type (class)
 459 @item @var{properties}
 460 A list of @code{g-property-definition} structures.
 461 @end table
 462
 463 This function returns the list of properties that are available in class @code{type}.
 464
 465 Example:
 466 @example
 467 (class-properties "GtkWidget")
 468 @result{}
 469 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
 470  #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
 471  #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
 472  #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
 473  #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
 474  #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
 475  #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
 476  #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
 477  #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
 478  #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
 479  #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
 480  #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
 481  #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
 482  #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
 483  #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
 484  #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
 485  #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
 486  #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
 487  #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
 488  #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
 489  #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
 490  #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
 491  #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
 492 @end example
 493
 494 @node class-property-info
 495 @section class-property-info
 496 @code{(class-property-info type property-name) @result{} property}
 497
 498 @table @var
 499 @item @var{type}
 500 A GType designator
 501 @item @var{property-name}
 502 A string naming the property
 503 @item @var{property}
 504 An instance of @code{g-property-definition} structure
 505 @end table
 506
 507 Returns the property information for a single property.
 508
 509 Example:
 510 @example
 511 (class-property-info "GtkButton" "label")
 512 @result{}
 513 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 514 @end example
 515
 516 @node interface-properties
 517 @section interface-properties
 518
 519 @code{(interface-properties type) @result{} properties}
 520
 521 @table @var
 522 @item @var{type}
 523 A GType designator
 524 @item @var{properties}
 525 A list of @code{g-property-definition} structures
 526 @end table
 527
 528 This function returns the list of properties that are available in interface @code{type}.
 529
 530 Example:
 531 @example
 532 (interface-properties "GtkFileChooser")
 533 @result{}
 534 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
 535  #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
 536  #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
 537  #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
 538  #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
 539  #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
 540  #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
 541  #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
 542  #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
 543  #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
 544  #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
 545 @end example
 546
 547 @node signal-info
 548 @section signal-info
 549
 550 @example
 551 (defstruct signal-info
 552   id
 553   name
 554   owner-type
 555   flags
 556   return-type
 557   param-types
 558   detail)
 559 @end example
 560
 561 @table @var
 562 @item @var{id}
 563 An integer - the identifier of a signal
 564 @item @var{name}
 565 Name of a signal
 566 @item @var{owner-type}
 567 A GType designator identifying the type on which the signal was defined
 568 @item @var{flags}
 569 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
 570 @item @var{return-type}
 571 The return type of a signal (and signal handlers)
 572 @item @var{param-types}
 573 A list of GType designators that specify the types of signal parameters
 574 @item @var{detail}
 575 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
 576 @end table
 577
 578 When @code{*print-readably*} is nil, the following print syntax is used:
 579 @example
 580 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 581 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
 582 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
 583 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
 584 @end example
 585
 586 This syntax specifies:
 587 @itemize
 588 @item the signal id
 589 @item signal return type
 590 @item owner type
 591 @item signal name
 592 @item detail
 593 @item list of types of parameters
 594 @item flags
 595 @end itemize
 596
 597 @node type-signals
 598 @section type-signals
 599 @code{(type-signals type &key (include-inherited t)) @result{} signals}
 600 @table @var
 601 @item @var{type}
 602 A GType designator
 603 @item @var{signals}
 604 A list of @code{signal-info} structures
 605 @item @var{include-inherited}
 606 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
 607 @end table
 608
 609 Returns the list of signals that are available in type @code{type}.
 610
 611 Example:
 612 @example
 613 (type-signals "GtkLabel" :include-inherited nil)
 614 @result{}
 615 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
 616  #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
 617  #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
 618 @end example
 619
 620 @node parse-signal-name
 621 @section parse-signal-name
 622
 623 @code{(parse-signal-name type signal-name) @result{} signal}
 624
 625 @table @var
 626 @item @var{type}
 627 A GType designator that has the signal.
 628 @item @var{signal-name}
 629 A string that identifies the signal.
 630 @item @var{signal}
 631 A list @code{signal-info} structures.
 632 @end table
 633
 634 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
 635
 636 Example:
 637 @example
 638 (parse-signal-name "GObject" "notify::label")
 639 @result{}
 640 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 641 @end example
 642
 643 @node query-signal-info
 644 @section query-signal-info
 645 @code{(query-signal-info signal-id) @result{} signal}
 646 @table @var
 647 @item @var{signal-id}
 648 An integer identifying the signal
 649 @item @var{signal}
 650 An instance of @code{signal-info} structure
 651 @end table
 652
 653 Retrieves the signal information by its id.
 654
 655 Example:
 656 @example
 657 (query-signal-info 73)
 658 @result{}
 659 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
 660 @end example
 661
 662 @node g-type-interfaces
 663 @section g-type-interfaces
 664
 665 @code{(g-type-interfaces type) @result{} interfaces}
 666
 667 @table @var
 668 @item @var{type}
 669 A GType designator
 670 @item @var{interfaces}
 671 A list of GType designators
 672 @end table
 673
 674 Returns the list of interfaces that @code{type} implements.
 675
 676 Example:
 677 @example
 678 (g-type-interfaces "GtkButton")
 679 @result{}
 680 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
 681 @end example
 682
 683 @node g-type-interface-prerequisites
 684 @section g-type-interface-prerequisites
 685
 686 @code{(g-type-interface-prerequisites type) @result{} types}
 687
 688 @table @var
 689 @item @var{type}
 690 A GType designator of interface
 691 @item @var{types}
 692 A list of GType designators specifying the interface prerequisites
 693 @end table
 694
 695 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
 696
 697 Example:
 698 @example
 699 (g-type-interface-prerequisites "GtkCellEditable")
 700 @result{}
 701 ("GtkObject" "GtkWidget")
 702 @end example
 703
 704 @node Enum types information
 705 @chapter Enum types information
 706 @menu
 707 * enum-item::
 708 * flags-item::
 709 * get-enum-items::
 710 * get-flags-items::
 711 @end menu
 712
 713 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.
 714
 715 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.
 716
 717 @node enum-item
 718 @section enum-item
 719 @example
 720 (defstruct enum-item
 721   name value nick)
 722 @end example
 723
 724 @table @var
 725 @item @var{name}
 726 A string - name of enum item
 727 @item @var{value}
 728 An integer - numeric value of enum item
 729 @item @var{nick}
 730 A string - short name of an enum item
 731 @end table
 732
 733 Structure @code{enum-item} represents a single item of an enumeration type.
 734
 735 Example:
 736 @example
 737 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
 738 @end example
 739
 740 @node flags-item
 741 @section flags-item
 742 @example
 743 (defstruct flags-item
 744   name value nick)
 745 @end example
 746
 747 @table @var
 748 @item @var{name}
 749 A string - name of flags item
 750 @item @var{value}
 751 An integer - numeric value of flags item
 752 @item @var{nick}
 753 A string - short name of an flags item
 754 @end table
 755
 756 Structure @code{flags-item} represents a single item of an flags type.
 757
 758 Example:
 759 @example
 760 #S(FLAGS-ITEM
 761    :NAME "GDK_POINTER_MOTION_HINT_MASK"
 762    :VALUE 8
 763    :NICK "pointer-motion-hint-mask")
 764 @end example
 765
 766 @node get-enum-items
 767 @section get-enum-items
 768
 769 @code{(get-enum-items type) @result{} items}
 770
 771 @table @var
 772 @item @var{type}
 773 A GType designator of an enum type
 774 @item @var{items}
 775 A list of @code{enum-item} structures
 776 @end table
 777
 778 Returns a list of items in an enumeration
 779
 780 Example:
 781 @example
 782 (get-enum-items "GtkScrollType")
 783 @result{}
 784 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
 785  #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
 786  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
 787  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
 788  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
 789  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
 790  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
 791  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
 792  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
 793  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
 794  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
 795  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
 796  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
 797  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
 798  #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
 799  #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
 800 @end example
 801
 802 @node get-flags-items
 803 @section get-flags-items
 804
 805 @code{(get-flags-items type) @result{} items}
 806
 807 @table @var
 808 @item @var{type}
 809 A GType designator of an flags type
 810 @item @var{items}
 811 A list of @code{flags-item} structures
 812 @end table
 813
 814 Returns a list of items in an flags type
 815
 816 Example:
 817 @example
 818 (get-flags-items "GtkAttachOptions")
 819 @result{}
 820 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
 821  #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
 822  #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
 823 @end example
 824
 825 @node Using GValues
 826 @chapter Using GValues
 827 @menu
 828 * g-value-zero::
 829 * g-value-init::
 830 * g-value-unset::
 831 * parse-g-value::
 832 * set-g-value::
 833 * Registering types::
 834 @end menu
 835
 836 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
 837
 838 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.
 839
 840 GValue is used whenever a value of unkown type should be passed. It is used in:
 841 @itemize
 842 @item Closure marshal functions
 843 @item Property get and set functions
 844 @end itemize
 845
 846 Example of usage:
 847 @example
 848 (cffi:with-foreign-object (gval 'g-value)
 849   (set-g-value gval "Hello" "gchararray" :zero-g-value t)
 850   (format t "~S~%" (parse-g-value gval))
 851   (g-value-unset gval))
 852 @result{}
 853 "Hello"
 854 @end example
 855
 856 @node g-value-zero
 857 @section g-value-zero
 858 @code{(g-value-zero g-value)}
 859 @table @var
 860 @item @var{g-value}
 861 A foreign pointer to GValue structure.
 862 @end table
 863
 864 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
 865 @example
 866 GValue value = @{ 0 @};
 867 @end example
 868
 869 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).
 870
 871 @node g-value-init
 872 @section g-value-init
 873
 874 @code{(g-value-init value type)}
 875 @table @var
 876 @item @var{value}
 877 A foreign pointer to GValue structure
 878 @item @var{type}
 879 A GType designator
 880 @end table
 881
 882 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).
 883
 884 @node g-value-unset
 885 @section g-value-unset
 886 @code{(g-value-unset value)}
 887 @table @var
 888 @item @var{value}
 889 A foreign pointer to GValue structure.
 890 @end table
 891
 892 Unsets the GValue. This frees all resources associated with GValue.
 893
 894 @node parse-g-value
 895 @section parse-g-value
 896 @code{(parse-g-value value) @result{} object}
 897 @table @var
 898 @item @var{value}
 899 A foreign pointer to GValue structure
 900 @item @var{object}
 901 A Lisp object
 902 @end table
 903
 904 Retrieves the object from GValue structure.
 905
 906 @node set-g-value
 907 @section set-g-value
 908 @code{(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))}
 909
 910 @table @var
 911 @item @var{gvalue}
 912 A foreign pointer to GValue structure
 913 @item @var{object}
 914 An object that is to be assigned to @code{gvalue}
 915 @item @var{type}
 916 A GType designator specifying what GType should be set
 917 @item @var{unset-g-value}
 918 A boolean specifying whether to call @code{g-value-unset} before assigment.
 919 @item @var{zero-g-value}
 920 A boolean specifying whether to call @code{g-value-zero} before assignment
 921 @item @var{g-value-init}
 922 A boolean specifying whether to call @code{g-value-init} before assignment
 923 @end table
 924
 925 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
 926
 927 @node Registering types
 928 @section Registering types
 929
 930 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.
 931
 932 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.
 933
 934 @subsection
 935 @code{(register-enum-type name type)}
 936 @table @var
 937 @item @var{name}
 938 A string naming the GEnum type
 939 @item @var{type}
 940 A symbol - name of CFFI foreign enum type
 941 @end table
 942
 943 Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
 944
 945 Example:
 946 @example
 947 (defcenum text-direction
 948   :none :ltr :rtl)
 949 (register-enum-type "GtkTextDirection" 'text-direction)
 950 @end example
 951
 952 @subsection
 953 @code{(register-flags-type name type)}
 954 @table @var
 955 @item @var{name}
 956 A string naming the GFlags type
 957 @item @var{type}
 958 A symbol - name of CFFI foreign flags type
 959 @end table
 960
 961 Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
 962
 963 Example:
 964 @example
 965 (defcenum state-type
 966   :normal :active :prelight :selected :insensitive)
 967 (register-enum-type "GtkStateType" 'state-type)
 968 @end example
 969
 970 @node Stable pointers
 971 @chapter Stable pointers
 972 @menu
 973 * allocate-stable-pointer::
 974 * free-stable-pointer::
 975 * stable-pointer-value::
 976 * with-stable-pointer::
 977 @end menu
 978
 979 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.
 980
 981 @node allocate-stable-pointer
 982 @section allocate-stable-pointer
 983
 984 @code{(allocate-stable-pointer thing) @result{} stable-pointer}
 985
 986 @table @var
 987 @item @var{thing}
 988 An arbitrary Lisp object
 989 @item @var{stable-pointer}
 990 A foreign pointer
 991 @end table
 992
 993 Allocates a stable pointer to @code{thing}.
 994
 995 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
 996
 997 Example:
 998 @example
 999 (allocate-stable-pointer (lambda (x) (+ x 10)))
1000 @result{}
1001 #.(SB-SYS:INT-SAP #X00000002)
1002
1003 (stable-pointer-value *)
1004 @result{}
1005 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1006
1007 (free-stable-pointer **)
1008 @result{}
1009 NIL
1010 @end example
1011
1012 @node free-stable-pointer
1013 @section free-stable-pointer
1014
1015 @code{(free-stable-pointer stable-pointer)}
1016
1017 @table @var
1018 @item @var{stable-pointer}
1019 A foreign pointer that was created with @code{allocate-stable-pointer}.
1020 @end table
1021
1022 Frees the stable pointer, enabling the garbage collector to reclaim the object.
1023
1024 Example:
1025 @example
1026 (allocate-stable-pointer (lambda (x) (+ x 10)))
1027 @result{}
1028 #.(SB-SYS:INT-SAP #X00000002)
1029
1030 (stable-pointer-value *)
1031 @result{}
1032 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1033
1034 (free-stable-pointer **)
1035 @result{}
1036 NIL
1037 @end example
1038
1039 @node stable-pointer-value
1040 @section stable-pointer-value
1041
1042 @example
1043 (stable-pointer-value stable-pointer) @result{} thing
1044 (setf (stable-pointer-value stable-pointer) thing)
1045 @end example
1046
1047 @table @var
1048 @item @var{stable-pointer}
1049 A foreign pointer created by @code{allocate-stable-pointer}
1050 @item @var{thing}
1051 A Lisp object
1052 @end table
1053
1054 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.
1055
1056 @node with-stable-pointer
1057 @section with-stable-pointer
1058
1059 @code{(with-stable-pointer (ptr expr) &body body)}
1060
1061 @table @var
1062 @item @var{ptr}
1063 A variable that will be bound to the stable pointer
1064 @item @var{expr}
1065 An expression that will be evaluated once and its value will be bound to stable pointer's value
1066 @end table
1067
1068 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1069
1070 Example:
1071 @example
1072 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1073   (print (stable-pointer-value ptr)))
1074 ;;Prints:
1075 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1076 @end example
1077
1078 @node Closures
1079 @chapter Closures
1080
1081 Closure are anonymous functions that capture their lexical environment.
1082
1083 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).
1084
1085 @section create-g-closure
1086 @code{(create-g-closure fn) @result{} closure}
1087
1088 @table @var
1089 @item @var{fn}
1090 A function that will be called by closure invokation
1091 @item @var{closure}
1092 A foreign pointer to allocated closure
1093 @end table
1094
1095 Allocates the closure. The closure is destroyed automatically by GObject.
1096
1097 Example:
1098 @example
1099 (create-g-closure (lambda (x) (+ x 10)))
1100 @result{}
1101 #.(SB-SYS:INT-SAP #X006D7B20)
1102 @end example
1103
1104 Example of usage from GObject binding code:
1105 @example
1106 (defun connect-signal (object signal handler &key after)
1107   (g-signal-connect-closure (ensure-object-pointer object)
1108                             signal
1109                             (create-g-closure handler)
1110                             after))
1111 @end example
1112
1113 (TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
1114
1115 @node GObject low-level
1116 @chapter GObject low-level
1117 @menu
1118 * g-object-call-constructor::
1119 * g-type-from-object::
1120 * g-object-call-get-property::
1121 * g-object-call-set-property::
1122 @end menu
1123
1124 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.
1125
1126 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.
1127
1128 @node g-object-call-constructor
1129 @section g-object-call-constructor
1130
1131 @code{(g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr}
1132
1133 @table @var
1134 @item @var{object-type}
1135 A GType designator that specifies the object type that is to be created
1136 @item @var{args-names}
1137 A list of strings naming the arguments to constructor
1138 @item @var{args-value}
1139 A list of arguments values (in the same order as args-names)
1140 @item @var{args-types}
1141 Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
1142 @item @var{object-ptr}
1143 A foreign pointer to newly created instance
1144 @end table
1145
1146 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}.
1147
1148 Example:
1149 @example
1150 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1151 @result{}
1152 #.(SB-SYS:INT-SAP #X006D8900)
1153
1154 (g-object-call-get-property * "label")
1155 @result{}
1156 "Hello"
1157
1158 (g-object-call-get-property ** "use-underline")
1159 @result{}
1160 T
1161 @end example
1162
1163 @node g-type-from-object
1164 @section g-type-from-object
1165
1166 @code{(g-type-from-object object-ptr) @result{} type}
1167
1168 @table @var
1169 @item @var{object-ptr}
1170 A foreign pointer to a GObject instance
1171 @item @var{type}
1172 A GType designator
1173 @end table
1174
1175 Returns the type of an object by a pointer to its instance
1176
1177 Example:
1178 @example
1179 (g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
1180 @result{}
1181 "GtkButton"
1182 @end example
1183
1184 @node g-object-call-get-property
1185 @section g-object-call-get-property
1186
1187 @code{(g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value}
1188
1189 @table @var
1190 @item @var{object-ptr}
1191 A foreign pointer to a GObject instance
1192 @item @var{property-name}
1193 A string naming the property
1194 @item @var{property-type}
1195 Optional GType designator specifying the type of a property
1196 @item @var{property-value}
1197 The value of a property
1198 @end table
1199
1200 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.
1201
1202 Example:
1203 @example
1204 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1205 @result{}
1206 #.(SB-SYS:INT-SAP #X006D8900)
1207
1208 (g-object-call-get-property * "label")
1209 @result{}
1210 "Hello"
1211
1212 (g-object-call-get-property ** "use-underline")
1213 @result{}
1214 T
1215 @end example
1216
1217 @node g-object-call-set-property
1218 @section g-object-call-set-property
1219
1220 @code{(g-object-call-set-property object-ptr property-name new-value &optional property-type)}
1221
1222 @table @var
1223 @item @var{object-ptr}
1224 A foreign pointer to a GObject instance
1225 @item @var{property-name}
1226 A string naming the property
1227 @item @var{new-value}
1228 A new value of a property
1229 @item @var{property-type}
1230 Optional GType designator specifying the type of a property
1231 @end table
1232
1233 Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
1234
1235 Example:
1236 @example
1237 (g-object-call-constructor "GtkButton" nil nil)
1238 @result{}
1239 #.(SB-SYS:INT-SAP #X006D8B40)
1240
1241 (g-object-call-set-property * "label" "Hello")
1242 @result{}
1243 ; No value
1244
1245 (g-object-call-get-property ** "label")
1246 @result{}
1247 "Hello"
1248 @end example
1249
1250 @node GObject high-level
1251 @chapter GObject high-level
1252 @menu
1253 * GObject metaclass::
1254 * Using objects::
1255 * Signals::
1256 * GObject foreign class::
1257 @end menu
1258
1259 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):
1260 @itemize
1261 @item objects are created with @code{make-instance}
1262 @item properties are used as regular slots
1263 @end itemize
1264
1265 GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
1266
1267 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.
1268
1269 Example GObject class of definition:
1270 @example
1271 (defclass dialog (gtk-window atk-implementor-iface buildable)
1272   ((has-separator :accessor dialog-has-separator
1273                   :initarg :has-separator
1274                   :allocation :gobject-property
1275                   :g-property-type "gboolean"
1276                   :g-property-name "has-separator"))
1277   (:metaclass gobject-class)
1278   (:g-type-name . "GtkDialog")
1279   (:g-type-initializer . "gtk_dialog_get_type"))
1280 @end example
1281
1282 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.
1283
1284 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.
1285
1286 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).
1287
1288 @node GObject metaclass
1289 @section GObject metaclass
1290
1291 See MOP for information what metaclass is and why is it useful.
1292
1293 GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
1294
1295 Classes that correspond to GObject classes are instances of this class.
1296
1297 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}.
1298
1299 This class has the following slots:
1300 @itemize
1301 @item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
1302
1303 Specifies the name of GObject class
1304 @item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
1305
1306 Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
1307 @item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
1308
1309 A boolean specifying whether this CLOS class corresponds to GInterface.
1310 @end itemize
1311
1312 This metaclass defines the GObject classes.
1313
1314 Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
1315 @itemize
1316 @item @var{:g-property-type}
1317
1318 A string naming GType of property
1319 @item @var{:g-property-name}
1320
1321 A name of a property
1322 @end itemize
1323
1324 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:
1325 @itemize
1326 @item @var{:g-property-type}
1327 A CFFI foreign type of property
1328 @item @var{:g-getter}
1329 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)}.
1330 @item @var{:g-setter}
1331 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))}.
1332 @end itemize
1333
1334 Initargs of a slot are used to construct the GObject class.
1335
1336 Example:
1337 @example
1338 (defclass container (widget atk-implementor-iface buildable)
1339     ((border-width :allocation :gobject-property
1340                    :g-property-type "guint"
1341                    :accessor container-border-width
1342                    :initarg :border-width
1343                    :g-property-name "border-width")
1344      (resize-mode :allocation :gobject-property
1345                   :g-property-type "GtkResizeMode"
1346                   :accessor container-resize-mode
1347                   :initarg :resize-mode
1348                   :g-property-name "resize-mode")
1349      (child :allocation :gobject-property
1350             :g-property-type "GtkWidget"
1351             :accessor container-child
1352             :initarg :child
1353             :g-property-name "child")
1354      (focus-child :allocation :gobject-fn
1355                   :g-property-type g-object
1356                   :accessor container-focus-child
1357                   :initarg :focus-child
1358                   :g-getter "gtk_container_get_focus_child"
1359                   :g-setter "gtk_container_set_focus_child")
1360      (focus-vadjustment :allocation :gobject-fn
1361                         :g-property-type (g-object adjustment)
1362                         :accessor container-focus-vadjustment
1363                         :initarg :focus-vadjustment
1364                         :g-getter "gtk_container_get_focus_vadjustment"
1365                         :g-setter "gtk_container_set_focus_vadjustment")
1366      (focus-hadjustment :allocation :gobject-fn
1367                         :g-property-type (g-object adjustment)
1368                         :accessor container-focus-hadjustment
1369                         :initarg :focus-hadjustment
1370                         :g-getter "gtk_container_get_focus_hadjustment"
1371                         :g-setter "gtk_container_set_focus_hadjustment"))
1372     (:metaclass gobject-class)
1373     (:g-type-name . "GtkContainer")
1374     (:g-type-initializer . "gtk_container_get_type"))
1375 @end example
1376 (note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)
1377
1378 @node Using objects
1379 @section Using objects
1380 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.
1381
1382 Example:
1383 @example
1384 (make-instance 'gtk:dialog :has-separator t)
1385 @result{}
1386 #<GTK:DIALOG @{10036C5A71@}>
1387
1388 (defvar *d* (make-instance 'gtk:dialog :has-separator t))
1389 @result{}
1390 *D*
1391
1392 (gtk:dialog-has-separator *d*)
1393 @result{}
1394 T
1395
1396 (setf (gtk:dialog-has-separator *d*) nil)
1397 @result{}
1398 NIL
1399
1400 (gtk:dialog-has-separator *d*)
1401 @result{}
1402 NIL
1403 @end example
1404
1405 @node Signals
1406 @section Signals
1407
1408 To connect handler to a signal, @code{connect-signal} function is used.
1409
1410 @code{(connect-signal object signal handler &key after)}
1411
1412 @table @var
1413 @item @var{object}
1414 An instance of GObject object
1415 @item @var{signal}
1416 A signal name
1417 @item @var{handler}
1418 A function
1419 @item @var{after}
1420 A boolean specifying whether the handler should be called after the default handler
1421 @end table
1422
1423 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.
1424
1425 Example:
1426 @example
1427 (defvar *d* (make-instance 'gtk:dialog))
1428 @result{}
1429 *D*
1430
1431 *d*
1432 @result{}
1433 #<GTK:DIALOG @{1002D866F1@}>
1434
1435 (parse-signal-name "GtkDialog" "response")
1436 @result{}
1437 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1438
1439 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1440
1441 (emit-signal *d* "response" 14)
1442 @result{}
1443 ;; Prints:
1444 #<GTK:DIALOG @{1002D866F1@}>
1445 14
1446 @end example
1447
1448 Function @code{emit-signal} is used to emit signals on objects.
1449
1450 @code{(emit-signal object signal-name &rest args) @result{} return-value}
1451
1452 @table @var
1453 @item @var{object}
1454 An object on which the signal should be emitted
1455 @item @var{signal-name}
1456 A string naming the signal
1457 @item @var{args}
1458 Arguments for a signal
1459 @item @var{return-value}
1460 Return value of a signal
1461 @end table
1462
1463 Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
1464
1465 Example:
1466 @example
1467 (defvar *d* (make-instance 'gtk:dialog))
1468 @result{}
1469 *D*
1470
1471 *d*
1472 @result{}
1473 #<GTK:DIALOG @{1002D866F1@}>
1474
1475 (parse-signal-name "GtkDialog" "response")
1476 @result{}
1477 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1478
1479 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1480
1481 (emit-signal *d* "response" 14)
1482 @result{}
1483 ;; Prints:
1484 #<GTK:DIALOG @{1002D866F1@}>
1485 14
1486 @end example
1487
1488 @node GObject foreign class
1489 @section GObject foreign class
1490
1491 To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
1492
1493 This type has the following syntax:
1494 @code{(g-object &optional type)} or @code{g-object}.
1495
1496 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.
1497
1498 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.
1499
1500 This defines the function that may be called with instances of types @code{container} and @code{widget}:
1501 @example
1502 (defcfun (container-add "gtk_container_add") :void
1503   (container (g-object container))
1504   (widget (g-object widget)))
1505
1506 (let ((window (make-instance 'gtk-window))
1507       (widget (make-instance 'button)))
1508   (container-add window widget))
1509 @end example
1510 (@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
1511
1512 This defines the function that returns an instance of GObject class:
1513 @example
1514 (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
1515   (bin (g-object bin)))
1516
1517 (let ((window (make-instance 'gtk-window))
1518       (widget (make-instance 'button)))
1519   (container-add window widget)
1520   (bin-child window))
1521 @result{}
1522 #<GTK:BUTTON @{1002DE74B1@}>
1523 @end example
1524
1525 @node Subclassing GObjects and implementing GInterfaces
1526 @chapter Subclassing GObjects and implementing GInterfaces
1527
1528 @node GBoxed
1529 @chapter GBoxed
1530
1531 @node Generating type definitions by introspection
1532 @chapter Generating type definitions by introspection
1533 @menu
1534 * define-g-object-class::
1535 * define-g-interface::
1536 * define-g-enum::
1537 * define-g-flags::
1538 * get-g-enum-definition::
1539 * get-g-flags-definition::
1540 * get-g-interface-definition::
1541 * get-g-class-definition::
1542 * Specifying additional properties for CLOS classes::
1543 * Generating names for CLOS classes and accessors::
1544 * generate-types-hierarchy-to-file::
1545 @end menu
1546
1547 CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.
1548
1549 @node define-g-object-class
1550 @section define-g-object-class
1551
1552 @example
1553 (define-g-object-class g-type-name name
1554   (&key (superclass 'g-object) (export t) interfaces type-initializer)
1555   (&rest property*))
1556
1557 property ::= (name accessor gname type readable writable)
1558 property ::= (:cffi name acessor type reader writer)
1559 @end example
1560
1561 Parameters of @code{define-g-object-class}
1562 @table @var
1563 @item @var{superclass}
1564 A symbol naming the superclass of this class
1565 @item @var{export}
1566 Whether to export the name of the class and names of autogenerated properties names from the current package.
1567 @item @var{interfaces}
1568 A list of interfaces the this class implements
1569 @item @var{type-initializer}
1570 A string naming the type initiliazer function. It is usually named @code{class_get_type}.
1571 @item @var{properties}
1572 A list of slots of a class
1573 @end table
1574
1575 Parameters of @code{property}:
1576 @table @var
1577 @item @var{name}
1578 A symbol naming the slot
1579 @item @var{accessor}
1580 A symbol naming the accessor function for this slot
1581 @item @var{gname}
1582 A string naming the property of GObject
1583 @item @var{type}
1584 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)
1585 @item @var{readable}
1586 A boolean specifying whether the slot can be read
1587 @item @var{writable}
1588 A boolean specifying whether the slot can be assigned to
1589 @item @var{reader}
1590 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
1591 @item @var{writter}
1592 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
1593 @end table
1594
1595 Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.
1596
1597 Example:
1598 @example
1599 (define-g-object-class "GtkContainer" container
1600   (:superclass widget :export t :interfaces
1601                ("AtkImplementorIface" "GtkBuildable")
1602                :type-initializer "gtk_container_get_type")
1603   ((border-width container-border-width "border-width" "guint" t t)
1604    (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
1605    (child container-child "child" "GtkWidget" nil t)
1606    (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
1607    (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
1608    (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
1609 @end example
1610
1611 @node define-g-interface
1612 @section define-g-interface
1613
1614 @example
1615 (define-g-interface g-type-name name (&key (export t) type-initializer)
1616   &body property*)
1617
1618 property ::= (name accessor gname type readable writable)
1619 property ::= (:cffi name acessor type reader writer)
1620 @end example
1621
1622 Parameters of @code{define-g-interface}
1623 @table @var
1624 @item @var{export}
1625 Whether to export the name of the interface and names of autogenerated properties names from the current package.
1626 @item @var{type-initializer}
1627 A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
1628 @item @var{properties}
1629 A list of slots of a interface
1630 @end table
1631
1632 Parameters of @code{property}:
1633 @table @var
1634 @item @var{name}
1635 A symbol naming the slot
1636 @item @var{accessor}
1637 A symbol naming the accessor function for this slot
1638 @item @var{gname}
1639 A string naming the property of GObject
1640 @item @var{type}
1641 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)
1642 @item @var{readable}
1643 A boolean specifying whether the slot can be read
1644 @item @var{writable}
1645 A boolean specifying whether the slot can be assigned to
1646 @item @var{reader}
1647 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
1648 @item @var{writter}
1649 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
1650 @end table
1651
1652 Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.
1653
1654 Example:
1655 @example
1656 (define-g-interface "GtkFileChooser" file-chooser
1657   (:export t :type-initializer "gtk_file_chooser_get_type")
1658   (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
1659   (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
1660   (filter file-chooser-filter "filter" "GtkFileFilter" t t)
1661   (local-only file-chooser-local-only "local-only" "gboolean" t t)
1662   (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
1663   (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
1664   (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
1665   (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
1666   (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
1667   (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
1668   (action file-chooser-action "action" "GtkFileChooserAction" t t)
1669   (:cffi current-name file-chooser-current-name
1670    (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
1671   (:cffi filename file-chooser-filename
1672    (g-string :free-from-foreign t :free-to-foreign t)
1673    "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
1674   (:cffi current-folder file-chooser-current-folder
1675    (g-string :free-from-foreign t :free-to-foreign t)
1676    "gtk_file_chooser_get_current_folder"
1677    "gtk_file_chooser_set_current_folder")
1678   (:cffi uri file-chooser-uri
1679    (g-string :free-from-foreign t :free-to-foreign t)
1680    "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
1681   (:cffi current-folder-uri file-chooser-current-folder-uri
1682    (g-string :free-from-foreign t :free-to-foreign t)
1683    "gtk_file_chooser_get_current_folder_uri"
1684    "gtk_file_chooser_set_current_folder_uri")
1685   (:cffi preview-filename file-chooser-preview-filename
1686    (g-string :free-from-foreign t :free-to-foreign t)
1687    "gtk_file_chooser_get_preview_filename" nil)
1688   (:cffi preview-uri file-chooser-preview-uri
1689    (g-string :free-from-foreign t :free-to-foreign t)
1690    "gtk_file_chooser_get_preview_uri" nil))
1691 @end example
1692
1693 @node define-g-enum
1694 @section define-g-enum
1695
1696 @example
1697 (define-g-enum g-name name (&key (export t) type-initializer) &body value*)
1698
1699 value ::= :keyword
1700 value ::= (:keyword integer)
1701 @end example
1702
1703 @table @var
1704 @item @var{g-name}
1705 A string naming the GEnum type
1706 @item @var{name}
1707 A symbol naming the CFFI enumeration type
1708 @item @var{export}
1709 A boolean indicating whether to export @code{name}
1710 @item @var{type-initializer}
1711 A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
1712 @end table
1713
1714 Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
1715
1716 Example:
1717 @example
1718 (define-g-enum "GtkTextDirection" text-direction
1719   (:export t :type-initializer "gtk_text_direction_get_type")
1720   (:none 0) (:ltr 1) (:rtl 2))
1721
1722 (define-g-enum "GtkSizeGroupMode" size-group-mode
1723  (:export t :type-initializer "gtk_size_group_mode_get_type")
1724  :none :horizontal :vertical :both)
1725 @end example
1726
1727 @node define-g-flags
1728 @section define-g-flags
1729
1730 @example
1731 (define-g-flags g-name name (&key (export t) type-initializer) &body value*)
1732
1733 value ::= :keyword
1734 value ::= (:keyword integer)
1735 @end example
1736
1737 @table @var
1738 @item @var{g-name}
1739 A string naming the GFlags type
1740 @item @var{name}
1741 A symbol naming the CFFI flags type
1742 @item @var{export}
1743 A boolean indicating whether to export @code{name}
1744 @item @var{type-initializer}
1745 A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
1746 @end table
1747
1748 Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
1749
1750 Example:
1751 @example
1752 (define-g-flags "GtkAttachOptions" attach-options
1753   (:export t :type-initializer "gtk_attach_options_get_type")
1754   (:expand 1) (:shrink 2) (:fill 4))
1755
1756 (define-g-flags "GtkButtonAction" button-action
1757   (:export t :type-initializer "gtk_button_action_get_type")
1758   :ignored :selects :drags :expands)
1759 @end example
1760
1761 @node get-g-enum-definition
1762 @section get-g-enum-definition
1763
1764 @code{(get-g-enum-definition type &optional lisp-name-package) @result{} definition}
1765
1766 @table @var
1767 @item @var{type}
1768 A string naming the GEnum type
1769 @item @var{lisp-name-package}
1770 A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
1771 @item @var{definition}
1772 A Lisp form that when evaluated defines the GEnum.
1773 @end table
1774
1775 Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.
1776
1777 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
1778
1779 Example:
1780 @example
1781 (get-g-enum-definition "GtkDirectionType")
1782 @result{}
1783 (DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
1784                (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
1785                (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
1786                (:RIGHT 5))
1787 @end example
1788
1789 @node get-g-flags-definition
1790 @section get-g-flags-definition
1791
1792 @code{(get-g-flags-definition type &optional lisp-name-package) @result{} definition}
1793
1794 @table @var
1795 @item @var{type}
1796 A string naming the GFlags type
1797 @item @var{lisp-name-package}
1798 A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
1799 @item @var{definition}
1800 A Lisp form that when evaluated defines the GFlags.
1801 @end table
1802
1803 Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.
1804
1805 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
1806
1807 Example:
1808 @example
1809 (get-g-flags-definition "GtkCalendarDisplayOptions")
1810 @result{}
1811 (DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
1812                 (:EXPORT T :TYPE-INITIALIZER
1813                  "gtk_calendar_display_options_get_type")
1814                 (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
1815                 (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
1816                 (:SHOW-DETAILS 32))
1817 @end example
1818
1819 @node get-g-interface-definition
1820 @section get-g-interface-definition
1821
1822 @code{get-g-interface-definition type &optional lisp-name-package) @result{} definition}
1823
1824 @table @var
1825 @item @var{type}
1826 A string naming the GInterface type
1827 @item @var{lisp-name-package}
1828 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*}
1829 @item @var{definition}
1830 A Lisp form that when evaluated defines the GInterface.
1831 @end table
1832
1833 Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.
1834
1835 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
1836
1837 Example:
1838 @example
1839 (get-g-interface-definition "GtkActivatable")
1840 @result{}
1841 (DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
1842                     (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
1843                     (USE-ACTION-APPEARANCE
1844                      GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
1845                      "use-action-appearance" "gboolean" T T)
1846                     (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
1847                      "related-action" "GtkAction" T T))
1848 @end example
1849
1850 @node get-g-class-definition
1851 @section get-g-class-definition
1852
1853
1854 @code{get-g-class-definition type &optional lisp-name-package) @result{} definition}
1855
1856 @table @var
1857 @item @var{type}
1858 A string naming the GObject type
1859 @item @var{lisp-name-package}
1860 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*}
1861 @item @var{definition}
1862 A Lisp form that when evaluated defines the GObject.
1863 @end table
1864
1865 Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.
1866
1867 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
1868
1869 Example:
1870 @example
1871 (get-g-class-definition "GtkButton")
1872 @result{}
1873 (DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
1874                        (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
1875                         ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
1876                         :TYPE-INITIALIZER "gtk_button_get_type")
1877                        ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
1878                         (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
1879                         (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
1880                          T)
1881                         (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
1882                          "gboolean" T T)
1883                         (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
1884                          T T)
1885                         (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
1886                          "focus-on-click" "gboolean" T T)
1887                         (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
1888                         (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
1889                         (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
1890                          "image-position" "GtkPositionType" T T)))
1891 @end example
1892
1893 @node Specifying additional properties for CLOS classes
1894 @section Specifying additional properties for CLOS classes
1895
1896 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.
1897
1898 Definitions generator uses variable @code{*additional-properties*} to get this information.
1899
1900 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).
1901
1902 To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
1903
1904 Example:
1905 @example
1906 (("GtkTreeViewColumn"
1907   (:cffi gtk::tree-view
1908          gtk::tree-view-column-tree-view
1909          g-object "gtk_tree_view_column_get_tree_view" nil)
1910   (:cffi gtk::sort-column-id
1911          gtk::tree-view-column-sort-column-id
1912          :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
1913   (:cffi gtk::cell-renderers
1914          gtk::tree-view-column-cell-renderers
1915          (glist g-object  :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
1916  ("GtkTreeSelection"
1917   (:cffi gtk::mode
1918          gtk::tree-selection-mode
1919          gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
1920   (:cffi gtk::select-function
1921          gtk::tree-selection-select-function
1922          nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
1923 @end example
1924
1925 @node Generating names for CLOS classes and accessors
1926 @section Generating names for CLOS classes and accessors
1927
1928 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).
1929
1930 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.
1931
1932 Name generation affected by following variables:
1933 @itemize
1934 @item @var{*strip-prefix*}
1935 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}.
1936 @item @var{*lisp-name-exceptions*}
1937 A plist mapping from strings (type names) to symbols (class names) that have special name processing.
1938 Example:
1939 @example
1940 `(("GObject" gobject:g-object)
1941   ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
1942   ("GInitiallyUnowned" gobject::g-initially-unowned)
1943   ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
1944   ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
1945   ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
1946 @end example
1947 @end itemize
1948
1949 @node generate-types-hierarchy-to-file
1950 @section generate-types-hierarchy-to-file
1951
1952 @example
1953 (generate-types-hierarchy-to-file file
1954                                   root-type
1955                                   &key include-referenced
1956                                   prefix
1957                                   package
1958                                   exceptions
1959                                   prologue
1960                                   interfaces
1961                                   enums
1962                                   flags
1963                                   objects
1964                                   exclusions
1965                                   additional-properties)
1966 @end example
1967
1968 @table @var
1969 @item @var{file}
1970 A string or pathname naming the file, or a stream.
1971 @item @var{root-type}
1972 A GType designator for a root type. All types that inherit from this type will be defined.
1973 @item @var{&key include-referenced}
1974 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
1975 @item @var{prefix}
1976 A string naming the prefix that should be removed from the beginning of names
1977 @item @var{package}
1978 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
1979 @item @var{exceptions}
1980 A plist that maps GType names to their Lisp names.
1981 See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
1982 @item @var{prologue}
1983 A string that will be included verbatim in generated code file
1984 @item @var{interfaces}
1985 Additional list of interfaces that will also be included in generation
1986 @item @var{enums}
1987 Additional list of enums that will also be included in generation
1988 @item @var{flags}
1989 Additional list of flags that will also be included in generation
1990 @item @var{objects}
1991 Additional list of object types that will also be included in generation
1992 @item @var{exclusions}
1993 A list of GType names that will be excluded from generation
1994 @item @var{additional-properties}
1995 A plist of properties definitions that will be added to generated classes.
1996 See @ref{Specifying additional properties for CLOS classes} for more information.
1997 @end table
1998
1999 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.
2000
2001 Example of usage:
2002 @example
2003 (generate-types-hierarchy-to-file
2004  "gtk.generated-classes.lisp"
2005  "GtkObject"
2006  :include-referenced t
2007  :prefix "Gtk"
2008  :package (or (find-package :gtk) (make-package :gtk))
2009  :exceptions `(("GObject" gobject:g-object)
2010                ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2011                ("GInitiallyUnowned" gobject::g-initially-unowned)
2012                ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2013                ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2014                ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2015  :prologue (format nil "(in-package :gtk)")
2016  :interfaces '("GtkBuildable" "GtkCellEditable" ...)
2017  :objects '("GtkSettings" "GtkRcStyle" ...)
2018  :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
2019  :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
2020  :exclusions '("PangoStretch" "PangoVariant" ...)
2021  :additional-properties
2022  '(("GtkTreeViewColumn"
2023     (:cffi
2024      gtk::tree-view
2025      gtk::tree-view-column-tree-view
2026      g-object
2027      "gtk_tree_view_column_get_tree_view"
2028      nil)
2029     ...)
2030    ...))
2031 @end example
2032
2033 @bye
2034