diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/ChangeLog | 6 | ||||
| -rw-r--r-- | docs/reference/pygio-asyncresult.xml | 117 | ||||
| -rw-r--r-- | docs/reference/pygio-classes.xml | 1 |
3 files changed, 124 insertions, 0 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index e65dea5..50a7724 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -2,6 +2,12 @@ * docs/Makefile.am: * docs/reference/pygio-classes.xml: + * docs/reference/pygio-asyncresult.xml: Add gio.AsyncResult in docs. + +2009-03-24 Gian Mario Tagliaretti <gianmt@gnome.org> + + * docs/Makefile.am: + * docs/reference/pygio-classes.xml: * docs/reference/pygio-appinfo.xml: * docs/reference/pygio-constants.xml: * docs/reference/pygio-fileattributeinfo.xml: Add gio.AppInfo and diff --git a/docs/reference/pygio-asyncresult.xml b/docs/reference/pygio-asyncresult.xml new file mode 100644 index 0000000..abe56ce --- /dev/null +++ b/docs/reference/pygio-asyncresult.xml @@ -0,0 +1,117 @@ +<?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-gioasyncresult"> + <refnamediv> + <refname>gio.AsyncResult</refname> + <refpurpose>Asynchronous Function Results.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.AsyncResult</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioasyncresult--get-source-object">get_source_object</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioasyncresult">gio.AsyncResult</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is required by + <link linkend="class-gobject"><classname>gobject.GObject</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is implemented by + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + provides a base class for implementing asynchronous function results. + </para> + <para> + Asynchronous operations are broken up into two separate operations which are chained + together by a GAsyncReadyCallback. To begin an asynchronous operation, provide a + GAsyncReadyCallback to the asynchronous function. This callback will be triggered when + the operation has completed, and will be passed a GAsyncResult instance filled with the + details of the operation's success or failure, the object the asynchronous function was + started for and any error codes returned. The asynchronous callback function is then expected + to call the corresponding "_finish()" function with the object the function was called for, + and the <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + instance, and optionally, an error to grab any error conditions that may have occurred. + </para> + <para> + The purpose of the "_finish()" function is to take the generic result of type GAsyncResult and + return the specific result that the operation in question yields (e.g. a + <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + for a "enumerate children" operation). If the result or error status of the operation is not needed, + there is no need to call the "_finish()" function, GIO will take care of cleaning up the result and error + information after the GAsyncReadyCallback returns. It is also allowed to take a reference to the + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + and call "_finish()" later. + </para> + <para> + The callback for an asynchronous operation is called only once, and is always called, even + in the case of a cancelled operation. On cancellation the result is a gio.ERROR_CANCELLED error. + </para> + <para> + Some ascynchronous operations are implemented using synchronous calls. These are run in a + separate thread, if GThread has been initialized, but otherwise they are sent to the Main Event + Loop and processed in an idle function. So, if you truly need asynchronous operations, make + sure to initialize GThread. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioasyncresult--get-source-object"> + <title>gio.AsyncResult.get_source_object</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_source_object</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the source object for the res. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_source_object</methodname>() method gets the source object + from a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml index b3ecda5..f401bf9 100644 --- a/docs/reference/pygio-classes.xml +++ b/docs/reference/pygio-classes.xml @@ -9,6 +9,7 @@ <!-- GIO CLASSES --> <xi:include href="pygio-appinfo.xml"/> <xi:include href="pygio-applaunchcontext.xml"/> +<xi:include href="pygio-asyncresult.xml"/> <xi:include href="pygio-cancellable.xml"/> <xi:include href="pygio-emblem.xml"/> <xi:include href="pygio-icon.xml"/> |