diff options
Diffstat (limited to 'docs/reference/pyglib-functions.xml')
| -rw-r--r-- | docs/reference/pyglib-functions.xml | 1047 |
1 files changed, 1047 insertions, 0 deletions
diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml new file mode 100644 index 0000000..358fa83 --- /dev/null +++ b/docs/reference/pyglib-functions.xml @@ -0,0 +1,1047 @@ +<?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--timeout-add-seconds">glib.timeout_add_seconds</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--get-user-cache-dir">glib.get_user_cache_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-config-dir">glib.get_user_config_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-data-dir">glib.get_user_data_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-special-dir">glib.get_user_special_dir</link></methodname> + <methodparam><parameter role="keyword">directory</parameter></methodparam> + </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--timeout-add-seconds"> + <title>glib.timeout_add_seconds</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.timeout_add_seconds</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 +seconds </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_seconds</function>() is similar to + <function>glib.timeout_add</function>() except + that <parameter>interval</parameter> must be specified in seconds, not + milliseconds, and the function should cause less CPU wakeups, which is important + for laptops' batteries.</para> + + <para>Unlike <function>glib.timeout_add</function>(), this function operates at + whole second granularity. The initial starting point of the timer is determined + by the implementation and the implementation is expected to group multiple timers + together so that they fire all at the same time. To allow this grouping, the + interval to the first timer is rounded and can deviate up to one second from the + specified interval. Subsequent timer iterations will generally run at the + specified interval.</para> + + <para>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.</para> + + <para>The grouping of timers to fire at the same time results in a more power and + CPU efficient behavior so if your timer is in multiples of seconds and you don't + require the first timer exactly one second from now, the use of + <function>glib.timeout_add_seconds</function>() is preferred + over <function>glib.timeout_add</function>().</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--get-user-cache-dir"> + <title>glib.get_user_cache_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_cache_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's cache directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to store non-essential, + cached data specific to particular user.</para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-config-dir"> + <title>glib.get_user_config_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_config_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's configuration directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to store user-specific + application configuration information such as user preferences + and settings. </para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-data-dir"> + <title>glib.get_user_data_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_data_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's data directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to access application + data such as icons that is customized for a particular + user</para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-special-dir"> + <title>glib.get_user_special_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_special_dir</methodname> + <methodparam><parameter>directory</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>directory</emphasis> :</term> + <listitem> + <simpara> + the logical id of special directory, + see <link linkend="glib-user-directory-constants">User + Directory constants</link> for the list of supported + values + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to the requested directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns the full path of a special directory using its + logical id.</para> + + <para>On Unix this is done using the XDG special user + directories. For compatibility with existing practise, + <link linkend="glib-user-directory-constants">glib.USER_DIRECTORY_DESKTOP</link> + falls back to <literal>$HOME/Desktop</literal> when XDG + special user directories have not been set up.</para> + + <para>Depending on the platform, the user might be able to + change the path of the special directory without requiring the + session to restart; GLib will not reflect any change once the + special directories are loaded.</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> |