pygobject r1034 - in trunk/docs: . reference
- From: gianmt svn gnome org
- To: svn-commits-list gnome org
- Subject: pygobject r1034 - in trunk/docs: . reference
- Date: Tue, 24 Mar 2009 23:56:09 +0000 (UTC)
Author: gianmt
Date: Tue Mar 24 23:56:09 2009
New Revision: 1034
URL: http://svn.gnome.org/viewvc/pygobject?rev=1034&view=rev
Log:
2009-03-25 Gian Mario Tagliaretti <gianmt gnome org>
* docs/Makefile.am:
* docs/reference/pygio-classes.xml:
* docs/reference/pygio-simpleasyncresult.xml:
Add gio.SimpleAsyncResult in docs.
Added:
trunk/docs/reference/pygio-simpleasyncresult.xml
Modified:
trunk/docs/Makefile.am
trunk/docs/reference/ChangeLog
trunk/docs/reference/pygio-classes.xml
Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am (original)
+++ trunk/docs/Makefile.am Tue Mar 24 23:56:09 2009
@@ -26,6 +26,7 @@
html/class-giofileenumerator.html \
html/class-giofileicon.html \
html/class-gioicon.html \
+ html/class-giosimpleasyncresult.html \
html/gio-constants.html \
html/gio-class-reference.html \
html/gobject-constants.html \
@@ -61,7 +62,8 @@
reference/pygio-icon.xml \
reference/pygio-fileattributeinfo.xml \
reference/pygio-fileenumerator.xml \
- reference/pygio-fileicon.xml
+ reference/pygio-fileicon.xml \
+ reference/pygio-simpleasyncresult.xml
XSL_FILES = \
xsl/common.xsl \
Modified: trunk/docs/reference/pygio-classes.xml
==============================================================================
--- trunk/docs/reference/pygio-classes.xml (original)
+++ trunk/docs/reference/pygio-classes.xml Tue Mar 24 23:56:09 2009
@@ -17,6 +17,7 @@
<xi:include href="pygio-fileenumerator.xml"/>
<xi:include href="pygio-fileicon.xml"/>
<xi:include href="pygio-icon.xml"/>
+<xi:include href="pygio-simpleasyncresult.xml"/>
<xi:include href="pygio-constants.xml"/>
</chapter>
Added: trunk/docs/reference/pygio-simpleasyncresult.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pygio-simpleasyncresult.xml Tue Mar 24 23:56:09 2009
@@ -0,0 +1,317 @@
+<?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-giosimpleasyncresult">
+ <refnamediv>
+ <refname>gio.SimpleAsyncResult</refname>
+ <refpurpose>Simple asynchronous results implementation.</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+
+ <classsynopsis language="python">
+ <ooclass><classname>gio.SimpleAsyncResult</classname></ooclass>
+ <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--complete">complete</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">complete_in_idle</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">get_op_res_gboolean</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">get_op_res_gssize</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--propagate-error">propagate_error</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">set_handle_cancellation</link></methodname>
+ <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">set_op_res_gboolean</link></methodname>
+ <methodparam><parameter role="keyword">op_res</parameter></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">set_op_res_gssize</link></methodname>
+ <methodparam><parameter role="keyword">op_res</parameter></methodparam>
+ </methodsynopsis>
+
+ </classsynopsis>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+ +-- <link linkend="class-giosimpleasyncresult">gio.SimpleAsyncResult</link>
+</synopsis>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Implemented Interface</title>
+ <para>
+ <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> implements
+ <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Implements <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+ for simple cases. Most of the time, this will be all an application needs, and will be used transparently
+ Because of this, GSimpleAsyncResult is used throughout GIO for handling asynchronous functions.
+ </para>
+ <para>
+ <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>
+ handles GAsyncReadyCallbacks, error reporting, operation cancellation and the final state of an
+ operation, completely transparent to the application. Results can be returned as a pointer e.g.
+ for functions that return data that is collected asynchronously, a boolean value for checking the
+ success or failure of an operation, or a gssize for operations which return the number of bytes modified
+ by the operation; all of the simple return cases are covered.
+ </para>
+ <para>
+ Most of the time, an application will not need to know of the details of this API; it is handled
+ transparently, and any necessary operations are handled by GAsyncResult's interface. However, if
+ implementing a new GIO module, for writing language bindings, or for complex applications that need
+ better control of how asynchronous operations are completed, it is important to understand this functionality.
+ </para>
+ <para>
+ <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>
+ are tagged with the calling function to ensure that asynchronous functions and
+ their finishing functions are used together correctly.
+ </para>
+ <!-- NEEDS LOVE
+ <para>
+ To create a new <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>,
+ call g_simple_async_result_new(). If the result needs to be created for a GError, use g_simple_async_result_new_from_error().
+ If a GError is not available (e.g. the asynchronous operation's doesn't take a GError argument), but the result still needs
+ to be created for an error condition, use g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
+ if your application or binding requires passing a variable argument list directly), and the error can then be propegated
+ through the use of g_simple_async_result_propagate_error().
+ </para>
+ -->
+ <para>
+ An asynchronous operation can be made to ignore a cancellation event by calling
+ <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">gio.SimpleAsyncResult.set_handle_cancellation</link></methodname>()
+ with a
+ <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+ for the operation and <literal>False</literal>. This is useful for operations that are dangerous to cancel,
+ such as close (which would cause a leak if cancelled before being run).
+ </para>
+ <para>
+ <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+ can integrate into GLib's event loop, GMainLoop, or it can use GThreads if available.
+ <methodname><link linkend="method-giosimpleasyncresult--complete">gio.SimpleAsyncResult.complete</link></methodname>()
+ will finish an I/O task directly within the main event loop.
+ <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>()
+ will integrate the I/O task into the main event loop as an idle function.
+ <!--
+ and g_simple_async_result_run_in_thread()
+ will run the job in a separate thread.
+ -->
+ </para>
+ <para>
+ To set the results of an asynchronous function,
+ <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">gio.SimpleAsyncResult.set_op_res_gboolean</link></methodname>(), and
+ <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">gio.SimpleAsyncResult.set_op_res_gssize</link></methodname>()
+ are provided, setting the operation's result to a gboolean, or gssize, respectively.
+ </para>
+ <para>
+ Likewise, to get the result of an asynchronous function,
+ <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">gio.SimpleAsyncResult.get_op_res_gboolean</link></methodname>() and
+ <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">gio.SimpleAsyncResult.get_op_res_gssize</link></methodname>()
+ are provided, getting the operation's result as a gboolean and gssize, respectively.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Methods</title>
+
+ <refsect2 id="method-giosimpleasyncresult--complete">
+ <title>gio.SimpleAsyncResult.complete</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>complete</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ </variablelist>
+
+ <para>
+ The <methodname>complete</methodname>() method completes an asynchronous I/O job.
+ Must be called in the main thread, as it invokes the callback that should be called
+ in the main thread. If you are in a different thread use
+ <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--complete-in-idle">
+ <title>gio.SimpleAsyncResult.complete_in_idle</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>complete_in_idle</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ </variablelist>
+
+ <para>
+ The <methodname>complete_in_idle</methodname>() method completes an asynchronous
+ function in the main event loop using an idle function.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--get-op-res-gboolean">
+ <title>gio.SimpleAsyncResult.get_op_res_gboolean</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_op_res_gboolean</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if the operation's result was
+ <literal>True</literal>, <literal>False</literal> if the operation's result
+ was <literal>False</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_op_res_gboolean</methodname>() method gets the operation
+ result boolean from within the asynchronous result.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--get-op-res-gssize">
+ <title>gio.SimpleAsyncResult.get_op_res_gssize</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_op_res_gssize</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a gssize returned from the asynchronous function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_op_res_gssize</methodname>() method gets a gssize
+ from the asynchronous result.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--propagate-error">
+ <title>gio.SimpleAsyncResult.propagate_error</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>propagate_error</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if the error was propegated
+ to dest. <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>propagate_error</methodname>() method propagates an error
+ from within the simple asynchronous result to a given destination.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--set-handle-cancellation">
+ <title>gio.SimpleAsyncResult.set_handle_cancellation</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>set_handle_cancellation</methodname>
+ <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">handle_cancellation</parameter> :</term>
+ <listitem><simpara>a boolean.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>set_handle_cancellation</methodname>() method sets whether
+ to handle cancellation within the asynchronous operation.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--set-op-res-gboolean">
+ <title>gio.SimpleAsyncResult.set_op_res_gboolean</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>set_op_res_gboolean</methodname>
+ <methodparam><parameter role="keyword">op_res</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">op_res</parameter> :</term>
+ <listitem><simpara>a boolean.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>set_op_res_gboolean</methodname>() method sets the operation
+ result to a boolean within the asynchronous result.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giosimpleasyncresult--set-op-res-gssize">
+ <title>gio.SimpleAsyncResult.set_op_res_gssize</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>set_op_res_gssize</methodname>
+ <methodparam><parameter role="keyword">op_res</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">op_res</parameter> :</term>
+ <listitem><simpara>a gssize.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>set_op_res_gssize</methodname>() method sets the operation
+ result within the asynchronous result to the given op_res.
+ </para>
+ </refsect2>
+ </refsect1>
+</refentry>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
