diff options
Diffstat (limited to 'docs/reference/pygobject-functions.xml')
| -rw-r--r-- | docs/reference/pygobject-functions.xml | 1373 |
1 files changed, 1373 insertions, 0 deletions
diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml new file mode 100644 index 0000000..6a18676 --- /dev/null +++ b/docs/reference/pygobject-functions.xml @@ -0,0 +1,1373 @@ +<?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="gobject-functions"> + <refnamediv> + <refname>gobject Functions</refname> + <refpurpose>miscellaneous functions</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-name">gobject.type_name</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-from-name">gobject.type_from_name</link></methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-parent">gobject.type_parent</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-is-a">gobject.type_is_a</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-children">gobject.type_children</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-interfaces">gobject.type_interfaces</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-register">gobject.type_register</link></methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-new">gobject.signal_new</link></methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-names">gobject.signal_list_names</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-ids">gobject.signal_list_ids</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-name">gobject.signal_name</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query1">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query2">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--list-properties">gobject.list_properties</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--new">gobject.new</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <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></programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>These functions are part of the <literal>PyGTK</literal> gobject +module but are not directly associated with a specific class.</para> + + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gobject--type-name"> + <title>gobject.type_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_name</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_name</function>() function returns +the unique name that is assigned to the specified +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function raises a TypeError exception +if <parameter>type</parameter> isn't a <literal>PyGTK</literal> type.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-from-name"> + <title>gobject.type_from_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_from_name</methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type_name</parameter> :</term> + <listitem><simpara>a string containing the name of a +type</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the type ID named +<parameter>type_name</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_from_name</function>() function +returns the type ID of the <literal>PyGTK</literal> type with the name +specified by <parameter>type_name</parameter>. This function raises a +RuntimeError exception if no type matches +<parameter>type_name</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-parent"> + <title>gobject.type_parent</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_parent</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the parent type ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_parent</function>() function returns +the direct parent type ID of the specified <parameter>type</parameter>. +<parameter>type</parameter> can be a GObject type, type ID or instance. If +<parameter>type</parameter> has no parent, i.e. is a fundamental type, the +RuntimeError exception is raised. </para> + + </refsect2> + + <refsect2 id="function-gobject--type-is-a"> + <title>gobject.type_is_a</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_is_a</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>parent_type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if +<parameter>parent_type</parameter> is an ancestor of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_is_a</function>() function returns +<literal>TRUE</literal> if the specified <parameter>type</parameter> is a +descendant of the type specified by <parameter>parent_type</parameter>. This +function also returns <literal>TRUE</literal> if +<parameter>parent_type</parameter> is an interface and +<parameter>type</parameter> conforms to it.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-children"> + <title>gobject.type_children</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_children</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the child types of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_children</function>() function +returns a list containing the child types of the specified +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-interfaces"> + <title>gobject.type_interfaces</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_interfaces</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the interface types supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_interfaces</function>() function +returns a list of the interface types supported by +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function returns a RuntimeError exception if +type is not a valid type or has no interfaces.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-register"> + <title>gobject.type_register</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_register</methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>class</parameter> :</term> + <listitem><simpara>a Python class that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_register</function>() function +registers the specified Python <parameter>class</parameter> as a PyGTK type. +class must be a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. The function generates a name for the new type.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-new"> + <title>gobject.signal_new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_new</methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>signal_name</parameter> :</term> + <listitem><simpara>a string containing the name of the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>the object type that the signal is associated +with</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>the signal flags</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>return_type</parameter> :</term> + <listitem><simpara>the return type of the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>param_types</parameter> :</term> + <listitem><simpara>the parameter types passed to the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a unique integer signal ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_new</function>() function registers +a signal with the specified <parameter>signal_name</parameter> for the +specified object <parameter>type</parameter>. The value of +<parameter>flags</parameter> is a combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_FIRST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the first emission +stage. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_LAST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the third emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term> + <listitem> + <simpara>Invoke the object method handler in the last emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_RECURSE</literal></term> + <listitem> + <simpara>Signals being emitted for an object while currently +being in emission for this very object will not be emitted recursively, but +instead cause the first emission to be restarted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_DETAILED</literal></term> + <listitem> + <simpara>This signal supports "::detail" appendixes to the +signal name upon handler connections and emissions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_ACTION</literal></term> + <listitem> + <simpara>Action signals are signals that may freely be emitted +on alive objects from user code via <link +linkend="method-gobject--emit"><methodname>gobject.emit()</methodname>()</link> +and friends, without the need of being embedded into extra code that +performs pre or post emission adjustments on the object. They can also be +thought of as generically callable object methods.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_HOOKS</literal></term> + <listitem> + <simpara> No emissions hooks are supported for this +signal.</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para><parameter>return_type</parameter> is the type of the return +value from a signal handler and may be a gobject type, type ID or instance. +The <parameter>param_types</parameter> parameter is a list of additional +types that are passed to the signal handler. Each parameter type may be +specified as a gobject type, type ID or instance. For example, to add a +signal to the gtk.Window type called "my-signal" that calls a handler with a +gtk.Button widget and an integer value and a return value that is a +boolean, use:</para> + + <programlisting> + gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT)) +</programlisting> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-names"> + <title>gobject.signal_list_names</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_names</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal names supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_list_names</function>() function +returns a list of the names of the signals that are supported by the +specified GObject <parameter>type</parameter></para> + + <note> + <para>The type keyword is available in PyGTK 2.6 and above.</para> + </note> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-ids"> + <title>gobject.signal_list_ids</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_ids</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal ids supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_list_ids</function>() function +returns a list of the integer ids of the signals that are supported by the +GObject specified by <parameter>type</parameter></para> + + </refsect2> + + <refsect2 id="function-gobject--signal-lookup"> + <title>gobject.signal_lookup</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_lookup</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the integer id of a signal supported by +<parameter>type</parameter></simpara> or 0.</listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_lookup</function>() function +returns the id of the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified +specified by<parameter>type</parameter>. 0 is returned if the signal is not +found.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-name"> + <title>gobject.signal_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_name</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>an integer signal id</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the name of the signal or +<literal>None</literal>.</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_name</function>() function returns +the name of the signal that has the signal id specified by +<parameter>id</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-query1"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified by +<parameter>type</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--signal-query2"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>the integer id of a signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the id specified by +<parameter>signal_id</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--list-properties"> + <title>gobject.list_properties</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.list_properties</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the properties (as GParam objects) +supported by <parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.list_properties</function>() function +returns a list of the properties (as GParam objects) supported by +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--new"> + <title>gobject.new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.new</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more property-value +pairs</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new object if the specified +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.new</function>() function returns a new +object of the specified <parameter>type</parameter>. type must specify a +type that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A +TypeError exception is raised if <parameter>type</parameter> specifies an +abstract class or a type that is not a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A set +of property-value pairs may be specified to set the value of the object's +properties.</para> + + </refsect2> + + <refsect2 id="function-gobject--idle-add"> + <title>gobject.idle_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.idle_add</methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call when +<literal>PyGTK</literal> is idle</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>optionals arguments to be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.idle_add</function>() function adds a +function (specified by <parameter>callback</parameter>) to be called +whenever there are no higher priority events pending to the default main +loop. The function is given the default idle priority, +<literal>gobject.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to +pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority can be specified as a +keyword-value pair with the keyword "priority". If +<parameter>callback</parameter> returns <literal>FALSE</literal> it is +automatically removed from the list of event sources and will not be called +again.</para> + + </refsect2> + + <refsect2 id="function-gobject--timeout-add"> + <title>gobject.timeout_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.timeout_add</methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>interval</parameter> :</term> + <listitem><simpara>the time between calls to the function, in +milliseconds </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more arguments that will be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event +source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.timeout_add</function>() function sets a +function (specified by <parameter>callback</parameter>) to be called at +regular intervals (specified by <parameter>interval</parameter>, with the +default priority, <literal>gobject.PRIORITY_DEFAULT</literal>. Additional +arguments to pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority may be specified as a +keyword-value pair with the keyword "priority".</para> + + <para>The function is called repeatedly until it returns +<literal>FALSE</literal>, at which point the timeout is automatically +destroyed and the function will not be called again. The first call to the +function will be at the end of the first interval. Note that timeout +functions may be delayed, due to the processing of other event sources. Thus +they should not be relied on for precise timing. After each call to the +timeout function, the time of the next timeout is recalculated based on the +current time and the given interval (it does not try to 'catch up' time lost +in delays).</para> + + </refsect2> + + <refsect2 id="function-gobject--io-add-watch"> + <title>gobject.io_add_watch</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.io_add_watch</methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a Python file object or an integer file +descriptor ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>condition</parameter> :</term> + <listitem><simpara>a condition mask</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional arguments to pass to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.io_add_watch</function>() function +arranges for the file (specified by <parameter>fd</parameter>) to be +monitored by the main loop for the specified +<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python +file object or an integer file descriptor. The value of condition is a +combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.IO_IN</literal></term> + <listitem> + <simpara>There is data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking). </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for +pipes and sockets).</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>Additional arguments to pass to <parameter>callback</parameter> +can be specified after <parameter>callback</parameter>. The idle priority +may be specified as a keyword-value pair with the keyword "priority". The +signature of the callback function is:</para> + + <programlisting> + def callback(source, cb_condition, ...) +</programlisting> + + <para>where <parameter>source</parameter> is +<parameter>fd</parameter>, the file descriptor; +<parameter>cb_condition</parameter> is the condition that triggered the +signal; and, <parameter>...</parameter> are the zero or more arguments that +were passed to the <function>gobject.io_add_watch</function>() +function.</para> + + <para>If the callback function returns <literal>FALSE</literal> it +will be automatically removed from the list of event sources and will not be +called again. If it returns <literal>TRUE</literal> it will be called again +when the condition is matched.</para> + + </refsect2> + + <refsect2 id="function-gobject--source-remove"> + <title>gobject.source_remove</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.source_remove</methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>tag</parameter> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the event source was +removed</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.source_remove</function>() function +removes the event source specified by tag (as returned by the <link +linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link>, +<link +linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function></link>() +and <link +linkend="function-gobject--io-add-watch"><function>gobject.io_add_watch</function>()</link> +functions)</para> + + </refsect2> + + <refsect2 id="function-gobject--main-context-default"> + <title>gobject.main_context_default</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.main_context_default</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the default gobject.MainContext +object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.main_context_default</function>() function +returns the default gobject.MainContext object.</para> + + </refsect2> + + <refsect2 id="function-gobject--markup-escape-text"> + <title>gobject.markup_escape_text</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.markup_escape_text</methodname> + <methodparam><parameter>text</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>text</parameter> :</term> + <listitem><simpara>the UTF-8 string to be +escaped</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the escaped text</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>gobject.markup_escape_text</function>() function +escapes the string specified by <parameter>text</parameter> so that the +markup parser will parse it verbatim. Less than, greater than, ampersand, +etc. are replaced with the corresponding entities. This function would +typically be used when writing out a file to be parsed with the markup +parser.</para> + + <para>Note that this function doesn't protect whitespace and line +endings from being processed according to the XML rules for normalization of +line endings and attribute values.</para> + + </refsect2> + + <refsect2 id="function-gobject--child-watch-add"> + <title>gobject.child_watch_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.child_watch_add</methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>gobject.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">pid</parameter> :</term> + <listitem><simpara>process id of a child process to watch</simpara></listitem> + </varlistentry> + <varlistentry><term><parameter role="keyword">function</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>the optional data to pass to +<parameter>function</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">priority</parameter> :</term> + <listitem><simpara>the priority of the idle source - one of the +<xref linkend="gobject-priority-constants" +endterm="gobject-priority-constants-title"></xref></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the id of event source.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.child_watch_add</function>() function sets +the function specified by <parameter>function</parameter> to be called with +the user data specified by <parameter>data</parameter> when the child +indicated by <parameter>pid</parameter> exits. The signature for the +callback is:</para> + + <programlisting> +def callback(pid, condition, user_data) +</programlisting> + + <para>where <parameter>pid</parameter> is is the child process id, +<parameter>condition</parameter> is the status information about the child +process and <parameter>user_data</parameter> is <parameter>data</parameter> +PyGTK supports only a single callback per process id.</para> + + </refsect2> + + <refsect2 id="function-gobject--spawn-async"> + <title>gobject.spawn_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.spawn_async</methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">argv</parameter> :</term> + <listitem><simpara>a sequence of strings containing the arguments +of the child process</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">envp</parameter> :</term> + <listitem><simpara>the child's environment or +<literal>None</literal> to inherit the parent's +environment.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">working_directory</parameter> :</term> + <listitem><simpara>the child's current working directory, or +<literal>None</literal> to inherit parent's</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags from the <xref +linkend="gobject-spawn-flag-constants" +endterm="gobject-spawn-flag-constants-title"></xref>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">child_setup</parameter> :</term> + <listitem><simpara>a function to run in the child just before +calling <function>exec</function>()</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>the user data for the +<parameter>child_setup</parameter> function</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_input</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdin</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_output</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdout</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_error</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stderr</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 4-tuple containing the child's process id and +the stdin, stdout and stderr file descriptor integers.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.spawn_async</function>() function executes +a child program asynchronously (your program will not block waiting for the +child to exit). The child program is specified by the only argument that +must be provided, <parameter>argv</parameter>. <parameter>argv</parameter> +should be a sequence of strings, to be passed as the argument vector for the +child. The first string in <parameter>argv</parameter> is of course the name +of the program to execute. By default, the name of the program must be a +full path; the <envar>PATH</envar> shell variable will only be searched if +you pass the <literal>gobject.SPAWN_SEARCH_PATH</literal> flag in +<parameter>flags</parameter>. The function returns a 4-tuple containing the +child's process id and the file descriptors for the child's stdin, stdout +and stderr. The stdin, stdout and stderr file descriptors are returned only +ofthe corresponding <parameter>standard_input</parameter>, +<parameter>standard_output</parameter> or +<parameter>standard_error</parameter> params are +<literal>TRUE</literal>.</para> + + <para>On Windows, the low-level child process creation API +(<function>CreateProcess</function>()) doesn't use argument vectors, but a +command line. The C runtime library's <function>spawn*</function>() family +of functions (which <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +eventually calls) paste the argument vector elements into a command line, +and the C runtime startup code does a corresponding reconstruction of an +argument vector from the command line, to be passed to +<function>main</function>(). Complications arise when you have argument +vector elements that contain spaces of double quotes. The +<function>spawn*</function>() functions don't do any quoting or escaping, +but on the other hand the startup code does do unquoting and unescaping in +order to enable receiving arguments with embedded spaces or double +quotes. To work around this asymmetry, the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function will do quoting and escaping on argument vector elements that need +it before calling the C runtime <function>spawn</function>() +function.</para> + + <para><parameter>envp</parameter> is a sequence of strings, where each + string has the form <literal>KEY=VALUE</literal>. This will become the + child's environment. If <parameter>envp</parameter> is + <parameter>None</parameter> or not specified, the child inherits its + parent's environment.</para> + + <para><parameter>flags</parameter> should be the bitwise +<literal>OR</literal> of the <xref linkend="gobject-spawn-flag-constants" +endterm="gobject-spawn-flag-constants-title"></xref> you want to affect the +function's behaviour. The <literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> +flag means that the child will not automatically be reaped; you must use a +GChildWatch source to be notified about the death of the child +process. Eventually you must call g_spawn_close_pid() on the child_pid, in +order to free resources which may be associated with the child process. (On +Unix, using a GChildWatch source is equivalent to calling +<function>waitpid</function>() or handling the <literal>SIGCHLD</literal> +signal manually. On Windows, calling g_spawn_close_pid() is equivalent to +calling <function>CloseHandle</function>() on the process handle +returned).</para> + + <para><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means +that the parent's open file descriptors will be inherited by the child; +otherwise all descriptors except stdin/stdout/stderr will be closed before +calling <function>exec</function>() in the +child. <literal>gobject.SPAWN_SEARCH_PATH</literal> means that +<parameter>argv</parameter>[0] need not be an absolute path, it will be +looked for in the user's +<envar>PATH</envar>. <literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> +means that the child's standard output will be discarded, instead of going +to the same location as the parent's standard output. If you use this flag, +<parameter>standard_output</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> +means that the child's standard error will be discarded, instead of going to +the same location as the parent's standard error. If you use this flag, +<parameter>standard_error</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> +means that the child will inherit the parent's standard input (by default, +the child's standard input is attached to +<filename>/dev/null</filename>). If you use this flag, +<parameter>standard_input</parameter> must be +<literal>None</literal>. <literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal> +means that the first element of <parameter>argv</parameter> is the file to +execute, while the remaining elements are the actual argument vector to pass +to the file. Normally the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function uses <parameter>argv</parameter>[0] as the file to execute, and +passes all of <parameter>argv</parameter> to the child.</para> + + <para><parameter>child_setup</parameter> and +<parameter>user_data</parameter> are a function and user data. On POSIX +platforms, the function is called in the child after GLib has performed all +the setup it plans to perform (including creating pipes, closing file +descriptors, etc.) but before calling <function>exec</function>(). That is, +<parameter>child_setup</parameter> is called just before calling +<function>exec</function>() in the child. Obviously actions taken in this +function will only affect the child, not the parent. On Windows, there is no +separate <function>fork</function>() and <function>exec</function>() +functionality. Child processes are created and run right away with one API +call, +<function>CreateProcess</function>(). <parameter>child_setup</parameter> is +called in the parent process just before creating the child process. You +should carefully consider what you do in <parameter>child_setup</parameter> +if you intend your software to be portable to Windows.</para> + + <para>The returned child process id can be used to send signals to the +child, or to wait for the child if you specified the +<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child +pid will be returned only if you specified the +<literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para> + + <para>The caller of the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +must close any returned file descriptors when they are no longer in +use.</para> + + <para>If <parameter>standard_input</parameter> is +<literal>None</literal>, the child's standard input is attached to +<filename>/dev/null</filename> unless +<literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para> + + <para>If <parameter>standard_error</parameter> is +<literal>None</literal>, the child's standard error goes to the same +location as the parent's standard error unless +<literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para> + + <para>If <parameter>standard_output</parameter> is +<literal>None</literal>, the child's standard output goes to the same +location as the parent's standard output unless +<literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para> + + <para>If an error occurs, the gobject.GError exception will be +raised.</para> + + </refsect2> + + <refsect2 id="function-gobject--get-current-time"> + <title>gobject.get_current_time</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.get_current_time</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current time as the number of seconds and +microseconds from the epoch.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>gobject.get_current_time</function>() function +reurns the current time of day as the number of seconds and microseconds +from the epoch.</para> + + </refsect2> + + <refsect2 id="function-gobject--main-depth"> + <title>gobject.main_depth</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.main_depth</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>he 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> + + </refsect1> + +</refentry> |