pygtk-gobject-mainloop.xml Add.

	* pygtk-gobject-mainloop.xml Add.

2 files changed, 204 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 117949bd..348bc5ad 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -17,6 +17,8 @@
 
 	* pygtk-gobject-maincontext.xml Add.
 
+	* pygtk-gobject-mainloop.xml Add.
+
 2004-04-25  John Finlay  <finlay@moeraki.com>
 
 	* pygtk-pango-functions.xml Add.
diff --git a/docs/reference/pygtk-gobject-mainloop.xml b/docs/reference/pygtk-gobject-mainloop.xml
new file mode 100644
index 00000000..d90f534d
--- /dev/null
+++ b/docs/reference/pygtk-gobject-mainloop.xml
@@ -0,0 +1,202 @@
+<?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-gobjectmainloop">
+  <refnamediv>
+    <refname>gobject.MainLoop</refname>
+
+    <refpurpose>an object representing the main event loop of a PyGTK
+    application.</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Synopsis</title>
+
+<classsynopsis language="python">
+  <ooclass><classname>gobject.MainLoop</classname></ooclass>
+<constructorsynopsis language="python">
+    <methodname><link linkend="constructor-gobjectmainloop">gobject.MainLoop</link></methodname>
+    <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam>
+    <methodparam><parameter>is_running</parameter><initializer>0</initializer></methodparam>
+  </constructorsynopsis>
+<methodsynopsis language="python">
+    <methodname><link linkend="method-gobjectmainloop--get-context">get_context</link></methodname>
+  </methodsynopsis>
+<methodsynopsis language="python">
+    <methodname><link linkend="method-gobjectmainloop--is-running">is_running</link></methodname>
+  </methodsynopsis>
+<methodsynopsis language="python">
+    <methodname><link linkend="method-gobjectmainloop--quit">quit</link></methodname>
+  </methodsynopsis>
+<methodsynopsis language="python">
+    <methodname><link linkend="method-gobjectmainloop--run">run</link></methodname>
+  </methodsynopsis>
+</classsynopsis>
+
+</refsect1>
+
+  <refsect1>
+    <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobjectmainloop">gobject.MainLoop</link>
+</synopsis>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><link
+linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>
+represents a main event loop. A <link
+linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>
+is created with the <link
+linkend="constructor-gobjectmainloop">gobject.MainLoop</link>()
+constructor. After adding the initial event sources, the <link
+linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link>
+method is called. This continuously checks for new events from each of the
+event sources and dispatches them. Finally, the processing of an event from
+one of the sources leads to a call to the <link
+linkend="method-gobjectmainloop--quit"><methodname>quit</methodname>()</link>
+method to exit the main loop, and the <link
+linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link>
+method returns.</para>
+
+    <para>It is possible to create new instances of <link
+linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>
+recursively. This is often used in <literal>PyGTK</literal> applications
+when showing modal dialog boxes. Note that event sources are associated with
+a particular <link
+linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>,
+and will be checked and dispatched for all main loops associated with that
+<link
+linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>.</para>
+
+    <para><literal>PyGTK</literal> contains wrappers of some of these
+functions, e.g. the <link
+linkend="function-gtk--main"><function>gtk.main</function>()</link>, <link
+linkend="function-gtk--main-quit"><function>gtk.main_quit</function>()</link>
+and <link
+linkend="function-gtk--events-pending"><function>gtk.events_pending</function>()</link>
+functions.</para>
+
+  </refsect1>
+
+  <refsect1 id="constructor-gobjectmainloop">
+    <title>Constructor</title>
+
+    <programlisting><constructorsynopsis language="python">
+	<methodname>gobject.MainLoop</methodname>
+	<methodparam><parameter>context</parameter><initializer>None</initializer></methodparam>
+	<methodparam><parameter>is_running</parameter><initializer>None</initializer></methodparam>
+      </constructorsynopsis></programlisting>
+    <variablelist>
+      <varlistentry>
+	<term><parameter>context</parameter>&nbsp;:</term>
+	<listitem><simpara>a <link
+	linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
+	or <literal>None</literal> to use the default
+	context.</simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><parameter>is_running</parameter>&nbsp;:</term>
+	<listitem><simpara>if <literal>TRUE</literal> indicates that the
+	loop is running. This is not very important since calling the <link
+	linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link>
+	method will set this to <literal>TRUE</literal>
+	anyway.</simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	<listitem><simpara>a new <link
+	linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>
+	object.</simpara></listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Creates a new <link
+linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>
+object.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Methods</title>
+
+    <refsect2 id="method-gobjectmainloop--get-context">
+      <title>gobject.MainLoop.get_context</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_context</methodname>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>the <link
+	  linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
+	  the mainloop is associated with</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>get_context</methodname>() method returns the
+<link
+linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>
+that the mainloop was created with.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gobjectmainloop--is-running">
+      <title>gobject.MainLoop.is_running</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>is_running</methodname>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara><literal>TRUE</literal> if the mainloop is
+	  currently being run.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>is_running</methodname>() method checks to see
+if the mainloop is currently being run via the <link
+linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link>
+method.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gobjectmainloop--quit">
+      <title>gobject.MainLoop.quit</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>quit</methodname>
+	</methodsynopsis></programlisting>
+
+      <para>The <methodname>quit</methodname>() method stops the mainloop
+from running. Any subsequent calls to the <link
+linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link>
+method will return immediately.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gobjectmainloop--run">
+      <title>gobject.MainLoop.run</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>run</methodname>
+	</methodsynopsis></programlisting>
+
+      <para>The <methodname>run</methodname>() method runs a mainloop until
+the <link
+linkend="method-gobjectmainloop--quit"><methodname>quit</methodname>()</link>
+method is called. If this is called for the thread of the loop's <link
+linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link>,
+it will process events from the loop, otherwise it will simply wait.</para>
+
+    </refsect2>
+
+  </refsect1>
+
+</refentry>