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 bindings
 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 @node Installation
 142 @chapter Installation
 143
 144 CL-GTK2-GObject comes as a part of CL-GTK2 bindings that are avaiable at its @uref{http://common-lisp.net/project/cl-gtk2/,,website}.
 145
 146 To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.
 147
 148 CL-GTK2-GObject defines two packages: @code{gobject} and @code{gobject.ffi}. The @code{gobject.ffi} package contains definitions for low-level CFFI imports. The @code{gobject} package contains symbols for external API of this GObject binding.
 149
 150 @node GType designator
 151 @chapter GType designator
 152
 153 @menu
 154 * g-type-string::
 155 * g-type-numeric::
 156 @end menu
 157
 158 GObject is an object system based on GType type system. Types in it are identified by an integer value of type @code{GType}. In @code{cl-gtk2-gobject}, types are identified by GType designators. GType designator is an integer (equal to corresponding GType identifier) or a string (equal to the name of corresponding type). The important difference between GType and GType designator is that GType values may change between program runs (all GTypes except fundamental GTypes will change values), but string GType designators do not change (because names of types do not change). As such, if ever GType must be saved in a code, string GType designator should be preferred.
 159
 160 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
 161
 162 Some of the types are fundamental and have constant integer values. They are identified by constants:
 163 @itemize
 164 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
 165 @item @code{+g-type-void+}. A fundamental type which is used as a replacement for the C @code{void} return type.
 166 @item @code{+g-type-interface+}. The fundamental type from which all interfaces are derived.
 167 @item @code{+g-type-char+}. The fundamental type corresponding to gchar. The type designated by @code{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.
 168 @item @code{+g-type-uchar+}. The fundamental type corresponding to @code{guchar}.
 169 @item @code{+g-type-boolean+}. The fundamental type corresponding to @code{gboolean}.
 170 @item @code{+g-type-int+}. The fundamental type corresponding to @code{gint}.
 171 @item @code{+g-type-uint+}. The fundamental type corresponding to @code{guint}.
 172 @item @code{+g-type-long+}. The fundamental type corresponding to @code{glong}.
 173 @item @code{+g-type-ulong+}. The fundamental type corresponding to @code{gulong}.
 174 @item @code{+g-type-int64+}. The fundamental type corresponding to @code{gint64}.
 175 @item @code{+g-type-uint64+}. The fundamental type corresponding to @code{guint64}.
 176 @item @code{+g-type-enum+}. The fundamental type from which all enumeration types are derived.
 177 @item @code{+g-type-flags+}. The fundamental type from which all flags types are derived.
 178 @item @code{+g-type-float+}. The fundamental type corresponding to @code{gfloat}.
 179 @item @code{+g-type-double+}. The fundamental type corresponding to @code{gdouble}.
 180 @item @code{+g-type-string+}. The fundamental type corresponding to null-terminated C strings.
 181 @item @code{+g-type-pointer+}. The fundamental type corresponding to @code{gpointer}.
 182 @item @code{+g-type-boxed+}. The fundamental type from which all boxed types are derived.
 183 @item @code{+g-type-param+}. The fundamental type from which all GParamSpec types are derived.
 184 @item @code{+g-type-object+}. The fundamental type for GObject.
 185 @end itemize
 186
 187 Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them).
 188
 189 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
 190
 191 @example
 192 (g-type-numeric "GObject") @result{} 80
 193 (g-type-numeric 80) @result{} 80
 194 (g-type-string "GObject") @result{} "GObject"
 195 (g-type-string 80) @result{} "GObject"
 196 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
 197 @end example
 198
 199 @node g-type-string
 200 @section g-type-string
 201
 202 @code{(g-type-string g-type-designator) @result{} name}
 203
 204 @table @var
 205 @item @var{g-type-designator}
 206 The GType designator for the GType
 207 @item @var{name}
 208 The name of GType
 209 @end table
 210
 211 Returns the name of GType.
 212
 213 @node g-type-numeric
 214 @section g-type-numeric
 215
 216 @code{(g-type-numeric g-type-designator) @result{} GType}
 217
 218 @table @var
 219 @item @var{g-type-designator}.
 220 The GType designator for the GType.
 221 @item @var{GType}
 222 The numeric identifier of GType
 223 @end table
 224
 225 Returns the numeric identifier of GType
 226
 227 @node Type hierarchy and type relations
 228 @chapter Type hierarchy and type relations
 229
 230 @menu
 231 * g-type-children::
 232 * g-type-parent::
 233 * g-type-fundamental::
 234 * g-type-depth::
 235 * g-type-next-base::
 236 @end menu
 237
 238 GTypes are organized into hierarchy. Each GType (except fundamental types) has a parent type and zero or more children types. Parent of GType identified by @code{g-type-parent} function and its children are identified by @code{g-type-children} function.
 239
 240 There are functions to query some specific information:
 241 @itemize
 242 @item @code{g-type-fundamental} retrieves the fundamental type for given type
 243 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
 244 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
 245 @end itemize
 246
 247 @node g-type-children
 248 @section g-type-children
 249
 250 @code{(g-type-children type) @result{} children}
 251 @table @var
 252 @item @var{type}
 253 A GType designator
 254 @item @var{children}
 255 A list of GType designators
 256 @end table
 257
 258 Returns the list of descendent types.
 259
 260 Example:
 261 @example
 262 (g-type-children "GtkButton")
 263 @result{}
 264 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
 265 @end example
 266
 267 @node g-type-parent
 268 @section g-type-parent
 269
 270 @code{(g-type-parent type) @result{} parent}
 271
 272 @table @var
 273 @item @var{type}
 274 A GType designator
 275 @item @var{parent}
 276 A GType designator
 277 @end table
 278
 279 Returns the parent of @code{type}.
 280
 281 Example:
 282 @example
 283 (g-type-parent "GtkToggleButton")
 284 @result{}
 285 "GtkButton"
 286 @end example
 287 @node g-type-fundamental
 288 @section g-type-fundamental
 289
 290 @code{(g-type-fundamental type) @result{} fundamental-type}
 291
 292 @table @var
 293 @item @var{type}
 294 A GType designator
 295 @item @var{fundamental-type}
 296 A GType designator for one of the fundamental types
 297 @end table
 298
 299 Returns the fundamental type that is the ancestor of @code{type}.
 300
 301 Example:
 302 @example
 303 (g-type-fundamental "GtkButton") @result{} "GObject"
 304
 305 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
 306
 307 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
 308 @end example
 309
 310 @node g-type-depth
 311 @section g-type-depth
 312
 313 @code{(g-type-depth type) @result{} depth}
 314
 315 @table @var
 316 @item @var{type}
 317 A GType designator
 318 @item @var{depth}
 319 An integer
 320 @end table
 321
 322 Returns the depth of the @code{type}. Depth is the number of types between the @code{type} and its fundamental types (including both @code{type} and its fundamental type). Depth of a fundamental type equals to 1.
 323
 324 Example:
 325 @example
 326 (g-type-depth "GObject") @result{} 1
 327 (g-type-depth "GInitiallyUnowned") @result{} 2
 328 @end example
 329
 330 @node g-type-next-base
 331 @section g-type-next-base
 332
 333 @code{(g-type-next-base leaf-type root-type) @result{} base-type}
 334
 335 @table @var
 336 @item @var{leaf-type}
 337 A GType designator
 338 @item @var{root-type}
 339 A GType designator
 340 @item @var{base-type}
 341 A GType designator
 342 @end table
 343
 344 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
 345 @example
 346 + GObject
 347  \
 348   + GInitiallyUnowned
 349    \
 350     + GtkObject
 351     |\
 352     | + GtkAdjustment
 353      \
 354       + GtkWidget
 355        \
 356         + GtkContainer
 357          \
 358           + GtkTable
 359 @end example
 360
 361 the following will be returned:
 362
 363 @example
 364 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
 365 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
 366 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
 367 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
 368 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
 369 @end example
 370
 371 @node Object types information
 372 @chapter Object types information
 373 @menu
 374 * g-class-property-definition::
 375 * class-properties::
 376 * class-property-info::
 377 * interface-properties::
 378 * signal-info::
 379 * type-signals::
 380 * parse-signal-name::
 381 * query-signal-info::
 382 * g-type-interfaces::
 383 * g-type-interface-prerequisites::
 384 @end menu
 385
 386 GObject classes and interfaces have properties that can be queried with @code{class-properties}, @code{class-property-info} and @code{interface-properties}. These functions represent information about properties with instances of @code{g-class-property-definition} structure.
 387
 388 Information about signals can be queries with @code{type-signals}, @code{parse-signal-name} and @code{query-signal-info} functions. Information is returned within instances of @code{signal-info} structures.
 389
 390 @node g-class-property-definition
 391 @section g-class-property-definition
 392
 393 @example
 394 (defstruct g-class-property-definition
 395   name
 396   type
 397   readable
 398   writable
 399   constructor
 400   constructor-only
 401   owner-type)
 402 @end example
 403
 404 @table @var
 405 @item @var{name}
 406 A string that names the property
 407 @item @var{type}
 408 A GType designator. Identifies the type of the property
 409 @item @var{readable}
 410 A boolean. Identifies whether the property can be read
 411 @item @var{writable}
 412 A boolean. Identifies whether the property can be assigned
 413 @item @var{constructor}
 414 A boolean. Identifies whether constructor of object accepts this property
 415 @item @var{constructor-only}
 416 A boolean. Identifies whether this property may only be set in constructor, not in property setter
 417 @item @var{owner-type}
 418 A GType designator. Identifies the type on which the property was defined.
 419 @end table
 420
 421 This structure identifies a single property. Its field specify attributes of a property.
 422
 423 Structures of this type have shortened print syntax:
 424 @example
 425 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 426 @end example
 427
 428 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
 429
 430 This syntax specifies:
 431 @itemize
 432 @item type of property
 433 @item the owner type of property
 434 @item name of property
 435 @item additional flags of property
 436 @end itemize
 437
 438 @node class-properties
 439 @section class-properties
 440
 441 @code{(class-properties type) @result{} properties}
 442
 443 @table @var
 444 @item @var{type}
 445 A GType designator. Specifies the object type (class)
 446 @item @var{properties}
 447 A list of @code{g-property-definition} structures.
 448 @end table
 449
 450 This function returns the list of properties that are available in class @code{type}.
 451
 452 Example:
 453 @example
 454 (class-properties "GtkWidget")
 455 @result{}
 456 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
 457  #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
 458  #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
 459  #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
 460  #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
 461  #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
 462  #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
 463  #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
 464  #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
 465  #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
 466  #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
 467  #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
 468  #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
 469  #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
 470  #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
 471  #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
 472  #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
 473  #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
 474  #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
 475  #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
 476  #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
 477  #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
 478  #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
 479 @end example
 480
 481 @node class-property-info
 482 @section class-property-info
 483 @code{(class-property-info type property-name) @result{} property}
 484
 485 @table @var
 486 @item @var{type}
 487 A GType designator
 488 @item @var{property-name}
 489 A string naming the property
 490 @item @var{property}
 491 An instance of @code{g-property-definition} structure
 492 @end table
 493
 494 Returns the property information for a single property.
 495
 496 Example:
 497 @example
 498 (class-property-info "GtkButton" "label")
 499 @result{}
 500 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 501 @end example
 502
 503 @node interface-properties
 504 @section interface-properties
 505
 506 @code{(interface-properties type) @result{} properties}
 507
 508 @table @var
 509 @item @var{type}
 510 A GType designator
 511 @item @var{properties}
 512 A list of @code{g-property-definition} structures
 513 @end table
 514
 515 This function returns the list of properties that are available in interface @code{type}.
 516
 517 Example:
 518 @example
 519 (interface-properties "GtkFileChooser")
 520 @result{}
 521 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
 522  #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
 523  #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
 524  #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
 525  #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
 526  #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
 527  #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
 528  #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
 529  #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
 530  #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
 531  #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
 532 @end example
 533
 534 @node signal-info
 535 @section signal-info
 536
 537 @example
 538 (defstruct signal-info
 539   id
 540   name
 541   owner-type
 542   flags
 543   return-type
 544   param-types
 545   detail)
 546 @end example
 547
 548 @table @var
 549 @item @var{id}
 550 An integer - the identifier of a signal
 551 @item @var{name}
 552 Name of a signal
 553 @item @var{owner-type}
 554 A GType designator identifying the type on which the signal was defined
 555 @item @var{flags}
 556 A list of keywords of type @code{'(member :run-first :run-last :run-cleanup :no-recurse :detailed :action :no-hooks)}. Specifies the attributes of a signals
 557 @item @var{return-type}
 558 The return type of a signal (and signal handlers)
 559 @item @var{param-types}
 560 A list of GType designators that specify the types of signal parameters
 561 @item @var{detail}
 562 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
 563 @end table
 564
 565 When @code{*print-readably*} is nil, the following print syntax is used:
 566 @example
 567 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 568 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
 569 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
 570 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
 571 @end example
 572
 573 This syntax specifies:
 574 @itemize
 575 @item the signal id
 576 @item signal return type
 577 @item owner type
 578 @item signal name
 579 @item detail
 580 @item list of types of parameters
 581 @item flags
 582 @end itemize
 583
 584 @node type-signals
 585 @section type-signals
 586 @code{(type-signals type &key (include-inherited t)) @result{} signals}
 587 @table @var
 588 @item @var{type}
 589 A GType designator
 590 @item @var{signals}
 591 A list of @code{signal-info} structures
 592 @item @var{include-inherited}
 593 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
 594 @end table
 595
 596 Returns the list of signals that are available in type @code{type}.
 597
 598 Example:
 599 @example
 600 (type-signals "GtkLabel" :include-inherited nil)
 601 @result{}
 602 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
 603  #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
 604  #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
 605 @end example
 606
 607 @node parse-signal-name
 608 @section parse-signal-name
 609
 610 @code{(parse-signal-name type signal-name) @result{} signal}
 611
 612 @table @var
 613 @item @var{type}
 614 A GType designator that has the signal.
 615 @item @var{signal-name}
 616 A string that identifies the signal.
 617 @item @var{signal}
 618 A list @code{signal-info} structures.
 619 @end table
 620
 621 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
 622
 623 Example:
 624 @example
 625 (parse-signal-name "GObject" "notify::label")
 626 @result{}
 627 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 628 @end example
 629
 630 @node query-signal-info
 631 @section query-signal-info
 632 @code{(query-signal-info signal-id) @result{} signal}
 633 @table @var
 634 @item @var{signal-id}
 635 An integer identifying the signal
 636 @item @var{signal}
 637 An instance of @code{signal-info} structure
 638 @end table
 639
 640 Retrieves the signal information by its id.
 641
 642 Example:
 643 @example
 644 (query-signal-info 73)
 645 @result{}
 646 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
 647 @end example
 648
 649 @node g-type-interfaces
 650 @section g-type-interfaces
 651
 652 @code{(g-type-interfaces type) @result{} interfaces}
 653
 654 @table @var
 655 @item @var{type}
 656 A GType designator
 657 @item @var{interfaces}
 658 A list of GType designators
 659 @end table
 660
 661 Returns the list of interfaces that @code{type} implements.
 662
 663 Example:
 664 @example
 665 (g-type-interfaces "GtkButton")
 666 @result{}
 667 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
 668 @end example
 669
 670 @node g-type-interface-prerequisites
 671 @section g-type-interface-prerequisites
 672
 673 @code{(g-type-interface-prerequisites type) @result{} types}
 674
 675 @table @var
 676 @item @var{type}
 677 A GType designator of interface
 678 @item @var{types}
 679 A list of GType designators specifying the interface prerequisites
 680 @end table
 681
 682 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
 683
 684 Example:
 685 @example
 686 (g-type-interface-prerequisites "GtkCellEditable")
 687 @result{}
 688 ("GtkObject" "GtkWidget")
 689 @end example
 690
 691 @node Enum types information
 692 @chapter Enum types information
 693 @menu
 694 * enum-item::
 695 * flags-item::
 696 * get-enum-items::
 697 * get-flags-items::
 698 @end menu
 699
 700 Enum types have items that can be listed with @code{get-enum-items} function. This information is exposed within instances of @code{enum-item} structure.
 701
 702 Flags types (flags is a kind of enum whose values can be combined) have items that can be queried with @code{get-flags-items} function. This information is exposed within instances of @code{flags-item} structure.
 703
 704 @node enum-item
 705 @section enum-item
 706 @example
 707 (defstruct enum-item
 708   name value nick)
 709 @end example
 710
 711 @table @var
 712 @item @var{name}
 713 A string - name of enum item
 714 @item @var{value}
 715 An integer - numeric value of enum item
 716 @item @var{nick}
 717 A string - short name of an enum item
 718 @end table
 719
 720 Structure @code{enum-item} represents a single item of an enumeration type.
 721
 722 Example:
 723 @example
 724 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
 725 @end example
 726
 727 @node flags-item
 728 @section flags-item
 729 @example
 730 (defstruct flags-item
 731   name value nick)
 732 @end example
 733
 734 @table @var
 735 @item @var{name}
 736 A string - name of flags item
 737 @item @var{value}
 738 An integer - numeric value of flags item
 739 @item @var{nick}
 740 A string - short name of an flags item
 741 @end table
 742
 743 Structure @code{flags-item} represents a single item of an flags type.
 744
 745 Example:
 746 @example
 747 #S(FLAGS-ITEM
 748    :NAME "GDK_POINTER_MOTION_HINT_MASK"
 749    :VALUE 8
 750    :NICK "pointer-motion-hint-mask")
 751 @end example
 752
 753 @node get-enum-items
 754 @section get-enum-items
 755
 756 @code{(get-enum-items type) @result{} items}
 757
 758 @table @var
 759 @item @var{type}
 760 A GType designator of an enum type
 761 @item @var{items}
 762 A list of @code{enum-item} structures
 763 @end table
 764
 765 Returns a list of items in an enumeration
 766
 767 Example:
 768 @example
 769 (get-enum-items "GtkScrollType")
 770 @result{}
 771 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
 772  #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
 773  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
 774  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
 775  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
 776  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
 777  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
 778  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
 779  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
 780  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
 781  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
 782  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
 783  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
 784  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
 785  #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
 786  #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
 787 @end example
 788
 789 @node get-flags-items
 790 @section get-flags-items
 791
 792 @code{(get-flags-items type) @result{} items}
 793
 794 @table @var
 795 @item @var{type}
 796 A GType designator of an flags type
 797 @item @var{items}
 798 A list of @code{flags-item} structures
 799 @end table
 800
 801 Returns a list of items in an flags type
 802
 803 Example:
 804 @example
 805 (get-flags-items "GtkAttachOptions")
 806 @result{}
 807 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
 808  #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
 809  #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
 810 @end example
 811
 812 @node Using GValues
 813 @chapter Using GValues
 814 @menu
 815 * g-value-zero::
 816 * g-value-init::
 817 * g-value-unset::
 818 * parse-g-value::
 819 * set-g-value::
 820 @end menu
 821
 822 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
 823
 824 CL-GTK2-GOBJECT works with GValue as a foreign type @code{g-value}. Functions @code{g-value-zero}, @code{g-value-type}, @code{g-value-init}, @code{parse-g-value}, @code{set-g-value} are used to inspect and assign GValues. @code{g-value} is a CFFI foreign type that is used by all these functions. Pointer to foreign instance of this type is passed to them.
 825
 826 GValue is used whenever a value of unkown type should be passed. It is used in:
 827 @itemize
 828 @item Closure marshal functions
 829 @item Property get and set functions
 830 @end itemize
 831
 832 Example of usage:
 833 @example
 834 (cffi:with-foreign-object (gval 'g-value)
 835   (set-g-value gval "Hello" "gchararray" :zero-g-value t)
 836   (format t "~S~%" (parse-g-value gval))
 837   (g-value-unset gval))
 838 @result{}
 839 "Hello"
 840 @end example
 841
 842 @node g-value-zero
 843 @section g-value-zero
 844 @code{(g-value-zero g-value)}
 845 @table @var
 846 @item @var{g-value}
 847 A foreign pointer to GValue structure.
 848 @end table
 849
 850 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
 851 @example
 852 GValue value = @{ 0 @};
 853 @end example
 854
 855 Must be called before other functions that work with GValue (except @code{set-g-value} with keyword argument @code{:zero-g-value} set to true).
 856
 857 @node g-value-init
 858 @section g-value-init
 859
 860 @code{(g-value-init value type)}
 861 @table @var
 862 @item @var{value}
 863 A foreign pointer to GValue structure
 864 @item @var{type}
 865 A GType designator
 866 @end table
 867
 868 Initializes the GValue to store instances of type @code{type}. Must be called before other functions operate on GValue (except @code{g-value-zero} and @code{set-g-value} with keyword argument @code{:g-value-init} set to true).
 869
 870 @node g-value-unset
 871 @section g-value-unset
 872 @code{(g-value-unset value)}
 873 @table @var
 874 @item @var{value}
 875 A foreign pointer to GValue structure.
 876 @end table
 877
 878 Unsets the GValue. This frees all resources associated with GValue.
 879
 880 @node parse-g-value
 881 @section parse-g-value
 882 @code{(parse-g-value value) @result{} object}
 883 @table @var
 884 @item @var{value}
 885 A foreign pointer to GValue structure
 886 @item @var{object}
 887 A Lisp object
 888 @end table
 889
 890 Retrieves the object from GValue structure.
 891
 892 @node set-g-value
 893 @section set-g-value
 894 @code{(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))}
 895
 896 @table @var
 897 @item @var{gvalue}
 898 A foreign pointer to GValue structure
 899 @item @var{object}
 900 An object that is to be assigned to @code{gvalue}
 901 @item @var{type}
 902 A GType designator specifying what GType should be set
 903 @item @var{unset-g-value}
 904 A boolean specifying whether to call @code{g-value-unset} before assigment.
 905 @item @var{zero-g-value}
 906 A boolean specifying whether to call @code{g-value-zero} before assignment
 907 @item @var{g-value-init}
 908 A boolean specifying whether to call @code{g-value-init} before assignment
 909 @end table
 910
 911 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
 912
 913 @node Stable pointers
 914 @chapter Stable pointers
 915 @menu
 916 * allocate-stable-pointer::
 917 * free-stable-pointer::
 918 * stable-pointer-value::
 919 * with-stable-pointer::
 920 @end menu
 921
 922 Sometimes it is necessary to pass arbitrary Lisp object to C code and then receive it back. Stable pointer serve to this purpose. Stable pointer is an integer (that is passed to C code as a @code{void*} pointer) that is created on Lisp side by call to @code{allocate-stable-pointer} and can be dereferenced by Lisp side at any time by calling @code{stable-pointer-value}. Stable pointer exists and does not change its value until explicitly freed by calling @code{free-stable-poitner}. Convenience macro @code{with-stable-pointer} binds the stable pointer for the duration of its body.
 923
 924 @node allocate-stable-pointer
 925 @section allocate-stable-pointer
 926
 927 @code{(allocate-stable-pointer thing) @result{} stable-pointer}
 928
 929 @table @var
 930 @item @var{thing}
 931 An arbitrary Lisp object
 932 @item @var{stable-pointer}
 933 A foreign pointer
 934 @end table
 935
 936 Allocates a stable pointer to @code{thing}.
 937
 938 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
 939
 940 Example:
 941 @example
 942 (allocate-stable-pointer (lambda (x) (+ x 10)))
 943 @result{}
 944 #.(SB-SYS:INT-SAP #X00000002)
 945
 946 (stable-pointer-value *)
 947 @result{}
 948 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
 949
 950 (free-stable-pointer **)
 951 @result{}
 952 NIL
 953 @end example
 954
 955 @node free-stable-pointer
 956 @section free-stable-pointer
 957
 958 @code{(free-stable-pointer stable-pointer)}
 959
 960 @table @var
 961 @item @var{stable-pointer}
 962 A foreign pointer that was created with @code{allocate-stable-pointer}.
 963 @end table
 964
 965 Frees the stable pointer, enabling the garbage collector to reclaim the object.
 966
 967 Example:
 968 @example
 969 (allocate-stable-pointer (lambda (x) (+ x 10)))
 970 @result{}
 971 #.(SB-SYS:INT-SAP #X00000002)
 972
 973 (stable-pointer-value *)
 974 @result{}
 975 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
 976
 977 (free-stable-pointer **)
 978 @result{}
 979 NIL
 980 @end example
 981
 982 @node stable-pointer-value
 983 @section stable-pointer-value
 984
 985 @code{(stable-pointer-value stable-pointer) @result{} thing}
 986
 987 @code{(setf (stable-pointer-value stable-pointer) thing)}
 988
 989 @table @var
 990 @item @var{stable-pointer}
 991 A foreign pointer created by @code{allocate-stable-pointer}
 992 @item @var{thing}
 993 A Lisp object
 994 @end table
 995
 996 Dereferences a @code{stable-pointer}, returning the stable pointer value. @code{stable-pointer-value} is a SETFable form, SETFing it sets the stable pointer's value to new value.
 997
 998 @node with-stable-pointer
 999 @section with-stable-pointer
1000
1001 @code{(with-stable-pointer (ptr expr) &body body)}
1002
1003 @table @var
1004 @item @var{ptr}
1005 A variable that will be bound to the stable pointer
1006 @item @var{expr}
1007 An expression that will be evaluated once and its value will be bound to stable pointer's value
1008 @end table
1009
1010 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1011
1012 Example:
1013 @example
1014 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1015   (print (stable-pointer-value ptr)))
1016 ;;Prints:
1017 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1018 @end example
1019
1020 @node Closures
1021 @chapter Closures
1022
1023 GObject supports using closures (as instances of type GClosure) as signal handlers and in some other places where a function is expected. Function @code{create-g-closure} create closure from lisp function. The GClosure is finalized automatically when GObject no longer needs it (e.g., when GClosure is disconnected from signal).
1024
1025 @section create-g-closure
1026
1027 @node GObject low-level
1028 @chapter GObject low-level
1029
1030 GObject low-level support includes facilities for working with objects as foreign pointers and using explicit function to get and set properties.
1031
1032 Function @code{g-type-from-object} identifies the type of the object. Function @code{g-object-call-get-property} retrieves the value of the property and function @code{g-object-call-set-property} sets the value of the property. Function @code{g-object-call-constructor} calls the constructor of the GObject type.
1033
1034 @section g-type-from-object
1035
1036 @section g-object-call-get-property
1037
1038 @section g-object-call-set-property
1039
1040 @section g-object-call-constructor
1041
1042 @node GObject high-level
1043 @chapter GObject high-level
1044
1045 @node Subclassing GObjects and implementing GInterfaces
1046 @chapter Subclassing GObjects and implementing GInterfaces
1047
1048 @node GBoxed
1049 @chapter GBoxed
1050
1051 @node Generating type definitions by introspection
1052 @chapter Generating type definitions by introspection
1053
1054
1055 @bye
1056