diff options
| author | Johan Dahlin <johan@gnome.org> | 2008-08-01 22:52:06 +0000 |
|---|---|---|
| committer | Johan Dahlin <johan@src.gnome.org> | 2008-08-01 22:52:06 +0000 |
| commit | 0b6932cf263ac3dc68640e3f59e0d83678315aea (patch) | |
| tree | 467fa195ea553e53eca9e371ce7b59927bf1e841 /docs/reference | |
| parent | 9e22741a4683e4184ffcdaf7382b0ba045f4a3be (diff) | |
| download | pygobject-0b6932cf263ac3dc68640e3f59e0d83678315aea.tar.gz pygobject-0b6932cf263ac3dc68640e3f59e0d83678315aea.tar.xz pygobject-0b6932cf263ac3dc68640e3f59e0d83678315aea.zip | |
Separate the glib and gobject bindings in the manual.
2008-08-02 Johan Dahlin <johan@gnome.org>
* docs/Makefile.am:
* docs/reference/pyglib-constants.xml:
* docs/reference/pyglib-functions.xml:
* docs/reference/pyglib-maincontext.xml:
* docs/reference/pyglib-mainloop.xml:
* docs/reference/pygobject-classes.xml:
* docs/reference/pygobject-constants.xml:
* docs/reference/pygobject-functions.xml:
* docs/reference/pygobject-maincontext.xml:
* docs/reference/pygobject-mainloop.xml:
Separate the glib and gobject bindings in the manual.
svn path=/trunk/; revision=910
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/pyglib-constants.xml | 222 | ||||
| -rw-r--r-- | docs/reference/pyglib-functions.xml | 834 | ||||
| -rw-r--r-- | docs/reference/pyglib-maincontext.xml (renamed from docs/reference/pygobject-maincontext.xml) | 40 | ||||
| -rw-r--r-- | docs/reference/pyglib-mainloop.xml (renamed from docs/reference/pygobject-mainloop.xml) | 76 | ||||
| -rw-r--r-- | docs/reference/pygobject-classes.xml | 11 | ||||
| -rw-r--r-- | docs/reference/pygobject-constants.xml | 105 | ||||
| -rw-r--r-- | docs/reference/pygobject-functions.xml | 763 |
7 files changed, 1123 insertions, 928 deletions
diff --git a/docs/reference/pyglib-constants.xml b/docs/reference/pyglib-constants.xml new file mode 100644 index 0000000..a879171 --- /dev/null +++ b/docs/reference/pyglib-constants.xml @@ -0,0 +1,222 @@ +<?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="glib-constants"> + <refnamediv> + <refname>glib Constants</refname> + <refpurpose>the built-in constants of the glib module</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<xref linkend="glib-io-condition-constants" endterm="glib-io-condition-constants-title"></xref> +<xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> +<xref linkend="glib-spawn-flag-constants" endterm="glib-spawn-flag-constants-title"></xref> +<xref linkend="glib-version-constants" endterm="glib-version-constants-title"></xref> +</programlisting> + + </refsect1> + + <refsect1 id="glib-constants-description"> + <title>Description</title> + + <refsect2 id="glib-io-condition-constants"> + <title id="glib-io-condition-constants-title">Glib IO Condition Constants</title> + + <para>The IO Condition constants are a set of bit-flags that specify a +condition to watch for on an event source.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.IO_IN</literal></term> + <listitem> + <simpara>There is data to read</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for + pipes and sockets).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_NVAL</literal></term> + <listitem> + <simpara>Invalid request. The file descriptor is not + open.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-priority-constants"> + <title id="glib-priority-constants-title">Glib Priority Constants</title> + + <para>The Priority constants specify </para> + + <variablelist> + <varlistentry> + <term><literal>glib.PRIORITY_HIGH</literal></term> + <listitem> + <simpara>Use this for high priority event sources.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_DEFAULT</literal></term> + <listitem> + <simpara>Use this for default priority event sources. This + priority is used when adding timeout functions with the <link + linkend="function-glib--timeout-add"><function>glib.timeout_add</function>()</link> + function. This priority is also used for events from the X + server.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_HIGH_IDLE</literal></term> + <listitem> + <simpara>Use this for high priority idle functions. For example, + glib.PRIORITY_HIGH_IDLE + 10 is used for resizing operations; + and, glib.PRIORITY_HIGH_IDLE + 20, for redrawing + operations. (This is done to ensure that any pending resizes are + processed before any pending redraws, so that widgets are not + redrawn twice unnecessarily.)</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_DEFAULT_IDLE</literal></term> + <listitem> + <simpara>Use this for default priority idle functions. This + priority is used when adding idle functions with the <link + linkend="function-glib--idle-add"><function>glib.idle_add</function>()</link> + function.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_LOW</literal></term> + <listitem> + <simpara>Use this for very low priority background + tasks.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-spawn-flag-constants"> + <title id="glib-spawn-flag-constants-title">Glib Spawn Flag Constants</title> + + <para>The Spawn Flag constants are a set of bit-flags that can be +passed to the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal></term> + <listitem> + <simpara>the parent's open file descriptors will be inherited by +the child; otherwise all descriptors except stdin/stdout/stderr will be +closed before calling <function>exec</function>() in the child.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal></term> + <listitem> + <simpara>the child will not be automatically reaped; you must +call <function>waitpid</function>() or handle <literal>SIGCHLD</literal> +yourself, or the child will become a zombie.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_SEARCH_PATH</literal></term> + <listitem> + <simpara><parameter>argv</parameter>[0] need not be an absolute +path, it will be looked for in the user's <envar>PATH</envar>.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard output will be discarded, instead +of going to the same location as the parent's standard output.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard error will be discarded.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal></term> + <listitem> + <simpara>the child will inherit the parent's standard input (by +default, the child's standard input is attached to /dev/null).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_FILE_AND_ARGV_ZERO</literal></term> + <listitem> + <simpara>the first element of <parameter>argv</parameter> is the +file to execute, while the remaining elements are the actual argument vector +to pass to the file. Normally <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +uses <parameter>argv</parameter>[0] as the file to execute, and passes all +of <parameter>argv</parameter> to the child.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-version-constants"> + <title id="glib-version-constants-title">Glib Version Constants</title> + <para>The Version constants specify the version of +<literal>Glib</literal> used by PyGObject as a 3-tuple containing the major, +minor and patch release numbers.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.glib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers of glib.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.pyglib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers of the python bindings.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml new file mode 100644 index 0000000..3464a80 --- /dev/null +++ b/docs/reference/pyglib-functions.xml @@ -0,0 +1,834 @@ +<?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="glib-functions"> + <refnamediv> + <refname>glib Functions</refname> + <refpurpose>miscellaneous functions</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-glib--idle-add">glib.idle_add</link></methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--timeout-add">glib.timeout_add</link></methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--io-add-watch">glib.io_add_watch</link></methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--source-remove">glib.source_remove</link></methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--main-context-default">glib.main_context_default</link></methodname> + <methodparam></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--markup-escape-text">glib.markup_escape_text</link></methodname> + <methodparam><parameter role="keyword">text</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-glib--child-watch-add">glib.child_watch_add</link></methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--spawn-async">glib.spawn_async</link></methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--get-current-time">glib.get_current_time</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--main-depth">glib.main_depth</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--threads-init">glib.threads_init</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-display-name">glib.filename_display_name</link></methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-display-basename">glib.filename_display_basename</link></methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-from-utf8">glib.filename_from_utf8</link></methodname> + <methodparam><parameter>utf8string</parameter></methodparam> + </methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>These functions are part of the <literal>PyGObject</literal> glib +module but are not directly associated with a specific class.</para> + + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-glib--idle-add"> + <title>glib.idle_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.idle_add</methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call when +<literal>PyGTK</literal> is idle</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>optionals arguments to be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.idle_add</function>() function adds a +function (specified by <parameter>callback</parameter>) to be called +whenever there are no higher priority events pending to the default main +loop. The function is given the default idle priority, +<literal>glib.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to +pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority can be specified as a +keyword-value pair with the keyword "priority". If +<parameter>callback</parameter> returns <literal>FALSE</literal> it is +automatically removed from the list of event sources and will not be called +again.</para> + + </refsect2> + + <refsect2 id="function-glib--timeout-add"> + <title>glib.timeout_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.timeout_add</methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>interval</parameter> :</term> + <listitem><simpara>the time between calls to the function, in +milliseconds </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more arguments that will be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event +source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.timeout_add</function>() function sets a +function (specified by <parameter>callback</parameter>) to be called at +regular intervals (specified by <parameter>interval</parameter>, with the +default priority, <literal>glib.PRIORITY_DEFAULT</literal>. Additional +arguments to pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority may be specified as a +keyword-value pair with the keyword "priority".</para> + + <para>The function is called repeatedly until it returns +<literal>FALSE</literal>, at which point the timeout is automatically +destroyed and the function will not be called again. The first call to the +function will be at the end of the first interval. Note that timeout +functions may be delayed, due to the processing of other event sources. Thus +they should not be relied on for precise timing. After each call to the +timeout function, the time of the next timeout is recalculated based on the +current time and the given interval (it does not try to 'catch up' time lost +in delays).</para> + + </refsect2> + + <refsect2 id="function-glib--io-add-watch"> + <title>glib.io_add_watch</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.io_add_watch</methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a Python file object or an integer file +descriptor ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>condition</parameter> :</term> + <listitem><simpara>a condition mask</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional arguments to pass to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.io_add_watch</function>() function +arranges for the file (specified by <parameter>fd</parameter>) to be +monitored by the main loop for the specified +<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python +file object or an integer file descriptor. The value of condition is a +combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>glib.IO_IN</literal></term> + <listitem> + <simpara>There is data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking). </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for +pipes and sockets).</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>Additional arguments to pass to <parameter>callback</parameter> +can be specified after <parameter>callback</parameter>. The idle priority +may be specified as a keyword-value pair with the keyword "priority". The +signature of the callback function is:</para> + + <programlisting> + def callback(source, cb_condition, ...) +</programlisting> + + <para>where <parameter>source</parameter> is +<parameter>fd</parameter>, the file descriptor; +<parameter>cb_condition</parameter> is the condition that triggered the +signal; and, <parameter>...</parameter> are the zero or more arguments that +were passed to the <function>glib.io_add_watch</function>() +function.</para> + + <para>If the callback function returns <literal>FALSE</literal> it +will be automatically removed from the list of event sources and will not be +called again. If it returns <literal>TRUE</literal> it will be called again +when the condition is matched.</para> + + </refsect2> + + <refsect2 id="function-glib--source-remove"> + <title>glib.source_remove</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.source_remove</methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>tag</parameter> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the event source was +removed</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.source_remove</function>() function +removes the event source specified by tag (as returned by the <link +linkend="function-glib--idle-add"><function>glib.idle_add</function>()</link>, +<link +linkend="function-glib--timeout-add"><function>glib.timeout_add</function></link>() +and <link +linkend="function-glib--io-add-watch"><function>glib.io_add_watch</function>()</link> +functions)</para> + + </refsect2> + + <refsect2 id="function-glib--main-context-default"> + <title>glib.main_context_default</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.main_context_default</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the default glib.MainContext +object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.main_context_default</function>() function +returns the default glib.MainContext object.</para> + + </refsect2> + + <refsect2 id="function-glib--markup-escape-text"> + <title>glib.markup_escape_text</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.markup_escape_text</methodname> + <methodparam><parameter>text</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>text</parameter> :</term> + <listitem><simpara>the UTF-8 string to be +escaped</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the escaped text</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>glib.markup_escape_text</function>() function +escapes the string specified by <parameter>text</parameter> so that the +markup parser will parse it verbatim. Less than, greater than, ampersand, +etc. are replaced with the corresponding entities. This function would +typically be used when writing out a file to be parsed with the markup +parser.</para> + + <para>Note that this function doesn't protect whitespace and line +endings from being processed according to the XML rules for normalization of +line endings and attribute values.</para> + + </refsect2> + + <refsect2 id="function-glib--child-watch-add"> + <title>glib.child_watch_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.child_watch_add</methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">pid</parameter> :</term> + <listitem><simpara>process id of a child process to watch</simpara></listitem> + </varlistentry> + <varlistentry><term><parameter role="keyword">function</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>the optional data to pass to +<parameter>function</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">priority</parameter> :</term> + <listitem><simpara>the priority of the idle source - one of the +<xref linkend="glib-priority-constants" +endterm="glib-priority-constants-title"></xref></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the id of event source.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>glib.child_watch_add</function>() function sets +the function specified by <parameter>function</parameter> to be called with +the user data specified by <parameter>data</parameter> when the child +indicated by <parameter>pid</parameter> exits. The signature for the +callback is:</para> + + <programlisting> +def callback(pid, condition, user_data) +</programlisting> + + <para>where <parameter>pid</parameter> is is the child process id, +<parameter>condition</parameter> is the status information about the child +process and <parameter>user_data</parameter> is <parameter>data</parameter> +PyGTK supports only a single callback per process id.</para> + + </refsect2> + + <refsect2 id="function-glib--spawn-async"> + <title>glib.spawn_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.spawn_async</methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">argv</parameter> :</term> + <listitem><simpara>a sequence of strings containing the arguments +of the child process</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">envp</parameter> :</term> + <listitem><simpara>the child's environment or +<literal>None</literal> to inherit the parent's +environment.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">working_directory</parameter> :</term> + <listitem><simpara>the child's current working directory, or +<literal>None</literal> to inherit parent's</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags from the <xref +linkend="glib-spawn-flag-constants" +endterm="glib-spawn-flag-constants-title"></xref>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">child_setup</parameter> :</term> + <listitem><simpara>a function to run in the child just before +calling <function>exec</function>()</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>the user data for the +<parameter>child_setup</parameter> function</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_input</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdin</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_output</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdout</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_error</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stderr</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 4-tuple containing the child's process id and +the stdin, stdout and stderr file descriptor integers.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>glib.spawn_async</function>() function executes +a child program asynchronously (your program will not block waiting for the +child to exit). The child program is specified by the only argument that +must be provided, <parameter>argv</parameter>. <parameter>argv</parameter> +should be a sequence of strings, to be passed as the argument vector for the +child. The first string in <parameter>argv</parameter> is of course the name +of the program to execute. By default, the name of the program must be a +full path; the <envar>PATH</envar> shell variable will only be searched if +you pass the <literal>glib.SPAWN_SEARCH_PATH</literal> flag in +<parameter>flags</parameter>. The function returns a 4-tuple containing the +child's process id and the file descriptors for the child's stdin, stdout +and stderr. The stdin, stdout and stderr file descriptors are returned only +ofthe corresponding <parameter>standard_input</parameter>, +<parameter>standard_output</parameter> or +<parameter>standard_error</parameter> params are +<literal>TRUE</literal>.</para> + + <para>On Windows, the low-level child process creation API +(<function>CreateProcess</function>()) doesn't use argument vectors, but a +command line. The C runtime library's <function>spawn*</function>() family +of functions (which <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +eventually calls) paste the argument vector elements into a command line, +and the C runtime startup code does a corresponding reconstruction of an +argument vector from the command line, to be passed to +<function>main</function>(). Complications arise when you have argument +vector elements that contain spaces of double quotes. The +<function>spawn*</function>() functions don't do any quoting or escaping, +but on the other hand the startup code does do unquoting and unescaping in +order to enable receiving arguments with embedded spaces or double +quotes. To work around this asymmetry, the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function will do quoting and escaping on argument vector elements that need +it before calling the C runtime <function>spawn</function>() +function.</para> + + <para><parameter>envp</parameter> is a sequence of strings, where each + string has the form <literal>KEY=VALUE</literal>. This will become the + child's environment. If <parameter>envp</parameter> is + <parameter>None</parameter> or not specified, the child inherits its + parent's environment.</para> + + <para><parameter>flags</parameter> should be the bitwise +<literal>OR</literal> of the <xref linkend="glib-spawn-flag-constants" +endterm="glib-spawn-flag-constants-title"></xref> you want to affect the +function's behaviour. The <literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> +flag means that the child will not automatically be reaped; you must use a +GChildWatch source to be notified about the death of the child +process. Eventually you must call g_spawn_close_pid() on the child_pid, in +order to free resources which may be associated with the child process. (On +Unix, using a GChildWatch source is equivalent to calling +<function>waitpid</function>() or handling the <literal>SIGCHLD</literal> +signal manually. On Windows, calling g_spawn_close_pid() is equivalent to +calling <function>CloseHandle</function>() on the process handle +returned).</para> + + <para><literal>glib.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means +that the parent's open file descriptors will be inherited by the child; +otherwise all descriptors except stdin/stdout/stderr will be closed before +calling <function>exec</function>() in the +child. <literal>glib.SPAWN_SEARCH_PATH</literal> means that +<parameter>argv</parameter>[0] need not be an absolute path, it will be +looked for in the user's +<envar>PATH</envar>. <literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal> +means that the child's standard output will be discarded, instead of going +to the same location as the parent's standard output. If you use this flag, +<parameter>standard_output</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal> +means that the child's standard error will be discarded, instead of going to +the same location as the parent's standard error. If you use this flag, +<parameter>standard_error</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal> +means that the child will inherit the parent's standard input (by default, +the child's standard input is attached to +<filename>/dev/null</filename>). If you use this flag, +<parameter>standard_input</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_FILE_AND_ARGV_ZERO</literal> +means that the first element of <parameter>argv</parameter> is the file to +execute, while the remaining elements are the actual argument vector to pass +to the file. Normally the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function uses <parameter>argv</parameter>[0] as the file to execute, and +passes all of <parameter>argv</parameter> to the child.</para> + + <para><parameter>child_setup</parameter> and +<parameter>user_data</parameter> are a function and user data. On POSIX +platforms, the function is called in the child after GLib has performed all +the setup it plans to perform (including creating pipes, closing file +descriptors, etc.) but before calling <function>exec</function>(). That is, +<parameter>child_setup</parameter> is called just before calling +<function>exec</function>() in the child. Obviously actions taken in this +function will only affect the child, not the parent. On Windows, there is no +separate <function>fork</function>() and <function>exec</function>() +functionality. Child processes are created and run right away with one API +call, +<function>CreateProcess</function>(). <parameter>child_setup</parameter> is +called in the parent process just before creating the child process. You +should carefully consider what you do in <parameter>child_setup</parameter> +if you intend your software to be portable to Windows.</para> + + <para>The returned child process id can be used to send signals to the +child, or to wait for the child if you specified the +<literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child +pid will be returned only if you specified the +<literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para> + + <para>The caller of the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +must close any returned file descriptors when they are no longer in +use.</para> + + <para>If <parameter>standard_input</parameter> is +<literal>None</literal>, the child's standard input is attached to +<filename>/dev/null</filename> unless +<literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para> + + <para>If <parameter>standard_error</parameter> is +<literal>None</literal>, the child's standard error goes to the same +location as the parent's standard error unless +<literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para> + + <para>If <parameter>standard_output</parameter> is +<literal>None</literal>, the child's standard output goes to the same +location as the parent's standard output unless +<literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para> + + <para>If an error occurs, the glib.GError exception will be +raised.</para> + + </refsect2> + + <refsect2 id="function-glib--get-current-time"> + <title>glib.get_current_time</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_current_time</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current time as the number of seconds and +microseconds from the epoch.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>glib.get_current_time</function>() function +reurns the current time of day as the number of seconds and microseconds +from the epoch.</para> + + </refsect2> + + <refsect2 id="function-glib--main-depth"> + <title>glib.main_depth</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.main_depth</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the depth of the stack of calls to the main +context.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>main_depth</function>() function returns the depth +of the stack of calls in the main context. That is, when called from the +toplevel, it gives 0. When called from within a callback from the <link +linkend="method-glibmaincontext--iteration"><methodname>glib.MainContext.iteration</methodname>()</link> +method (or the <link +linkend="method-glibmainloop--run"><methodname>glib.MainLoop.run</methodname>()</link> +method, etc.) it returns 1. When called from within a callback to a +recursive call to the <link +linkend="method-glibmaincontext--iteration"><methodname>glib.MainContext.iteration</methodname>()</link> +method), it returns 2. And so forth.</para> + + </refsect2> + + <refsect2 id="function-glib--threads-init"> + <title>glib.threads_init</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.threads_init</methodname> + <methodparam><parameter></parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara></simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.4 and above.</para> + </note> + + <para>The <function>threads_init</function>() function initializes the + the use of Python threading in the glib module. This function is + different than the <link + linkend="function-gdk--threads-init"><function>gtk.gdk.threads_init</function>()</link> + function as that function also initializes the gdk threads.</para> + + </refsect2> + + <refsect2 id="function-glib--signal-accumulator-true-handled"> + <title>glib.signal_accumulator_true_handled</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.signal_accumulator_true_handled</methodname> + </methodsynopsis></programlisting> + + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>signal_accumulator_true_handled</function>() + function is only used as accumulator argument when registering + signals.</para> + + </refsect2> + + <refsect2 id="function-glib--filename-display-name"> + <title>glib.filename_display_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_display_name</methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>filename</emphasis> :</term> + <listitem><simpara>a pathname in the file name + encoding</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an UTF8 rendition of + <parameter>filename</parameter>.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.10 and above.</para> + </note> + + <para>The <function>filename_display_name</function>() function + converts a filename into a valid UTF-8 string. The conversion is not + necessarily reversible, so you should keep the original around and use + the return value of this function only for display purposes. Unlike + g_filename_to_utf8(), the result is guaranteed to be non-None even if + the filename actually isn't in the file name encoding.</para> + + <para>If you know the whole pathname of the file you should use the + <link + linkend="function-glib--filename-display-basename"><function>glib.filename_display_basename</function>()</link> + function, since that allows location-based translation of + filenames.</para> + + </refsect2> + + <refsect2 id="function-glib--filename-display-basename"> + <title>glib.filename_display_basename</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_display_basename</methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>filename</emphasis> :</term> + <listitem><simpara>an absolute pathname in the file name + encoding</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an UTF8 rendition of + <parameter>filename</parameter>.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.10 and above.</para> + </note> + + <para>The <function>filename_display_basename</function>() function + returns the display basename for the particular filename, guaranteed + to be valid UTF-8. The display name might not be identical to the + filename, for instance there might be problems converting it to UTF-8, + and some files can be translated in the display.</para> + + <para>You must pass the whole absolute pathname to this functions so + that translation of well known locations can be done.</para> + + <para>This function is preferred over the <link + linkend="function-glib--filename-display-name"><function>glib.filename_display_name</function>()</link> + function if you know the whole path, as it allows translation.</para> + + </refsect2> + + <refsect2 id="function-glib--filename-from-utf8"> + <title>glib.filename_from_utf8</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_from_utf8</methodname> + <methodparam><parameter>utf8string</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>utf8string</emphasis> :</term> + <listitem><simpara>a UTF-8 encoded string.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a filename encoded in the GLib filename + encoding.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.10 and above.</para> + </note> + + <para>The <function>filename_from_utf8</function>() function converts + a string from UTF-8 to the encoding GLib uses for filenames. Note that + on Windows GLib uses UTF-8 for filenames.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-maincontext.xml b/docs/reference/pyglib-maincontext.xml index 129197a..ccb91bb 100644 --- a/docs/reference/pygobject-maincontext.xml +++ b/docs/reference/pyglib-maincontext.xml @@ -2,29 +2,29 @@ <!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-gobjectmaincontext"> +<refentry id="class-glibmaincontext"> <refnamediv> - <refname>gobject.MainContext</refname> + <refname>glib.MainContext</refname> <refpurpose>an object representing a set of event sources to be handled in a <link -linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>.</refpurpose> +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>.</refpurpose> </refnamediv> <refsect1> <title>Synopsis</title> <classsynopsis language="python"> - <ooclass><classname>gobject.MainContext</classname></ooclass> + <ooclass><classname>glib.MainContext</classname></ooclass> <constructorsynopsis language="python"> - <methodname><link linkend="constructor-gobjectmaincontext">gobject.MainContext</link></methodname> + <methodname><link linkend="constructor-glibmaincontext">glib.MainContext</link></methodname> </constructorsynopsis> <methodsynopsis language="python"> - <methodname><link linkend="method-gobjectmaincontext--iteration">iteration</link></methodname> + <methodname><link linkend="method-glibmaincontext--iteration">iteration</link></methodname> <methodparam><parameter>may_block</parameter></methodparam> </methodsynopsis> <methodsynopsis language="python"> - <methodname><link linkend="method-gobjectmaincontext--pending">pending</link></methodname> + <methodname><link linkend="method-glibmaincontext--pending">pending</link></methodname> </methodsynopsis> </classsynopsis> @@ -33,7 +33,7 @@ linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>.< <refsect1> <title>Ancestry</title> -<synopsis>+-- <link linkend="class-gobjectmaincontext">gobject.MainContext</link> +<synopsis>+-- <link linkend="class-glibmaincontext">glib.MainContext</link> </synopsis> </refsect1> @@ -42,39 +42,39 @@ linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link>.< <title>Description</title> <para>A <link -linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> represents a set of event sources that can be run in a single thread. File descriptors (plain files, pipes or sockets) and timeouts are the standard event sources for <literal>GTK</literal> and <literal>PyGTK</literal> though others can be added. Each event source is assigned a priority. The default -priority, <literal>gobject.PRIORITY_DEFAULT</literal>, is 0. Values less +priority, <literal>glib.PRIORITY_DEFAULT</literal>, is 0. Values less than 0 denote higher priorities. Values greater than 0 denote lower priorities. Events from high priority sources are always processed before events from lower priority sources. Single iterations of a <link -linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> can be run with the <link -linkend="method-gobjectmaincontext--iteration"><methodname>iteration</methodname>()</link> +linkend="method-glibmaincontext--iteration"><methodname>iteration</methodname>()</link> method.</para> </refsect1> - <refsect1 id="constructor-gobjectmaincontext"> + <refsect1 id="constructor-glibmaincontext"> <title>Constructor</title> <programlisting><constructorsynopsis language="python"> - <methodname>gobject.MainContext</methodname> + <methodname>glib.MainContext</methodname> </constructorsynopsis></programlisting> <variablelist> <varlistentry> <term><emphasis>Returns</emphasis> :</term> <listitem><simpara>a new <link - linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> object.</simpara></listitem> </varlistentry> </variablelist> <para>Creates a new <link -linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> object.</para> </refsect1> @@ -82,8 +82,8 @@ object.</para> <refsect1> <title>Methods</title> - <refsect2 id="method-gobjectmaincontext--iteration"> - <title>gobject.MainContext.iteration</title> + <refsect2 id="method-glibmaincontext--iteration"> + <title>glib.MainContext.iteration</title> <programlisting><methodsynopsis language="python"> <methodname>iteration</methodname> @@ -128,8 +128,8 @@ becoming ready.</para> </refsect2> - <refsect2 id="method-gobjectmaincontext--pending"> - <title>gobject.MainContext.pending</title> + <refsect2 id="method-glibmaincontext--pending"> + <title>glib.MainContext.pending</title> <programlisting><methodsynopsis language="python"> <methodname>pending</methodname> diff --git a/docs/reference/pygobject-mainloop.xml b/docs/reference/pyglib-mainloop.xml index d90f534..bd12fca 100644 --- a/docs/reference/pygobject-mainloop.xml +++ b/docs/reference/pyglib-mainloop.xml @@ -2,9 +2,9 @@ <!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"> +<refentry id="class-glibmainloop"> <refnamediv> - <refname>gobject.MainLoop</refname> + <refname>glib.MainLoop</refname> <refpurpose>an object representing the main event loop of a PyGTK application.</refpurpose> @@ -14,23 +14,23 @@ <title>Synopsis</title> <classsynopsis language="python"> - <ooclass><classname>gobject.MainLoop</classname></ooclass> + <ooclass><classname>glib.MainLoop</classname></ooclass> <constructorsynopsis language="python"> - <methodname><link linkend="constructor-gobjectmainloop">gobject.MainLoop</link></methodname> + <methodname><link linkend="constructor-glibmainloop">glib.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> + <methodname><link linkend="method-glibmainloop--get-context">get_context</link></methodname> </methodsynopsis> <methodsynopsis language="python"> - <methodname><link linkend="method-gobjectmainloop--is-running">is_running</link></methodname> + <methodname><link linkend="method-glibmainloop--is-running">is_running</link></methodname> </methodsynopsis> <methodsynopsis language="python"> - <methodname><link linkend="method-gobjectmainloop--quit">quit</link></methodname> + <methodname><link linkend="method-glibmainloop--quit">quit</link></methodname> </methodsynopsis> <methodsynopsis language="python"> - <methodname><link linkend="method-gobjectmainloop--run">run</link></methodname> + <methodname><link linkend="method-glibmainloop--run">run</link></methodname> </methodsynopsis> </classsynopsis> @@ -39,7 +39,7 @@ <refsect1> <title>Ancestry</title> -<synopsis>+-- <link linkend="class-gobjectmainloop">gobject.MainLoop</link> +<synopsis>+-- <link linkend="class-glibmainloop">glib.MainLoop</link> </synopsis> </refsect1> @@ -48,30 +48,30 @@ <title>Description</title> <para><link -linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> represents a main event loop. A <link -linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> is created with the <link -linkend="constructor-gobjectmainloop">gobject.MainLoop</link>() +linkend="constructor-glibmainloop">glib.MainLoop</link>() constructor. After adding the initial event sources, the <link -linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +linkend="method-glibmainloop--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> +linkend="method-glibmainloop--quit"><methodname>quit</methodname>()</link> method to exit the main loop, and the <link -linkend="method-gobjectmainloop--run"><methodname>run</methodname>()</link> +linkend="method-glibmainloop--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> +linkend="class-glibmainloop"><classname>glib.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>, +linkend="class-glibmaincontext"><classname>glib.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> +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>.</para> <para><literal>PyGTK</literal> contains wrappers of some of these functions, e.g. the <link @@ -83,11 +83,11 @@ functions.</para> </refsect1> - <refsect1 id="constructor-gobjectmainloop"> + <refsect1 id="constructor-glibmainloop"> <title>Constructor</title> <programlisting><constructorsynopsis language="python"> - <methodname>gobject.MainLoop</methodname> + <methodname>glib.MainLoop</methodname> <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam> <methodparam><parameter>is_running</parameter><initializer>None</initializer></methodparam> </constructorsynopsis></programlisting> @@ -95,7 +95,7 @@ functions.</para> <varlistentry> <term><parameter>context</parameter> :</term> <listitem><simpara>a <link - linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> or <literal>None</literal> to use the default context.</simpara></listitem> </varlistentry> @@ -103,20 +103,20 @@ functions.</para> <term><parameter>is_running</parameter> :</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> + linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> method will set this to <literal>TRUE</literal> anyway.</simpara></listitem> </varlistentry> <varlistentry> <term><emphasis>Returns</emphasis> :</term> <listitem><simpara>a new <link - linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> + linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> object.</simpara></listitem> </varlistentry> </variablelist> <para>Creates a new <link -linkend="class-gobjectmainloop"><classname>gobject.MainLoop</classname></link> +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> object.</para> </refsect1> @@ -124,8 +124,8 @@ object.</para> <refsect1> <title>Methods</title> - <refsect2 id="method-gobjectmainloop--get-context"> - <title>gobject.MainLoop.get_context</title> + <refsect2 id="method-glibmainloop--get-context"> + <title>glib.MainLoop.get_context</title> <programlisting><methodsynopsis language="python"> <methodname>get_context</methodname> @@ -134,20 +134,20 @@ object.</para> <varlistentry> <term><emphasis>Returns</emphasis> :</term> <listitem><simpara>the <link - linkend="class-gobjectmaincontext"><classname>gobject.MainContext</classname></link> + linkend="class-glibmaincontext"><classname>glib.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> +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> that the mainloop was created with.</para> </refsect2> - <refsect2 id="method-gobjectmainloop--is-running"> - <title>gobject.MainLoop.is_running</title> + <refsect2 id="method-glibmainloop--is-running"> + <title>glib.MainLoop.is_running</title> <programlisting><methodsynopsis language="python"> <methodname>is_running</methodname> @@ -162,13 +162,13 @@ that the mainloop was created with.</para> <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> +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> method.</para> </refsect2> - <refsect2 id="method-gobjectmainloop--quit"> - <title>gobject.MainLoop.quit</title> + <refsect2 id="method-glibmainloop--quit"> + <title>glib.MainLoop.quit</title> <programlisting><methodsynopsis language="python"> <methodname>quit</methodname> @@ -176,13 +176,13 @@ method.</para> <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> +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> method will return immediately.</para> </refsect2> - <refsect2 id="method-gobjectmainloop--run"> - <title>gobject.MainLoop.run</title> + <refsect2 id="method-glibmainloop--run"> + <title>glib.MainLoop.run</title> <programlisting><methodsynopsis language="python"> <methodname>run</methodname> @@ -190,9 +190,9 @@ method will return immediately.</para> <para>The <methodname>run</methodname>() method runs a mainloop until the <link -linkend="method-gobjectmainloop--quit"><methodname>quit</methodname>()</link> +linkend="method-glibmainloop--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>, +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>, it will process events from the loop, otherwise it will simply wait.</para> </refsect2> diff --git a/docs/reference/pygobject-classes.xml b/docs/reference/pygobject-classes.xml index e4b488f..710e4b7 100644 --- a/docs/reference/pygobject-classes.xml +++ b/docs/reference/pygobject-classes.xml @@ -4,16 +4,19 @@ <chapter id="gobject-class-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> -<title>The gobject Class Reference</title> +<title>PyGObject Class Reference</title> -<!-- GOBJECT CLASSES --> +<!-- GLIB CLASSES --> +<xi:include href="pyglib-maincontext.xml"/> +<xi:include href="pyglib-mainloop.xml"/> +<xi:include href="pyglib-functions.xml"/> +<xi:include href="pyglib-constants.xml"/> +<!-- GOBJECT CLASSES --> <xi:include href="pygobject.xml"/> <xi:include href="pygobject-gboxed.xml"/> <xi:include href="pygobject-gpointer.xml"/> <xi:include href="pygobject-ginterface.xml"/> -<xi:include href="pygobject-maincontext.xml"/> -<xi:include href="pygobject-mainloop.xml"/> <xi:include href="pygobject-functions.xml"/> <xi:include href="pygobject-constants.xml"/> diff --git a/docs/reference/pygobject-constants.xml b/docs/reference/pygobject-constants.xml index 894c8ae..a8f9711 100644 --- a/docs/reference/pygobject-constants.xml +++ b/docs/reference/pygobject-constants.xml @@ -12,11 +12,8 @@ <title>Synopsis</title> <programlisting> -<xref linkend="gobject-io-condition-constants" endterm="gobject-io-condition-constants-title"></xref> <xref linkend="gobject-param-constants" endterm="gobject-param-constants-title"></xref> -<xref linkend="gobject-priority-constants" endterm="gobject-priority-constants-title"></xref> <xref linkend="gobject-signal-constants" endterm="gobject-signal-constants-title"></xref> -<xref linkend="gobject-spawn-flag-constants" endterm="gobject-spawn-flag-constants-title"></xref> <xref linkend="gobject-type-constants" endterm="gobject-type-constants-title"></xref> <xref linkend="gobject-version-constants" endterm="gobject-version-constants-title"></xref> </programlisting> @@ -26,55 +23,6 @@ <refsect1 id="gobject-constants-description"> <title>Description</title> - <refsect2 id="gobject-io-condition-constants"> - <title id="gobject-io-condition-constants-title">GObject IO Condition Constants</title> - - <para>The IO Condition constants are a set of bit-flags that specify a -condition to watch for on an event source.</para> - - <variablelist> - <varlistentry> - <term><literal>gobject.IO_IN</literal></term> - <listitem> - <simpara>There is data to read</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_OUT</literal></term> - <listitem> - <simpara>Data can be written (without blocking).</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_PRI</literal></term> - <listitem> - <simpara>There is urgent data to read.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_ERR</literal></term> - <listitem> - <simpara>Error condition.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_HUP</literal></term> - <listitem> - <simpara>Hung up (the connection has been broken, usually for - pipes and sockets).</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_NVAL</literal></term> - <listitem> - <simpara>Invalid request. The file descriptor is not - open.</simpara> - </listitem> - </varlistentry> - </variablelist> - - </refsect2> - <refsect2 id="gobject-param-constants"> <title id="gobject-param-constants-title">GObject Param Flag Constants</title> @@ -119,59 +67,6 @@ certain aspects of parameters that can be configured.</para> </refsect2> - <refsect2 id="gobject-priority-constants"> - <title id="gobject-priority-constants-title">GObject Priority Constants</title> - - <para>The Priority constants specify </para> - - <variablelist> - <varlistentry> - <term><literal>gobject.PRIORITY_HIGH</literal></term> - <listitem> - <simpara>Use this for high priority event sources.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.PRIORITY_DEFAULT</literal></term> - <listitem> - <simpara>Use this for default priority event sources. This - priority is used when adding timeout functions with the <link - linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function>()</link> - function. This priority is also used for events from the X - server.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.PRIORITY_HIGH_IDLE</literal></term> - <listitem> - <simpara>Use this for high priority idle functions. For example, - gobject.PRIORITY_HIGH_IDLE + 10 is used for resizing operations; - and, gobject.PRIORITY_HIGH_IDLE + 20, for redrawing - operations. (This is done to ensure that any pending resizes are - processed before any pending redraws, so that widgets are not - redrawn twice unnecessarily.)</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.PRIORITY_DEFAULT_IDLE</literal></term> - <listitem> - <simpara>Use this for default priority idle functions. This - priority is used when adding idle functions with the <link - linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link> - function.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.PRIORITY_LOW</literal></term> - <listitem> - <simpara>Use this for very low priority background - tasks.</simpara> - </listitem> - </varlistentry> - </variablelist> - - </refsect2> - <refsect2 id="gobject-signal-constants"> <title id="gobject-signal-constants-title">GObject Signal Flag Constants</title> diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml index c0c6234..a35afec 100644 --- a/docs/reference/pygobject-functions.xml +++ b/docs/reference/pygobject-functions.xml @@ -86,63 +86,6 @@ linkend="function-gobject--new">gobject.new</link></methodname> <methodparam><parameter>...</parameter></methodparam> </methodsynopsis><methodsynopsis language="python"> <methodname><link -linkend="function-gobject--idle-add">gobject.idle_add</link></methodname> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--timeout-add">gobject.timeout_add</link></methodname> - <methodparam><parameter>interval</parameter></methodparam> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--io-add-watch">gobject.io_add_watch</link></methodname> - <methodparam><parameter>fd</parameter></methodparam> - <methodparam><parameter>condition</parameter></methodparam> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--source-remove">gobject.source_remove</link></methodname> - <methodparam><parameter>tag</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--main-context-default">gobject.main_context_default</link></methodname> - <methodparam></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--markup-escape-text">gobject.markup_escape_text</link></methodname> - <methodparam><parameter role="keyword">text</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link linkend="function-gobject--child-watch-add">gobject.child_watch_add</link></methodname> - <methodparam><parameter role="keyword">pid</parameter></methodparam> - <methodparam><parameter role="keyword">function</parameter></methodparam> - <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--spawn-async">gobject.spawn_async</link></methodname> - <methodparam><parameter role="keyword">argv</parameter></methodparam> - <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> - <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--get-current-time">gobject.get_current_time</link></methodname> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--main-depth">gobject.main_depth</link></methodname> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--threads-init">gobject.threads_init</link></methodname> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link linkend="function-gobject--signal-accumulator-true-handled">gobject.signal_accumulator_true_handled</link></methodname> </methodsynopsis><methodsynopsis language="python"> <methodname><link @@ -161,19 +104,8 @@ linkend="function-gobject--remove-emission-hook">gobject.remove_emission_hook</l <methodname><link linkend="function-gobject---install-metaclass">gobject._install_metaclass</link></methodname> <methodparam><parameter>metaclass</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--filename-display-name">gobject.filename_display_name</link></methodname> - <methodparam><parameter>filename</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--filename-display-basename">gobject.filename_display_basename</link></methodname> - <methodparam><parameter>filename</parameter></methodparam> - </methodsynopsis><methodsynopsis language="python"> - <methodname><link -linkend="function-gobject--filename-from-utf8">gobject.filename_from_utf8</link></methodname> - <methodparam><parameter>utf8string</parameter></methodparam> - </methodsynopsis></programlisting> + </methodsynopsis> + </programlisting> </refsect1> @@ -816,593 +748,6 @@ properties.</para> </refsect2> - <refsect2 id="function-gobject--idle-add"> - <title>gobject.idle_add</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.idle_add</methodname> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>callback</parameter> :</term> - <listitem><simpara>a function to call when -<literal>PyGTK</literal> is idle</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>...</parameter> :</term> - <listitem><simpara>optionals arguments to be passed to -<parameter>callback</parameter></simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>an integer ID</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <function>gobject.idle_add</function>() function adds a -function (specified by <parameter>callback</parameter>) to be called -whenever there are no higher priority events pending to the default main -loop. The function is given the default idle priority, -<literal>gobject.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to -pass to <parameter>callback</parameter> can be specified after -<parameter>callback</parameter>. The idle priority can be specified as a -keyword-value pair with the keyword "priority". If -<parameter>callback</parameter> returns <literal>FALSE</literal> it is -automatically removed from the list of event sources and will not be called -again.</para> - - </refsect2> - - <refsect2 id="function-gobject--timeout-add"> - <title>gobject.timeout_add</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.timeout_add</methodname> - <methodparam><parameter>interval</parameter></methodparam> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>interval</parameter> :</term> - <listitem><simpara>the time between calls to the function, in -milliseconds </simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>callback</parameter> :</term> - <listitem><simpara>the function to call</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>...</parameter> :</term> - <listitem><simpara>zero or more arguments that will be passed to -<parameter>callback</parameter></simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>an integer ID of the event -source</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <function>gobject.timeout_add</function>() function sets a -function (specified by <parameter>callback</parameter>) to be called at -regular intervals (specified by <parameter>interval</parameter>, with the -default priority, <literal>gobject.PRIORITY_DEFAULT</literal>. Additional -arguments to pass to <parameter>callback</parameter> can be specified after -<parameter>callback</parameter>. The idle priority may be specified as a -keyword-value pair with the keyword "priority".</para> - - <para>The function is called repeatedly until it returns -<literal>FALSE</literal>, at which point the timeout is automatically -destroyed and the function will not be called again. The first call to the -function will be at the end of the first interval. Note that timeout -functions may be delayed, due to the processing of other event sources. Thus -they should not be relied on for precise timing. After each call to the -timeout function, the time of the next timeout is recalculated based on the -current time and the given interval (it does not try to 'catch up' time lost -in delays).</para> - - </refsect2> - - <refsect2 id="function-gobject--io-add-watch"> - <title>gobject.io_add_watch</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.io_add_watch</methodname> - <methodparam><parameter>fd</parameter></methodparam> - <methodparam><parameter>condition</parameter></methodparam> - <methodparam><parameter>callback</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter> :</term> - <listitem><simpara>a Python file object or an integer file -descriptor ID</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>condition</parameter> :</term> - <listitem><simpara>a condition mask</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>callback</parameter> :</term> - <listitem><simpara>a function to call</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>...</parameter> :</term> - <listitem><simpara>additional arguments to pass to -<parameter>callback</parameter></simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>an integer ID of the event source</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <function>gobject.io_add_watch</function>() function -arranges for the file (specified by <parameter>fd</parameter>) to be -monitored by the main loop for the specified -<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python -file object or an integer file descriptor. The value of condition is a -combination of:</para> - - <variablelist> - <varlistentry> - <term><literal>gobject.IO_IN</literal></term> - <listitem> - <simpara>There is data to read.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_OUT</literal></term> - <listitem> - <simpara>Data can be written (without blocking). </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_PRI</literal></term> - <listitem> - <simpara>There is urgent data to read.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_ERR</literal></term> - <listitem> - <simpara>Error condition.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gobject.IO_HUP</literal></term> - <listitem> - <simpara>Hung up (the connection has been broken, usually for -pipes and sockets).</simpara> - </listitem> - </varlistentry> - </variablelist> - - <para>Additional arguments to pass to <parameter>callback</parameter> -can be specified after <parameter>callback</parameter>. The idle priority -may be specified as a keyword-value pair with the keyword "priority". The -signature of the callback function is:</para> - - <programlisting> - def callback(source, cb_condition, ...) -</programlisting> - - <para>where <parameter>source</parameter> is -<parameter>fd</parameter>, the file descriptor; -<parameter>cb_condition</parameter> is the condition that triggered the -signal; and, <parameter>...</parameter> are the zero or more arguments that -were passed to the <function>gobject.io_add_watch</function>() -function.</para> - - <para>If the callback function returns <literal>FALSE</literal> it -will be automatically removed from the list of event sources and will not be -called again. If it returns <literal>TRUE</literal> it will be called again -when the condition is matched.</para> - - </refsect2> - - <refsect2 id="function-gobject--source-remove"> - <title>gobject.source_remove</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.source_remove</methodname> - <methodparam><parameter>tag</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>tag</parameter> :</term> - <listitem><simpara>an integer ID</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the event source was -removed</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <function>gobject.source_remove</function>() function -removes the event source specified by tag (as returned by the <link -linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link>, -<link -linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function></link>() -and <link -linkend="function-gobject--io-add-watch"><function>gobject.io_add_watch</function>()</link> -functions)</para> - - </refsect2> - - <refsect2 id="function-gobject--main-context-default"> - <title>gobject.main_context_default</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.main_context_default</methodname> - <methodparam></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>the default gobject.MainContext -object</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <function>gobject.main_context_default</function>() function -returns the default gobject.MainContext object.</para> - - </refsect2> - - <refsect2 id="function-gobject--markup-escape-text"> - <title>gobject.markup_escape_text</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.markup_escape_text</methodname> - <methodparam><parameter>text</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>text</parameter> :</term> - <listitem><simpara>the UTF-8 string to be -escaped</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>the escaped text</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This function is available in PyGTK 2.8 and above.</para> - </note> - - <para>The <function>gobject.markup_escape_text</function>() function -escapes the string specified by <parameter>text</parameter> so that the -markup parser will parse it verbatim. Less than, greater than, ampersand, -etc. are replaced with the corresponding entities. This function would -typically be used when writing out a file to be parsed with the markup -parser.</para> - - <para>Note that this function doesn't protect whitespace and line -endings from being processed according to the XML rules for normalization of -line endings and attribute values.</para> - - </refsect2> - - <refsect2 id="function-gobject--child-watch-add"> - <title>gobject.child_watch_add</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.child_watch_add</methodname> - <methodparam><parameter role="keyword">pid</parameter></methodparam> - <methodparam><parameter role="keyword">function</parameter></methodparam> - <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><parameter role="keyword">pid</parameter> :</term> - <listitem><simpara>process id of a child process to watch</simpara></listitem> - </varlistentry> - <varlistentry><term><parameter role="keyword">function</parameter> :</term> - <listitem><simpara>the function to call</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">data</parameter> :</term> - <listitem><simpara>the optional data to pass to -<parameter>function</parameter></simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">priority</parameter> :</term> - <listitem><simpara>the priority of the idle source - one of the -<xref linkend="gobject-priority-constants" -endterm="gobject-priority-constants-title"></xref></simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>the id of event source.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.6 and above.</para> - </note> - - <para>The <function>gobject.child_watch_add</function>() function sets -the function specified by <parameter>function</parameter> to be called with -the user data specified by <parameter>data</parameter> when the child -indicated by <parameter>pid</parameter> exits. The signature for the -callback is:</para> - - <programlisting> -def callback(pid, condition, user_data) -</programlisting> - - <para>where <parameter>pid</parameter> is is the child process id, -<parameter>condition</parameter> is the status information about the child -process and <parameter>user_data</parameter> is <parameter>data</parameter> -PyGTK supports only a single callback per process id.</para> - - </refsect2> - - <refsect2 id="function-gobject--spawn-async"> - <title>gobject.spawn_async</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.spawn_async</methodname> - <methodparam><parameter role="keyword">argv</parameter></methodparam> - <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> - <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> - <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><parameter role="keyword">argv</parameter> :</term> - <listitem><simpara>a sequence of strings containing the arguments -of the child process</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">envp</parameter> :</term> - <listitem><simpara>the child's environment or -<literal>None</literal> to inherit the parent's -environment.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">working_directory</parameter> :</term> - <listitem><simpara>the child's current working directory, or -<literal>None</literal> to inherit parent's</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">flags</parameter> :</term> - <listitem><simpara>flags from the <xref -linkend="gobject-spawn-flag-constants" -endterm="gobject-spawn-flag-constants-title"></xref>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">child_setup</parameter> :</term> - <listitem><simpara>a function to run in the child just before -calling <function>exec</function>()</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">user_data</parameter> :</term> - <listitem><simpara>the user data for the -<parameter>child_setup</parameter> function</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">standard_input</parameter> :</term> - <listitem><simpara>if <literal>TRUE</literal> return the file -descriptor for the child's stdin</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">standard_output</parameter> :</term> - <listitem><simpara>if <literal>TRUE</literal> return the file -descriptor for the child's stdout</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">standard_error</parameter> :</term> - <listitem><simpara>if <literal>TRUE</literal> return the file -descriptor for the child's stderr</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>a 4-tuple containing the child's process id and -the stdin, stdout and stderr file descriptor integers.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.6 and above.</para> - </note> - - <para>The <function>gobject.spawn_async</function>() function executes -a child program asynchronously (your program will not block waiting for the -child to exit). The child program is specified by the only argument that -must be provided, <parameter>argv</parameter>. <parameter>argv</parameter> -should be a sequence of strings, to be passed as the argument vector for the -child. The first string in <parameter>argv</parameter> is of course the name -of the program to execute. By default, the name of the program must be a -full path; the <envar>PATH</envar> shell variable will only be searched if -you pass the <literal>gobject.SPAWN_SEARCH_PATH</literal> flag in -<parameter>flags</parameter>. The function returns a 4-tuple containing the -child's process id and the file descriptors for the child's stdin, stdout -and stderr. The stdin, stdout and stderr file descriptors are returned only -ofthe corresponding <parameter>standard_input</parameter>, -<parameter>standard_output</parameter> or -<parameter>standard_error</parameter> params are -<literal>TRUE</literal>.</para> - - <para>On Windows, the low-level child process creation API -(<function>CreateProcess</function>()) doesn't use argument vectors, but a -command line. The C runtime library's <function>spawn*</function>() family -of functions (which <link -linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> -eventually calls) paste the argument vector elements into a command line, -and the C runtime startup code does a corresponding reconstruction of an -argument vector from the command line, to be passed to -<function>main</function>(). Complications arise when you have argument -vector elements that contain spaces of double quotes. The -<function>spawn*</function>() functions don't do any quoting or escaping, -but on the other hand the startup code does do unquoting and unescaping in -order to enable receiving arguments with embedded spaces or double -quotes. To work around this asymmetry, the <link -linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> -function will do quoting and escaping on argument vector elements that need -it before calling the C runtime <function>spawn</function>() -function.</para> - - <para><parameter>envp</parameter> is a sequence of strings, where each - string has the form <literal>KEY=VALUE</literal>. This will become the - child's environment. If <parameter>envp</parameter> is - <parameter>None</parameter> or not specified, the child inherits its - parent's environment.</para> - - <para><parameter>flags</parameter> should be the bitwise -<literal>OR</literal> of the <xref linkend="gobject-spawn-flag-constants" -endterm="gobject-spawn-flag-constants-title"></xref> you want to affect the -function's behaviour. The <literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> -flag means that the child will not automatically be reaped; you must use a -GChildWatch source to be notified about the death of the child -process. Eventually you must call g_spawn_close_pid() on the child_pid, in -order to free resources which may be associated with the child process. (On -Unix, using a GChildWatch source is equivalent to calling -<function>waitpid</function>() or handling the <literal>SIGCHLD</literal> -signal manually. On Windows, calling g_spawn_close_pid() is equivalent to -calling <function>CloseHandle</function>() on the process handle -returned).</para> - - <para><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means -that the parent's open file descriptors will be inherited by the child; -otherwise all descriptors except stdin/stdout/stderr will be closed before -calling <function>exec</function>() in the -child. <literal>gobject.SPAWN_SEARCH_PATH</literal> means that -<parameter>argv</parameter>[0] need not be an absolute path, it will be -looked for in the user's -<envar>PATH</envar>. <literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> -means that the child's standard output will be discarded, instead of going -to the same location as the parent's standard output. If you use this flag, -<parameter>standard_output</parameter> must be -<literal>None</literal>. <literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> -means that the child's standard error will be discarded, instead of going to -the same location as the parent's standard error. If you use this flag, -<parameter>standard_error</parameter> must be -<literal>None</literal>. <literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> -means that the child will inherit the parent's standard input (by default, -the child's standard input is attached to -<filename>/dev/null</filename>). If you use this flag, -<parameter>standard_input</parameter> must be -<literal>None</literal>. <literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal> -means that the first element of <parameter>argv</parameter> is the file to -execute, while the remaining elements are the actual argument vector to pass -to the file. Normally the <link -linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> -function uses <parameter>argv</parameter>[0] as the file to execute, and -passes all of <parameter>argv</parameter> to the child.</para> - - <para><parameter>child_setup</parameter> and -<parameter>user_data</parameter> are a function and user data. On POSIX -platforms, the function is called in the child after GLib has performed all -the setup it plans to perform (including creating pipes, closing file -descriptors, etc.) but before calling <function>exec</function>(). That is, -<parameter>child_setup</parameter> is called just before calling -<function>exec</function>() in the child. Obviously actions taken in this -function will only affect the child, not the parent. On Windows, there is no -separate <function>fork</function>() and <function>exec</function>() -functionality. Child processes are created and run right away with one API -call, -<function>CreateProcess</function>(). <parameter>child_setup</parameter> is -called in the parent process just before creating the child process. You -should carefully consider what you do in <parameter>child_setup</parameter> -if you intend your software to be portable to Windows.</para> - - <para>The returned child process id can be used to send signals to the -child, or to wait for the child if you specified the -<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child -pid will be returned only if you specified the -<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para> - - <para>The caller of the <link -linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> -must close any returned file descriptors when they are no longer in -use.</para> - - <para>If <parameter>standard_input</parameter> is -<literal>None</literal>, the child's standard input is attached to -<filename>/dev/null</filename> unless -<literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para> - - <para>If <parameter>standard_error</parameter> is -<literal>None</literal>, the child's standard error goes to the same -location as the parent's standard error unless -<literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para> - - <para>If <parameter>standard_output</parameter> is -<literal>None</literal>, the child's standard output goes to the same -location as the parent's standard output unless -<literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para> - - <para>If an error occurs, the gobject.GError exception will be -raised.</para> - - </refsect2> - - <refsect2 id="function-gobject--get-current-time"> - <title>gobject.get_current_time</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.get_current_time</methodname> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>the current time as the number of seconds and -microseconds from the epoch.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.8 and above.</para> - </note> - - <para>The <function>gobject.get_current_time</function>() function -reurns the current time of day as the number of seconds and microseconds -from the epoch.</para> - - </refsect2> - - <refsect2 id="function-gobject--main-depth"> - <title>gobject.main_depth</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.main_depth</methodname> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>the depth of the stack of calls to the main -context.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.8 and above.</para> - </note> - - <para>The <function>main_depth</function>() function returns the depth -of the stack of calls in the main context. That is, when called from the -toplevel, it gives 0. When called from within a callback from the <link -linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link> -method (or the <link -linkend="method-gobjectmainloop--run"><methodname>gobject.MainLoop.run</methodname>()</link> -method, etc.) it returns 1. When called from within a callback to a -recursive call to the <link -linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link> -method), it returns 2. And so forth.</para> - - </refsect2> - <refsect2 id="function-gobject--threads-init"> <title>gobject.threads_init</title> @@ -1554,110 +899,6 @@ method), it returns 2. And so forth.</para> </refsect2> - <refsect2 id="function-gobject--filename-display-name"> - <title>gobject.filename_display_name</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.filename_display_name</methodname> - <methodparam><parameter>filename</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><emphasis>filename</emphasis> :</term> - <listitem><simpara>a pathname in the file name - encoding</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>an UTF8 rendition of - <parameter>filename</parameter>.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.10 and above.</para> - </note> - - <para>The <function>filename_display_name</function>() function - converts a filename into a valid UTF-8 string. The conversion is not - necessarily reversible, so you should keep the original around and use - the return value of this function only for display purposes. Unlike - g_filename_to_utf8(), the result is guaranteed to be non-None even if - the filename actually isn't in the file name encoding.</para> - - <para>If you know the whole pathname of the file you should use the - <link - linkend="function-gobject--filename-display-basename"><function>gobject.filename_display_basename</function>()</link> - function, since that allows location-based translation of - filenames.</para> - - </refsect2> - - <refsect2 id="function-gobject--filename-display-basename"> - <title>gobject.filename_display_basename</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.filename_display_basename</methodname> - <methodparam><parameter>filename</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><emphasis>filename</emphasis> :</term> - <listitem><simpara>an absolute pathname in the file name - encoding</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>an UTF8 rendition of - <parameter>filename</parameter>.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.10 and above.</para> - </note> - - <para>The <function>filename_display_basename</function>() function - returns the display basename for the particular filename, guaranteed - to be valid UTF-8. The display name might not be identical to the - filename, for instance there might be problems converting it to UTF-8, - and some files can be translated in the display.</para> - - <para>You must pass the whole absolute pathname to this functions so - that translation of well known locations can be done.</para> - - <para>This function is preferred over the <link - linkend="function-gobject--filename-display-name"><function>gobject.filename_display_name</function>()</link> - function if you know the whole path, as it allows translation.</para> - - </refsect2> - - <refsect2 id="function-gobject--filename-from-utf8"> - <title>gobject.filename_from_utf8</title> - - <programlisting><methodsynopsis language="python"> - <methodname>gobject.filename_from_utf8</methodname> - <methodparam><parameter>utf8string</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist role="params"> - <varlistentry> - <term><emphasis>utf8string</emphasis> :</term> - <listitem><simpara>a UTF-8 encoded string.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>a filename encoded in the GLib filename - encoding.</simpara></listitem> - </varlistentry> - </variablelist> - <note> - <para>This function is available in PyGTK 2.10 and above.</para> - </note> - - <para>The <function>filename_from_utf8</function>() function converts - a string from UTF-8 to the encoding GLib uses for filenames. Note that - on Windows GLib uses UTF-8 for filenames.</para> - - </refsect2> - </refsect1> </refentry> |