diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/pygobject-introduction.xml | 239 | ||||
| -rw-r--r-- | docs/reference/pygobject-ref.xml | 141 | ||||
| -rw-r--r-- | docs/reference/version.xml.in | 1 |
3 files changed, 252 insertions, 129 deletions
diff --git a/docs/reference/pygobject-introduction.xml b/docs/reference/pygobject-introduction.xml new file mode 100644 index 0000000..a139646 --- /dev/null +++ b/docs/reference/pygobject-introduction.xml @@ -0,0 +1,239 @@ +<?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="pygobject-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. I have attempted to document as much of the + <literal>PyGObject</literal> <literal>API</literal> as I can but there are + undoubtedly errors and omissions. If you discover any of these please send + me email at <email><ulink + url="mailto:finlay@moeraki.com">finlay@moeraki.com</ulink></email> or file + a bug report at <ulink + url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink> for the + <literal>pygobject</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 <literal>gobject</literal> 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="pygobject-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 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> + + <sect1 id="pygobject-reference-copyright"> + <title>Copyright and License Notice</title> + + <para>The PyGObject 2.0 Reference is Copyright (C) 2004-2006 John + Finlay.</para> + + <para>This work is licensed under the Creative Commons + Attribution-ShareAlike License. To view a copy of this license, visit + <ulink + url="http://creativecommons.org/licenses/by-sa/1.0/">http://creativecommons.org/licenses/by-sa/1.0/</ulink> + or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, + California 94305, USA.</para> + + </sect1> + + </chapter> diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml index 9252ea0..c455145 100644 --- a/docs/reference/pygobject-ref.xml +++ b/docs/reference/pygobject-ref.xml @@ -1,13 +1,15 @@ <?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "version.xml"> +<!ENTITY builddate SYSTEM "builddate.xml"> ]> -<book id="pygtk-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> +<book id="pygobject-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> <bookinfo> - <pubdate>July 6, 2006</pubdate> + <pubdate>&builddate;</pubdate> <title>PyGObject Reference Manual</title> - <edition>for version 2.12.x</edition> - <releaseinfo>Version 2.11.0</releaseinfo> + <edition>for version &version;</edition> + <releaseinfo>for PyGObject version &version;</releaseinfo> <authorgroup> <author> <firstname>John</firstname> @@ -18,137 +20,18 @@ <para>This reference describes the classes of the python gobject module.</para> </abstract> -<!-- <revhistory> - <revision> - <revnumber>2.9.0</revnumber> - <date>July 7, 2006</date> - <revremark>Release covering PyGTK 2.9.x (GTK+ 2.9)</revremark> - </revision> - <revision> - <revnumber>2.8.2</revnumber> - <date>October 7, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.8.1</revnumber> - <date>September 17, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.8.0</revnumber> - <date>September 7, 2005</date> - <revremark>Release covering PyGTK 2.8.x (GTK+ 2.8)</revremark> - </revision> - <revision> - <revnumber>2.6.0</revnumber> - <date>April 10, 2005</date> - <revremark>First release covering PyGTK 2.6.x (GTK+ 2.6)</revremark> - </revision> - <revision> - <revnumber>2.5.2</revnumber> - <date>March 5, 2005</date> - </revision> - <revision> - <revnumber>2.5.1</revnumber> - <date>December 23, 2004</date> - <revremark>First release covering PyGTK 2.5.1 (GTK+ 2.6)</revremark> - </revision> - <revision> - <revnumber>2.5.0</revnumber> - <date>November 15, 2004</date> - <revremark>First release covering PyGTK 2.5.x</revremark> - </revision> - <revision> - <revnumber>2.4.11</revnumber> - <date>October 3, 2004</date> - </revision> - <revision> - <revnumber>2.4.10</revnumber> - <date>August 11, 2004</date> - </revision> - <revision> - <revnumber>2.4.9</revnumber> - <date>August 3, 2004</date> - </revision> - <revision> - <revnumber>2.4.8</revnumber> - <date>July 1, 2004</date> - </revision> - <revision> - <revnumber>2.4.7</revnumber> - <date>May 19, 2004</date> - </revision> - <revision> - <revnumber>2.4.6</revnumber> - <date>May 17, 2004</date> - </revision> - <revision> - <revnumber>2.4.4</revnumber> - <date>May 5, 2004</date> - </revision> - <revision> - <revnumber>2.4.2</revnumber> - <date>April 29, 2004</date> - </revision> - <revision> - <revnumber>2.4.0</revnumber> - <date>April 27, 2004</date> - <revremark>First release covering PyGTK 2.2 and 2.4</revremark> - </revision> - <revision> - <revnumber>1.9</revnumber> - <date>January 28, 2004</date> - </revision> - <revision> - <revnumber>1.8</revnumber> - <date>October 7, 2003</date> - </revision> - <revision> - <revnumber>1.7</revnumber> - <date>August 23, 2003</date> - </revision> - <revision> - <revnumber>1.6</revnumber> - <date>July 20, 2003</date> - </revision> - <revision> - <revnumber>1.5</revnumber> - <date>July 17, 2003</date> - </revision> - <revision> - <revnumber>1.4</revnumber> - <date>July 16, 2003</date> - </revision> - <revision> - <revnumber>1.3</revnumber> - <date>July 15, 2003</date> - </revision> - <revision> - <revnumber>1.2</revnumber> - <date>July 12, 2003</date> - </revision> - <revision> - <revnumber>1.1</revnumber> - <date>July 11, 2003</date> - </revision> - <revision> - <revnumber>1.0</revnumber> - <date>July 2, 2003</date> - <revremark>First release for PyGTK 2.0</revremark> - </revision> - </revhistory>--> </bookinfo> <toc> </toc> - <!-- <xi:include href="pygtk-introduction.xml"/> --> + <xi:include href="pygobject-introduction.xml"/> <xi:include href="pygobject-classes.xml"/> + <!-- -<appendix id="pygtk-ref-changelog"> -<title>ChangeLog</title> - <xi:include href="ChangeLog.xml"/> -</appendix> - --> + <index> + <title>Index</title> + </index> +--> </book> diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in new file mode 100644 index 0000000..a24f987 --- /dev/null +++ b/docs/reference/version.xml.in @@ -0,0 +1 @@ +@PACKAGE_VERSION@ |