Add GtkAssistant documentation

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

diff --git a/doc/gobject.ref.texi b/doc/gobject.ref.texi
index 9d446ab..457450c 100644 (file)
--- a/doc/gobject.ref.texi
+++ b/doc/gobject.ref.texi
@@ -1263,6 +1263,7 @@ Example:
 @chapter GObject high-level
 @menu
 * g-object::
+* g-initially-unowned::
 * GObject metaclass::
 * Using objects::
 * Signals::
@@ -1309,6 +1310,15 @@ A base class for all GObject classes.
 
 An accessor that accesses the foreign pointer to object.
 
+@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
 
@@ -1316,7 +1326,9 @@ 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.
+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}.
 
@@ -1324,13 +1336,13 @@ 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
+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 type initializer function. This function initializes the class and returns its GType. Typically it is named @code{class_get_type}.
+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.
+A boolean specifying whether this CLOS class corresponds to GInterface. It is NIL by default.
 @end itemize
 
 This metaclass defines the GObject classes.
@@ -1518,9 +1530,9 @@ Example:
 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}.
+@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.
+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.
 
@@ -1549,6 +1561,16 @@ This defines the function that returns an instance of GObject class:
 #<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