Add few gio classes.

2009-03-08  Gian Mario Tagliaretti  <gianmt@gnome.org>

	* docs/Makefile.am:
	* docs/reference/pygio-classes.xml:
	* docs/reference/pygobject-ref.xml:
	* docs/reference/pygio-applaunchcontext.xml:
	* docs/reference/pygio-cancellable.xml: Add few gio classes.


svn path=/trunk/; revision=1023

4 files changed, 366 insertions, 0 deletions

diff --git a/docs/reference/pygio-applaunchcontext.xml b/docs/reference/pygio-applaunchcontext.xml
new file mode 100644
index 0000000..0d5edb6
--- /dev/null
+++ b/docs/reference/pygio-applaunchcontext.xml
@@ -0,0 +1,194 @@
+<?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-gdkapplaunchcontext">
+    <refnamediv>
+        <refname>gio.AppLaunchContext</refname>
+        <refpurpose>Application launch context.</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.AppLaunchContext</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+    
+    <constructorsynopsis language="python">
+	<methodname><link linkend="constructor-gioapplaunchcontext">gio.AppLaunchContext</link></methodname>
+	<methodparam></methodparam>
+    </constructorsynopsis>
+    
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioapplaunchcontext--get-display">get_display</link></methodname>
+        <methodparam><parameter role="keyword">info</parameter></methodparam>
+        <methodparam><parameter role="keyword">files</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname>
+        <methodparam><parameter role="keyword">info</parameter></methodparam>
+        <methodparam><parameter role="keyword">files</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioapplaunchcontext--launch-failed">launch_failed</link></methodname>
+        <methodparam><parameter role="keyword">startup_notify_id</parameter></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+  +-- <link linkend="class-gioapplaunchcontext">gio.AppLaunchContext</link>
+</synopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            The <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link>
+            is used for integrating the launch with the launching application. This is used to handle for
+            instance startup notification and launching the new application on the same screen as the launching window.
+        </para>
+    </refsect1>
+
+    <refsect1 id="constructor-gioapplaunchcontext">
+        <title>Constructor</title>
+  
+        <programlisting><constructorsynopsis language="python">
+            <methodname>gio.AppLaunchContext</methodname>
+            <methodparam></methodparam>
+        </constructorsynopsis></programlisting>
+        <variablelist>
+            <varlistentry>
+                <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                <listitem><simpara>a new
+                <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link>.
+                </simpara></listitem>
+            </varlistentry>
+        </variablelist>
+    
+        <para>
+            Creates a new application launch context. This is not normally used, instead
+            you instantiate a subclass of this, such as
+            <link linkend="class-gdkapplaunchcontext"><classname>gtk.gdk.AppLaunchContext</classname></link>.
+        </para>
+  
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+
+        <refsect2 id="method-gioapplaunchcontext--get-display">
+            <title>gio.AppLaunchContext.get_display</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_display</methodname>
+                <methodparam><parameter role="keyword">info</parameter></methodparam>
+                <methodparam><parameter role="keyword">files</parameter></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><parameter>info</parameter>&nbsp;:</term>
+                    <listitem><simpara>a
+                    <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>
+                    </simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><parameter>files</parameter>&nbsp;:</term>
+                    <listitem><simpara>a list of
+                    <link linkend="class-giofile"><classname>gio.File</classname></link>
+                    objects.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>a display string for the display. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_display</methodname>() method gets the display
+                string for the display. This is used to ensure new applications
+                are started on the same display as the launching application.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioapplaunchcontext--get-startup-notify-id">
+            <title>gio.AppLaunchContext.get_startup_notify_id</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_startup_notify_id</methodname>
+                <methodparam><parameter role="keyword">info</parameter></methodparam>
+                <methodparam><parameter role="keyword">files</parameter></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><parameter>info</parameter>&nbsp;:</term>
+                    <listitem><simpara>a
+                    <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>
+                    </simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><parameter>files</parameter>&nbsp;:</term>
+                    <listitem><simpara>a list of
+                    <link linkend="class-giofile"><classname>gio.File</classname></link>
+                    objects.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>a startup notification ID for the application,
+                    or <literal>None</literal> if not supported. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_startup_notify_id</methodname>() method initiates
+                startup notification for the application and returns the DESKTOP_STARTUP_ID
+                for the launched operation, if supported. 
+            </para>
+            <para>
+                Startup notification IDs are defined in the FreeDesktop.Org Startup Notifications standard.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioapplaunchcontext--launch-failed">
+            <title>gio.AppLaunchContext.launch_failed</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>launch_failed</methodname>
+                <methodparam><parameter role="keyword">startup_notify_id</parameter></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><parameter>startup_notify_id</parameter>&nbsp;:</term>
+                    <listitem><simpara>the startup notification id that was returned by
+                    <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname>.
+                    </simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>a startup notification ID for the application,
+                    or <literal>None</literal> if not supported. 
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_startup_notify_id</methodname>() method is called
+                when an application has failed to launch, so that it can cancel the application
+                startup notification started in
+                <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname>
+            </para>
+        </refsect2>
+    </refsect1>
+</refentry>
diff --git a/docs/reference/pygio-cancellable.xml b/docs/reference/pygio-cancellable.xml
new file mode 100644
index 0000000..d36421c
--- /dev/null
+++ b/docs/reference/pygio-cancellable.xml
@@ -0,0 +1,159 @@
+<?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-giocancellable">
+    <refnamediv>
+        <refname>gio.Cancellable</refname>
+        <refpurpose>Thread-safe Operation Cancellation Stack.</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.Cancellable</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+    
+    <constructorsynopsis language="python">
+	<methodname><link linkend="constructor-giocancellable">gio.Cancellable</link></methodname>
+	<methodparam></methodparam>
+    </constructorsynopsis>
+    
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--cancel">cancel</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--get-fd">get_fd</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--is-cancelled">is_cancelled</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--pop-current">pop_current</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--push-current">push_current</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--reset">reset</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giocancellable--set-error-if-cancelled">set_error_if_cancelled</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+  +-- <link linkend="class-giocancellable">gio.Cancellable</link>
+</synopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            The <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+            is a thread-safe operation cancellation stack used throughout GIO to allow for
+            cancellation of synchronous and asynchronous operations.
+        </para>
+    </refsect1>
+
+    <refsect1 id="constructor-giocancellable">
+        <title>Constructor</title>
+  
+        <programlisting><constructorsynopsis language="python">
+            <methodname>gio.Cancellable</methodname>
+            <methodparam></methodparam>
+        </constructorsynopsis></programlisting>
+        <variablelist>
+            <varlistentry>
+                <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                <listitem><simpara>a new
+                <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>.
+                </simpara></listitem>
+            </varlistentry>
+        </variablelist>
+    
+        <para>
+            Creates a new <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> object.
+        </para>
+        <para>
+            Applications that want to start one or more operations that should be cancellable should create a
+            <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+            and pass it to the operations. 
+        </para>
+        <para>
+            One <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+            can be used in multiple consecutive operations, but not in multiple concurrent operations.
+        </para>
+  
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+
+        <refsect2 id="method-giocancellable--cancel">
+            <title>gio.Cancellable.cancel</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>cancel</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+            </variablelist>
+    
+            <para>
+                The <methodname>cancel</methodname>() method will set cancellable to cancelled,
+                and will emit the "cancelled" signal. (However, see the warning about race conditions
+                in the documentation for that signal if you are planning to connect to it.) 
+            </para>
+            <para>
+                This function is thread-safe. In other words, you can safely call it from a thread
+                other than the one running the operation that was passed the cancellable. 
+            </para>
+            <para>
+                The convention within gio is that cancelling an asynchronous operation causes it
+                to complete asynchronously. That is, if you cancel the operation from the same thread
+                in which it is running, then the operation's GAsyncReadyCallback will not be invoked
+                until the application returns to the main loop.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-giocancellable--get-fd">
+            <title>gio.Cancellable.get_fd</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_fd</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+            <varlistentry>
+                <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                <listitem><simpara>A valid file descriptor. -1 if the file descriptor
+                is not supported, or on errors.</simpara></listitem>
+            </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_fd</methodname>() method gets the file descriptor
+                for a cancellable job. This can be used to implement cancellable operations
+                on Unix systems. The returned fd will turn readable when cancellable is cancelled. 
+            </para>
+        </refsect2>
+    </refsect1>
+</refentry>
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
new file mode 100644
index 0000000..f4df171
--- /dev/null
+++ b/docs/reference/pygio-classes.xml
@@ -0,0 +1,12 @@
+<?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="gio-class-reference"
+  xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<title>PyGioClass Reference</title>
+
+<!-- GLIB CLASSES -->
+<xi:include href="pygio-applaunchcontext.xml"/>
+
+</chapter>
diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml
index ee90a55..08dd1dd 100644
--- a/docs/reference/pygobject-ref.xml
+++ b/docs/reference/pygobject-ref.xml
@@ -24,6 +24,7 @@ module.</para>
 
   <xi:include href="pyglib-classes.xml"/>
   <xi:include href="pygobject-classes.xml"/>
+  <xi:include href="pygio-classes.xml"/>
 
 <!--
   <index>