doc/gobject.ref.texi

   1
   2 @menu
   3 * Introduction::
   4 * GType designator::
   5 * Type hierarchy and type relations::
   6 * Object types information::
   7 * Enum types information::
   8 * Using GValues::
   9 * Stable pointers::
  10 * Closures::
  11 * GObject low-level::
  12 * GObject high-level::
  13 * Creating GObjects classes and implementing GInterfaces::
  14 * GBoxed::
  15 * Generating type definitions by introspection::
  16 @end menu
  17
  18 @node Introduction
  19 @chapter Introduction
  20
  21 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.
  22
  23 The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.
  24
  25 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.
  26
  27 CL-GTK2-GObject is logically split into several layers:
  28 @itemize
  29 @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.
  30 @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.
  31 @item High-level GObject integration. This layer includes support for interoperability between CLOS and GObject and automatic generation of corresponding definitions.
  32 @end itemize
  33
  34 Naturally, users of CL-GTK2-GObject should use the high-level GObject integration, but occasionaly it may be necessary to use lower-level functionality.
  35
  36 @node GType designator
  37 @chapter GType designator
  38
  39 @menu
  40 * g-type-string::
  41 * g-type-numeric::
  42 * g-type=::
  43 * g-type/=::
  44 @end menu
  45
  46 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.
  47
  48 An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.
  49
  50 Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
  51 @itemize
  52 @item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
  53 @item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
  54 @item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
  55 @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}.
  56 @item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
  57 @item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
  58 @item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
  59 @item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
  60 @item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
  61 @item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
  62 @item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
  63 @item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
  64 @item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
  65 @item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
  66 @item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
  67 @item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
  68 @item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
  69 @item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
  70 @item @code{+g-type-boxed+} ("GBoxed"). The fundamental type from which all boxed types are derived. Values of this type correspond to by-value structures.
  71 @item @code{+g-type-param+} ("GParam"). The fundamental type from which all GParamSpec types are derived. Values of this type correspond to instances of structure @code{g-class-property-definition}.
  72 @item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
  73 @end itemize
  74
  75 Functions @ref{g-type-string} and @ref{g-type-numeric} return the numeric and string representations of GType designators (given any of them). Functions @ref{g-type=} and @ref{g-type/=} check types for equality.
  76
  77 Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.
  78
  79 @lisp
  80 (g-type-numeric "GObject") @result{} 80
  81 (g-type-numeric 80) @result{} 80
  82 (g-type-string "GObject") @result{} "GObject"
  83 (g-type-string 80) @result{} "GObject"
  84 (g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
  85 @end lisp
  86
  87 @node g-type-string
  88 @section g-type-string
  89
  90 @Function g-type-string
  91 @lisp
  92 (g-type-string g-type-designator) @result{} name
  93 @end lisp
  94
  95 @table @var
  96 @item @var{g-type-designator}
  97 The GType designator for the GType
  98 @item @var{name}
  99 The name of GType
 100 @end table
 101
 102 Returns the name of GType.
 103
 104 @node g-type-numeric
 105 @section g-type-numeric
 106
 107 @Function g-type-numeric
 108 @lisp
 109 (g-type-numeric g-type-designator) @result{} GType
 110 @end lisp
 111
 112 @table @var
 113 @item @var{g-type-designator}.
 114 The GType designator for the GType.
 115 @item @var{GType}
 116 The numeric identifier of GType
 117 @end table
 118
 119 Returns the numeric identifier of GType
 120
 121 @node g-type=
 122 @section g-type=
 123
 124 @Function g-type=
 125 @lisp
 126 (g-type= type-1 type-2) @result{} eq
 127 @end lisp
 128
 129 @table @var
 130 @item @var{type-1}
 131 A GType designator
 132 @item @var{type-2}
 133 A GType designator
 134 @item @var{eq}
 135 A boolean that is true if @code{type-1} and @code{type-2} designate the same type.
 136 @end table
 137
 138 @node g-type/=
 139 @section g-type/=
 140
 141 @Function g-type/=
 142 @lisp
 143 (g-type/= type-1 type-2) @result{} eq
 144 @end lisp
 145
 146 @table @var
 147 @item @var{type-1}
 148 A GType designator
 149 @item @var{type-2}
 150 A GType designator
 151 @item @var{eq}
 152 A boolean that is true if @code{type-1} and @code{type-2} designate different types.
 153 @end table
 154
 155 @node Type hierarchy and type relations
 156 @chapter Type hierarchy and type relations
 157
 158 @menu
 159 * g-type-children::
 160 * g-type-parent::
 161 * g-type-fundamental::
 162 * g-type-depth::
 163 * g-type-next-base::
 164 @end menu
 165
 166 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.
 167
 168 There are functions to query some specific information:
 169 @itemize
 170 @item @code{g-type-fundamental} retrieves the fundamental type for given type
 171 @item @code{g-type-depth} calculates the depth of the type in type hierarchy
 172 @item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
 173 @end itemize
 174
 175 @node g-type-children
 176 @section g-type-children
 177
 178 @Function g-type-children
 179 @lisp
 180 (g-type-children type) @result{} children
 181 @end lisp
 182
 183 @table @var
 184 @item @var{type}
 185 A GType designator
 186 @item @var{children}
 187 A list of GType designators
 188 @end table
 189
 190 Returns the list of descendent types.
 191
 192 Example:
 193 @lisp
 194 (g-type-children "GtkButton")
 195 @result{}
 196 ("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
 197 @end lisp
 198
 199 @node g-type-parent
 200 @section g-type-parent
 201
 202 @Function g-type-parent
 203 @lisp
 204 (g-type-parent type) @result{} parent
 205 @end lisp
 206
 207 @table @var
 208 @item @var{type}
 209 A GType designator
 210 @item @var{parent}
 211 A GType designator
 212 @end table
 213
 214 Returns the parent of @code{type}.
 215
 216 Example:
 217 @lisp
 218 (g-type-parent "GtkToggleButton")
 219 @result{}
 220 "GtkButton"
 221 @end lisp
 222
 223 @node g-type-fundamental
 224 @section g-type-fundamental
 225
 226 @Function g-type-fundamental
 227 @lisp
 228 (g-type-fundamental type) @result{} fundamental-type
 229 @end lisp
 230
 231 @table @var
 232 @item @var{type}
 233 A GType designator
 234 @item @var{fundamental-type}
 235 A GType designator for one of the fundamental types
 236 @end table
 237
 238 Returns the fundamental type that is the ancestor of @code{type}.
 239
 240 Example:
 241 @lisp
 242 (g-type-fundamental "GtkButton") @result{} "GObject"
 243
 244 (g-type-fundamental "GtkWindowType") @result{} "GEnum"
 245
 246 (g-type-fundamental "GdkEvent") @result{} "GBoxed"
 247 @end lisp
 248
 249 @node g-type-depth
 250 @section g-type-depth
 251
 252 @Function g-type-depth
 253 @lisp
 254 (g-type-depth type) @result{} depth
 255 @end lisp
 256
 257 @table @var
 258 @item @var{type}
 259 A GType designator
 260 @item @var{depth}
 261 An integer
 262 @end table
 263
 264 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.
 265
 266 Example:
 267 @lisp
 268 (g-type-depth "GObject") @result{} 1
 269 (g-type-depth "GInitiallyUnowned") @result{} 2
 270 @end lisp
 271
 272 @node g-type-next-base
 273 @section g-type-next-base
 274
 275 @Function g-type-next-base
 276 @lisp
 277 (g-type-next-base leaf-type root-type) @result{} base-type
 278 @end lisp
 279
 280 @table @var
 281 @item @var{leaf-type}
 282 A GType designator
 283 @item @var{root-type}
 284 A GType designator
 285 @item @var{base-type}
 286 A GType designator
 287 @end table
 288
 289 Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
 290 @lisp
 291 + GObject
 292  \
 293   + GInitiallyUnowned
 294    \
 295     + GtkObject
 296     |\
 297     | + GtkAdjustment
 298      \
 299       + GtkWidget
 300        \
 301         + GtkContainer
 302          \
 303           + GtkTable
 304 @end lisp
 305
 306 the following will be returned:
 307
 308 @lisp
 309 (g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
 310 (g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
 311 (g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
 312 (g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
 313 (g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
 314 @end lisp
 315
 316 @node Object types information
 317 @chapter Object types information
 318 @menu
 319 * g-class-property-definition::
 320 * class-properties::
 321 * class-property-info::
 322 * interface-properties::
 323 * signal-info::
 324 * type-signals::
 325 * parse-signal-name::
 326 * query-signal-info::
 327 * g-type-interfaces::
 328 * g-type-interface-prerequisites::
 329 @end menu
 330
 331 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.
 332
 333 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.
 334
 335 @node g-class-property-definition
 336 @section g-class-property-definition
 337
 338 @Struct g-class-property-definition
 339 @lisp
 340 (defstruct g-class-property-definition
 341   name
 342   type
 343   readable
 344   writable
 345   constructor
 346   constructor-only
 347   owner-type)
 348 @end lisp
 349
 350 @table @var
 351 @item @var{name}
 352 A string that names the property
 353 @item @var{type}
 354 A GType designator. Identifies the type of the property
 355 @item @var{readable}
 356 A boolean. Identifies whether the property can be read
 357 @item @var{writable}
 358 A boolean. Identifies whether the property can be assigned
 359 @item @var{constructor}
 360 A boolean. Identifies whether constructor of object accepts this property
 361 @item @var{constructor-only}
 362 A boolean. Identifies whether this property may only be set in constructor, not in property setter
 363 @item @var{owner-type}
 364 A GType designator. Identifies the type on which the property was defined.
 365 @end table
 366
 367 This structure identifies a single property. Its field specify attributes of a property.
 368
 369 Structures of this type have shortened print syntax:
 370 @lisp
 371 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 372 @end lisp
 373
 374 (When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)
 375
 376 This syntax specifies:
 377 @itemize
 378 @item type of property
 379 @item the owner type of property
 380 @item name of property
 381 @item additional flags of property
 382 @end itemize
 383
 384 @node class-properties
 385 @section class-properties
 386
 387 @Function class-properties
 388 @lisp
 389 (class-properties type) @result{} properties
 390 @end lisp
 391
 392 @table @var
 393 @item @var{type}
 394 A GType designator. Specifies the object type (class)
 395 @item @var{properties}
 396 A list of @code{g-property-definition} structures.
 397 @end table
 398
 399 This function returns the list of properties that are available in class @code{type}.
 400
 401 Example:
 402 @lisp
 403 (class-properties "GtkWidget")
 404 @result{}
 405 (#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
 406  #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
 407  #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
 408  #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
 409  #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
 410  #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
 411  #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
 412  #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
 413  #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
 414  #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
 415  #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
 416  #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
 417  #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
 418  #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
 419  #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
 420  #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
 421  #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
 422  #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
 423  #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
 424  #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
 425  #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
 426  #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
 427  #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
 428 @end lisp
 429
 430 @node class-property-info
 431 @section class-property-info
 432 @Function class-property-info
 433 @lisp
 434 (class-property-info type property-name) @result{} property
 435 @end lisp
 436
 437 @table @var
 438 @item @var{type}
 439 A GType designator
 440 @item @var{property-name}
 441 A string naming the property
 442 @item @var{property}
 443 An instance of @code{g-property-definition} structure
 444 @end table
 445
 446 Returns the property information for a single property.
 447
 448 Example:
 449 @lisp
 450 (class-property-info "GtkButton" "label")
 451 @result{}
 452 #<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
 453 @end lisp
 454
 455 @node interface-properties
 456 @section interface-properties
 457
 458 @Function interface-properties
 459 @lisp
 460 (interface-properties type) @result{} properties
 461 @end lisp
 462
 463 @table @var
 464 @item @var{type}
 465 A GType designator
 466 @item @var{properties}
 467 A list of @code{g-property-definition} structures
 468 @end table
 469
 470 This function returns the list of properties that are available in interface @code{type}.
 471
 472 Example:
 473 @lisp
 474 (interface-properties "GtkFileChooser")
 475 @result{}
 476 (#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
 477  #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
 478  #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
 479  #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
 480  #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
 481  #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
 482  #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
 483  #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
 484  #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
 485  #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
 486  #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
 487 @end lisp
 488
 489 @node signal-info
 490 @section signal-info
 491
 492 @Struct signal-info
 493 @lisp
 494 (defstruct signal-info
 495   id
 496   name
 497   owner-type
 498   flags
 499   return-type
 500   param-types
 501   detail)
 502 @end lisp
 503
 504 @table @var
 505 @item @var{id}
 506 An integer - the identifier of a signal
 507 @item @var{name}
 508 Name of a signal
 509 @item @var{owner-type}
 510 A GType designator identifying the type on which the signal was defined
 511 @item @var{flags}
 512 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
 513 @item @var{return-type}
 514 The return type of a signal (and signal handlers)
 515 @item @var{param-types}
 516 A list of GType designators that specify the types of signal parameters
 517 @item @var{detail}
 518 A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
 519 @end table
 520
 521 When @code{*print-readably*} is nil, the following print syntax is used:
 522 @lisp
 523 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 524 #<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
 525 #<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
 526 #<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
 527 @end lisp
 528
 529 This syntax specifies:
 530 @itemize
 531 @item the signal id
 532 @item signal return type
 533 @item owner type
 534 @item signal name
 535 @item detail
 536 @item list of types of parameters
 537 @item flags
 538 @end itemize
 539
 540 @node type-signals
 541 @section type-signals
 542 @Function type-signals
 543 @lisp
 544 (type-signals type &key (include-inherited t)) @result{} signals
 545 @end lisp
 546 @table @var
 547 @item @var{type}
 548 A GType designator
 549 @item @var{signals}
 550 A list of @code{signal-info} structures
 551 @item @var{include-inherited}
 552 A boolean that specifies whether to include signals defined on this type or also on ancestor types.
 553 @end table
 554
 555 Returns the list of signals that are available in type @code{type}.
 556
 557 Example:
 558 @lisp
 559 (type-signals "GtkLabel" :include-inherited nil)
 560 @result{}
 561 (#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
 562  #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
 563  #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
 564 @end lisp
 565
 566 @node parse-signal-name
 567 @section parse-signal-name
 568
 569 @Function parse-signal-name
 570 @lisp
 571 (parse-signal-name type signal-name) @result{} signal
 572 @end lisp
 573
 574 @table @var
 575 @item @var{type}
 576 A GType designator that has the signal.
 577 @item @var{signal-name}
 578 A string that identifies the signal.
 579 @item @var{signal}
 580 A list @code{signal-info} structures.
 581 @end table
 582
 583 Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.
 584
 585 Example:
 586 @lisp
 587 (parse-signal-name "GObject" "notify::label")
 588 @result{}
 589 #<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
 590 @end lisp
 591
 592 @node query-signal-info
 593 @section query-signal-info
 594 @Function query-signal-info
 595 @lisp
 596 (query-signal-info signal-id) @result{} signal
 597 @end lisp
 598 @table @var
 599 @item @var{signal-id}
 600 An integer identifying the signal
 601 @item @var{signal}
 602 An instance of @code{signal-info} structure
 603 @end table
 604
 605 Retrieves the signal information by its id.
 606
 607 Example:
 608 @lisp
 609 (query-signal-info 73)
 610 @result{}
 611 #<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
 612 @end lisp
 613
 614 @node g-type-interfaces
 615 @section g-type-interfaces
 616
 617 @Function g-type-interfaces
 618 @lisp
 619 (g-type-interfaces type) @result{} interfaces
 620 @end lisp
 621
 622 @table @var
 623 @item @var{type}
 624 A GType designator
 625 @item @var{interfaces}
 626 A list of GType designators
 627 @end table
 628
 629 Returns the list of interfaces that @code{type} implements.
 630
 631 Example:
 632 @lisp
 633 (g-type-interfaces "GtkButton")
 634 @result{}
 635 ("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
 636 @end lisp
 637
 638 @node g-type-interface-prerequisites
 639 @section g-type-interface-prerequisites
 640
 641 @Function g-type-interface-prerequisites
 642 @lisp
 643 (g-type-interface-prerequisites type) @result{} types
 644 @end lisp
 645
 646 @table @var
 647 @item @var{type}
 648 A GType designator of interface
 649 @item @var{types}
 650 A list of GType designators specifying the interface prerequisites
 651 @end table
 652
 653 Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.
 654
 655 Example:
 656 @lisp
 657 (g-type-interface-prerequisites "GtkCellEditable")
 658 @result{}
 659 ("GtkObject" "GtkWidget")
 660 @end lisp
 661
 662 @node Enum types information
 663 @chapter Enum types information
 664 @menu
 665 * enum-item::
 666 * flags-item::
 667 * get-enum-items::
 668 * get-flags-items::
 669 @end menu
 670
 671 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.
 672
 673 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.
 674
 675 @node enum-item
 676 @section enum-item
 677 @Struct enum-item
 678 @lisp
 679 (defstruct enum-item
 680   name value nick)
 681 @end lisp
 682
 683 @table @var
 684 @item @var{name}
 685 A string - name of enum item
 686 @item @var{value}
 687 An integer - numeric value of enum item
 688 @item @var{nick}
 689 A string - short name of an enum item
 690 @end table
 691
 692 Structure @code{enum-item} represents a single item of an enumeration type.
 693
 694 Example:
 695 @lisp
 696 #S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
 697 @end lisp
 698
 699 @node flags-item
 700 @section flags-item
 701 @Struct flags-item
 702 @lisp
 703 (defstruct flags-item
 704   name value nick)
 705 @end lisp
 706
 707 @table @var
 708 @item @var{name}
 709 A string - name of flags item
 710 @item @var{value}
 711 An integer - numeric value of flags item
 712 @item @var{nick}
 713 A string - short name of an flags item
 714 @end table
 715
 716 Structure @code{flags-item} represents a single item of an flags type.
 717
 718 Example:
 719 @lisp
 720 #S(FLAGS-ITEM
 721    :NAME "GDK_POINTER_MOTION_HINT_MASK"
 722    :VALUE 8
 723    :NICK "pointer-motion-hint-mask")
 724 @end lisp
 725
 726 @node get-enum-items
 727 @section get-enum-items
 728
 729 @Function get-enum-items
 730 @lisp
 731 (get-enum-items type) @result{} items
 732 @end lisp
 733
 734 @table @var
 735 @item @var{type}
 736 A GType designator of an enum type
 737 @item @var{items}
 738 A list of @code{enum-item} structures
 739 @end table
 740
 741 Returns a list of items in an enumeration
 742
 743 Example:
 744 @lisp
 745 (get-enum-items "GtkScrollType")
 746 @result{}
 747 (#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
 748  #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
 749  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
 750  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
 751  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
 752  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
 753  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
 754  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
 755  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
 756  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
 757  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
 758  #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
 759  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
 760  #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
 761  #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
 762  #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
 763 @end lisp
 764
 765 @node get-flags-items
 766 @section get-flags-items
 767
 768 @Function get-flags-items
 769 @lisp
 770 (get-flags-items type) @result{} items
 771 @end lisp
 772
 773 @table @var
 774 @item @var{type}
 775 A GType designator of an flags type
 776 @item @var{items}
 777 A list of @code{flags-item} structures
 778 @end table
 779
 780 Returns a list of items in an flags type
 781
 782 Example:
 783 @lisp
 784 (get-flags-items "GtkAttachOptions")
 785 @result{}
 786 (#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
 787  #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
 788  #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
 789 @end lisp
 790
 791 @node Using GValues
 792 @chapter Using GValues
 793 @menu
 794 * g-value-zero::
 795 * g-value-init::
 796 * g-value-unset::
 797 * parse-g-value::
 798 * set-g-value::
 799 * Registering types::
 800 @end menu
 801
 802 GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.
 803
 804 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.
 805
 806 GValue is used whenever a value of unkown type should be passed. It is used in:
 807 @itemize
 808 @item Closure marshal functions
 809 @item Property get and set functions
 810 @end itemize
 811
 812 Example of usage:
 813 @lisp
 814 (cffi:with-foreign-object (gval 'g-value)
 815   (set-g-value gval "Hello" "gchararray" :zero-g-value t)
 816   (format t "~S~%" (parse-g-value gval))
 817   (g-value-unset gval))
 818 @result{}
 819 "Hello"
 820 @end lisp
 821
 822 @node g-value-zero
 823 @section g-value-zero
 824 @Function g-value-zero
 825 @lisp
 826 (g-value-zero g-value)
 827 @end lisp
 828 @table @var
 829 @item @var{g-value}
 830 A foreign pointer to GValue structure.
 831 @end table
 832
 833 Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
 834 @lisp
 835 GValue value = @{ 0 @};
 836 @end lisp
 837
 838 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).
 839
 840 @node g-value-init
 841 @section g-value-init
 842
 843 @Function g-value-init
 844 @lisp
 845 (g-value-init value type)
 846 @end lisp
 847 @table @var
 848 @item @var{value}
 849 A foreign pointer to GValue structure
 850 @item @var{type}
 851 A GType designator
 852 @end table
 853
 854 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).
 855
 856 @node g-value-unset
 857 @section g-value-unset
 858 @Function g-value-unset
 859 @lisp
 860 (g-value-unset value)
 861 @end lisp
 862 @table @var
 863 @item @var{value}
 864 A foreign pointer to GValue structure.
 865 @end table
 866
 867 Unsets the GValue. This frees all resources associated with GValue.
 868
 869 @node parse-g-value
 870 @section parse-g-value
 871 @Function parse-g-value
 872 @lisp
 873 (parse-g-value value) @result{} object
 874 @end lisp
 875 @table @var
 876 @item @var{value}
 877 A foreign pointer to GValue structure
 878 @item @var{object}
 879 A Lisp object
 880 @end table
 881
 882 Retrieves the object from GValue structure.
 883
 884 @node set-g-value
 885 @section set-g-value
 886 @Function set-g-value
 887 @lisp
 888 (set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))
 889 @end lisp
 890
 891 @table @var
 892 @item @var{gvalue}
 893 A foreign pointer to GValue structure
 894 @item @var{object}
 895 An object that is to be assigned to @code{gvalue}
 896 @item @var{type}
 897 A GType designator specifying what GType should be set
 898 @item @var{unset-g-value}
 899 A boolean specifying whether to call @code{g-value-unset} before assigment.
 900 @item @var{zero-g-value}
 901 A boolean specifying whether to call @code{g-value-zero} before assignment
 902 @item @var{g-value-init}
 903 A boolean specifying whether to call @code{g-value-init} before assignment
 904 @end table
 905
 906 Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.
 907
 908 @node Registering types
 909 @section Registering types
 910
 911 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.
 912
 913 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.
 914
 915 @subsection register-enum-type
 916 @Function register-enum-type
 917 @lisp
 918 (register-enum-type name type)
 919 @end lisp
 920 @table @var
 921 @item @var{name}
 922 A string naming the GEnum type
 923 @item @var{type}
 924 A symbol - name of CFFI foreign enum type
 925 @end table
 926
 927 Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.
 928
 929 Example:
 930 @lisp
 931 (defcenum text-direction
 932   :none :ltr :rtl)
 933 (register-enum-type "GtkTextDirection" 'text-direction)
 934 @end lisp
 935
 936 @subsection register-flags-type
 937 @Function register-flags-type
 938 @lisp
 939 (register-flags-type name type)
 940 @end lisp
 941 @table @var
 942 @item @var{name}
 943 A string naming the GFlags type
 944 @item @var{type}
 945 A symbol - name of CFFI foreign flags type
 946 @end table
 947
 948 Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.
 949
 950 Example:
 951 @lisp
 952 (defcenum state-type
 953   :normal :active :prelight :selected :insensitive)
 954 (register-enum-type "GtkStateType" 'state-type)
 955 @end lisp
 956
 957 @node Stable pointers
 958 @chapter Stable pointers
 959 @menu
 960 * allocate-stable-pointer::
 961 * free-stable-pointer::
 962 * stable-pointer-value::
 963 * with-stable-pointer::
 964 @end menu
 965
 966 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.
 967
 968 @node allocate-stable-pointer
 969 @section allocate-stable-pointer
 970
 971 @Function allocate-stable-pointer
 972 @lisp
 973 (allocate-stable-pointer thing) @result{} stable-pointer
 974 @end lisp
 975
 976 @table @var
 977 @item @var{thing}
 978 An arbitrary Lisp object
 979 @item @var{stable-pointer}
 980 A foreign pointer
 981 @end table
 982
 983 Allocates a stable pointer to @code{thing}.
 984
 985 (Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})
 986
 987 Example:
 988 @lisp
 989 (allocate-stable-pointer (lambda (x) (+ x 10)))
 990 @result{}
 991 #.(SB-SYS:INT-SAP #X00000002)
 992
 993 (stable-pointer-value *)
 994 @result{}
 995 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
 996
 997 (free-stable-pointer **)
 998 @result{}
 999 NIL
1000 @end lisp
1001
1002 @node free-stable-pointer
1003 @section free-stable-pointer
1004
1005 @Function free-stable-pointer
1006 @lisp
1007 (free-stable-pointer stable-pointer)
1008 @end lisp
1009
1010 @table @var
1011 @item @var{stable-pointer}
1012 A foreign pointer that was created with @code{allocate-stable-pointer}.
1013 @end table
1014
1015 Frees the stable pointer, enabling the garbage collector to reclaim the object.
1016
1017 Example:
1018 @lisp
1019 (allocate-stable-pointer (lambda (x) (+ x 10)))
1020 @result{}
1021 #.(SB-SYS:INT-SAP #X00000002)
1022
1023 (stable-pointer-value *)
1024 @result{}
1025 #<FUNCTION (LAMBDA (X)) @{1004D016F9@}>
1026
1027 (free-stable-pointer **)
1028 @result{}
1029 NIL
1030 @end lisp
1031
1032 @node stable-pointer-value
1033 @section stable-pointer-value
1034
1035 @Accessor stable-pointer-value
1036 @lisp
1037 (stable-pointer-value stable-pointer) @result{} thing
1038 (setf (stable-pointer-value stable-pointer) thing)
1039 @end lisp
1040
1041 @table @var
1042 @item @var{stable-pointer}
1043 A foreign pointer created by @code{allocate-stable-pointer}
1044 @item @var{thing}
1045 A Lisp object
1046 @end table
1047
1048 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.
1049
1050 @node with-stable-pointer
1051 @section with-stable-pointer
1052
1053 @Macro with-stable-pointer
1054 @lisp
1055 (with-stable-pointer (ptr expr) &body body)
1056 @end lisp
1057
1058 @table @var
1059 @item @var{ptr}
1060 A variable that will be bound to the stable pointer
1061 @item @var{expr}
1062 An expression that will be evaluated once and its value will be bound to stable pointer's value
1063 @end table
1064
1065 Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.
1066
1067 Example:
1068 @lisp
1069 (with-stable-pointer (ptr (lambda (x) (+ x 10)))
1070   (print (stable-pointer-value ptr)))
1071 ;;Prints:
1072 #<FUNCTION (LAMBDA (X)) @{1004807E79@}>
1073 @end lisp
1074
1075 @node Closures
1076 @chapter Closures
1077 @menu
1078 * create-signal-handler-closure::
1079 * Object-bound foreign functions::
1080 @end menu
1081
1082 Closure are anonymous functions that capture their lexical environment.
1083
1084 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-signal-handler-closure} create closure from lisp function that can be used a signal handler. The GClosure is finalized automatically when GObject no longer needs it (e.g., when GClosure is disconnected from signal).
1085
1086 (TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)
1087
1088 @node create-signal-handler-closure
1089 @section create-signal-handler-closure
1090 @Function create-signal-handler-closure
1091 @lisp
1092 (create-signal-handler-closure object fn) @result{} closure
1093 @end lisp
1094
1095 @table @var
1096 @item @var{object}
1097 An object for which the closure is created
1098 @item @var{fn}
1099 A function that will be called by closure invokation
1100 @item @var{closure}
1101 A foreign pointer to allocated closure
1102 @end table
1103
1104 Allocates the closure. The closure is destroyed automatically by GObject.
1105
1106 Example:
1107 @lisp
1108 (create-signal-handler-closure obj (lambda (x) (+ x 10)))
1109 @result{}
1110 #.(SB-SYS:INT-SAP #X006D7B20)
1111 @end lisp
1112
1113 Example of usage from GObject binding code:
1114 @lisp
1115 (defun connect-signal (object signal handler &key after)
1116   (g-signal-connect-closure (ensure-object-pointer object)
1117                             signal
1118                             (create-signal-handler-closure object handler)
1119                             after))
1120 @end lisp
1121
1122 @node Object-bound foreign functions
1123 @section Object-bound foreign functions
1124
1125 A common idiom for Gtk+ for passing user-defined function is as follows. Callback function has (besides its 'useful' arguments) an additional argument at the end - the 'data' pointer. This 'data' pointer, along with the pointer to 'destroy-notify' function is specified when passing the function. Destroy-notify function allows to free the function object (the Lisp closure) when it is not used by an object.
1126
1127 @RMacro define-cb-methods
1128 @lisp
1129 (define-cb-methods name return-type ((arg-1 type-1) ... (arg-n type-n)))
1130 @end lisp
1131
1132 Defines two CFFI callbacks assosiated with the callback function type @var{name}. Creates @var{name}-cb - a callback to be passed as an function and create @var{name}-destroy-notify - a callback to be passed as 'destroy-notify' function. These callbacks are intended to work together with @ref{create-fn-ref}.
1133
1134 Arguments and return-type are the same as CFFI arguments and return-type for callbacks. Arguments do not include the last 'data' pointer.
1135
1136 @RFunction create-fn-ref
1137 @lisp
1138 (create-fn-ref object function) @result{} foreign-pointer
1139 @end lisp
1140
1141 This function creates a foreign structure containing the data neccesary for callbacks defined by @ref{define-cb-methods} to call and dispose of the @var{function}. The @var{function} is bound to the @var{object}. This is neccesary for correct work of garbage collector. The created structure is freed by 'destroy-notify' function.
1142
1143 Example:
1144 @lisp
1145 (defcfun gtk-assistant-set-forward-page-func :void
1146   (assistant (g-object assistant))
1147   (page-func :pointer)
1148   (data :pointer)
1149   (destroy-notify :pointer))
1150
1151 (define-cb-methods assistant-page-func :int ((current-page :int)))
1152
1153 (defun set-assistant-forward-page-function (assistant function)
1154   (if function
1155       (gtk-assistant-set-forward-page-func assistant
1156                                            (callback assistant-page-func-cb)
1157                                            (create-fn-ref assistant function)
1158                                            (callback assistant-page-func-destroy-notify))
1159       (gtk-assistant-set-forward-page-func assistant (null-pointer) (null-pointer) (null-pointer))))
1160 @end lisp
1161
1162 @node GObject low-level
1163 @chapter GObject low-level
1164 @menu
1165 * g-object-call-constructor::
1166 * g-type-from-object::
1167 * g-object-call-get-property::
1168 * g-object-call-set-property::
1169 @end menu
1170
1171 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.
1172
1173 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.
1174
1175 @node g-object-call-constructor
1176 @section g-object-call-constructor
1177
1178 @Function g-object-call-constructor
1179 @lisp
1180 (g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr
1181 @end lisp
1182
1183 @table @var
1184 @item @var{object-type}
1185 A GType designator that specifies the object type that is to be created
1186 @item @var{args-names}
1187 A list of strings naming the arguments to constructor
1188 @item @var{args-value}
1189 A list of arguments values (in the same order as args-names)
1190 @item @var{args-types}
1191 Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
1192 @item @var{object-ptr}
1193 A foreign pointer to newly created instance
1194 @end table
1195
1196 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}.
1197
1198 Example:
1199 @lisp
1200 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1201 @result{}
1202 #.(SB-SYS:INT-SAP #X006D8900)
1203
1204 (g-object-call-get-property * "label")
1205 @result{}
1206 "Hello"
1207
1208 (g-object-call-get-property ** "use-underline")
1209 @result{}
1210 T
1211 @end lisp
1212
1213 @node g-type-from-object
1214 @section g-type-from-object
1215
1216 @Function g-type-from-object
1217 @lisp
1218 (g-type-from-object object-ptr) @result{} type
1219 @end lisp
1220
1221 @table @var
1222 @item @var{object-ptr}
1223 A foreign pointer to a GObject instance
1224 @item @var{type}
1225 A GType designator
1226 @end table
1227
1228 Returns the type of an object by a pointer to its instance
1229
1230 Example:
1231 @lisp
1232 (g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
1233 @result{}
1234 "GtkButton"
1235 @end lisp
1236
1237 @node g-object-call-get-property
1238 @section g-object-call-get-property
1239
1240 @Function g-object-call-get-property
1241 @lisp
1242 (g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value
1243 @end lisp
1244
1245 @table @var
1246 @item @var{object-ptr}
1247 A foreign pointer to a GObject instance
1248 @item @var{property-name}
1249 A string naming the property
1250 @item @var{property-type}
1251 Optional GType designator specifying the type of a property
1252 @item @var{property-value}
1253 The value of a property
1254 @end table
1255
1256 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.
1257
1258 Example:
1259 @lisp
1260 (g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
1261 @result{}
1262 #.(SB-SYS:INT-SAP #X006D8900)
1263
1264 (g-object-call-get-property * "label")
1265 @result{}
1266 "Hello"
1267
1268 (g-object-call-get-property ** "use-underline")
1269 @result{}
1270 T
1271 @end lisp
1272
1273 @node g-object-call-set-property
1274 @section g-object-call-set-property
1275
1276 @Function g-object-call-set-property
1277 @lisp
1278 (g-object-call-set-property object-ptr property-name new-value &optional property-type)
1279 @end lisp
1280
1281 @table @var
1282 @item @var{object-ptr}
1283 A foreign pointer to a GObject instance
1284 @item @var{property-name}
1285 A string naming the property
1286 @item @var{new-value}
1287 A new value of a property
1288 @item @var{property-type}
1289 Optional GType designator specifying the type of a property
1290 @end table
1291
1292 Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.
1293
1294 Example:
1295 @lisp
1296 (g-object-call-constructor "GtkButton" nil nil)
1297 @result{}
1298 #.(SB-SYS:INT-SAP #X006D8B40)
1299
1300 (g-object-call-set-property * "label" "Hello")
1301 @result{}
1302 ; No value
1303
1304 (g-object-call-get-property ** "label")
1305 @result{}
1306 "Hello"
1307 @end lisp
1308
1309 @node GObject high-level
1310 @chapter GObject high-level
1311 @menu
1312 * g-object::
1313 * g-initially-unowned::
1314 * GObject metaclass::
1315 * Using objects::
1316 * Signals::
1317 * GObject foreign class::
1318 @end menu
1319
1320 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):
1321 @itemize
1322 @item objects are created with @code{make-instance}
1323 @item properties are used as regular slots
1324 @end itemize
1325
1326 GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.
1327
1328 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.
1329
1330 Example GObject class of definition:
1331 @lisp
1332 (defclass dialog (gtk-window atk-implementor-iface buildable)
1333   ((has-separator :accessor dialog-has-separator
1334                   :initarg :has-separator
1335                   :allocation :gobject-property
1336                   :g-property-type "gboolean"
1337                   :g-property-name "has-separator"))
1338   (:metaclass gobject-class)
1339   (:g-type-name . "GtkDialog")
1340   (:g-type-initializer . "gtk_dialog_get_type"))
1341 @end lisp
1342
1343 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.
1344
1345 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.
1346
1347 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).
1348
1349 @node g-object
1350 @section g-object
1351
1352 @Class g-object
1353
1354 A base class for all GObject classes.
1355
1356 @Accessor pointer g-object
1357
1358 An accessor that accesses the foreign pointer to object.
1359
1360 @Function release
1361 @lisp
1362 (release object)
1363 @end lisp
1364
1365 Releases the @var{object} by dropping the reference from it in advance before GC reclaims it. Use this function as an optimization measure when you know that some object will not be needed. All access to the object's properties will be invalid after this function is called.
1366
1367 @Macro using
1368 @lisp
1369 (using (object expr) &body body)
1370 @end lisp
1371
1372 Evaluates and returns the result of evaluation of the @var{body} with @var{object} being bound to the result of evaluating @var{expr}. Ensures that @code{release} is called on @var{object} after the @var{body} is evaluated.
1373
1374 @Macro using
1375 @lisp
1376 (using ((var1 expr1) (var2 expr2) ... (varn exprn)) &body body)
1377 @end lisp
1378
1379 Evaluates and returns the result of evaluation of the @var{body} with @var{var}s being bound to the results of evaluating @var{expr}s. Ensures that @code{release} is called on every @var{var} after the @var{body} is evaluated.
1380
1381 @node g-initially-unowned
1382 @section g-initially-unowned
1383
1384 @Class g-initially-unowned
1385
1386 Superclass: @ref{g-object}
1387
1388 A base class for all GObject classes whose initial reference is floating.
1389
1390 @node GObject metaclass
1391 @section GObject metaclass
1392
1393 See MOP for information what metaclass is and why is it useful.
1394
1395 GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.
1396
1397 Classes that correspond to GObject classes are instances of this class. Each CLOS class of @code{gobject-class} metaclass is mapped to one GObject class. Two or more CLOS classes may map into one GObject class. GObject and CLOS inheritance must be consistent: if class @code{X} is a subclass or the same class as @code{Y} in CLOS, then this relation must hold for @code{X'} and @code{Y'}, where @code{X'} is a GObject class to which @code{X} class maps to.
1398
1399 For each instance of GObject-related CLOS class there is a corresponding instance of GObject class (of a GObject class to which the CLOS class maps). Whenever the GObject class instance reference enters the Lisp memory (by creating instance with @code{make-instance}, as the return value of foreign function or as a slot value of GObject class instance), an instance of CLOS class is created.
1400
1401 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}.
1402
1403 This class has the following slots:
1404 @itemize
1405 @item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})
1406
1407 Specifies the name of corresponding GObject class. String or NIL is allowed. If the name is NIL, then the same GObject class as its parent. Only one class may have specified a given @code{:g-type-name}.
1408 @item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})
1409
1410 Name of foreign type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}. String or NIL is allowed.
1411 @item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
1412
1413 A boolean specifying whether this CLOS class corresponds to GInterface. It is NIL by default.
1414 @end itemize
1415
1416 This metaclass defines the GObject classes.
1417
1418 Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
1419 @itemize
1420 @item @var{:g-property-type}
1421
1422 A string naming GType of property
1423 @item @var{:g-property-name}
1424
1425 A name of a property
1426 @end itemize
1427
1428 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:
1429 @itemize
1430 @item @var{:g-property-type}
1431 A CFFI foreign type of property
1432 @item @var{:g-getter}
1433 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)}.
1434 @item @var{:g-setter}
1435 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))}.
1436 @end itemize
1437
1438 Initargs of a slot are used to construct the GObject class.
1439
1440 Example:
1441 @lisp
1442 (defclass container (widget atk-implementor-iface buildable)
1443     ((border-width :allocation :gobject-property
1444                    :g-property-type "guint"
1445                    :accessor container-border-width
1446                    :initarg :border-width
1447                    :g-property-name "border-width")
1448      (resize-mode :allocation :gobject-property
1449                   :g-property-type "GtkResizeMode"
1450                   :accessor container-resize-mode
1451                   :initarg :resize-mode
1452                   :g-property-name "resize-mode")
1453      (child :allocation :gobject-property
1454             :g-property-type "GtkWidget"
1455             :accessor container-child
1456             :initarg :child
1457             :g-property-name "child")
1458      (focus-child :allocation :gobject-fn
1459                   :g-property-type g-object
1460                   :accessor container-focus-child
1461                   :initarg :focus-child
1462                   :g-getter "gtk_container_get_focus_child"
1463                   :g-setter "gtk_container_set_focus_child")
1464      (focus-vadjustment :allocation :gobject-fn
1465                         :g-property-type (g-object adjustment)
1466                         :accessor container-focus-vadjustment
1467                         :initarg :focus-vadjustment
1468                         :g-getter "gtk_container_get_focus_vadjustment"
1469                         :g-setter "gtk_container_set_focus_vadjustment")
1470      (focus-hadjustment :allocation :gobject-fn
1471                         :g-property-type (g-object adjustment)
1472                         :accessor container-focus-hadjustment
1473                         :initarg :focus-hadjustment
1474                         :g-getter "gtk_container_get_focus_hadjustment"
1475                         :g-setter "gtk_container_set_focus_hadjustment"))
1476     (:metaclass gobject-class)
1477     (:g-type-name . "GtkContainer")
1478     (:g-type-initializer . "gtk_container_get_type"))
1479 @end lisp
1480 (note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)
1481
1482 @node Using objects
1483 @section Using objects
1484 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.
1485
1486 Example:
1487 @lisp
1488 (make-instance 'gtk:dialog :has-separator t)
1489 @result{}
1490 #<GTK:DIALOG @{10036C5A71@}>
1491
1492 (defvar *d* (make-instance 'gtk:dialog :has-separator t))
1493 @result{}
1494 *D*
1495
1496 (gtk:dialog-has-separator *d*)
1497 @result{}
1498 T
1499
1500 (setf (gtk:dialog-has-separator *d*) nil)
1501 @result{}
1502 NIL
1503
1504 (gtk:dialog-has-separator *d*)
1505 @result{}
1506 NIL
1507 @end lisp
1508
1509 @node Signals
1510 @section Signals
1511
1512 To connect handler to a signal, @code{connect-signal} function is used. Function @code{disconnect-signal} removes the connected signal.
1513
1514 @Function connect-signal
1515 @lisp
1516 (connect-signal object signal handler &key after) @result{} handler-id
1517 @end lisp
1518
1519 @table @var
1520 @item @var{object}
1521 An instance of GObject object
1522 @item @var{signal}
1523 A signal name
1524 @item @var{handler}
1525 A function
1526 @item @var{after}
1527 A boolean specifying whether the handler should be called after the default handler
1528 @item @var{handler-id}
1529 An integer - identifier of signal handler; can be used to disconnect the signal handler with @code{disconnect-signal}
1530 @end table
1531
1532 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.
1533
1534 @Function disconnect-signal
1535 @lisp
1536 (disconnect-signal object handler-id)
1537 @end lisp
1538
1539 Disconnects the signal handler identified by @var{handler-id} from the corresponding signal for @var{object}. @var{handler-id} is the integer identifying the signal handler; @code{connect-signal} returns handler identifiers.
1540
1541 Example:
1542 @lisp
1543 (defvar *d* (make-instance 'gtk:dialog))
1544 @result{}
1545 *D*
1546
1547 *d*
1548 @result{}
1549 #<GTK:DIALOG @{1002D866F1@}>
1550
1551 (parse-signal-name "GtkDialog" "response")
1552 @result{}
1553 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1554
1555 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1556
1557 (emit-signal *d* "response" 14)
1558 @result{}
1559 ;; Prints:
1560 #<GTK:DIALOG @{1002D866F1@}>
1561 14
1562 @end lisp
1563
1564 Function @code{emit-signal} is used to emit signals on objects.
1565
1566 @RFunction emit-signal
1567 @code{(emit-signal object signal-name &rest args) @result{} return-value}
1568
1569 @table @var
1570 @item @var{object}
1571 An object on which the signal should be emitted
1572 @item @var{signal-name}
1573 A string naming the signal
1574 @item @var{args}
1575 Arguments for a signal
1576 @item @var{return-value}
1577 Return value of a signal
1578 @end table
1579
1580 Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.
1581
1582 Example:
1583 @lisp
1584 (defvar *d* (make-instance 'gtk:dialog))
1585 @result{}
1586 *D*
1587
1588 *d*
1589 @result{}
1590 #<GTK:DIALOG @{1002D866F1@}>
1591
1592 (parse-signal-name "GtkDialog" "response")
1593 @result{}
1594 #<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>
1595
1596 (connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))
1597
1598 (emit-signal *d* "response" 14)
1599 @result{}
1600 ;; Prints:
1601 #<GTK:DIALOG @{1002D866F1@}>
1602 14
1603 @end lisp
1604
1605 @node GObject foreign class
1606 @section GObject foreign class
1607
1608 To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.
1609
1610 This type has the following syntax:
1611 @code{(g-object [type] [:already-referenced])} or @code{g-object}. (Brackets indicate optional arguments)
1612
1613 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. If @code{:already-referenced} is included then it is assumed that the function returns already referenced object (so that it is not needed to call @code{g-object-ref} on returned object).
1614
1615 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.
1616
1617 This defines the function that may be called with instances of types @code{container} and @code{widget}:
1618 @lisp
1619 (defcfun (container-add "gtk_container_add") :void
1620   (container (g-object container))
1621   (widget (g-object widget)))
1622
1623 (let ((window (make-instance 'gtk-window))
1624       (widget (make-instance 'button)))
1625   (container-add window widget))
1626 @end lisp
1627 (@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})
1628
1629 This defines the function that returns an instance of GObject class:
1630 @lisp
1631 (defcfun (bin-child "gtk_bin_get_child") (g-object widget)
1632   (bin (g-object bin)))
1633
1634 (let ((window (make-instance 'gtk-window))
1635       (widget (make-instance 'button)))
1636   (container-add window widget)
1637   (bin-child window))
1638 @result{}
1639 #<GTK:BUTTON @{1002DE74B1@}>
1640 @end lisp
1641
1642 This example shows the use of @code{:already-referenced} option:
1643 @lisp
1644 (defcfun (widget-create-pango-layout "gtk_widget_create_pango_layout") (g-object gdk::pango-layout :already-referenced)
1645   (widget (g-object widget))
1646   (text :string))
1647
1648 (defcfun gdk-gc-new (g-object graphics-context :already-referenced)
1649   (drawable (g-object drawable)))
1650 @end lisp
1651
1652 @node Creating GObjects classes and implementing GInterfaces
1653 @chapter Creating GObjects classes and implementing GInterfaces
1654
1655 @menu
1656 * define-vtable::
1657 * register-object-type-implementation::
1658 @end menu
1659
1660 Creating GObject classes from Lisp is the most complex part of GObject binding.
1661
1662 GObject binding at the moment provides only limited scenarios of creating GObject classes. It lets register GObject class (as a subclass of another class or of GObject), specify its properties and implemented interfaces. Each property is associated with Lisp getter and setter functions. Each interface is associated wth vtable (table of virtual function pointers, see @uref{http://en.wikipedia.org/wiki/Vtable}) that specifies a list of methods and their signatures. If class is ever created from GObject side (not from Lisp side, must be constructable with no parameters).
1663
1664 Each virtual function is mapped to a generic function for which class should provide a specialized method. This function should not be called by user. Rather, user code should call corresponding foreign function.
1665
1666 Practically speaking, creating GObject class requires defining CLOS class that correspond to GObject class and calling @code{register-object-type-implementation} with information about the class (its GType name, superclass, interfaces and properties).
1667
1668 Interface that is implemented by a class should have its vtable defined by @code{define-vtable}. Vtable definitions consists of a list of functions's names and signatures and their locations in vtable.
1669
1670 Unfortunately, GObject does not provide information about vtables, and does not support using GClosures to implement virtual functions. Therefore, implementation for all interface's functions are defined as CFFI foreign callbacks. These callbacks in turn call corresponding generic functions that should be specialized on required objects.
1671
1672 @node define-vtable
1673 @section define-vtable
1674
1675 @Macro define-vtable
1676 @lisp
1677 (define-vtable (type-name cstruct-name)
1678   &body item*)
1679
1680 item ::= (name callback-name return-type &rest arg*)
1681 item ::= (:skip cffi-structure-item)
1682 arg ::= (arg-name arg-type)
1683 @end lisp
1684
1685 @table @var
1686 @item @var{type-name}
1687 A string naming the GObject type of interface
1688 @item @var{cstruct-name}
1689 A name for a generated CFFI foreign structure
1690 @item @var{name}
1691 A name for implementation generic function
1692 @item @var{callback-name}
1693 A name for generated callback function
1694 @item @var{return-type}
1695 A CFFI specifier for foreign function return type
1696 @item @var{arg-name}
1697 A symbol naming the argument of interface method
1698 @item @var{arg-type}
1699 A CFFI specifier for foreign function argument type
1700 @end table
1701
1702 Macro that specifies the vtable for an interface. This macro defines generic functions (named by @code{name}) that correspond to methods of an interface. On these generic functions methods should be defined that implement the interface method. @code{item}s specify the CFFI foreign structure for vtable. Vtable contains not only function pointers, but other slots. Such slots should be specified here with @code{:skip} prepended to them. This is needed to be able to correctly calculate offsets to function pointers in vtable.
1703
1704 Example:
1705 @lisp
1706 (define-vtable ("GtkTreeModel" c-gtk-tree-model)
1707   (:skip parent-instance g-type-interface)
1708   ;;some signals
1709   (:skip tree-model-row-changed :pointer)
1710   (:skip tree-model-row-inserted :pointer)
1711   (:skip tree-model-row-has-child-toggled :pointer)
1712   (:skip tree-model-row-deleted :pointer)
1713   (:skip tree-model-rows-reordered :pointer)
1714   ;;methods
1715   (tree-model-get-flags-impl tree-model-get-flags-cb
1716     tree-model-flags
1717     (tree-model g-object))
1718   (tree-model-get-n-columns-impl tree-model-get-n-columns-cb
1719     :int
1720     (tree-model g-object))
1721   (tree-model-get-column-type-impl tree-model-get-column-type-cb
1722     g-type-designator
1723     (tree-model g-object) (index :int))
1724   (tree-model-get-iter-impl tree-model-get-iter-cb
1725     :boolean
1726     (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (path (g-boxed-foreign tree-path)))
1727   (tree-model-get-path-impl tree-model-get-path-cb
1728     (g-boxed-foreign tree-path :return)
1729     (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1730   (tree-model-get-value-impl tree-model-get-value-cb
1731     :void
1732     (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
1733   (tree-model-iter-next-impl tree-model-iter-next-cb
1734     :boolean
1735     (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1736   (tree-model-iter-children-impl tree-model-iter-children-cb
1737     :boolean
1738     (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)))
1739   (tree-model-iter-has-child-impl tree-model-iter-has-child-cb
1740     :boolean
1741     (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1742   (tree-model-iter-n-children-impl tree-model-iter-n-children-cb
1743     :int
1744     (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1745   (tree-model-iter-nth-child-impl tree-model-iter-nth-child-cb
1746     :boolean
1747     (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (parent (g-boxed-foreign tree-iter)) (n :int))
1748   (tree-model-iter-parent-impl tree-model-iter-parent-cb
1749     :boolean
1750     (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (child (g-boxed-foreign tree-iter)))
1751   (tree-model-ref-node-impl tree-model-ref-node-cb
1752     :void
1753     (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
1754   (tree-model-unref-node-impl tree-model-unref-node-cb
1755     :void
1756     (tree-model g-object) (iter (g-boxed-foreign tree-iter))))
1757 @end lisp
1758
1759 @node register-object-type-implementation
1760 @section register-object-type-implementation
1761
1762 @Macro register-object-type-implementation
1763 @lisp
1764 (register-object-type-implementation name class parent interfaces properties)
1765 @end lisp
1766
1767 @table @var
1768 @item @var{name}
1769 A string naming the new GObject class.
1770 @item @var{class}
1771 A class name of corresponding CLOS class. It should be inherited from @code{g-object} or its descendants.
1772 @item @var{parent}
1773 A string naming the GObject superclass
1774 @item @var{interfaces}
1775 A list of names of interfaces that this class implements.
1776 @item @var{properties}
1777 A list of properties that this class provides.
1778 Each property is defined as
1779 @lisp
1780 property ::= (property-name property-type accessor property-get-fn property-set-fn)
1781 @end lisp
1782 @end table
1783
1784 A macro that creates a new GObject type and registers the Lisp implementation for it.
1785
1786 Example:
1787 @lisp
1788 (register-object-type-implementation "LispArrayListStore" array-list-store "GObject" ("GtkTreeModel") nil)
1789 @end lisp
1790
1791 @node GBoxed
1792 @chapter GBoxed
1793 @menu
1794 * define-g-boxed-cstruct::
1795 * define-g-boxed-variant-cstruct::
1796 * define-g-boxed-opaque::
1797 * g-boxed-opaque::
1798 * define-boxed-opaque-accessor::
1799 * boxed-related-symbols::
1800 * GBoxed foreign type::
1801 @end menu
1802
1803 GObject manual defines this type in the following way:
1804
1805 ``GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.
1806
1807 Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries.''
1808
1809 Naturally, it is hard to provide support for ``arbitrary C structures''. We support a few useful use cases of GBoxed types:
1810 @itemize
1811 @item Simple C structures. A Lisp structure is a one-to-one correspondence to C structure and is passes to and from foreign code by copying the data it contains. Examples of simple structures are GdkPoint, GdkRectangle.
1812 @item ``Variant'' C structures. A one common idiom of C is to define a union of structures sharing the same parts in order to implement the polymorphism of structures. These structures are mapped to a hierarchy of Lisp structures (where one structure subclasses another via the @code{:include} @code{defstruct} option).
1813
1814 For example, Gdk has structure GdkEvent which is a union of GdkEventAny, GdkEventExpose and other structures. These structures have common slots: ``type'', ``window'', ``send_event''. By dispatching on ``type'', user or GdkEvent structure knows which of GdkEvent* structures it has and can access other fields.
1815 @item Opaque C structures. A C structure the has ``hidden'' fields and should only created/destroyed with specific functions and be accessed only with specific accessors. Example of such structures is GtkTreePath.
1816 @end itemize
1817
1818 @node define-g-boxed-cstruct
1819 @section define-g-boxed-cstruct
1820 @Macro define-g-boxed-cstruct
1821 @lisp
1822 (define-g-boxed-cstruct name g-type-name
1823   &body slot*)
1824
1825 slot ::= (slot-name slot-type &key count initform inline)
1826 @end lisp
1827
1828 @table @var
1829 @item @var{name}
1830 A symbol naming the type being defined
1831 @item @var{g-type-name}
1832 A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
1833 @item @var{slot-name}
1834 A symbol naming the slot of a structure
1835 @item @var{slot-type}
1836 A foreign type of a slot
1837 @item @var{count}
1838 An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
1839 @item @var{initform}
1840 A form that is the initform of Lisp structure slot
1841 @item @var{inline}
1842 A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
1843 @end table
1844
1845 Defines the ``simple'' GBoxed structure corresponding to C structure. The slot specification is analogous to CFFI @code{defstruct} slot specification with the addition of @code{inline} option. This also defines the @var{name}-cstruct CFFI structure definition with equivalent structure.
1846
1847 Example of usage:
1848 @lisp
1849 (define-g-boxed-cstruct rectangle "GdkRectangle"
1850   (left :int :initform 0)
1851   (top :int :initform 0)
1852   (width :int :initform 0)
1853   (height :int :initform 0))
1854
1855 (define-g-boxed-cstruct point nil
1856   (x :int :initform 0)
1857   (y :int :initform 0))
1858
1859 (define-g-boxed-cstruct vector4 nil
1860   (coords :double :count 4 :initform (vector 0d0 0d0 0d0 0d0)))
1861
1862 (define-g-boxed-cstruct segment nil
1863   (a point :inline t :initform (make-point))
1864   (b point :inline t :initform (make-point)))
1865 @end lisp
1866
1867 @node define-g-boxed-variant-cstruct
1868 @section define-g-boxed-variant-cstruct
1869
1870 @Macro define-g-boxed-variant-cstruct
1871 @lisp
1872 (define-g-boxed-variant-cstruct name g-type-name
1873   &body slot-or-variant-specification*)
1874
1875 slot ::= (slot-name slot-type &key count initform inline)
1876 variant-specification ::= (:variant dispatching-slot-name structure-variant*)
1877 structure-variant ::= (dispatching-slot-values structure-name &body slot-or-variant-specification*)
1878 @end lisp
1879
1880 @table @var
1881 @item @var{name}
1882 A symbol naming the type being defined
1883 @item @var{g-type-name}
1884 A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
1885 @item @var{slot-name}
1886 A symbol naming the slot of a structure
1887 @item @var{slot-type}
1888 A foreign type of a slot
1889 @item @var{count}
1890 An integer. Corresponds to @code{:count} option of slot in CFFI @code{defcstruct}. If @code{count} is not NIL, then the slot is mapped to Lisp array.
1891 @item @var{initform}
1892 A form that is the initform of Lisp structure slot
1893 @item @var{inline}
1894 A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
1895 @item @var{dispatching-slot-name}
1896 A name of the dispatching slot
1897 @item @var{dispatching-slot-values}
1898 A single value or a list of values.
1899 @item @var{structure-name}
1900 A symbol naming the structure
1901 @end table
1902
1903 Defines the variant GBoxed structure. Slots of variant structures are defined the same way as the slots of ``simple'' cstructs. After the last slot, @code{variant-specification} may be used to specify the variants of the structure. For this, dispatching slot is specified. The value of this slot specifies which variant of structure is used. Each variant is specified by values of the dispatching slot, by its slots and its variants.
1904
1905 Variant structure is represented in Lisp via a hierarchy on structures. For example, @code{GdkEvent} structure has variants @code{GdkEventAny}, @code{GdkEventButton}, @code{GdkEventMotion}. In Lisp, @code{event} structure is defined with all common fields of these structures and @code{event-button}, @code{event-motion} structures inherit from @code{event} structure.
1906
1907 It is assumed that the variant of structures can be represented as C structures with fields of their ``parent'' structures prepended to them. This assumption breaks when structures include their ``parent'' structure as a first field (this changes the memory alignment and changes offsets of fields).
1908
1909 This also defines the @var{name}-cstruct, @var{structure-name}-cstruct, @var{structure-name}-cunion CFFI structures definitions with equivalent structures (unions).
1910
1911 For example, for these structures this assumption holds:
1912 @example
1913 union GdkEvent
1914 @{
1915   GdkEventType   type;
1916   GdkEventKey    key;
1917   GdkEventButton button;
1918 @};
1919
1920 struct GdkEventKey @{
1921   GdkEventType type; //
1922   GdkWindow *window; // These fields are common
1923   gint8 send_event;  //
1924   guint32 time;
1925   guint state;
1926   guint keyval;
1927   ...
1928 @};
1929
1930 struct GdkEventButton @{
1931   GdkEventType type; //
1932   GdkWindow *window; // These fields are common
1933   gint8 send_event;  //
1934   guint32 time;
1935   gdouble x;
1936   gdouble y;
1937   ...
1938 @};
1939 @end example
1940
1941 Example:
1942 @lisp
1943 (define-g-boxed-variant-cstruct event "GdkEvent"
1944   (type event-type)
1945   (window (g-object gdk-window))
1946   (send-event (:boolean :int8))
1947   (:variant type
1948             ((:key-press :key-release) event-key
1949              (time :uint32)
1950              (state modifier-type)
1951              (keyval :uint)
1952              (length :int)
1953              (string (:string :free-from-foreign nil
1954                               :free-to-foreign nil))
1955              (hardware-keycode :uint16)
1956              (group :uint8)
1957              (is-modifier :uint))
1958             ((:button-press :2button-press :3button-press
1959               :button-release) event-button
1960              (time :uint32)
1961              (x :double)
1962              (y :double)
1963              (axes (fixed-array :double 2))
1964              (state :uint)
1965              (button :uint)
1966              (device (g-object device))
1967              (x-root :double)
1968              (y-root :double))
1969              ...))
1970 @end lisp
1971
1972 This code defines following structures:
1973 @lisp
1974 (defstruct event
1975   type window send-event)
1976
1977 (defstruct (event-key (:include event))
1978   time state keyval length string
1979   hardware-keycode group is-modifier)
1980
1981 (defstruct (event-button (:include event))
1982   time x y axes state button device x-root y-root)
1983 @end lisp
1984
1985 @node define-g-boxed-opaque
1986 @section define-g-boxed-opaque
1987
1988 @Macro define-g-boxed-opaque
1989 @lisp
1990 (define-g-boxed-opaque name g-type-name &key alloc)
1991 @end lisp
1992
1993 @table @var
1994 @item @var{name}
1995 A name of boxed type
1996 @item @var{g-type-name}
1997 A string; the name of GType
1998 @item @var{alloc}
1999 A form that when evaluated produces a pointer to newly allocated structure. This pointer should be copiable with @code{g_boxed_copy} and freeable with @code{g_boxed_free} function.
2000 @end table
2001
2002 Defines a opaque boxed structure. A class named @var{name} is defined as a subclass of @code{g-boxed-opaque} class. Instances of this class contain pointers to corresponding structures. An @code{:after} method for @code{initialize-instance} generic function is defined that speciales on class @var{name}. This method either accepts a @code{:pointer} initarg or evaluates @var{alloc} form if @code{:pointer} is not specified; the resulting pointer is saved in instance; finalizer is registered to free the pointer when the garbage collectors deletes this object.
2003
2004 Example:
2005 @lisp
2006 (defcfun gtk-tree-path-new :pointer)
2007
2008 (define-g-boxed-opaque tree-path "GtkTreePath"
2009   :alloc (gtk-tree-path-new))
2010 @end lisp
2011 @node g-boxed-opaque
2012 @section g-boxed-opaque
2013 @Class g-boxed-opaque
2014 @lisp
2015 (defclass g-boxed-opaque ()
2016   ((pointer :initarg :pointer
2017             :initform nil
2018             :accessor g-boxed-opaque-pointer)))
2019 @end lisp
2020
2021 A class that is the base class for wrappers of opaque structures. Contains a pointer to the wrapped opaque structure.
2022
2023 Accessor function @code{g-boxed-opaque-pointer} is used to access the pointer. Pointer should not be modified directly, only read.
2024 @node define-boxed-opaque-accessor
2025 @section define-boxed-opaque-accessor
2026 @Macro define-boxed-opaque-accessor
2027 @lisp
2028 (define-boxed-opaque-accessor
2029   boxed-name accessor-name &key type reader writer)
2030 @end lisp
2031
2032 @table @var
2033 @item @var{boxed-name}
2034 A symbol naming the opaque structure type for which the accessor is being defined
2035 @item @var{accessor-name}
2036 A symbol naming the accessor
2037 @item @var{type}
2038 A CFFI foreign type of the property for which the accessor is being defined
2039 @item @var{reader}
2040 A @code{NIL} or a string or a function designator for the reader function
2041 @item @var{writer}
2042 A @code{NIL} or a string or a function designator for the writer function
2043 @end table
2044
2045 Defines the accessor named @var{accessor-name} for property of opaque structure named @var{boxed-name} of type specified by CFFI foreign-type @var{type}.
2046
2047 @var{reader} is a string naming a foreign function of one argument of CFFI foreign-type @code{(g-boxed-foreign @var{boxed-name})} that returns a value of CFFI foreign-type @var{type}; or a function designator for a function that accepts a single argument - an instance of @code{g-boxed-opaque} class and returns the value of a property; or a @code{NIL} if the property is not readable.
2048
2049 @var{writer} is a string naming a foreign function of two arguments: of types @var{type} and @code{(g-boxed-foreign @var{boxed-name})} (with the first argument being the new value and the second being the object); or a function designator for a function of two arguments: a new value and an instance of @code{g-boxed-opaque} class; or a @code{NIL} if the property is not writable.
2050
2051 Example:
2052 @lisp
2053 (define-boxed-opaque-accessor text-iter text-iter-child-anchor
2054   :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))
2055
2056 (define-boxed-opaque-accessor text-iter text-iter-tags
2057   :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))
2058
2059 (define-boxed-opaque-accessor text-iter text-iter-chars-in-line
2060   :reader "gtk_text_iter_get_chars_in_line" :type :int)
2061
2062 (define-boxed-opaque-accessor text-iter text-iter-offset
2063   :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
2064 @end lisp
2065
2066 @node boxed-related-symbols
2067 @section boxed-related-symbols
2068
2069 @Function boxed-related-symbols
2070 @lisp
2071 (boxed-related-symbols name) @result{} symbols
2072 @end lisp
2073
2074 @table @var
2075 @item @var{name}
2076 A symbol naming the boxed type
2077 @item @var{symbols}
2078 A list of symbols
2079 @end table
2080
2081 This function returns the list of symbols that are related to GBoxed type @var{name}. These symbols are returned:
2082 @itemize
2083 @item name of boxed type
2084 @item name of all accessors of cstruct and variant-cstruct boxed types
2085 @item names of all variants of variant-cstruct boxed types
2086 @item names of constructors and copiers of cstruct and variant-cstruct boxed-types
2087 @end itemize
2088
2089 Typical usage of this function is to export the symbols related to given boxed type.
2090
2091 Example:
2092 @lisp
2093 (define-g-boxed-cstruct rectangle "GdkRectangle"
2094   (x :int :initform 0)
2095   (y :int :initform 0)
2096   (width :int :initform 0)
2097   (height :int :initform 0))
2098
2099 (boxed-related-symbols 'rectangle)
2100 @result{}
2101 (RECTANGLE MAKE-RECTANGLE COPY-RECTANGLE RECTANGLE-X RECTANGLE-Y
2102  RECTANGLE-WIDTH RECTANGLE-HEIGHT)
2103 @end lisp
2104
2105 @node GBoxed foreign type
2106 @section GBoxed foreign type
2107
2108 @ForeignType g-boxed-foreign
2109 @lisp
2110 (g-boxed-foreign name &rest option*)
2111
2112 option ::= :return
2113 @end lisp
2114
2115 @table @var
2116 @item @var{name}
2117 Name of GBoxed type
2118 @item @var{option}
2119 Option of foreign type
2120 @item @code{:return}
2121 An option that identifies the foreign type which is used at return position (as foreign function return type or as a callback return type)
2122 @end table
2123
2124 @code{g-boxed-foreign} type deals with marshaling data between Lisp code and foreign code. The marshaling follows the following principles:
2125 @itemize
2126 @item All operations on Lisp objects corresponding to GBoxed types are type-safe and should never lead to any form of memory corruption (if some operation is impossible due to e.g., pointer in opaque pointer wrapper being invalidated, error should be signalled)
2127 @item Lisp objects should not be manually managed and are properly reclaimed by garbage collector, leaving no memory leaks
2128 @item Foreign code can change objects that are passed to them as arguments. This is required for functions that operate by modifying their arguments
2129 @item Lisp code in callbacks can change objects that are passed as arguments. This is required to be able to implement interfaces that have functions that operate by modifying their arguments
2130 @end itemize
2131
2132 The @code{:return} option is required to be able to properly manage memory of opaque pointer wrappers and propagate changes to foreign and lisp structures.
2133
2134 In order to be able to correctly use @code{g-boxed-foreign} foreign type in callbacks, you should use @code{glib-defcallback}. This macro is a thin wrapper around @code{cffi:defcallback} that adds proper handling of @code{g-boxed-foreign} foreign types.
2135
2136 Examples of usage:
2137 @lisp
2138 (define-vtable ("GtkTreeModel" c-gtk-tree-model)
2139   ...
2140   (tree-model-get-path-impl tree-model-get-path-cb
2141     (g-boxed-foreign tree-path :return) (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
2142   (tree-model-get-value-impl tree-model-get-value-cb
2143     :void (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
2144   (tree-model-iter-next-impl tree-model-iter-next-cb
2145     :boolean (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
2146   ...)
2147
2148 (defcfun gtk-text-iter-forward-search :boolean
2149   (iter (g-boxed-foreign text-iter))
2150   (str (:string :free-to-foreign t))
2151   (flags text-search-flags)
2152   (match-start (g-boxed-foreign text-iter))
2153   (match-end (g-boxed-foreign text-iter))
2154   (limit (g-boxed-foreign text-iter)))
2155 @end lisp
2156
2157 @node Generating type definitions by introspection
2158 @chapter Generating type definitions by introspection
2159 @menu
2160 * define-g-object-class::
2161 * define-g-interface::
2162 * define-g-enum::
2163 * define-g-flags::
2164 * get-g-enum-definition::
2165 * get-g-flags-definition::
2166 * get-g-interface-definition::
2167 * get-g-class-definition::
2168 * Specifying additional properties for CLOS classes::
2169 * Generating names for CLOS classes and accessors::
2170 * generate-types-hierarchy-to-file::
2171 @end menu
2172
2173 CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.
2174
2175 @node define-g-object-class
2176 @section define-g-object-class
2177
2178 @Macro define-g-object-class
2179 @lisp
2180 (define-g-object-class g-type-name name
2181   (&key (superclass 'g-object) (export t) interfaces type-initializer)
2182   (&rest property*))
2183
2184 property ::= (name accessor gname type readable writable)
2185 property ::= (:cffi name acessor type reader writer)
2186 @end lisp
2187
2188 Parameters of @code{define-g-object-class}
2189 @table @var
2190 @item @var{superclass}
2191 A symbol naming the superclass of this class
2192 @item @var{export}
2193 Whether to export the name of the class and names of autogenerated properties names from the current package.
2194 @item @var{interfaces}
2195 A list of interfaces the this class implements
2196 @item @var{type-initializer}
2197 A string naming the type initiliazer function. It is usually named @code{class_get_type}.
2198 @item @var{properties}
2199 A list of slots of a class
2200 @end table
2201
2202 Parameters of @code{property}:
2203 @table @var
2204 @item @var{name}
2205 A symbol naming the slot
2206 @item @var{accessor}
2207 A symbol naming the accessor function for this slot
2208 @item @var{gname}
2209 A string naming the property of GObject
2210 @item @var{type}
2211 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)
2212 @item @var{readable}
2213 A boolean specifying whether the slot can be read
2214 @item @var{writable}
2215 A boolean specifying whether the slot can be assigned to
2216 @item @var{reader}
2217 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2218 @item @var{writter}
2219 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2220 @end table
2221
2222 Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.
2223
2224 Example:
2225 @lisp
2226 (define-g-object-class "GtkContainer" container
2227   (:superclass widget :export t :interfaces
2228                ("AtkImplementorIface" "GtkBuildable")
2229                :type-initializer "gtk_container_get_type")
2230   ((border-width container-border-width "border-width" "guint" t t)
2231    (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
2232    (child container-child "child" "GtkWidget" nil t)
2233    (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
2234    (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
2235    (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
2236 @end lisp
2237
2238 @node define-g-interface
2239 @section define-g-interface
2240
2241 @Macro define-g-interface
2242 @lisp
2243 (define-g-interface g-type-name name (&key (export t) type-initializer)
2244   &body property*)
2245
2246 property ::= (name accessor gname type readable writable)
2247 property ::= (:cffi name acessor type reader writer)
2248 @end lisp
2249
2250 Parameters of @code{define-g-interface}
2251 @table @var
2252 @item @var{export}
2253 Whether to export the name of the interface and names of autogenerated properties names from the current package.
2254 @item @var{type-initializer}
2255 A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
2256 @item @var{properties}
2257 A list of slots of a interface
2258 @end table
2259
2260 Parameters of @code{property}:
2261 @table @var
2262 @item @var{name}
2263 A symbol naming the slot
2264 @item @var{accessor}
2265 A symbol naming the accessor function for this slot
2266 @item @var{gname}
2267 A string naming the property of GObject
2268 @item @var{type}
2269 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)
2270 @item @var{readable}
2271 A boolean specifying whether the slot can be read
2272 @item @var{writable}
2273 A boolean specifying whether the slot can be assigned to
2274 @item @var{reader}
2275 A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
2276 @item @var{writter}
2277 A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
2278 @end table
2279
2280 Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.
2281
2282 Example:
2283 @lisp
2284 (define-g-interface "GtkFileChooser" file-chooser
2285   (:export t :type-initializer "gtk_file_chooser_get_type")
2286   (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
2287   (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
2288   (filter file-chooser-filter "filter" "GtkFileFilter" t t)
2289   (local-only file-chooser-local-only "local-only" "gboolean" t t)
2290   (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
2291   (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
2292   (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
2293   (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
2294   (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
2295   (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
2296   (action file-chooser-action "action" "GtkFileChooserAction" t t)
2297   (:cffi current-name file-chooser-current-name
2298    (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
2299   (:cffi filename file-chooser-filename
2300    (g-string :free-from-foreign t :free-to-foreign t)
2301    "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
2302   (:cffi current-folder file-chooser-current-folder
2303    (g-string :free-from-foreign t :free-to-foreign t)
2304    "gtk_file_chooser_get_current_folder"
2305    "gtk_file_chooser_set_current_folder")
2306   (:cffi uri file-chooser-uri
2307    (g-string :free-from-foreign t :free-to-foreign t)
2308    "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
2309   (:cffi current-folder-uri file-chooser-current-folder-uri
2310    (g-string :free-from-foreign t :free-to-foreign t)
2311    "gtk_file_chooser_get_current_folder_uri"
2312    "gtk_file_chooser_set_current_folder_uri")
2313   (:cffi preview-filename file-chooser-preview-filename
2314    (g-string :free-from-foreign t :free-to-foreign t)
2315    "gtk_file_chooser_get_preview_filename" nil)
2316   (:cffi preview-uri file-chooser-preview-uri
2317    (g-string :free-from-foreign t :free-to-foreign t)
2318    "gtk_file_chooser_get_preview_uri" nil))
2319 @end lisp
2320
2321 @node define-g-enum
2322 @section define-g-enum
2323
2324 @Macro define-g-enum
2325 @lisp
2326 (define-g-enum g-name name (&key (export t) type-initializer) &body value*)
2327
2328 value ::= :keyword
2329 value ::= (:keyword integer)
2330 @end lisp
2331
2332 @table @var
2333 @item @var{g-name}
2334 A string naming the GEnum type
2335 @item @var{name}
2336 A symbol naming the CFFI enumeration type
2337 @item @var{export}
2338 A boolean indicating whether to export @code{name}
2339 @item @var{type-initializer}
2340 A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
2341 @end table
2342
2343 Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.
2344
2345 Example:
2346 @lisp
2347 (define-g-enum "GtkTextDirection" text-direction
2348   (:export t :type-initializer "gtk_text_direction_get_type")
2349   (:none 0) (:ltr 1) (:rtl 2))
2350
2351 (define-g-enum "GtkSizeGroupMode" size-group-mode
2352  (:export t :type-initializer "gtk_size_group_mode_get_type")
2353  :none :horizontal :vertical :both)
2354 @end lisp
2355
2356 @node define-g-flags
2357 @section define-g-flags
2358
2359 @Macro define-g-flags
2360 @lisp
2361 (define-g-flags g-name name (&key (export t) type-initializer) &body value*)
2362
2363 value ::= :keyword
2364 value ::= (:keyword integer)
2365 @end lisp
2366
2367 @table @var
2368 @item @var{g-name}
2369 A string naming the GFlags type
2370 @item @var{name}
2371 A symbol naming the CFFI flags type
2372 @item @var{export}
2373 A boolean indicating whether to export @code{name}
2374 @item @var{type-initializer}
2375 A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
2376 @end table
2377
2378 Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.
2379
2380 Example:
2381 @lisp
2382 (define-g-flags "GtkAttachOptions" attach-options
2383   (:export t :type-initializer "gtk_attach_options_get_type")
2384   (:expand 1) (:shrink 2) (:fill 4))
2385
2386 (define-g-flags "GtkButtonAction" button-action
2387   (:export t :type-initializer "gtk_button_action_get_type")
2388   :ignored :selects :drags :expands)
2389 @end lisp
2390
2391 @node get-g-enum-definition
2392 @section get-g-enum-definition
2393
2394 @Function get-g-enum-definition
2395 @lisp
2396 (get-g-enum-definition type &optional lisp-name-package) @result{} definition
2397 @end lisp
2398
2399 @table @var
2400 @item @var{type}
2401 A string naming the GEnum type
2402 @item @var{lisp-name-package}
2403 A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
2404 @item @var{definition}
2405 A Lisp form that when evaluated defines the GEnum.
2406 @end table
2407
2408 Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.
2409
2410 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2411
2412 Example:
2413 @lisp
2414 (get-g-enum-definition "GtkDirectionType")
2415 @result{}
2416 (DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
2417                (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
2418                (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
2419                (:RIGHT 5))
2420 @end lisp
2421
2422 @node get-g-flags-definition
2423 @section get-g-flags-definition
2424
2425 @Function get-g-flags-definition
2426 @lisp
2427 (get-g-flags-definition type &optional lisp-name-package) @result{} definition
2428 @end lisp
2429
2430 @table @var
2431 @item @var{type}
2432 A string naming the GFlags type
2433 @item @var{lisp-name-package}
2434 A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
2435 @item @var{definition}
2436 A Lisp form that when evaluated defines the GFlags.
2437 @end table
2438
2439 Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.
2440
2441 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2442
2443 Example:
2444 @lisp
2445 (get-g-flags-definition "GtkCalendarDisplayOptions")
2446 @result{}
2447 (DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
2448                 (:EXPORT T :TYPE-INITIALIZER
2449                  "gtk_calendar_display_options_get_type")
2450                 (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
2451                 (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
2452                 (:SHOW-DETAILS 32))
2453 @end lisp
2454
2455 @node get-g-interface-definition
2456 @section get-g-interface-definition
2457
2458 @Function get-g-interface-definition
2459 @lisp
2460 get-g-interface-definition type &optional lisp-name-package) @result{} definition
2461 @end lisp
2462
2463 @table @var
2464 @item @var{type}
2465 A string naming the GInterface type
2466 @item @var{lisp-name-package}
2467 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*}
2468 @item @var{definition}
2469 A Lisp form that when evaluated defines the GInterface.
2470 @end table
2471
2472 Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.
2473
2474 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2475
2476 Example:
2477 @lisp
2478 (get-g-interface-definition "GtkActivatable")
2479 @result{}
2480 (DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
2481                     (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
2482                     (USE-ACTION-APPEARANCE
2483                      GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
2484                      "use-action-appearance" "gboolean" T T)
2485                     (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
2486                      "related-action" "GtkAction" T T))
2487 @end lisp
2488
2489 @node get-g-class-definition
2490 @section get-g-class-definition
2491
2492 @Function get-g-class-definition
2493 @lisp
2494 (get-g-class-definition type &optional lisp-name-package) @result{} definition
2495 @end lisp
2496
2497 @table @var
2498 @item @var{type}
2499 A string naming the GObject type
2500 @item @var{lisp-name-package}
2501 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*}
2502 @item @var{definition}
2503 A Lisp form that when evaluated defines the GObject.
2504 @end table
2505
2506 Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.
2507
2508 See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.
2509
2510 Example:
2511 @lisp
2512 (get-g-class-definition "GtkButton")
2513 @result{}
2514 (DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
2515                        (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
2516                         ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
2517                         :TYPE-INITIALIZER "gtk_button_get_type")
2518                        ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
2519                         (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
2520                         (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
2521                          T)
2522                         (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
2523                          "gboolean" T T)
2524                         (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
2525                          T T)
2526                         (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
2527                          "focus-on-click" "gboolean" T T)
2528                         (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
2529                         (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
2530                         (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
2531                          "image-position" "GtkPositionType" T T)))
2532 @end lisp
2533
2534 @node Specifying additional properties for CLOS classes
2535 @section Specifying additional properties for CLOS classes
2536
2537 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.
2538
2539 Definitions generator uses variable @code{*additional-properties*} to get this information.
2540
2541 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).
2542
2543 To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.
2544
2545 Example:
2546 @lisp
2547 (("GtkTreeViewColumn"
2548   (:cffi gtk::tree-view
2549          gtk::tree-view-column-tree-view
2550          g-object "gtk_tree_view_column_get_tree_view" nil)
2551   (:cffi gtk::sort-column-id
2552          gtk::tree-view-column-sort-column-id
2553          :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
2554   (:cffi gtk::cell-renderers
2555          gtk::tree-view-column-cell-renderers
2556          (glist g-object  :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
2557  ("GtkTreeSelection"
2558   (:cffi gtk::mode
2559          gtk::tree-selection-mode
2560          gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
2561   (:cffi gtk::select-function
2562          gtk::tree-selection-select-function
2563          nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
2564 @end lisp
2565
2566 @node Generating names for CLOS classes and accessors
2567 @section Generating names for CLOS classes and accessors
2568
2569 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).
2570
2571 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.
2572
2573 Name generation affected by following variables:
2574 @itemize
2575 @item @var{*strip-prefix*}
2576 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}.
2577 @item @var{*lisp-name-exceptions*}
2578 A plist mapping from strings (type names) to symbols (class names) that have special name processing.
2579 Example:
2580 @lisp
2581 `(("GObject" gobject:g-object)
2582   ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2583   ("GInitiallyUnowned" gobject::g-initially-unowned)
2584   ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2585   ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2586   ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2587 @end lisp
2588 @end itemize
2589
2590 @node generate-types-hierarchy-to-file
2591 @section generate-types-hierarchy-to-file
2592
2593 @Function generate-types-hierarchy-to-file
2594 @lisp
2595 (generate-types-hierarchy-to-file file
2596                                   root-type
2597                                   &key include-referenced
2598                                   prefix
2599                                   package
2600                                   exceptions
2601                                   prologue
2602                                   interfaces
2603                                   enums
2604                                   flags
2605                                   objects
2606                                   exclusions
2607                                   additional-properties)
2608 @end lisp
2609
2610 @table @var
2611 @item @var{file}
2612 A string or pathname naming the file, or a stream.
2613 @item @var{root-type}
2614 A GType designator for a root type. All types that inherit from this type will be defined.
2615 @item @var{&key include-referenced}
2616 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
2617 @item @var{prefix}
2618 A string naming the prefix that should be removed from the beginning of names
2619 @item @var{package}
2620 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
2621 @item @var{exceptions}
2622 A plist that maps GType names to their Lisp names.
2623 See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
2624 @item @var{prologue}
2625 A string that will be included verbatim in generated code file
2626 @item @var{interfaces}
2627 Additional list of interfaces that will also be included in generation
2628 @item @var{enums}
2629 Additional list of enums that will also be included in generation
2630 @item @var{flags}
2631 Additional list of flags that will also be included in generation
2632 @item @var{objects}
2633 Additional list of object types that will also be included in generation
2634 @item @var{exclusions}
2635 A list of GType names that will be excluded from generation
2636 @item @var{additional-properties}
2637 A plist of properties definitions that will be added to generated classes.
2638 See @ref{Specifying additional properties for CLOS classes} for more information.
2639 @end table
2640
2641 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.
2642
2643 Example of usage:
2644 @lisp
2645 (generate-types-hierarchy-to-file
2646  "gtk.generated-classes.lisp"
2647  "GtkObject"
2648  :include-referenced t
2649  :prefix "Gtk"
2650  :package (or (find-package :gtk) (make-package :gtk))
2651  :exceptions `(("GObject" gobject:g-object)
2652                ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
2653                ("GInitiallyUnowned" gobject::g-initially-unowned)
2654                ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
2655                ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
2656                ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
2657  :prologue (format nil "(in-package :gtk)")
2658  :interfaces '("GtkBuildable" "GtkCellEditable" ...)
2659  :objects '("GtkSettings" "GtkRcStyle" ...)
2660  :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
2661  :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
2662  :exclusions '("PangoStretch" "PangoVariant" ...)
2663  :additional-properties
2664  '(("GtkTreeViewColumn"
2665     (:cffi
2666      gtk::tree-view
2667      gtk::tree-view-column-tree-view
2668      g-object
2669      "gtk_tree_view_column_get_tree_view"
2670      nil)
2671     ...)
2672    ...))
2673 @end lisp