Added documentation of GObject high-level layer

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

\input texinfo  @c -*-texinfo-*-
@c %**start of header (This is for running texinfo on a region.)
@setfilename gobject.info
@settitle CL-Gtk2-GObject
@c %**end of header (This is for running texinfo on a region.)

@c @documentencoding utf-8

@macro Function {args}
@defun \args\
@end defun
@end macro

@macro Macro {args}
@defmac \args\
@end defmac
@end macro

@macro Accessor {args}
@deffn {Accessor} \args\
@end deffn
@end macro

@macro GenericFunction {args}
@deffn {Generic Function} \args\
@end deffn
@end macro

@macro ForeignType {args}
@deftp {Foreign Type} \args\
@end deftp
@end macro

@macro Variable {args}
@defvr {Special Variable} \args\
@end defvr
@end macro

@macro Condition {args}
@deftp {Condition Type} \args\
@end deftp
@end macro

@macro cffi
@acronym{CFFI}
@end macro

@macro impnote {text}
@quotation
@strong{Implementor's note:} @emph{\text\}
@end quotation
@end macro

@c Info "requires" that x-refs end in a period or comma, or ) in the
@c case of @pxref.  So the following implements that requirement for
@c the "See also" subheadings that permeate this manual, but only in
@c Info mode.
@ifinfo
@macro seealso {name}
@ref{\name\}.
@end macro
@end ifinfo

@ifnotinfo
@alias seealso = ref
@end ifnotinfo

@c Typeset comments in roman font for the TeX output.
@iftex
@alias lispcmt = r
@end iftex
@ifnottex
@alias lispcmt = asis
@end ifnottex

@c My copy of makeinfo is not generating any HTML for @result{} for
@c some odd reason. (It certainly used to...)
@ifhtml
@macro result
=>
@end macro
@end ifhtml

@c Similar macro to @result. Its purpose is to work around the fact
@c that ⇒ does not work properly inside @lisp.
@ifhtml
@macro res
@html
⇒
@end html
@end macro
@end ifhtml

@ifnothtml
@alias res = result
@end ifnothtml

@c ============================= Macros =============================


@c Show types, functions, and concepts in the same index.
@syncodeindex tp cp
@syncodeindex fn cp

@titlepage
@title CL-GTK2
@subtitle A Common Lisp binding for Gtk+
@subtitle GObject
@author Dmitry Kalyanov
@end titlepage

@contents

@ifnottex
@node Top
@top cl-gtk2-gobject
@end ifnottex

@menu
* Introduction::
* Installation::
* GType designator::
* Type hierarchy and type relations::
* Object types information::
* Enum types information::
* Using GValues::
* Stable pointers::
* Closures::
* GObject low-level::
* GObject high-level::
* Subclassing GObjects 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.

@node Installation
@chapter Installation

CL-GTK2-GObject comes as a part of CL-GTK2 bindings that are avaiable at its @uref{http://common-lisp.net/project/cl-gtk2/,,website}.

To use the CL-GTK2-GObject, download and install CL-GTK2 bindings and load the ASDF system @code{cl-gtk2-glib}.

CL-GTK2-GObject defines two packages: @code{gobject} and @code{gobject.ffi}. The @code{gobject.ffi} package contains definitions for low-level CFFI imports. The @code{gobject} package contains symbols for external API of this GObject binding.

@node GType designator
@chapter GType designator

@menu
* g-type-string::
* g-type-numeric::
@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:
@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+}. A fundamental type which is used as a replacement for the C @code{void} return type.
@item @code{+g-type-interface+}. The fundamental type from which all interfaces are derived.
@item @code{+g-type-char+}. The fundamental type corresponding to gchar. The type designated by @code{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.
@item @code{+g-type-uchar+}. The fundamental type corresponding to @code{guchar}.
@item @code{+g-type-boolean+}. The fundamental type corresponding to @code{gboolean}.
@item @code{+g-type-int+}. The fundamental type corresponding to @code{gint}.
@item @code{+g-type-uint+}. The fundamental type corresponding to @code{guint}.
@item @code{+g-type-long+}. The fundamental type corresponding to @code{glong}.
@item @code{+g-type-ulong+}. The fundamental type corresponding to @code{gulong}.
@item @code{+g-type-int64+}. The fundamental type corresponding to @code{gint64}.
@item @code{+g-type-uint64+}. The fundamental type corresponding to @code{guint64}.
@item @code{+g-type-enum+}. The fundamental type from which all enumeration types are derived.
@item @code{+g-type-flags+}. The fundamental type from which all flags types are derived.
@item @code{+g-type-float+}. The fundamental type corresponding to @code{gfloat}.
@item @code{+g-type-double+}. The fundamental type corresponding to @code{gdouble}.
@item @code{+g-type-string+}. The fundamental type corresponding to null-terminated C strings.
@item @code{+g-type-pointer+}. The fundamental type corresponding to @code{gpointer}.
@item @code{+g-type-boxed+}. The fundamental type from which all boxed types are derived.
@item @code{+g-type-param+}. The fundamental type from which all GParamSpec types are derived.
@item @code{+g-type-object+}. 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).

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

@example
(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 example

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

@code{(g-type-string g-type-designator) @result{} name}

@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

@code{(g-type-numeric g-type-designator) @result{} GType}

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

@code{(g-type-children type) @result{} children}
@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:
@example
(g-type-children "GtkButton")
@result{}
("GtkToggleButton" "GtkColorButton" "GtkFontButton" "GtkLinkButton" "GtkScaleButton")
@end example

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

@code{(g-type-parent type) @result{} parent}

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

Returns the parent of @code{type}.

Example:
@example
(g-type-parent "GtkToggleButton")
@result{}
"GtkButton"
@end example
@node g-type-fundamental
@section g-type-fundamental

@code{(g-type-fundamental type) @result{} fundamental-type}

@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:
@example
(g-type-fundamental "GtkButton") @result{} "GObject"

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

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

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

@code{(g-type-depth type) @result{} depth}

@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:
@example
(g-type-depth "GObject") @result{} 1
(g-type-depth "GInitiallyUnowned") @result{} 2
@end example

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

@code{(g-type-next-base leaf-type root-type) @result{} base-type}

@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:
@example
+ GObject
 \
  + GInitiallyUnowned
   \
    + GtkObject
    |\
    | + GtkAdjustment
     \
      + GtkWidget
       \
        + GtkContainer
         \
          + GtkTable
@end example

the following will be returned:

@example
(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 example

@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

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

@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:
@example
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)> 
@end example

(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

@code{(class-properties type) @result{} properties}

@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:
@example
(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 example

@node class-property-info
@section class-property-info
@code{(class-property-info type property-name) @result{} property}

@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:
@example
(class-property-info "GtkButton" "label")
@result{}
#<PROPERTY gchararray GtkButton.label (flags: readable writable constructor)>
@end example

@node interface-properties
@section interface-properties

@code{(interface-properties type) @result{} properties}

@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:
@example
(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 example

@node signal-info
@section signal-info

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

@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:
@example
#<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 example

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
@code{(type-signals type &key (include-inherited t)) @result{} signals}
@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:
@example
(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 example

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

@code{(parse-signal-name type signal-name) @result{} signal}

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

@node query-signal-info
@section query-signal-info
@code{(query-signal-info signal-id) @result{} signal}
@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:
@example
(query-signal-info 73)
@result{}
#<Signal [#73] gboolean GtkWidget.show-help(GtkWidgetHelpType) [RUN-LAST, ACTION]>
@end example

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

@code{(g-type-interfaces type) @result{} interfaces}

@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:
@example
(g-type-interfaces "GtkButton")
@result{}
("AtkImplementorIface" "GtkBuildable" "GtkActivatable")
@end example

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

@code{(g-type-interface-prerequisites type) @result{} types}

@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:
@example
(g-type-interface-prerequisites "GtkCellEditable")
@result{}
("GtkObject" "GtkWidget")
@end example

@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
@example
(defstruct enum-item
  name value nick)
@end example

@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:
@example
#S(ENUM-ITEM :NAME "GTK_WINDOW_TOPLEVEL" :VALUE 0 :NICK "toplevel")
@end example

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

@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:
@example
#S(FLAGS-ITEM
   :NAME "GDK_POINTER_MOTION_HINT_MASK"
   :VALUE 8
   :NICK "pointer-motion-hint-mask")
@end example

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

@code{(get-enum-items type) @result{} items}

@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:
@example
(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 example

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

@code{(get-flags-items type) @result{} items}

@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:
@example
(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 example

@node Using GValues
@chapter Using GValues
@menu
* g-value-zero::
* g-value-init::
* g-value-unset::
* parse-g-value::
* set-g-value::
@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:
@example
(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 example

@node g-value-zero
@section g-value-zero
@code{(g-value-zero g-value)}
@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:
@example
GValue value = @{ 0 @};
@end example

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

@code{(g-value-init value type)}
@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
@code{(g-value-unset value)}
@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
@code{(parse-g-value value) @result{} object}
@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
@code{(set-g-value gvalue object type &key zero-g-value unset-g-value (g-value-init t))}

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

@code{(allocate-stable-pointer thing) @result{} stable-pointer}

@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:
@example
(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 example

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

@code{(free-stable-pointer stable-pointer)}

@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:
@example
(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 example

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

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

@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

@code{(with-stable-pointer (ptr expr) &body body)}

@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:
@example
(with-stable-pointer (ptr (lambda (x) (+ x 10)))
  (print (stable-pointer-value ptr)))
;;Prints:
#<FUNCTION (LAMBDA (X)) @{1004807E79@}>
@end example

@node Closures
@chapter Closures

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-g-closure} create closure from lisp function. The GClosure is finalized automatically when GObject no longer needs it (e.g., when GClosure is disconnected from signal).

@section create-g-closure
@code{(create-g-closure fn) @result{} closure}

@table @var
@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:
@example
(create-g-closure (lambda (x) (+ x 10)))
@result{}
#.(SB-SYS:INT-SAP #X006D7B20)
@end example

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

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

@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

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

@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:
@example
(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 example

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

@code{(g-type-from-object object-ptr) @result{} type}

@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:
@example
(g-type-from-object (g-object-call-constructor "GtkButton" nil nil))
@result{}
"GtkButton"
@end example

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

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

@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:
@example
(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 example

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

@code{(g-object-call-set-property object-ptr property-name new-value &optional property-type)}

@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:
@example
(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 example

@node GObject high-level
@chapter GObject high-level
@menu
* 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:
@example
(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 example

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

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

Name of type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
@item @var{interface-p} (accessor @code{gobject-class-interface-p}, initarg @code{:interface-p})
@end itemize

This metaclass defines the GObject classes.

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

A name of a type of property
@item @var{:g-property-name}

A name of a property
@end itemize

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

Example:
@example
(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 example
(note the dot in @code{(:g-type-name . "GtkDialog")} and in @code{(:g-type-initializer . "gtk_dialog_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:
@example
(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 example

@node Signals
@section Signals

To connect handler to a signal, @code{connect-signal} function is used.

@code{(connect-signal object signal handler &key after)}

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

Example:
@example
(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 example

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

@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:
@example
(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 example

@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 &optional type)} or @code{g-object}.

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.

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}:
@example
(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 example
(@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:
@example
(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 example

@node Subclassing GObjects and implementing GInterfaces
@chapter Subclassing GObjects and implementing GInterfaces

@node GBoxed
@chapter GBoxed

@node Generating type definitions by introspection
@chapter Generating type definitions by introspection


@bye