bindings/python/docs: added documentation for gladeui.InspectorBINDINGS

svn path=/branches/BINDINGS/; revision=1474

5 files changed, 225 insertions, 233 deletions

diff --git a/bindings/python/docs/Makefile.am b/bindings/python/docs/Makefile.am
index 5ce36f7d..c4791b85 100644
--- a/bindings/python/docs/Makefile.am
+++ b/bindings/python/docs/Makefile.am
@@ -7,15 +7,16 @@ HTML_STYLE = $(PYGOBJECT_DATADIR)/pygobject/xsl/ref-html-style.xsl
 
 XMLFILES = 				\
 	pygladeui.xml			\
-	pygladeui-introduction.xml	\
-	pygladeui-classes.xml
+	pygladeui-classes.xml		\
+	pygladeui-inspector.xml	
 
 
-HTML_FILES = 	\
-	html/index.html		\
-	html/index.sgml		\
-	html/pygladeui.devhelp	\
-	html/pygladeui-introduction.html
+HTML_FILES =				\
+	html/index.html			\
+	html/index.sgml			\
+	html/pygladeui.devhelp		\
+	html/gladeui-class-reference	\
+	html/class-inspector.html
 
 CSS_FILES = $(PYGOBJECT_PYGDOCS)/style.css
 
diff --git a/bindings/python/docs/pygladeui-classes.xml b/bindings/python/docs/pygladeui-classes.xml
index 8b137891..b49e895a 100644
--- a/bindings/python/docs/pygladeui-classes.xml
+++ b/bindings/python/docs/pygladeui-classes.xml
@@ -1 +1,8 @@
-
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<chapter id="gladeui-class-reference" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <title>The gladeui Class Reference</title>
+  
+  <xi:include href="pygladeui-inspector.xml"/>
+</chapter>
diff --git a/bindings/python/docs/pygladeui-inspector.xml b/bindings/python/docs/pygladeui-inspector.xml
new file mode 100644
index 00000000..00ae656a
--- /dev/null
+++ b/bindings/python/docs/pygladeui-inspector.xml
@@ -0,0 +1,206 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+       <refentry id="class-inspector">
+         <refnamediv>
+           <refname>gladeui.Inspector</refname>
+           <refpurpose>A widget for inspecting objects in a project</refpurpose>
+         </refnamediv>
+         <refsect1>
+           <title>Synopsis</title>
+           <classsynopsis language="python">
+             <ooclass><classname>gladeui.Inspector</classname></ooclass>
+             <ooclass><classname><link linkend="class-gtkdialog">gtk.VBox</link></classname></ooclass>
+             <constructorsynopsis language="python">
+               <methodname><link linkend="constructor-inspector">gladeui.Inspector</link></methodname>
+               <methodparam></methodparam>
+             </constructorsynopsis>
+             <methodsynopsis language="python">
+               <methodname><link linkend="method-inspector--get-project">get_project</link></methodname>
+               <methodparam></methodparam>
+             </methodsynopsis>
+             <methodsynopsis language="python">
+               <methodname><link linkend="method-inspector--set-project">set_project</link></methodname>
+               <methodparam><parameter role="keyword">project</parameter></methodparam>
+             </methodsynopsis>
+             <methodsynopsis language="python">
+               <methodname><link linkend="method-inspector--get-selected-items">get_selected_items</link></methodname>
+               <methodparam></methodparam>
+             </methodsynopsis>             
+           </classsynopsis>
+<programlisting>
+<emphasis role="bold">Functions</emphasis>
+<methodsynopsis language="python">
+<methodname><link linkend="function-gladeui--inspector-new-with-project">gladeui.inspector_new_with_project</link></methodname>
+<methodparam><parameter role="keyword">project</parameter></methodparam>
+</methodsynopsis>
+</programlisting>            
+         </refsect1>
+         <refsect1>
+             <title>Ancestry</title>
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+  +-- <link linkend="class-gtkobject">gtk.Object</link>
+    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
+      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
+        +-- <link linkend="class-gtkbin">gtk.Box</link>
+          +-- <link linkend="class-gtkexpander">gtk.VBox</link>
+            +-- <link linkend="class-inspector">gladeui.Inspector</link>          
+</synopsis>
+            </refsect1>
+            <refsect1>
+    <blockquote role="properties">
+      <informaltable pgwide="1" frame="none">
+	<tgroup cols="3">
+	  <colspec column="1" colwidth="1in"/>
+	  <colspec column="2" colwidth="1in"/>
+	  <colspec column="3" colwidth="4in"/>
+	  <tbody>
+
+	    <row valign="top">
+	      <entry>"project"</entry>
+	      <entry>Read-Write</entry>
+	      <entry>The project being inspected.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </blockquote>            
+            </refsect1>
+
+            <refsect1 id="signal-prototypes-inspector">
+              <title>gladeui.Inspector Signal Prototypes</title>
+    <variablelist>
+      <varlistentry>
+        <term>"<link linkend="signal-inspector--item-activated">item-activated</link>"</term>
+        <listitem>
+          <methodsynopsis language="python"><methodname>callback</methodname>
+            <methodparam><parameter>inspector</parameter></methodparam>
+            <methodparam><parameter>user_param1</parameter></methodparam>
+            <methodparam><parameter>...</parameter></methodparam>
+          </methodsynopsis>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>"<link linkend="signal-inspector--selection-changed">selection-changed</link>"</term>
+        <listitem>
+          <methodsynopsis language="python"><methodname>callback</methodname>
+            <methodparam><parameter>inspector</parameter></methodparam>
+            <methodparam><parameter>user_param1</parameter></methodparam>
+            <methodparam><parameter>...</parameter></methodparam>
+          </methodsynopsis>
+        </listitem>
+      </varlistentry>      
+    </variablelist>
+    </refsect1>
+    
+    <refsect1>
+    <title>Description</title>
+      <para>A <link linkend="class-inspector"><classname>gladeui.Inspector</classname></link>
+       is a widget for inspecting the objects that make up a user interface design. 
+      </para>    
+    </refsect1>
+    
+  <refsect1 id="constructor-inspector">
+    <title>Constructor</title>
+
+    <programlisting><constructorsynopsis language="python">
+	<methodname>gladeui.Inspector</methodname>
+	<methodparam></methodparam>
+      </constructorsynopsis></programlisting>
+    <variablelist>
+      <varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	<listitem><simpara>a new <link linkend="class-inspector"><classname>gladeui.Inspector</classname></link> widget.</simpara></listitem>
+      </varlistentry>
+    </variablelist>
+    <para>Creates a new inspector.</para>
+  </refsect1>    
+
+  <refsect1>
+    <title>Methods</title>
+
+
+    <refsect2 id="method-inspector--get-project">
+      <title>gladeui.Inspector.get_project</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_project</methodname>
+	  <methodparam></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>The project being inspected.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>get_project</methodname>() gets the current
+      project being inspected.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-inspector--set-project">
+      <title>gladeui.Inspector.set_project</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>set_project</methodname>
+	  <methodparam><parameter role="keyword">project</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter role="keyword">project</parameter>&nbsp;:</term>
+	  <listitem><simpara>project to inspect or None.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>set_project</methodname>() method sets the
+"project" property to the value of <parameter>project</parameter>.</para>
+    </refsect2>
+    
+    <refsect2 id="method-inspector--get-selected-items">
+      <title>gladeui.Inspector.get_selected_items</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_selected_items</methodname>
+	  <methodparam></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>A list of items in the current selection.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>get_selected_items</methodname>() gets the list of items
+      in the current selection. This is useful for getting the last item which was activated
+      by the user</para> 
+
+    </refsect2>    
+    
+    </refsect1>
+    
+  <refsect1>
+    <title>Functions</title>
+
+    <refsect2 id="function-gladeui--inspector-new-with-project">
+      <title>gladeui.inspector_new_with_project</title>
+
+      <programlisting><methodsynopsis language="python">
+          <methodname>gladeui.inspector_new_with_project</methodname>
+          <methodparam><parameter role="keyword">project</parameter>
+          </methodparam>
+        </methodsynopsis></programlisting>
+
+      <variablelist>
+        <varlistentry>
+          <term><parameter role="keyword">project</parameter>&nbsp;:</term>
+          <listitem><simpara>a <link linkend="class-project"><classname>gladeui.Project</classname></link></simpara></listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>This is a convenience function to initialize a new inspector with a project.</para>
+
+    </refsect2>    
+</refsect1>
+
+       </refentry>
diff --git a/bindings/python/docs/pygladeui-introduction.xml b/bindings/python/docs/pygladeui-introduction.xml
deleted file mode 100644
index d5888f77..00000000
--- a/bindings/python/docs/pygladeui-introduction.xml
+++ /dev/null
@@ -1,224 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY builddate SYSTEM "builddate.xml">
-]>
-
-  <chapter id="pygladeui-introduction">
-  <title>Introduction</title>
-
-  <para>This document describes many of the <literal>PyGObject</literal>
-  version 2.12 classes and their methods and associated
-  functions. Deprecated classes, functions and methods have been
-  specifically left out of this reference though classes that have become
-  deprecated since PyGObject 2.0 have been left in but annotated with a
-  deprecation warning. This document attempts to document as much of the
-  <literal>PyGObject</literal> <literal>API</literal> as possible but there
-  are undoubtedly errors and omissions. If you discover any of these please
-  file a bug report at <ulink
-  url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink> for the
-  <literal>pygladeui</literal> project. Specific areas that have not been
-  documented include:</para>
-
-  <itemizedlist>
-    <listitem>
-      <simpara>The GParamSpec class</simpara>
-    </listitem>
-  </itemizedlist>
-
-  <para>This reference describes the API for <literal>PyGObject</literal> as
-  of version 2.11.0+ and assumes that the additional API changes for version
-  2.12 will not be significant. There will undoubtedly be changes that are
-  not reflected in this reference. The differences in the API between
-  version 2.0 and previous versions are denoted in this reference with a
-  Note that describes the availability of the object, constructor, method or
-  function. Any of these that do not have a notation can be assumed to be
-  available in all versions of PyGObject from 2.0 and up. The source code
-  must be consulted if this reference and your version of
-  <literal>PyGObject</literal> seem to differ. You are encouraged to use the
-  latest version of <literal>PyGObject</literal> that is available. See the
-  <ulink url="http://www.pygtk.org"><literal>PyGTK</literal>
-  homepage</ulink> for more information and more resources on how to use
-  PyGObject as well as help in its development.</para>
-
-  <para> The Reference contains a chapter for each
-  <literal>PyGObject</literal> module containing the class descriptions. The
-  class descriptions are arranged alphabetically within the
-  chapters. Currently there is one module chapter:</para>
-
-  <variablelist>
-    <varlistentry>
-      <term>The&nbsp;<literal>gobject</literal>&nbsp;module</term>
-      <listitem><simpara>The classes that are included in the
-<literal>gobject</literal> module of <literal>PyGObject</literal> and are
-accessed similar to: gobject.GObject. These classes are the base object
-classes that the <literal>gtk</literal> and <literal>gtk.gdk</literal>
-module classes are built on.</simpara>
-      </listitem>
-    </varlistentry>
-  </variablelist>
-
-<!--
-  <sect1>
-    <title>Major Changes since Version 2.11</title>
-
-    <para>The major changes in this document since version 2.11
-    include:</para>
-
-    <itemizedlist>
-      <listitem>
-	<para></para>
-      </listitem>
-    </itemizedlist>
-
-  </sect1>
--->
-
-  <sect1 id="pygladeui-reference-format">
-    <title>Reference Page Format</title>
-
-    <para>Each <literal>PyGObject</literal> class is described in a reference
-page that has a number of sections in a fixed format. Each reference page
-will have a subset of the following sections:</para>
-
-    <variablelist>
-      <varlistentry>
-	<term>Name</term>
-	<listitem>
-	  <simpara>The name and a one-line description of the
-class.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Synopsis</term>
-	<listitem>
-	  <simpara>A synopsis of the class and its methods and
-optionally a list of associated functions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Ancestry</term>
-	<listitem>
-	  <simpara>The list of the parent classes of the class. This
-section may not be present in all class descriptions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Properties</term>
- 	<listitem>
-	  <simpara>A list of the properties (internal state)
-supported by the class. This section may not be present in all classes. The
-property descriptions include the name, the access operations (e.g. Read,
-Write), and a brief description. Properties are accessed using the <link
-linkend="method-gobject--set-property"><methodname>gobject.set_property</methodname>()</link> 
-and <link
-linkend="method-gobject--get-property"><methodname>gobject.get_property</methodname>()</link> 
-methods that are available to every <literal>PyGObject</literal> object. This
-section may not be present in all class descriptions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Attributes</term>
-	<listitem>
-	  <simpara>A set of internal object state data accessible as Python
-	  attributes (e.g. object.attr). The attribute descriptions include
-	  a name by which the attribute data is accessed, the access mode
-	  (e.g. Read, Write), and a brief description of the attribute. Most
-	  <literal>PyGObject</literal> classes do not support attributes so
-	  this section is not present in most class descriptions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Signal&nbsp;Prototypes</term>
-	<listitem>
-	  <simpara>A list of the signals supported by the class including
-	  the signal name and a synopsis of the signal handler function
-	  prototype. This section may not be present in all class
-	  descriptions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Description</term>
-	<listitem><simpara>A description of the class and possibly some of
-	the methods supported by the class.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Constructor</term>
-	<listitem>
-	  <simpara>The description of the class object constructor including
-	  the synopsis with brief parameter descriptions and a description
-	  of th use of the constructor. There may be more than one
-	  constructor description if the constructor supports different
-	  parameter lists. This section may not be present in all class
-	  descriptions.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Methods</term>
-	<listitem>
-	  <simpara>A list of methods supported by the class. Each method
-	  description includes: a synopsis of the method and its parameters
-	  as well as a brief description of each parameter and return value
-	  (if any); and, a description of the use of the method.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Functions</term>
-	<listitem>
-	  <simpara>A list of related functions. Each function description
-	  includes a synopsis of the function and its parameters and return
-	  value (if any), and a description of the use of the
-	  function.</simpara>
-	</listitem>
-      </varlistentry>
-      <varlistentry>
-	<term>Signals</term>
-	<listitem>
-	  <simpara>A list of signals including a synopsis of the signal
-	  handler prototype function with its parameters and return value
-	  (if any). The signal emission conditions are briefly
-	  described. This section is not present in all class descriptions;
-	  specifically, the <literal>gtk.gdk</literal> classes do not
-	  usually support signals.</simpara>
-	</listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>The function and method synopsis parameters are displayed in
-    <emphasis role="bold">bold</emphasis> to denote Python keyword
-    parameters.  Also if the parameter is optional its default value will be
-    displayed. For example the <link
-    linkend="function-gobject--signal-lookup"><function>gobject.signal_lookup</function>()</link>
-    function synopsis is:</para>
-
-    <programlisting>
-<methodsynopsis language="python">
-	<methodname><link
-linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname>
-	<methodparam><parameter
-		       role="keyword">name</parameter></methodparam>
-	<methodparam><parameter
-		       role="keyword">type</parameter></methodparam>
-      </methodsynopsis>
-</programlisting>
-
-    <para>The parameters <parameter>name</parameter> and
-    <parameter>type</parameter> are keyword parameters that can be specified
-    in a call either by position or keyword (in which case position is not
-    important). The following calls have the same result:</para>
-
-    <programlisting>
-  id = gobject.signal_lookup("clicked", gtk.Button)
-  id = gobject.signal_lookup("clicked", type=gtk.Button)
-  id = gobject.signal_lookup(name="clicked", type=gtk.Button)
-  id = gobject.signal_lookup(type=gtk.Button, name="clicked")
-</programlisting>
-
-    <para>Parameters that are not keyword parameters are displayed in
-<emphasis>italic</emphasis> and must be specified positionally but may also
-be optional.</para>
-
-  </sect1>
-
-  </chapter>
diff --git a/bindings/python/docs/pygladeui.xml b/bindings/python/docs/pygladeui.xml
index 9f932f60..3f7f41e5 100644
--- a/bindings/python/docs/pygladeui.xml
+++ b/bindings/python/docs/pygladeui.xml
@@ -43,9 +43,11 @@
     <abstract>
       <para>This reference describes the classes of the Python gladeui module.</para>
     </abstract>
-    
   </bookinfo>
+  
   <toc>
   </toc>
+    <xi:include href="pygladeui-classes.xml"/>
+
 
 </book>