[cl-gtk2.git] / doc / gobject.ref.texi

@menu
* Introduction::
* GType designator::
* Type hierarchy and type relations::
* Object types information::
* Enum types information::
* Using GValues::
* Stable pointers::
* Closures::
* GObject low-level::
* GObject high-level::
* Creating GObjects classes and implementing GInterfaces::
* GBoxed::
* Generating type definitions by introspection::
@end menu

@node Introduction
@chapter Introduction

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.

The purpose of CL-GTK2-GObject is to ease the creation of binding for libraries based on GObject.

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.

CL-GTK2-GObject is logically split into several layers:
@itemize
@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.
@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.
@item High-level GObject integration. This layer includes support for interoperability between CLOS and GObject and automatic generation of corresponding definitions.
@end itemize

Naturally, users of CL-GTK2-GObject should use the high-level GObject integration, but occasionaly it may be necessary to use lower-level functionality.

@node GType designator
@chapter GType designator

@menu
* g-type-string::
* g-type-numeric::
* g-type=::
* g-type/=::
@end menu

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.

An example of GType designator is a string @code{"GObject"} and the numeric value 80 that corresponds to it.

Some of the types are fundamental and have constant integer values. They are identified by constants (strings in parentheses are corresponding type names):
@itemize
@item @code{+g-type-invalid+}. An invalid GType used as error return value in some functions which return a GType.
@item @code{+g-type-void+} ("void"). A fundamental type which is used as a replacement for the C @code{void} return type.
@item @code{+g-type-interface+} ("GInterface"). The fundamental type from which all interfaces are derived.
@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}.
@item @code{+g-type-uchar+} ("guchar"). The fundamental type corresponding to @code{guchar}.
@item @code{+g-type-boolean+} ("gboolean"). The fundamental type corresponding to @code{gboolean}.
@item @code{+g-type-int+} ("gint"). The fundamental type corresponding to @code{gint}.
@item @code{+g-type-uint+} ("guint"). The fundamental type corresponding to @code{guint}.
@item @code{+g-type-long+} ("glong"). The fundamental type corresponding to @code{glong}.
@item @code{+g-type-ulong+} ("gulong"). The fundamental type corresponding to @code{gulong}.
@item @code{+g-type-int64+} ("gint64"). The fundamental type corresponding to @code{gint64}.
@item @code{+g-type-uint64+} ("guint64"). The fundamental type corresponding to @code{guint64}.
@item @code{+g-type-enum+} ("GEnum"). The fundamental type from which all enumeration types are derived.
@item @code{+g-type-flags+} ("GFlags"). The fundamental type from which all flags types are derived.
@item @code{+g-type-float+} ("gfloat"). The fundamental type corresponding to @code{gfloat}.
@item @code{+g-type-double+} ("gdouble"). The fundamental type corresponding to @code{gdouble}.
@item @code{+g-type-string+} ("gchararray"). The fundamental type corresponding to null-terminated C strings.
@item @code{+g-type-pointer+} ("gpointer"). The fundamental type corresponding to @code{gpointer}.
@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.
@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}.
@item @code{+g-type-object+} ("GObject"). The fundamental type for GObject.
@end itemize

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.

Invalid type (the GType that does not exist) is identified as a 0 or @code{NIL}.

@lisp
(g-type-numeric "GObject") @result{} 80
(g-type-numeric 80) @result{} 80
(g-type-string "GObject") @result{} "GObject"
(g-type-string 80) @result{} "GObject"
(g-type-numeric "GtkWidget") @result{} 6905648 ;;Will be different on each run
@end lisp

@node g-type-string
@section g-type-string

@Function g-type-string
@lisp
(g-type-string g-type-designator) @result{} name
@end lisp

@table @var
@item @var{g-type-designator}
The GType designator for the GType
@item @var{name}
The name of GType
@end table

Returns the name of GType.

@node g-type-numeric
@section g-type-numeric

@Function g-type-numeric
@lisp
(g-type-numeric g-type-designator) @result{} GType
@end lisp

@table @var
@item @var{g-type-designator}.
The GType designator for the GType.
@item @var{GType}
The numeric identifier of GType
@end table

Returns the numeric identifier of GType

@node g-type=
@section g-type=

@Function g-type=
@lisp
(g-type= type-1 type-2) @result{} eq
@end lisp

@table @var
@item @var{type-1}
A GType designator
@item @var{type-2}
A GType designator
@item @var{eq}
A boolean that is true if @code{type-1} and @code{type-2} designate the same type.
@end table

@node g-type/=
@section g-type/=

@Function g-type/=
@lisp
(g-type/= type-1 type-2) @result{} eq
@end lisp

@table @var
@item @var{type-1}
A GType designator
@item @var{type-2}
A GType designator
@item @var{eq}
A boolean that is true if @code{type-1} and @code{type-2} designate different types.
@end table

@node Type hierarchy and type relations
@chapter Type hierarchy and type relations

@menu
* g-type-children::
* g-type-parent::
* g-type-fundamental::
* g-type-depth::
* g-type-next-base::
@end menu

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.

There are functions to query some specific information:
@itemize
@item @code{g-type-fundamental} retrieves the fundamental type for given type
@item @code{g-type-depth} calculates the depth of the type in type hierarchy
@item @code{g-type-next-base} calculates the first step in the path from base type to descendent type
@end itemize

@node g-type-children
@section g-type-children

@Function g-type-children
@lisp
(g-type-children type) @result{} children
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{children}
A list of GType designators
@end table

Returns the list of descendent types.

Example:
@lisp
(g-type-children "GtkButton")
@result{}
("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
@end lisp

@node g-type-parent
@section g-type-parent

@Function g-type-parent
@lisp
(g-type-parent type) @result{} parent
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{parent}
A GType designator
@end table

Returns the parent of @code{type}.

Example:
@lisp
(g-type-parent "GtkToggleButton")
@result{}
"GtkButton"
@end lisp

@node g-type-fundamental
@section g-type-fundamental

@Function g-type-fundamental
@lisp
(g-type-fundamental type) @result{} fundamental-type
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{fundamental-type}
A GType designator for one of the fundamental types
@end table

Returns the fundamental type that is the ancestor of @code{type}.

Example:
@lisp
(g-type-fundamental "GtkButton") @result{} "GObject"

(g-type-fundamental "GtkWindowType") @result{} "GEnum"

(g-type-fundamental "GdkEvent") @result{} "GBoxed"
@end lisp

@node g-type-depth
@section g-type-depth

@Function g-type-depth
@lisp
(g-type-depth type) @result{} depth
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{depth}
An integer
@end table

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.

Example:
@lisp
(g-type-depth "GObject") @result{} 1
(g-type-depth "GInitiallyUnowned") @result{} 2
@end lisp

@node g-type-next-base
@section g-type-next-base

@Function g-type-next-base
@lisp
(g-type-next-base leaf-type root-type) @result{} base-type
@end lisp

@table @var
@item @var{leaf-type}
A GType designator
@item @var{root-type}
A GType designator
@item @var{base-type}
A GType designator
@end table

Returns the next type that should be traversed from @code{root-type} in order to reach @code{leaf-type}. E.g., given type hierarchy:
@lisp
+ GObject
 \
  + GInitiallyUnowned
   \
    + GtkObject
    |\
    | + GtkAdjustment
     \
      + GtkWidget
       \
        + GtkContainer
         \
          + GtkTable
@end lisp

the following will be returned:

@lisp
(g-type-next-base "GtkTable" "GObject") @result{} "GInitiallyUnowned"
(g-type-next-base "GtkTable" "GInitiallyUnowned") @result{} "GtkObject"
(g-type-next-base "GtkTable" "GtkObject") @result{} "GtkWidget"
(g-type-next-base "GtkTable" "GtkWidget") @result{} "GtkContainer"
(g-type-next-base "GtkTable" "GtkContainer") @result{} "GtkTable"
@end lisp

@node Object types information
@chapter Object types information
@menu
* g-class-property-definition::
* class-properties::
* class-property-info::
* interface-properties::
* signal-info::
* type-signals::
* parse-signal-name::
* query-signal-info::
* g-type-interfaces::
* g-type-interface-prerequisites::
@end menu

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.

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.

@node g-class-property-definition
@section g-class-property-definition

@Struct g-class-property-definition
@lisp
(defstruct g-class-property-definition
  name
  type
  readable
  writable
  constructor
  constructor-only
  owner-type)
@end lisp

@table @var
@item @var{name}
A string that names the property
@item @var{type}
A GType designator. Identifies the type of the property
@item @var{readable}
A boolean. Identifies whether the property can be read
@item @var{writable}
A boolean. Identifies whether the property can be assigned
@item @var{constructor}
A boolean. Identifies whether constructor of object accepts this property
@item @var{constructor-only}
A boolean. Identifies whether this property may only be set in constructor, not in property setter
@item @var{owner-type}
A GType designator. Identifies the type on which the property was defined.
@end table

This structure identifies a single property. Its field specify attributes of a property.

Structures of this type have shortened print syntax:
@lisp
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)> 
@end lisp

(When @code{*print-readably*} is T, usual @code{defstruct} print syntax is used)

This syntax specifies:
@itemize
@item type of property
@item the owner type of property
@item name of property
@item additional flags of property
@end itemize

@node class-properties
@section class-properties

@Function class-properties
@lisp
(class-properties type) @result{} properties
@end lisp

@table @var
@item @var{type}
A GType designator. Specifies the object type (class)
@item @var{properties}
A list of @code{g-property-definition} structures.
@end table

This function returns the list of properties that are available in class @code{type}.

Example:
@lisp
(class-properties "GtkWidget")
@result{}
(#<PROPERTY gpointer GtkObject.user-data (flags: readable writable)>
 #<PROPERTY gchararray GtkWidget.name (flags: readable writable)>
 #<PROPERTY GtkContainer GtkWidget.parent (flags: readable writable)>
 #<PROPERTY gint GtkWidget.width-request (flags: readable writable)>
 #<PROPERTY gint GtkWidget.height-request (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.visible (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.sensitive (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.app-paintable (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.can-focus (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.has-focus (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.is-focus (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.can-default (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.has-default (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.receives-default (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.composite-child (flags: readable)>
 #<PROPERTY GtkStyle GtkWidget.style (flags: readable writable)>
 #<PROPERTY GdkEventMask GtkWidget.events (flags: readable writable)>
 #<PROPERTY GdkExtensionMode GtkWidget.extension-events (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.no-show-all (flags: readable writable)>
 #<PROPERTY gboolean GtkWidget.has-tooltip (flags: readable writable)>
 #<PROPERTY gchararray GtkWidget.tooltip-markup (flags: readable writable)>
 #<PROPERTY gchararray GtkWidget.tooltip-text (flags: readable writable)>
 #<PROPERTY GdkWindow GtkWidget.window (flags: readable)>)
@end lisp

@node class-property-info
@section class-property-info
@Function class-property-info
@lisp
(class-property-info type property-name) @result{} property
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{property-name}
A string naming the property
@item @var{property}
An instance of @code{g-property-definition} structure
@end table

Returns the property information for a single property.

Example:
@lisp
(class-property-info "GtkButton" "label")
@result{}
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
@end lisp

@node interface-properties
@section interface-properties

@Function interface-properties
@lisp
(interface-properties type) @result{} properties
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{properties}
A list of @code{g-property-definition} structures
@end table

This function returns the list of properties that are available in interface @code{type}.

Example:
@lisp
(interface-properties "GtkFileChooser")
@result{}
(#<PROPERTY GtkWidget GtkFileChooser.extra-widget (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.use-preview-label (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.preview-widget-active (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.show-hidden (flags: readable writable)>
 #<PROPERTY gchararray GtkFileChooser.file-system-backend (flags: writable constructor-only)>
 #<PROPERTY GtkFileChooserAction GtkFileChooser.action (flags: readable writable)>
 #<PROPERTY GtkFileFilter GtkFileChooser.filter (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.select-multiple (flags: readable writable)>
 #<PROPERTY GtkWidget GtkFileChooser.preview-widget (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.local-only (flags: readable writable)>
 #<PROPERTY gboolean GtkFileChooser.do-overwrite-confirmation (flags: readable writable)>)
@end lisp

@node signal-info
@section signal-info

@Struct signal-info
@lisp
(defstruct signal-info
  id
  name
  owner-type
  flags
  return-type
  param-types
  detail)
@end lisp

@table @var
@item @var{id}
An integer - the identifier of a signal
@item @var{name}
Name of a signal
@item @var{owner-type}
A GType designator identifying the type on which the signal was defined
@item @var{flags}
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
@item @var{return-type}
The return type of a signal (and signal handlers)
@item @var{param-types}
A list of GType designators that specify the types of signal parameters
@item @var{detail}
A string. Specifies the "detail" part of a signal name. E.g., @code{"label"} for signal @code{"notify::label"}.
@end table

When @code{*print-readably*} is nil, the following print syntax is used:
@lisp
#<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
#<Signal [#54] gboolean GtkWidget.proximity-in-event(GdkEvent) [RUN-LAST]>
#<Signal [#64] void GtkWidget.drag-data-received(GdkDragContext, gint, gint, GtkSelectionData, guint, guint) [RUN-LAST]>
#<Signal [#8] void GtkObject.destroy() [RUN-CLEANUP, NO-RECURSE, NO-HOOKS]>
@end lisp

This syntax specifies:
@itemize
@item the signal id
@item signal return type
@item owner type
@item signal name
@item detail
@item list of types of parameters
@item flags
@end itemize

@node type-signals
@section type-signals
@Function type-signals
@lisp
(type-signals type &key (include-inherited t)) @result{} signals
@end lisp
@table @var
@item @var{type}
A GType designator
@item @var{signals}
A list of @code{signal-info} structures
@item @var{include-inherited}
A boolean that specifies whether to include signals defined on this type or also on ancestor types.
@end table

Returns the list of signals that are available in type @code{type}.

Example:
@lisp
(type-signals "GtkLabel" :include-inherited nil)
@result{}
(#<Signal [#138] void GtkLabel.move-cursor(GtkMovementStep, gint, gboolean) [RUN-LAST, ACTION]>
 #<Signal [#139] void GtkLabel.copy-clipboard() [RUN-LAST, ACTION]>
 #<Signal [#140] void GtkLabel.populate-popup(GtkMenu) [RUN-LAST]>)
@end lisp

@node parse-signal-name
@section parse-signal-name

@Function parse-signal-name
@lisp
(parse-signal-name type signal-name) @result{} signal
@end lisp

@table @var
@item @var{type}
A GType designator that has the signal.
@item @var{signal-name}
A string that identifies the signal.
@item @var{signal}
A list @code{signal-info} structures.
@end table

Parses the signal name and returns the corresponding information. @code{signal-name} may include the detail part.

Example:
@lisp
(parse-signal-name "GObject" "notify::label")
@result{}
#<Signal [#1] void GObject.notify::label(GParam) [RUN-FIRST, NO-RECURSE, DETAILED, ACTION, NO-HOOKS]>
@end lisp

@node query-signal-info
@section query-signal-info
@Function query-signal-info
@lisp
(query-signal-info signal-id) @result{} signal
@end lisp
@table @var
@item @var{signal-id}
An integer identifying the signal
@item @var{signal}
An instance of @code{signal-info} structure
@end table

Retrieves the signal information by its id.

Example:
@lisp
(query-signal-info 73)
@result{}
#<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
@end lisp

@node g-type-interfaces
@section g-type-interfaces

@Function g-type-interfaces
@lisp
(g-type-interfaces type) @result{} interfaces
@end lisp

@table @var
@item @var{type}
A GType designator
@item @var{interfaces}
A list of GType designators
@end table

Returns the list of interfaces that @code{type} implements.

Example:
@lisp
(g-type-interfaces "GtkButton")
@result{}
("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
@end lisp

@node g-type-interface-prerequisites
@section g-type-interface-prerequisites

@Function g-type-interface-prerequisites
@lisp
(g-type-interface-prerequisites type) @result{} types
@end lisp

@table @var
@item @var{type}
A GType designator of interface
@item @var{types}
A list of GType designators specifying the interface prerequisites
@end table

Returns the prerequisites of an interface @code{type}. Prerequisite is a type that should be an ancestor of a type implementing interface @code{type}.

Example:
@lisp
(g-type-interface-prerequisites "GtkCellEditable")
@result{}
("GtkObject" "GtkWidget")
@end lisp

@node Enum types information
@chapter Enum types information
@menu
* enum-item::
* flags-item::
* get-enum-items::
* get-flags-items::
@end menu

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.

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.

@node enum-item
@section enum-item
@Struct enum-item
@lisp
(defstruct enum-item
  name value nick)
@end lisp

@table @var
@item @var{name}
A string - name of enum item
@item @var{value}
An integer - numeric value of enum item
@item @var{nick}
A string - short name of an enum item
@end table

Structure @code{enum-item} represents a single item of an enumeration type.

Example:
@lisp
#S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
@end lisp

@node flags-item
@section flags-item
@Struct flags-item
@lisp
(defstruct flags-item
  name value nick)
@end lisp

@table @var
@item @var{name}
A string - name of flags item
@item @var{value}
An integer - numeric value of flags item
@item @var{nick}
A string - short name of an flags item
@end table

Structure @code{flags-item} represents a single item of an flags type.

Example:
@lisp
#S(FLAGS-ITEM
   :NAME "GDK_POINTER_MOTION_HINT_MASK"
   :VALUE 8
   :NICK "pointer-motion-hint-mask")
@end lisp

@node get-enum-items
@section get-enum-items

@Function get-enum-items
@lisp
(get-enum-items type) @result{} items
@end lisp

@table @var
@item @var{type}
A GType designator of an enum type
@item @var{items}
A list of @code{enum-item} structures
@end table

Returns a list of items in an enumeration

Example:
@lisp
(get-enum-items "GtkScrollType")
@result{}
(#S(ENUM-ITEM :NAME "GTK_SCROLL_NONE" :VALUE 0 :NICK "none")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_JUMP" :VALUE 1 :NICK "jump")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_BACKWARD" :VALUE 2 :NICK "step-backward")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_FORWARD" :VALUE 3 :NICK "step-forward")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_BACKWARD" :VALUE 4 :NICK "page-backward")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_FORWARD" :VALUE 5 :NICK "page-forward")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_UP" :VALUE 6 :NICK "step-up")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_DOWN" :VALUE 7 :NICK "step-down")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_UP" :VALUE 8 :NICK "page-up")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_DOWN" :VALUE 9 :NICK "page-down")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_LEFT" :VALUE 10 :NICK "step-left")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_STEP_RIGHT" :VALUE 11 :NICK "step-right")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_LEFT" :VALUE 12 :NICK "page-left")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_PAGE_RIGHT" :VALUE 13 :NICK "page-right")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_START" :VALUE 14 :NICK "start")
 #S(ENUM-ITEM :NAME "GTK_SCROLL_END" :VALUE 15 :NICK "end"))
@end lisp

@node get-flags-items
@section get-flags-items

@Function get-flags-items
@lisp
(get-flags-items type) @result{} items
@end lisp

@table @var
@item @var{type}
A GType designator of an flags type
@item @var{items}
A list of @code{flags-item} structures
@end table

Returns a list of items in an flags type

Example:
@lisp
(get-flags-items "GtkAttachOptions")
@result{}
(#S(FLAGS-ITEM :NAME "GTK_EXPAND" :VALUE 1 :NICK "expand")
 #S(FLAGS-ITEM :NAME "GTK_SHRINK" :VALUE 2 :NICK "shrink")
 #S(FLAGS-ITEM :NAME "GTK_FILL" :VALUE 4 :NICK "fill"))
@end lisp

@node Using GValues
@chapter Using GValues
@menu
* g-value-zero::
* g-value-init::
* g-value-unset::
* parse-g-value::
* set-g-value::
* Registering types::
@end menu

GValue is a generic container for arbitrary value of type supported by GType system. Refer to GObject documentation for more detailed information.

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.

GValue is used whenever a value of unkown type should be passed. It is used in:
@itemize
@item Closure marshal functions
@item Property get and set functions
@end itemize

Example of usage:
@lisp
(cffi:with-foreign-object (gval 'g-value)
  (set-g-value gval "Hello" "gchararray" :zero-g-value t)
  (format t "~S~%" (parse-g-value gval))
  (g-value-unset gval))
@result{}
"Hello"
@end lisp

@node g-value-zero
@section g-value-zero
@Function g-value-zero
@lisp
(g-value-zero g-value)
@end lisp
@table @var
@item @var{g-value}
A foreign pointer to GValue structure.
@end table

Initializes the GValue to "unset" state. Equivalent of the following initializer in C:
@lisp
GValue value = @{ 0 @};
@end lisp

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).

@node g-value-init
@section g-value-init

@Function g-value-init
@lisp
(g-value-init value type)
@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure
@item @var{type}
A GType designator
@end table

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).

@node g-value-unset
@section g-value-unset
@Function g-value-unset
@lisp
(g-value-unset value)
@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure.
@end table

Unsets the GValue. This frees all resources associated with GValue.

@node parse-g-value
@section parse-g-value
@Function parse-g-value
@lisp
(parse-g-value value) @result{} object
@end lisp
@table @var
@item @var{value}
A foreign pointer to GValue structure
@item @var{object}
A Lisp object
@end table

Retrieves the object from GValue structure.

@node set-g-value
@section set-g-value
@Function set-g-value
@lisp
(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))
@end lisp

@table @var
@item @var{gvalue}
A foreign pointer to GValue structure
@item @var{object}
An object that is to be assigned to @code{gvalue}
@item @var{type}
A GType designator specifying what GType should be set
@item @var{unset-g-value}
A boolean specifying whether to call @code{g-value-unset} before assigment.
@item @var{zero-g-value}
A boolean specifying whether to call @code{g-value-zero} before assignment
@item @var{g-value-init}
A boolean specifying whether to call @code{g-value-init} before assignment
@end table

Assigns the @code{object} to the @code{gvalue}. When GValue is not used, call @code{g-value-unset} to deinitialize the @code{GValue}.

@node Registering types
@section Registering types

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.

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.

@subsection register-enum-type
@Function register-enum-type
@lisp
(register-enum-type name type)
@end lisp
@table @var
@item @var{name}
A string naming the GEnum type
@item @var{type}
A symbol - name of CFFI foreign enum type
@end table

Registers the @code{type} to be used for passing value of GEnum type @code{name} between GObject and Lisp.

Example:
@lisp
(defcenum text-direction
  :none :ltr :rtl)
(register-enum-type "GtkTextDirection" 'text-direction)
@end lisp

@subsection register-flags-type
@Function register-flags-type
@lisp
(register-flags-type name type)
@end lisp
@table @var
@item @var{name}
A string naming the GFlags type
@item @var{type}
A symbol - name of CFFI foreign flags type
@end table

Registers the @code{type} to be used for passing value of GFlags type @code{name} between GObject and Lisp.

Example:
@lisp
(defcenum state-type
  :normal :active :prelight :selected :insensitive)
(register-enum-type "GtkStateType" 'state-type)
@end lisp

@node Stable pointers
@chapter Stable pointers
@menu
* allocate-stable-pointer::
* free-stable-pointer::
* stable-pointer-value::
* with-stable-pointer::
@end menu

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.

@node allocate-stable-pointer
@section allocate-stable-pointer

@Function allocate-stable-pointer
@lisp
(allocate-stable-pointer thing) @result{} stable-pointer
@end lisp

@table @var
@item @var{thing}
An arbitrary Lisp object
@item @var{stable-pointer}
A foreign pointer
@end table

Allocates a stable pointer to @code{thing}.

(Note: @var{stable-pointer} should not be dereferenced with @code{cffi:mem-ref}. It should only be dereferenced with @code{stable-pointer-value})

Example:
@lisp
(allocate-stable-pointer (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X00000002)

(stable-pointer-value *)
@result{}
#<FUNCTION (LAMBDA (X)) @{1004D016F9@}>

(free-stable-pointer **)
@result{}
NIL
@end lisp

@node free-stable-pointer
@section free-stable-pointer

@Function free-stable-pointer
@lisp
(free-stable-pointer stable-pointer)
@end lisp

@table @var
@item @var{stable-pointer}
A foreign pointer that was created with @code{allocate-stable-pointer}.
@end table

Frees the stable pointer, enabling the garbage collector to reclaim the object.

Example:
@lisp
(allocate-stable-pointer (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X00000002)

(stable-pointer-value *)
@result{}
#<FUNCTION (LAMBDA (X)) @{1004D016F9@}>

(free-stable-pointer **)
@result{}
NIL
@end lisp

@node stable-pointer-value
@section stable-pointer-value

@Accessor stable-pointer-value
@lisp
(stable-pointer-value stable-pointer) @result{} thing
(setf (stable-pointer-value stable-pointer) thing)
@end lisp

@table @var
@item @var{stable-pointer}
A foreign pointer created by @code{allocate-stable-pointer}
@item @var{thing}
A Lisp object
@end table

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.

@node with-stable-pointer
@section with-stable-pointer

@Macro with-stable-pointer
@lisp
(with-stable-pointer (ptr expr) &body body)
@end lisp

@table @var
@item @var{ptr}
A variable that will be bound to the stable pointer
@item @var{expr}
An expression that will be evaluated once and its value will be bound to stable pointer's value
@end table

Executes the body with the @code{ptr} variable being bound to a stable pointer whose value is determined by @code{expr}.

Example:
@lisp
(with-stable-pointer (ptr (lambda (x) (+ x 10)))
  (print (stable-pointer-value ptr)))
;;Prints:
#<FUNCTION (LAMBDA (X)) @{1004807E79@}>
@end lisp

@node Closures
@chapter Closures
@menu
* create-signal-handler-closure::
* Object-bound foreign functions::
@end menu

Closure are anonymous functions that capture their lexical environment.

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).

(TODO: GObject defines finer closure API: g_closure_ref, g_closure_unref, g_closure_invoke. It should be bound.)

@node create-signal-handler-closure
@section create-signal-handler-closure
@Function create-signal-handler-closure
@lisp
(create-signal-handler-closure object fn) @result{} closure
@end lisp

@table @var
@item @var{object}
An object for which the closure is created
@item @var{fn}
A function that will be called by closure invokation
@item @var{closure}
A foreign pointer to allocated closure
@end table

Allocates the closure. The closure is destroyed automatically by GObject.

Example:
@lisp
(create-signal-handler-closure obj (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X006D7B20)
@end lisp

Example of usage from GObject binding code:
@lisp
(defun connect-signal (object signal handler &key after)
  (g-signal-connect-closure (ensure-object-pointer object)
                            signal
                            (create-signal-handler-closure object handler)
                            after))
@end lisp

@node Object-bound foreign functions
@section Object-bound foreign functions

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.

@RMacro define-cb-methods
@lisp
(define-cb-methods name return-type ((arg-1 type-1) ... (arg-n type-n)))
@end lisp

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}.

Arguments and return-type are the same as CFFI arguments and return-type for callbacks. Arguments do not include the last 'data' pointer.

@RFunction create-fn-ref
@lisp
(create-fn-ref object function) @result{} foreign-pointer
@end lisp

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.

Example:
@lisp
(defcfun gtk-assistant-set-forward-page-func :void
  (assistant (g-object assistant))
  (page-func :pointer)
  (data :pointer)
  (destroy-notify :pointer))

(define-cb-methods assistant-page-func :int ((current-page :int)))

(defun set-assistant-forward-page-function (assistant function)
  (if function
      (gtk-assistant-set-forward-page-func assistant
                                           (callback assistant-page-func-cb)
                                           (create-fn-ref assistant function)
                                           (callback assistant-page-func-destroy-notify))
      (gtk-assistant-set-forward-page-func assistant (null-pointer) (null-pointer) (null-pointer))))
@end lisp

@node GObject low-level
@chapter GObject low-level
@menu
* g-object-call-constructor::
* g-type-from-object::
* g-object-call-get-property::
* g-object-call-set-property::
@end menu

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.

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.

@node g-object-call-constructor
@section g-object-call-constructor

@Function g-object-call-constructor
@lisp
(g-object-call-constructor object-type args-names args-values &optional args-types) @result{} object-ptr
@end lisp

@table @var
@item @var{object-type}
A GType designator that specifies the object type that is to be created
@item @var{args-names}
A list of strings naming the arguments to constructor
@item @var{args-value}
A list of arguments values (in the same order as args-names)
@item @var{args-types}
Optional list of arguments types (in the same order as args-names). If not specified, it is detected automatically
@item @var{object-ptr}
A foreign pointer to newly created instance
@end table

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}.

Example:
@lisp
(g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
@result{}
#.(SB-SYS:INT-SAP #X006D8900)

(g-object-call-get-property * "label")
@result{}
"Hello"

(g-object-call-get-property ** "use-underline")
@result{}
T
@end lisp

@node g-type-from-object
@section g-type-from-object

@Function g-type-from-object
@lisp
(g-type-from-object object-ptr) @result{} type
@end lisp

@table @var
@item @var{object-ptr}
A foreign pointer to a GObject instance
@item @var{type}
A GType designator
@end table

Returns the type of an object by a pointer to its instance

Example:
@lisp
(g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
@result{}
"GtkButton"
@end lisp

@node g-object-call-get-property
@section g-object-call-get-property

@Function g-object-call-get-property
@lisp
(g-object-call-get-property object-ptr property-name &optional property-type) @result{} property-value
@end lisp

@table @var
@item @var{object-ptr}
A foreign pointer to a GObject instance
@item @var{property-name}
A string naming the property
@item @var{property-type}
Optional GType designator specifying the type of a property
@item @var{property-value}
The value of a property
@end table

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.

Example:
@lisp
(g-object-call-constructor "GtkButton" '("label" "use-underline") '("Hello" t) '("gchararray" "gboolean"))
@result{}
#.(SB-SYS:INT-SAP #X006D8900)

(g-object-call-get-property * "label")
@result{}
"Hello"

(g-object-call-get-property ** "use-underline")
@result{}
T
@end lisp

@node g-object-call-set-property
@section g-object-call-set-property

@Function g-object-call-set-property
@lisp
(g-object-call-set-property object-ptr property-name new-value &optional property-type)
@end lisp

@table @var
@item @var{object-ptr}
A foreign pointer to a GObject instance
@item @var{property-name}
A string naming the property
@item @var{new-value}
A new value of a property
@item @var{property-type}
Optional GType designator specifying the type of a property
@end table

Sets the property value of property @code{property-name} of object @code{object-ptr} to @code{new-value}.

Example:
@lisp
(g-object-call-constructor "GtkButton" nil nil)
@result{}
#.(SB-SYS:INT-SAP #X006D8B40)

(g-object-call-set-property * "label" "Hello")
@result{}
; No value

(g-object-call-get-property ** "label")
@result{}
"Hello"
@end lisp

@node GObject high-level
@chapter GObject high-level
@menu
* g-object::
* g-initially-unowned::
* GObject metaclass::
* Using objects::
* Signals::
* GObject foreign class::
@end menu

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):
@itemize
@item objects are created with @code{make-instance}
@item properties are used as regular slots
@end itemize

GObjects are reference counted, and CL-GTK2-GOBJECT manages its own reference to GObjects. This enables to have transparent garbage collection of unreferenced GObjects.

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.

Example GObject class of definition:
@lisp
(defclass dialog (gtk-window atk-implementor-iface buildable)
  ((has-separator :accessor dialog-has-separator
                  :initarg :has-separator
                  :allocation :gobject-property
                  :g-property-type "gboolean"
                  :g-property-name "has-separator"))
  (:metaclass gobject-class)
  (:g-type-name . "GtkDialog")
  (:g-type-initializer . "gtk_dialog_get_type"))
@end lisp

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.

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.

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).

@node g-object
@section g-object

@Class g-object

A base class for all GObject classes.

@Accessor pointer g-object

An accessor that accesses the foreign pointer to object.

@Function release
@lisp
(release object)
@end lisp

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.

@Macro using
@lisp
(using (object expr) &body body)
@end lisp

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.

@Macro using
@lisp
(using ((var1 expr1) (var2 expr2) ... (varn exprn)) &body body)
@end lisp

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.

@node g-initially-unowned
@section g-initially-unowned

@Class g-initially-unowned

Superclass: @ref{g-object}

A base class for all GObject classes whose initial reference is floating.

@node GObject metaclass
@section GObject metaclass

See MOP for information what metaclass is and why is it useful.

GObject metaclass @code{gobject-class} bridges two object systems: GObject and CLOS.

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.

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.

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}.

This class has the following slots:
@itemize
@item @var{g-type-name} (accessor @code{gobject-class-g-type-name}, initarg @code{:g-type-name})

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}.
@item @var{g-type-initializer} (accessor @code{gobject-class-g-type-initializer}, initarg @code{:g-type-initializer})

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.
@item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})

A boolean specifying whether this CLOS class corresponds to GInterface. It is NIL by default.
@end itemize

This metaclass defines the GObject classes.

Slots which have @code{:allocation} of @code{:gobject-property} are mapped to GObject properties. Such slots have following attributes:
@itemize
@item @var{:g-property-type}

A string naming GType of property
@item @var{:g-property-name}

A name of a property
@end itemize

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:
@itemize
@item @var{:g-property-type}
A CFFI foreign type of property
@item @var{:g-getter}
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)}.
@item @var{:g-setter}
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))}.
@end itemize

Initargs of a slot are used to construct the GObject class.

Example:
@lisp
(defclass container (widget atk-implementor-iface buildable)
    ((border-width :allocation :gobject-property
                   :g-property-type "guint"
                   :accessor container-border-width
                   :initarg :border-width
                   :g-property-name "border-width")
     (resize-mode :allocation :gobject-property
                  :g-property-type "GtkResizeMode"
                  :accessor container-resize-mode
                  :initarg :resize-mode
                  :g-property-name "resize-mode")
     (child :allocation :gobject-property
            :g-property-type "GtkWidget"
            :accessor container-child
            :initarg :child
            :g-property-name "child")
     (focus-child :allocation :gobject-fn
                  :g-property-type g-object
                  :accessor container-focus-child
                  :initarg :focus-child
                  :g-getter "gtk_container_get_focus_child"
                  :g-setter "gtk_container_set_focus_child")
     (focus-vadjustment :allocation :gobject-fn
                        :g-property-type (g-object adjustment)
                        :accessor container-focus-vadjustment
                        :initarg :focus-vadjustment
                        :g-getter "gtk_container_get_focus_vadjustment"
                        :g-setter "gtk_container_set_focus_vadjustment")
     (focus-hadjustment :allocation :gobject-fn
                        :g-property-type (g-object adjustment)
                        :accessor container-focus-hadjustment
                        :initarg :focus-hadjustment
                        :g-getter "gtk_container_get_focus_hadjustment"
                        :g-setter "gtk_container_set_focus_hadjustment"))
    (:metaclass gobject-class)
    (:g-type-name . "GtkContainer")
    (:g-type-initializer . "gtk_container_get_type"))
@end lisp
(note the dot in @code{(:g-type-name . "GtkContainer")} and in @code{(:g-type-initializer . "gtk_container_get_type")}. It should be present)

@node Using objects
@section Using objects
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.

Example:
@lisp
(make-instance 'gtk:dialog :has-separator t)
@result{}
#<GTK:DIALOG @{10036C5A71@}>

(defvar *d* (make-instance 'gtk:dialog :has-separator t))
@result{}
*D*

(gtk:dialog-has-separator *d*)
@result{}
T

(setf (gtk:dialog-has-separator *d*) nil)
@result{}
NIL

(gtk:dialog-has-separator *d*)
@result{}
NIL
@end lisp

@node Signals
@section Signals

To connect handler to a signal, @code{connect-signal} function is used. Function @code{disconnect-signal} removes the connected signal.

@Function connect-signal
@lisp
(connect-signal object signal handler &key after) @result{} handler-id
@end lisp

@table @var
@item @var{object}
An instance of GObject object
@item @var{signal}
A signal name
@item @var{handler}
A function
@item @var{after}
A boolean specifying whether the handler should be called after the default handler
@item @var{handler-id}
An integer - identifier of signal handler; can be used to disconnect the signal handler with @code{disconnect-signal}
@end table

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.

@Function disconnect-signal
@lisp
(disconnect-signal object handler-id)
@end lisp

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.

Example:
@lisp
(defvar *d* (make-instance 'gtk:dialog))
@result{}
*D*

*d*
@result{}
#<GTK:DIALOG @{1002D866F1@}>

(parse-signal-name "GtkDialog" "response")
@result{}
#<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>

(connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))

(emit-signal *d* "response" 14)
@result{}
;; Prints:
#<GTK:DIALOG @{1002D866F1@}>
14 
@end lisp

Function @code{emit-signal} is used to emit signals on objects.

@RFunction emit-signal
@code{(emit-signal object signal-name &rest args) @result{} return-value}

@table @var
@item @var{object}
An object on which the signal should be emitted
@item @var{signal-name}
A string naming the signal
@item @var{args}
Arguments for a signal
@item @var{return-value}
Return value of a signal
@end table

Emits the signal and calls all handlers of the signal. If signal returns a value, it is returned from @code{emit-signal}.

Example:
@lisp
(defvar *d* (make-instance 'gtk:dialog))
@result{}
*D*

*d*
@result{}
#<GTK:DIALOG @{1002D866F1@}>

(parse-signal-name "GtkDialog" "response")
@result{}
#<Signal [#86] void GtkDialog.response(gint) [RUN-LAST]>

(connect-signal *d* "response" (lambda (dialog response-value) (print dialog) (print response-value)))

(emit-signal *d* "response" 14)
@result{}
;; Prints:
#<GTK:DIALOG @{1002D866F1@}>
14 
@end lisp

@node GObject foreign class
@section GObject foreign class

To enable passing GObject instance between Lisp code and foreign code, @code{g-object} foreign type is introduced.

This type has the following syntax:
@code{(g-object [type] [:already-referenced])} or @code{g-object}. (Brackets indicate optional arguments)

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).

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.

This defines the function that may be called with instances of types @code{container} and @code{widget}:
@lisp
(defcfun (container-add "gtk_container_add") :void
  (container (g-object container))
  (widget (g-object widget)))

(let ((window (make-instance 'gtk-window))
      (widget (make-instance 'button)))
  (container-add window widget))
@end lisp
(@code{gtk-window} is a subclass of @code{container}; @code{button} is a subclass of @code{widget})

This defines the function that returns an instance of GObject class:
@lisp
(defcfun (bin-child "gtk_bin_get_child") (g-object widget)
  (bin (g-object bin)))

(let ((window (make-instance 'gtk-window))
      (widget (make-instance 'button)))
  (container-add window widget)
  (bin-child window))
@result{}
#<GTK:BUTTON @{1002DE74B1@}>
@end lisp

This example shows the use of @code{:already-referenced} option:
@lisp
(defcfun (widget-create-pango-layout "gtk_widget_create_pango_layout") (g-object gdk::pango-layout :already-referenced)
  (widget (g-object widget))
  (text :string))

(defcfun gdk-gc-new (g-object graphics-context :already-referenced)
  (drawable (g-object drawable)))
@end lisp

@node Creating GObjects classes and implementing GInterfaces
@chapter Creating GObjects classes and implementing GInterfaces

@menu
* define-vtable::
* register-object-type-implementation::
@end menu

Creating GObject classes from Lisp is the most complex part of GObject binding.

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).

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.

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).

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.

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.

@node define-vtable
@section define-vtable

@Macro define-vtable
@lisp
(define-vtable (g-type-name type-name)
  &body item*)

item ::= (:skip cffi-structure-item)
item ::= (method-name (return-type &rest arg*) &key impl-call)
arg ::= (arg-name arg-type)
impl-call ::= ((arg-name*) &body call-code)
@end lisp

@table @var
@item @var{g-type-name}
A string naming the GObject type of interface
@item @var{cffi-structure-item}
A structure item that is inserted verbatim into foreign structure definition of vtable and is not used as a pointer to method
@item @var{method-name}
A name for implementation generic function
@item @var{return-type}
A CFFI specifier for foreign function return type
@item @var{arg-name}
A symbol naming the argument of interface method
@item @var{arg-type}
A CFFI specifier for foreign function argument type
@item @var{call-code}
A body of code that is used to convert arguments and return values between interface signature and desired implementor generic function signature
@end table

Macro that specifies the vtable for an interface. Vtable for an interface is a structure that contains pointer to implementations of interface methods. Vtable is used to dispach method calls to corresponding method implementations. In cl-gtk2-gobject, vtables are needed to create classes that implement GObject interfaces.

GObject interfaces are implemented in the following way. For every method, an implementor generic function is defined. This generic function is called by interface method callback, and CLOS classes specialize on this generic function to implement an interface. The generic function has the same signature as the interface's function, but signatures may differ.

This macro defines generic functions (named by concatenatinag @var{type-name}, @var{name} and @code{impl}; e.g., @code{get-flags} method of class @code{tree-model} will have generic function named @code{tree-model-get-flags-impl}) 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.

In some cases, the signature of interface method is not very lispy: it may pass @code{void*} pointers, pointers to places where return values should be stored. To conceal such unlispy things, you specify your own code that will call the generic function and translate arguments for implementor generic function. This is implemented by specifying @var{impl-call} method option. @var{impl-call} specifies the signature of implementor function and code that calls the generic function and returns its result. The code is put in return position of callback, and it has access to the arguments of callback and its return value becomes the return value of callback.

Example:
@lisp
(define-vtable ("GtkTreeModel" tree-model)
  (:skip parent-instance g-type-interface)
  ;;some signals
  (:skip tree-model-row-changed :pointer)
  (:skip tree-model-row-inserted :pointer)
  (:skip tree-model-row-has-child-toggled :pointer)
  (:skip tree-model-row-deleted :pointer)
  (:skip tree-model-rows-reordered :pointer)
  ;;methods
  (get-flags (tree-model-flags (tree-model g-object)))
  (get-value (:void
              (tree-model g-object)
              (iter (g-boxed-foreign tree-iter))
              (n :int)
              (value (:pointer g-value)))
             :impl-call
             ((tree-model iter n)
              (multiple-value-bind (v type) (tree-model-get-value-impl tree-model iter n)
                (set-g-value value v type)))))

(defmethod tree-model-get-flags-impl ((model array-list-store))
  '(:list-only))

(defmethod tree-model-get-value-impl ((model array-list-store) iter n)
  (let ((n-row (tree-iter-user-data iter)))
    (values (funcall (aref (store-getters model) n) 
                     (aref (store-items model) n-row))
            (aref (store-types model) n))))
@end lisp

@node register-object-type-implementation
@section register-object-type-implementation

@Macro register-object-type-implementation
@lisp
(register-object-type-implementation name class parent interfaces properties)
@end lisp

@table @var
@item @var{name}
A string naming the new GObject class.
@item @var{class}
A class name of corresponding CLOS class. It should be inherited from @code{g-object} or its descendants.
@item @var{parent}
A string naming the GObject superclass
@item @var{interfaces}
A list of names of interfaces that this class implements.
@item @var{properties}
A list of properties that this class provides.
Each property is defined as
@lisp
property ::= (property-name property-type accessor property-get-fn property-set-fn)
@end lisp
@end table

A macro that creates a new GObject type and registers the Lisp implementation for it.

Example:
@lisp
(register-object-type-implementation "LispArrayListStore" array-list-store "GObject" ("GtkTreeModel") nil)
@end lisp

@node GBoxed
@chapter GBoxed
@menu
* define-g-boxed-cstruct::
* define-g-boxed-variant-cstruct::
* define-g-boxed-opaque::
* g-boxed-opaque::
* define-boxed-opaque-accessor::
* boxed-related-symbols::
* GBoxed foreign type::
* copy-boxed-slots-to-foreign::
* with-boxed-foreign-array::
@end menu

GObject manual defines this type in the following way:

``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.

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.''

Naturally, it is hard to provide support for ``arbitrary C structures''. We support a few useful use cases of GBoxed types:
@itemize
@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.
@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).

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.
@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.
@end itemize

@node define-g-boxed-cstruct
@section define-g-boxed-cstruct
@Macro define-g-boxed-cstruct
@lisp
(define-g-boxed-cstruct name g-type-name
  &body slot*)

slot ::= (slot-name slot-type &key count initform inline)
@end lisp

@table @var
@item @var{name}
A symbol naming the type being defined
@item @var{g-type-name}
A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
@item @var{slot-name}
A symbol naming the slot of a structure
@item @var{slot-type}
A foreign type of a slot
@item @var{count}
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.
@item @var{initform}
A form that is the initform of Lisp structure slot
@item @var{inline}
A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
@end table

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.

Example of usage:
@lisp
(define-g-boxed-cstruct rectangle "GdkRectangle"
  (left :int :initform 0)
  (top :int :initform 0)
  (width :int :initform 0)
  (height :int :initform 0))

(define-g-boxed-cstruct point nil
  (x :int :initform 0)
  (y :int :initform 0))

(define-g-boxed-cstruct vector4 nil
  (coords :double :count 4 :initform (vector 0d0 0d0 0d0 0d0)))

(define-g-boxed-cstruct segment nil
  (a point :inline t :initform (make-point))
  (b point :inline t :initform (make-point)))
@end lisp

@node define-g-boxed-variant-cstruct
@section define-g-boxed-variant-cstruct

@Macro define-g-boxed-variant-cstruct
@lisp
(define-g-boxed-variant-cstruct name g-type-name
  &body slot-or-variant-specification*)

slot ::= (slot-name slot-type &key count initform inline)
variant-specification ::= (:variant dispatching-slot-name structure-variant*)
structure-variant ::= (dispatching-slot-values structure-name &body slot-or-variant-specification*)
@end lisp

@table @var
@item @var{name}
A symbol naming the type being defined
@item @var{g-type-name}
A string specifying the GType name of this GBoxed. This may be nil if this type is not registered with GObject type system.
@item @var{slot-name}
A symbol naming the slot of a structure
@item @var{slot-type}
A foreign type of a slot
@item @var{count}
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.
@item @var{initform}
A form that is the initform of Lisp structure slot
@item @var{inline}
A boolean. If it is true, then the slot contains GBoxed structure whose name is @code{slot-type}.
@item @var{dispatching-slot-name}
A name of the dispatching slot
@item @var{dispatching-slot-values}
A single value or a list of values.
@item @var{structure-name}
A symbol naming the structure
@end table

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.

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.

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).

This also defines the @var{name}-cstruct, @var{structure-name}-cstruct, @var{structure-name}-cunion CFFI structures definitions with equivalent structures (unions).

For example, for these structures this assumption holds:
@example
union GdkEvent
@{
  GdkEventType   type;
  GdkEventKey    key;
  GdkEventButton button;
@};

struct GdkEventKey @{
  GdkEventType type; //
  GdkWindow *window; // These fields are common
  gint8 send_event;  //
  guint32 time;
  guint state;
  guint keyval;
  ...
@};

struct GdkEventButton @{
  GdkEventType type; //
  GdkWindow *window; // These fields are common
  gint8 send_event;  //
  guint32 time;
  gdouble x;
  gdouble y;
  ...
@};
@end example

Example:
@lisp
(define-g-boxed-variant-cstruct event "GdkEvent"
  (type event-type)
  (window (g-object gdk-window))
  (send-event (:boolean :int8))
  (:variant type
            ((:key-press :key-release) event-key
             (time :uint32)
             (state modifier-type)
             (keyval :uint)
             (length :int)
             (string (:string :free-from-foreign nil
                              :free-to-foreign nil))
             (hardware-keycode :uint16)
             (group :uint8)
             (is-modifier :uint))
            ((:button-press :2button-press :3button-press
              :button-release) event-button
             (time :uint32)
             (x :double)
             (y :double)
             (axes (fixed-array :double 2))
             (state :uint)
             (button :uint)
             (device (g-object device))
             (x-root :double)
             (y-root :double))
             ...))
@end lisp

This code defines following structures:
@lisp
(defstruct event
  type window send-event)

(defstruct (event-key (:include event))
  time state keyval length string
  hardware-keycode group is-modifier)

(defstruct (event-button (:include event))
  time x y axes state button device x-root y-root)
@end lisp

@node define-g-boxed-opaque
@section define-g-boxed-opaque

@Macro define-g-boxed-opaque
@lisp
(define-g-boxed-opaque name g-type-name &key alloc)
@end lisp

@table @var
@item @var{name}
A name of boxed type
@item @var{g-type-name}
A string; the name of GType
@item @var{alloc}
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.
@end table

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.

Example:
@lisp
(defcfun gtk-tree-path-new :pointer)

(define-g-boxed-opaque tree-path "GtkTreePath"
  :alloc (gtk-tree-path-new))
@end lisp
@node g-boxed-opaque
@section g-boxed-opaque
@Class g-boxed-opaque
@lisp
(defclass g-boxed-opaque ()
  ((pointer :initarg :pointer
            :initform nil
            :accessor g-boxed-opaque-pointer)))
@end lisp

A class that is the base class for wrappers of opaque structures. Contains a pointer to the wrapped opaque structure.

Accessor function @code{g-boxed-opaque-pointer} is used to access the pointer. Pointer should not be modified directly, only read.
@node define-boxed-opaque-accessor
@section define-boxed-opaque-accessor
@Macro define-boxed-opaque-accessor
@lisp
(define-boxed-opaque-accessor
  boxed-name accessor-name &key type reader writer)
@end lisp

@table @var
@item @var{boxed-name}
A symbol naming the opaque structure type for which the accessor is being defined
@item @var{accessor-name}
A symbol naming the accessor
@item @var{type}
A CFFI foreign type of the property for which the accessor is being defined
@item @var{reader}
A @code{NIL} or a string or a function designator for the reader function
@item @var{writer}
A @code{NIL} or a string or a function designator for the writer function
@end table

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}.

@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.

@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.

Example:
@lisp
(define-boxed-opaque-accessor text-iter text-iter-child-anchor
  :reader "gtk_text_iter_get_child_anchor" :type (g-object text-child-anchor))

(define-boxed-opaque-accessor text-iter text-iter-tags
  :reader "gtk_text_iter_get_tags" :type (gslist (g-object text-tag) :free-from-foreign t))

(define-boxed-opaque-accessor text-iter text-iter-chars-in-line
  :reader "gtk_text_iter_get_chars_in_line" :type :int)

(define-boxed-opaque-accessor text-iter text-iter-offset
  :reader "gtk_text_iter_get_offset" :writer "gtk_text_iter_set_offset" :type :int)
@end lisp

@node boxed-related-symbols
@section boxed-related-symbols

@Function boxed-related-symbols
@lisp
(boxed-related-symbols name) @result{} symbols
@end lisp

@table @var
@item @var{name}
A symbol naming the boxed type
@item @var{symbols}
A list of symbols
@end table

This function returns the list of symbols that are related to GBoxed type @var{name}. These symbols are returned:
@itemize
@item name of boxed type
@item name of all accessors of cstruct and variant-cstruct boxed types
@item names of all variants of variant-cstruct boxed types
@item names of constructors and copiers of cstruct and variant-cstruct boxed-types
@end itemize

Typical usage of this function is to export the symbols related to given boxed type.

Example:
@lisp
(define-g-boxed-cstruct rectangle "GdkRectangle"
  (x :int :initform 0)
  (y :int :initform 0)
  (width :int :initform 0)
  (height :int :initform 0))

(boxed-related-symbols 'rectangle)
@result{}
(RECTANGLE MAKE-RECTANGLE COPY-RECTANGLE RECTANGLE-X RECTANGLE-Y
 RECTANGLE-WIDTH RECTANGLE-HEIGHT)
@end lisp

@node GBoxed foreign type
@section GBoxed foreign type

@ForeignType g-boxed-foreign
@lisp
(g-boxed-foreign name &rest option*)

option ::= :return
@end lisp

@table @var
@item @var{name}
Name of GBoxed type
@item @var{option}
Option of foreign type
@item @code{:return}
An option that identifies the foreign type which is used at return position (as foreign function return type or as a callback return type)
@end table

@code{g-boxed-foreign} type deals with marshaling data between Lisp code and foreign code. The marshaling follows the following principles:
@itemize
@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)
@item Lisp objects should not be manually managed and are properly reclaimed by garbage collector, leaving no memory leaks
@item Foreign code can change objects that are passed to them as arguments. This is required for functions that operate by modifying their arguments
@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
@end itemize

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.

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.

Examples of usage:
@lisp
(define-vtable ("GtkTreeModel" c-gtk-tree-model)
  ...
  (tree-model-get-path-impl tree-model-get-path-cb
    (g-boxed-foreign tree-path :return) (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
  (tree-model-get-value-impl tree-model-get-value-cb
    :void (tree-model g-object) (iter (g-boxed-foreign tree-iter)) (n :int) (value (:pointer g-value)))
  (tree-model-iter-next-impl tree-model-iter-next-cb
    :boolean (tree-model g-object) (iter (g-boxed-foreign tree-iter)))
  ...)

(defcfun gtk-text-iter-forward-search :boolean
  (iter (g-boxed-foreign text-iter))
  (str (:string :free-to-foreign t))
  (flags text-search-flags)
  (match-start (g-boxed-foreign text-iter))
  (match-end (g-boxed-foreign text-iter))
  (limit (g-boxed-foreign text-iter)))
@end lisp


@node copy-boxed-slots-to-foreign
@section copy-boxed-slots-to-foreign

@Function copy-boxed-slots-to-foreign
@lisp
(copy-boxed-slots-to-foreign structure native-ptr &optional (type (and structure (type-of structure))))
@end lisp

@table @var
@item @var{structure}
A Lisp structure corresponding to some GBoxed type
@item @var{native-ptr}
A foreign pointer
@item @code{type}
Name of the GBoxed type. It is optional but may be included for optimization purposes
@end table

Copies the contents of @var{structure} to C structure pointed to by @var{native-ptr}. @var{type} is used to determine which slots and which cstruct definition should be used.

Examples:
@lisp
(cffi:with-foreign-object (point-ptr 'gdk::point-cstruct)
  (gobject:copy-boxed-slots-to-foreign (gdk:make-point :x 10 :y 10) point-ptr 'gdk:point))
@end lisp

@node with-boxed-foreign-array
@section with-boxed-foreign-array

@Macro with-boxed-foreign-array
@lisp
(with-foreign-boxed-array (n-var array-var type values-seq) &body body)
@end lisp

@table @var
@item @var{n-var}
A variable that will contain the count of items in @var{values-seq}
@item @var{array-var}
A variable that will contain the pointer to array of C structures
@item @var{type}
A symbol that specifies the type of GBoxed structure
@item @var{values-seq}
An expression that returns the sequence of structures (list or array)
@end table

Evaluates the @var{body} within the scope and extent of foreign array that contains copies of structures that are returned by @var{values-seq}. Binds @var{n-var} to the length of @var{values-seq}, @var{array-var} to the pointer to array of structures.

Examples:
@lisp
(defcfun gdk-region-polygon (g-boxed-foreign region :return)
  (points :pointer)
  (n-points :int)
  (fill-rule gdk-fill-rule))

(defun region-from-polygon (points fill-rule)
  (with-foreign-boxed-array (n pts point points)
    (gdk-region-polygon pts n fill-rule)))
@end lisp

@node Generating type definitions by introspection
@chapter Generating type definitions by introspection
@menu
* define-g-object-class::
* define-g-interface::
* define-g-enum::
* define-g-flags::
* get-g-enum-definition::
* get-g-flags-definition::
* get-g-interface-definition::
* get-g-class-definition::
* get-g-type-definition::
* Specifying additional properties for CLOS classes::
* Generating names for CLOS classes and accessors::
* generate-types-hierarchy-to-file::
@end menu

CL-GTK2-GOBJECT includes facilities for automatically generating parts of bindings for libraries that use GObject type system.

@node define-g-object-class
@section define-g-object-class

@Macro define-g-object-class
@lisp
(define-g-object-class g-type-name name
  (&key (superclass 'g-object) (export t) interfaces type-initializer)
  (&rest property*))

property ::= (name accessor gname type readable writable)
property ::= (:cffi name acessor type reader writer)
@end lisp

Parameters of @code{define-g-object-class}
@table @var
@item @var{superclass}
A symbol naming the superclass of this class
@item @var{export}
Whether to export the name of the class and names of autogenerated properties names from the current package.
@item @var{interfaces}
A list of interfaces the this class implements
@item @var{type-initializer}
A string naming the type initiliazer function. It is usually named @code{class_get_type}.
@item @var{properties}
A list of slots of a class
@end table

Parameters of @code{property}:
@table @var
@item @var{name}
A symbol naming the slot
@item @var{accessor}
A symbol naming the accessor function for this slot
@item @var{gname}
A string naming the property of GObject
@item @var{type}
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)
@item @var{readable}
A boolean specifying whether the slot can be read
@item @var{writable}
A boolean specifying whether the slot can be assigned to
@item @var{reader}
A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
@item @var{writter}
A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
@end table

Macro that expands to @code{defclass} for specified class. Additionally, if @code{export} is true, it exports accessor names and name of a class.

Example:
@lisp
(define-g-object-class "GtkContainer" container
  (:superclass widget :export t :interfaces
               ("AtkImplementorIface" "GtkBuildable")
               :type-initializer "gtk_container_get_type")
  ((border-width container-border-width "border-width" "guint" t t)
   (resize-mode container-resize-mode "resize-mode" "GtkResizeMode" t t)
   (child container-child "child" "GtkWidget" nil t)
   (:cffi focus-child container-focus-child g-object "gtk_container_get_focus_child" "gtk_container_set_focus_child")
   (:cffi focus-vadjustment container-focus-vadjustment (g-object adjustment) "gtk_container_get_focus_vadjustment" "gtk_container_set_focus_vadjustment")
   (:cffi focus-hadjustment container-focus-hadjustment (g-object adjustment) "gtk_container_get_focus_hadjustment" "gtk_container_set_focus_hadjustment")))
@end lisp

@node define-g-interface
@section define-g-interface

@Macro define-g-interface
@lisp
(define-g-interface g-type-name name (&key (export t) type-initializer)
  &body property*)

property ::= (name accessor gname type readable writable)
property ::= (:cffi name acessor type reader writer)
@end lisp

Parameters of @code{define-g-interface}
@table @var
@item @var{export}
Whether to export the name of the interface and names of autogenerated properties names from the current package.
@item @var{type-initializer}
A string naming the type initiliazer function. It is usually named @code{interface_get_type}.
@item @var{properties}
A list of slots of a interface
@end table

Parameters of @code{property}:
@table @var
@item @var{name}
A symbol naming the slot
@item @var{accessor}
A symbol naming the accessor function for this slot
@item @var{gname}
A string naming the property of GObject
@item @var{type}
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)
@item @var{readable}
A boolean specifying whether the slot can be read
@item @var{writable}
A boolean specifying whether the slot can be assigned to
@item @var{reader}
A string or a symbol naming getter function. See description of @code{gobject-class} metaclass for information.
@item @var{writter}
A string or a symbol naming setter function. See description of @code{gobject-class} metaclass for information.
@end table

Macro that expands to @code{defclass} for specified interface. Additionally, if @code{export} is true, it exports accessor names and name of a interface.

Example:
@lisp
(define-g-interface "GtkFileChooser" file-chooser
  (:export t :type-initializer "gtk_file_chooser_get_type")
  (do-overwrite-confirmation file-chooser-do-overwrite-confirmation "do-overwrite-confirmation" "gboolean" t t)
  (select-multiple file-chooser-select-multiple "select-multiple" "gboolean" t t)
  (filter file-chooser-filter "filter" "GtkFileFilter" t t)
  (local-only file-chooser-local-only "local-only" "gboolean" t t)
  (preview-widget file-chooser-preview-widget "preview-widget" "GtkWidget" t t)
  (use-preview-label file-chooser-use-preview-label "use-preview-label" "gboolean" t t)
  (preview-widget-active file-chooser-preview-widget-active "preview-widget-active" "gboolean" t t)
  (file-system-backend file-chooser-file-system-backend "file-system-backend" "gchararray" nil nil)
  (extra-widget file-chooser-extra-widget "extra-widget" "GtkWidget" t t)
  (show-hidden file-chooser-show-hidden "show-hidden" "gboolean" t t)
  (action file-chooser-action "action" "GtkFileChooserAction" t t)
  (:cffi current-name file-chooser-current-name
   (:string :free-to-foreign t :encoding :utf-8) nil "gtk_file_chooser_set_current_name")
  (:cffi filename file-chooser-filename
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_filename" "gtk_file_chooser_set_filename")
  (:cffi current-folder file-chooser-current-folder
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_current_folder"
   "gtk_file_chooser_set_current_folder")
  (:cffi uri file-chooser-uri
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_uri" "gtk_file_chooser_set_uri")
  (:cffi current-folder-uri file-chooser-current-folder-uri
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_current_folder_uri"
   "gtk_file_chooser_set_current_folder_uri")
  (:cffi preview-filename file-chooser-preview-filename
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_preview_filename" nil)
  (:cffi preview-uri file-chooser-preview-uri
   (g-string :free-from-foreign t :free-to-foreign t)
   "gtk_file_chooser_get_preview_uri" nil))
@end lisp

@node define-g-enum
@section define-g-enum

@Macro define-g-enum
@lisp
(define-g-enum g-name name (&key (export t) type-initializer) &body value*)

value ::= :keyword
value ::= (:keyword integer)
@end lisp

@table @var
@item @var{g-name}
A string naming the GEnum type
@item @var{name}
A symbol naming the CFFI enumeration type
@item @var{export}
A boolean indicating whether to export @code{name}
@item @var{type-initializer}
A string naming the foreign type initializer function. Usually named @code{enum_get_type}.
@end table

Macro that defines CFFI enumeration, registers it with GValue, and calls the type initializer.

Example:
@lisp
(define-g-enum "GtkTextDirection" text-direction
  (:export t :type-initializer "gtk_text_direction_get_type")
  (:none 0) (:ltr 1) (:rtl 2))

(define-g-enum "GtkSizeGroupMode" size-group-mode
 (:export t :type-initializer "gtk_size_group_mode_get_type")
 :none :horizontal :vertical :both)
@end lisp

@node define-g-flags
@section define-g-flags

@Macro define-g-flags
@lisp
(define-g-flags g-name name (&key (export t) type-initializer) &body value*)

value ::= :keyword
value ::= (:keyword integer)
@end lisp

@table @var
@item @var{g-name}
A string naming the GFlags type
@item @var{name}
A symbol naming the CFFI flags type
@item @var{export}
A boolean indicating whether to export @code{name}
@item @var{type-initializer}
A string naming the foreign type initializer function. Usually named @code{flags_get_type}.
@end table

Macro that defines CFFI bitfield, registers it with GValue, and calls the type initializer.

Example:
@lisp
(define-g-flags "GtkAttachOptions" attach-options
  (:export t :type-initializer "gtk_attach_options_get_type")
  (:expand 1) (:shrink 2) (:fill 4))

(define-g-flags "GtkButtonAction" button-action
  (:export t :type-initializer "gtk_button_action_get_type")
  :ignored :selects :drags :expands)
@end lisp

@node get-g-enum-definition
@section get-g-enum-definition

@Function get-g-enum-definition
@lisp
(get-g-enum-definition type &optional lisp-name-package) @result{} definition
@end lisp

@table @var
@item @var{type}
A string naming the GEnum type
@item @var{lisp-name-package}
A package that will be used as a package for generated symbols (enum name). If not specified, symbols are interned in @code{*package*}
@item @var{definition}
A Lisp form that when evaluated defines the GEnum.
@end table

Uses GObject introspection capabilities to automatically produce the definition of GEnum. The foreign library that defines the enum type should be loaded.

See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.

Example:
@lisp
(get-g-enum-definition "GtkDirectionType")
@result{}
(DEFINE-G-ENUM "GtkDirectionType" GTK-DIRECTION-TYPE
               (:EXPORT T :TYPE-INITIALIZER "gtk_direction_type_get_type")
               (:TAB-FORWARD 0) (:TAB-BACKWARD 1) (:UP 2) (:DOWN 3) (:LEFT 4)
               (:RIGHT 5))
@end lisp

@node get-g-flags-definition
@section get-g-flags-definition

@Function get-g-flags-definition
@lisp
(get-g-flags-definition type &optional lisp-name-package) @result{} definition
@end lisp

@table @var
@item @var{type}
A string naming the GFlags type
@item @var{lisp-name-package}
A package that will be used as a package for generated symbols (flags name). If not specified, symbols are interned in @code{*package*}
@item @var{definition}
A Lisp form that when evaluated defines the GFlags.
@end table

Uses GObject introspection capabilities to automatically produce the definition of GFlags. The foreign library that defines the flags type should be loaded.

See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.

Example:
@lisp
(get-g-flags-definition "GtkCalendarDisplayOptions")
@result{}
(DEFINE-G-FLAGS "GtkCalendarDisplayOptions" GTK-CALENDAR-DISPLAY-OPTIONS
                (:EXPORT T :TYPE-INITIALIZER
                 "gtk_calendar_display_options_get_type")
                (:SHOW-HEADING 1) (:SHOW-DAY-NAMES 2) (:NO-MONTH-CHANGE 4)
                (:SHOW-WEEK-NUMBERS 8) (:WEEK-START-MONDAY 16)
                (:SHOW-DETAILS 32))
@end lisp

@node get-g-interface-definition
@section get-g-interface-definition

@Function get-g-interface-definition
@lisp
get-g-interface-definition type &optional lisp-name-package) @result{} definition
@end lisp

@table @var
@item @var{type}
A string naming the GInterface type
@item @var{lisp-name-package}
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*}
@item @var{definition}
A Lisp form that when evaluated defines the GInterface.
@end table

Uses GObject introspection capabilities to automatically produce the definition of GInterface. The foreign library that defines the GInterface type should be loaded.

See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.

Example:
@lisp
(get-g-interface-definition "GtkActivatable")
@result{}
(DEFINE-G-INTERFACE "GtkActivatable" GTK-ACTIVATABLE
                    (:EXPORT T :TYPE-INITIALIZER "gtk_activatable_get_type")
                    (USE-ACTION-APPEARANCE
                     GTK-ACTIVATABLE-USE-ACTION-APPEARANCE
                     "use-action-appearance" "gboolean" T T)
                    (RELATED-ACTION GTK-ACTIVATABLE-RELATED-ACTION
                     "related-action" "GtkAction" T T))
@end lisp

@node get-g-class-definition
@section get-g-class-definition

@Function get-g-class-definition
@lisp
(get-g-class-definition type &optional lisp-name-package) @result{} definition
@end lisp

@table @var
@item @var{type}
A string naming the GObject type
@item @var{lisp-name-package}
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*}
@item @var{definition}
A Lisp form that when evaluated defines the GObject.
@end table

Uses GObject introspection capabilities to automatically produce the definition of GClass. The foreign library that defines the GObject type should be loaded.

See @ref{Generating names for CLOS classes and accessors} for information about used method for generating names.

Example:
@lisp
(get-g-class-definition "GtkButton")
@result{}
(DEFINE-G-OBJECT-CLASS "GtkButton" GTK-BUTTON
                       (:SUPERCLASS GTK-BIN :EXPORT T :INTERFACES
                        ("AtkImplementorIface" "GtkActivatable" "GtkBuildable")
                        :TYPE-INITIALIZER "gtk_button_get_type")
                       ((LABEL GTK-BUTTON-LABEL "label" "gchararray" T T)
                        (IMAGE GTK-BUTTON-IMAGE "image" "GtkWidget" T T)
                        (RELIEF GTK-BUTTON-RELIEF "relief" "GtkReliefStyle" T
                         T)
                        (USE-UNDERLINE GTK-BUTTON-USE-UNDERLINE "use-underline"
                         "gboolean" T T)
                        (USE-STOCK GTK-BUTTON-USE-STOCK "use-stock" "gboolean"
                         T T)
                        (FOCUS-ON-CLICK GTK-BUTTON-FOCUS-ON-CLICK
                         "focus-on-click" "gboolean" T T)
                        (XALIGN GTK-BUTTON-XALIGN "xalign" "gfloat" T T)
                        (YALIGN GTK-BUTTON-YALIGN "yalign" "gfloat" T T)
                        (IMAGE-POSITION GTK-BUTTON-IMAGE-POSITION
                         "image-position" "GtkPositionType" T T)))
@end lisp

@node get-g-type-definition
@section get-g-type-definition

@Function get-g-type-definition
@lisp
(get-g-class-definition type &optional lisp-name-package) @result{} definition
@end lisp

@table @var
@item @var{type}
A string naming the GEnum, GFlags, GInterface or GObject type
@item @var{lisp-name-package}
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*}
@item @var{definition}
A Lisp form that when evaluated defines the corresponding Lisp type.
@end table

Depending on a kind of @var{type}, calls @ref{get-g-enum-definition} or @ref{get-g-flags-definition} or @ref{get-g-interface-definition} or @ref{get-g-class-definition}.

@node Specifying additional properties for CLOS classes
@section Specifying additional properties for CLOS classes

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.

Definitions generator uses variable @code{*additional-properties*} to get this information.

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).

To supply the bindings generator with this information, bind @code{*additional-properties*} to such list when the generator is run.

Example:
@lisp
(("GtkTreeViewColumn"
  (:cffi gtk::tree-view
         gtk::tree-view-column-tree-view
         g-object "gtk_tree_view_column_get_tree_view" nil)
  (:cffi gtk::sort-column-id
         gtk::tree-view-column-sort-column-id
         :int "gtk_tree_view_column_get_sort_column_id" "gtk_tree_view_column_set_sort_column_id")
  (:cffi gtk::cell-renderers
         gtk::tree-view-column-cell-renderers
         (glist g-object  :free-from-foreign t) "gtk_tree_view_column_get_cell_renderers" nil))
 ("GtkTreeSelection"
  (:cffi gtk::mode
         gtk::tree-selection-mode
         gtk::selection-mode "gtk_tree_selection_get_mode" "gtk_tree_selection_set_mode")
  (:cffi gtk::select-function
         gtk::tree-selection-select-function
         nil gtk::tree-selection-get-selection-function gtk::tree-selection-set-select-function)))
@end lisp

@node Generating names for CLOS classes and accessors
@section Generating names for CLOS classes and accessors

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).

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.

Name generation affected by following variables:
@itemize
@item @var{*strip-prefix*}
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}.
@item @var{*lisp-name-exceptions*}
A plist mapping from strings (type names) to symbols (class names) that have special name processing.
Example:
@lisp
`(("GObject" gobject:g-object)
  ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
  ("GInitiallyUnowned" gobject::g-initially-unowned)
  ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
  ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
  ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
@end lisp
@end itemize

@node generate-types-hierarchy-to-file
@section generate-types-hierarchy-to-file

@Function generate-types-hierarchy-to-file
@lisp
(generate-types-hierarchy-to-file file
                                  root-type
                                  &key include-referenced
                                  prefix
                                  package
                                  exceptions
                                  prologue
                                  interfaces
                                  enums
                                  flags
                                  objects
                                  exclusions
                                  additional-properties)
@end lisp

@table @var
@item @var{file}
A string or pathname naming the file, or a stream.
@item @var{root-type}
A GType designator for a root type. All types that inherit from this type will be defined.
@item @var{&key include-referenced}
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
@item @var{prefix}
A string naming the prefix that should be removed from the beginning of names
@item @var{package}
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
@item @var{exceptions}
A plist that maps GType names to their Lisp names.
See @ref{Generating names for CLOS classes and accessors} for more info on exceptions from name generation mechanism
@item @var{prologue}
A string that will be included verbatim in generated code file
@item @var{interfaces}
Additional list of interfaces that will also be included in generation
@item @var{enums}
Additional list of enums that will also be included in generation
@item @var{flags}
Additional list of flags that will also be included in generation
@item @var{objects}
Additional list of object types that will also be included in generation
@item @var{exclusions}
A list of GType names that will be excluded from generation
@item @var{additional-properties}
A plist of properties definitions that will be added to generated classes.
See @ref{Specifying additional properties for CLOS classes} for more information.
@end table

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.

Example of usage:
@lisp
(generate-types-hierarchy-to-file
 "gtk.generated-classes.lisp"
 "GtkObject"
 :include-referenced t
 :prefix "Gtk"
 :package (or (find-package :gtk) (make-package :gtk))
 :exceptions `(("GObject" gobject:g-object)
               ("GtkObject" ,(intern "GTK-OBJECT" (find-package :gtk)))
               ("GInitiallyUnowned" gobject::g-initially-unowned)
               ("GtkWindow" ,(intern "GTK-WINDOW" (find-package :gtk)))
               ("GtkUIManager" ,(intern "UI-MANAGER" (find-package :gtk)))
               ("GtkUIManagerItemType" ,(intern "UI-MANAGER-ITEM-TYPE" (find-package :gtk))))
 :prologue (format nil "(in-package :gtk)")
 :interfaces '("GtkBuildable" "GtkCellEditable" ...)
 :objects '("GtkSettings" "GtkRcStyle" ...)
 :flags '("GtkTextSearchFlags" "GtkAccelFlags" ...)
 :enums '("GtkTextDirection" "GtkSizeGroupMode" ...)
 :exclusions '("PangoStretch" "PangoVariant" ...)
 :additional-properties
 '(("GtkTreeViewColumn"
    (:cffi
     gtk::tree-view
     gtk::tree-view-column-tree-view
     g-object
     "gtk_tree_view_column_get_tree_view"
     nil)
    ...)
   ...))
@end lisp