pygobject r910 - in trunk: . docs docs/reference
- From: johan svn gnome org
- To: svn-commits-list gnome org
- Subject: pygobject r910 - in trunk: . docs docs/reference
- Date: Fri, 1 Aug 2008 22:52:06 +0000 (UTC)
Author: johan
Date: Fri Aug 1 22:52:06 2008
New Revision: 910
URL: http://svn.gnome.org/viewvc/pygobject?rev=910&view=rev
Log:
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.
Added:
trunk/docs/reference/pyglib-constants.xml
trunk/docs/reference/pyglib-functions.xml
trunk/docs/reference/pyglib-maincontext.xml
trunk/docs/reference/pyglib-mainloop.xml
Removed:
trunk/docs/reference/pygobject-maincontext.xml
trunk/docs/reference/pygobject-mainloop.xml
Modified:
trunk/ChangeLog
trunk/docs/Makefile.am
trunk/docs/reference/pygobject-classes.xml
trunk/docs/reference/pygobject-constants.xml
trunk/docs/reference/pygobject-functions.xml
Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am (original)
+++ trunk/docs/Makefile.am Fri Aug 1 22:52:06 2008
@@ -10,8 +10,10 @@
html/class-gobjectginterface.html \
html/class-gobjectgpointer.html \
html/class-gobject.html \
- html/class-gobjectmaincontext.html \
- html/class-gobjectmainloop.html \
+ html/class-glibmaincontext.html \
+ html/class-glibmainloop.html \
+ html/glib-constants.html \
+ html/glib-functions.html \
html/gobject-class-reference.html \
html/gobject-constants.html \
html/gobject-functions.html \
@@ -31,8 +33,10 @@
reference/pygobject-gboxed.xml \
reference/pygobject-ginterface.xml \
reference/pygobject-gpointer.xml \
- reference/pygobject-maincontext.xml \
- reference/pygobject-mainloop.xml
+ reference/pyglib-constants.xml \
+ reference/pyglib-functions.xml \
+ reference/pyglib-maincontext.xml \
+ reference/pyglib-mainloop.xml
XSL_FILES = \
xsl/common.xsl \
Added: trunk/docs/reference/pyglib-constants.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pyglib-constants.xml Fri Aug 1 22:52:06 2008
@@ -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>
Added: trunk/docs/reference/pyglib-functions.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pyglib-functions.xml Fri Aug 1 22:52:06 2008
@@ -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>
Added: trunk/docs/reference/pyglib-maincontext.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pyglib-maincontext.xml Fri Aug 1 22:52:06 2008
@@ -0,0 +1,152 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+
+<refentry id="class-glibmaincontext">
+ <refnamediv>
+ <refname>glib.MainContext</refname>
+
+ <refpurpose>an object representing a set of event sources to be handled
+in a <link
+linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>.</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+
+<classsynopsis language="python">
+ <ooclass><classname>glib.MainContext</classname></ooclass>
+<constructorsynopsis language="python">
+ <methodname><link linkend="constructor-glibmaincontext">glib.MainContext</link></methodname>
+ </constructorsynopsis>
+<methodsynopsis language="python">
+ <methodname><link linkend="method-glibmaincontext--iteration">iteration</link></methodname>
+ <methodparam><parameter>may_block</parameter></methodparam>
+ </methodsynopsis>
+<methodsynopsis language="python">
+ <methodname><link linkend="method-glibmaincontext--pending">pending</link></methodname>
+ </methodsynopsis>
+</classsynopsis>
+
+</refsect1>
+
+ <refsect1>
+ <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-glibmaincontext">glib.MainContext</link>
+</synopsis>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>A <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>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-glibmaincontext"><classname>glib.MainContext</classname></link>
+can be run with the <link
+linkend="method-glibmaincontext--iteration"><methodname>iteration</methodname>()</link>
+method.</para>
+
+ </refsect1>
+
+ <refsect1 id="constructor-glibmaincontext">
+ <title>Constructor</title>
+
+ <programlisting><constructorsynopsis language="python">
+ <methodname>glib.MainContext</methodname>
+ </constructorsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a new <link
+ linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>
+ object.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Creates a new <link
+linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>
+object.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Methods</title>
+
+ <refsect2 id="method-glibmaincontext--iteration">
+ <title>glib.MainContext.iteration</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>iteration</methodname>
+ </methodsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>may_block</parameter> :</term>
+ <listitem><simpara>if <literal>TRUE</literal> the call may block
+ waiting for an event.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>TRUE</literal> if events were
+ dispatched.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The <methodname>iteration</methodname>() method runs a single
+iteration. This involves:</para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>checking to see if any associated event sources are ready
+to be processed;</simpara>
+ </listitem>
+ <listitem>
+ <simpara>then if no events sources are ready and
+<parameter>may_block</parameter> is <literal>TRUE</literal>, waiting for a
+source to become ready;</simpara>
+ </listitem>
+ <listitem>
+ <simpara>and finally, dispatching the highest priority events
+sources that are ready</simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that even when <parameter>may_block</parameter> is
+<literal>TRUE</literal>, it is still possible for
+<methodname>iteration</methodname>() to return <literal>FALSE</literal>,
+since the the wait may be interrupted for other reasons than an event source
+becoming ready.</para>
+
+ </refsect2>
+
+ <refsect2 id="method-glibmaincontext--pending">
+ <title>glib.MainContext.pending</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>pending</methodname>
+ </methodsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>TRUE</literal> if events are
+ pending.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The <methodname>pending</methodname>() method checks if any
+associated sources have pending events.</para>
+
+ </refsect2>
+
+ </refsect1>
+
+</refentry>
Added: trunk/docs/reference/pyglib-mainloop.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pyglib-mainloop.xml Fri Aug 1 22:52:06 2008
@@ -0,0 +1,202 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+
+<refentry id="class-glibmainloop">
+ <refnamediv>
+ <refname>glib.MainLoop</refname>
+
+ <refpurpose>an object representing the main event loop of a PyGTK
+ application.</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+
+<classsynopsis language="python">
+ <ooclass><classname>glib.MainLoop</classname></ooclass>
+<constructorsynopsis language="python">
+ <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-glibmainloop--get-context">get_context</link></methodname>
+ </methodsynopsis>
+<methodsynopsis language="python">
+ <methodname><link linkend="method-glibmainloop--is-running">is_running</link></methodname>
+ </methodsynopsis>
+<methodsynopsis language="python">
+ <methodname><link linkend="method-glibmainloop--quit">quit</link></methodname>
+ </methodsynopsis>
+<methodsynopsis language="python">
+ <methodname><link linkend="method-glibmainloop--run">run</link></methodname>
+ </methodsynopsis>
+</classsynopsis>
+
+</refsect1>
+
+ <refsect1>
+ <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-glibmainloop">glib.MainLoop</link>
+</synopsis>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><link
+linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>
+represents a main event loop. A <link
+linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>
+is created with the <link
+linkend="constructor-glibmainloop">glib.MainLoop</link>()
+constructor. After adding the initial event sources, the <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-glibmainloop--quit"><methodname>quit</methodname>()</link>
+method to exit the main loop, and the <link
+linkend="method-glibmainloop--run"><methodname>run</methodname>()</link>
+method returns.</para>
+
+ <para>It is possible to create new instances of <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-glibmaincontext"><classname>glib.MainContext</classname></link>,
+and will be checked and dispatched for all main loops associated with that
+<link
+linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>.</para>
+
+ <para><literal>PyGTK</literal> contains wrappers of some of these
+functions, e.g. the <link
+linkend="function-gtk--main"><function>gtk.main</function>()</link>, <link
+linkend="function-gtk--main-quit"><function>gtk.main_quit</function>()</link>
+and <link
+linkend="function-gtk--events-pending"><function>gtk.events_pending</function>()</link>
+functions.</para>
+
+ </refsect1>
+
+ <refsect1 id="constructor-glibmainloop">
+ <title>Constructor</title>
+
+ <programlisting><constructorsynopsis language="python">
+ <methodname>glib.MainLoop</methodname>
+ <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter>is_running</parameter><initializer>None</initializer></methodparam>
+ </constructorsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>context</parameter> :</term>
+ <listitem><simpara>a <link
+ linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>
+ or <literal>None</literal> to use the default
+ context.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <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-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-glibmainloop"><classname>glib.MainLoop</classname></link>
+ object.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Creates a new <link
+linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>
+object.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Methods</title>
+
+ <refsect2 id="method-glibmainloop--get-context">
+ <title>glib.MainLoop.get_context</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_context</methodname>
+ </methodsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>the <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-glibmaincontext"><classname>glib.MainContext</classname></link>
+that the mainloop was created with.</para>
+
+ </refsect2>
+
+ <refsect2 id="method-glibmainloop--is-running">
+ <title>glib.MainLoop.is_running</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>is_running</methodname>
+ </methodsynopsis></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>TRUE</literal> if the mainloop is
+ currently being run.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The <methodname>is_running</methodname>() method checks to see
+if the mainloop is currently being run via the <link
+linkend="method-glibmainloop--run"><methodname>run</methodname>()</link>
+method.</para>
+
+ </refsect2>
+
+ <refsect2 id="method-glibmainloop--quit">
+ <title>glib.MainLoop.quit</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>quit</methodname>
+ </methodsynopsis></programlisting>
+
+ <para>The <methodname>quit</methodname>() method stops the mainloop
+from running. Any subsequent calls to the <link
+linkend="method-glibmainloop--run"><methodname>run</methodname>()</link>
+method will return immediately.</para>
+
+ </refsect2>
+
+ <refsect2 id="method-glibmainloop--run">
+ <title>glib.MainLoop.run</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>run</methodname>
+ </methodsynopsis></programlisting>
+
+ <para>The <methodname>run</methodname>() method runs a mainloop until
+the <link
+linkend="method-glibmainloop--quit"><methodname>quit</methodname>()</link>
+method is called. If this is called for the thread of the loop's <link
+linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>,
+it will process events from the loop, otherwise it will simply wait.</para>
+
+ </refsect2>
+
+ </refsect1>
+
+</refentry>
Modified: trunk/docs/reference/pygobject-classes.xml
==============================================================================
--- trunk/docs/reference/pygobject-classes.xml (original)
+++ trunk/docs/reference/pygobject-classes.xml Fri Aug 1 22:52:06 2008
@@ -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"/>
Modified: trunk/docs/reference/pygobject-constants.xml
==============================================================================
--- trunk/docs/reference/pygobject-constants.xml (original)
+++ trunk/docs/reference/pygobject-constants.xml Fri Aug 1 22:52:06 2008
@@ -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 @@
</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>
Modified: trunk/docs/reference/pygobject-functions.xml
==============================================================================
--- trunk/docs/reference/pygobject-functions.xml (original)
+++ trunk/docs/reference/pygobject-functions.xml Fri Aug 1 22:52:06 2008
@@ -86,63 +86,6 @@
<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 @@
<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 @@
</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 @@
</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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
