path: root/docs/reference/pygobject-functions.xml

<?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><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--threads-init">gobject.threads_init</link></methodname>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--signal-accumulator-true-handled">gobject.signal_accumulator_true_handled</link></methodname>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--add-emission-hook">gobject.add_emission_hook</link></methodname>
 	<methodparam><parameter>type</parameter></methodparam>
 	<methodparam><parameter>name</parameter></methodparam>
 	<methodparam><parameter>callback</parameter></methodparam>
 	<methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--remove-emission-hook">gobject.remove_emission_hook</link></methodname>
 	<methodparam><parameter>type</parameter></methodparam>
 	<methodparam><parameter>name</parameter></methodparam>
 	<methodparam><parameter>hook_id</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject---install-metaclass">gobject._install_metaclass</link></methodname>
 	<methodparam><parameter>metaclass</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--filename-display-name">gobject.filename_display_name</link></methodname>
 	<methodparam><parameter>filename</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--filename-display-basename">gobject.filename_display_basename</link></methodname>
 	<methodparam><parameter>filename</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gobject--filename-from-utf8">gobject.filename_from_utf8</link></methodname>
 	<methodparam><parameter>utf8string</parameter></methodparam>
      </methodsynopsis></programlisting>

  </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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a string containing the name of a
type</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>parent_type</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a string containing the name of the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>type</parameter>&nbsp;:</term>
	  <listitem><simpara>the object type that the signal is associated
with</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the signal flags</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>return_type</parameter>&nbsp;:</term>
	  <listitem><simpara>the return type of the signal
handler</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>param_types</parameter>&nbsp;:</term>
	  <listitem><simpara>the parameter types passed to the signal
handler</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>the name of a signal for
<parameter>type</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>an integer signal id</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>the name of a signal for
<parameter>type</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>the integer id of a signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a GObject type, type ID or
instance</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>zero or more property-value
pairs</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a function to call when
<literal>PyGTK</literal> is idle</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>optionals arguments to be passed to
<parameter>callback</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>the time between calls to the function, in
milliseconds </simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>callback</parameter>&nbsp;:</term>
	  <listitem><simpara>the function to call</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>zero or more arguments that will be passed to
<parameter>callback</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a Python file object or an integer file
descriptor ID</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>condition</parameter>&nbsp;:</term>
	  <listitem><simpara>a condition mask</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>callback</parameter>&nbsp;:</term>
	  <listitem><simpara>a function to call</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional arguments to pass to
<parameter>callback</parameter></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>an integer ID</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>the UTF-8 string to be
escaped</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</term>
          <listitem><simpara>process id of a child process to watch</simpara></listitem>
        </varlistentry>
        <varlistentry><term><parameter role="keyword">function</parameter>&nbsp;:</term>
          <listitem><simpara>the function to call</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">data</parameter>&nbsp;:</term>
          <listitem><simpara>the optional data to pass to
<parameter>function</parameter></simpara></listitem>
        </varlistentry>
         <varlistentry>
          <term><parameter role="keyword">priority</parameter>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
          <listitem><simpara>a sequence of strings containing the arguments
of the child process</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">envp</parameter>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
          <listitem><simpara>the user data for the
<parameter>child_setup</parameter> function</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">standard_input</parameter>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
          <listitem><simpara>if <literal>TRUE</literal> return the file
descriptor for the child's stderr</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
          <listitem><simpara>the depth of the stack of calls to the main
context.</simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <function>main_depth</function>() function returns the depth
of the stack of calls in the main context. That is, when called from the
toplevel, it gives 0. When called from within a callback from the <link
linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link>
method (or the <link
linkend="method-gobjectmainloop--run"><methodname>gobject.MainLoop.run</methodname>()</link>
method, etc.) it returns 1. When called from within a callback to a
recursive call to the <link
linkend="method-gobjectmaincontext--iteration"><methodname>gobject.MainContext.iteration</methodname>()</link>
method), it returns 2. And so forth.</para>

    </refsect2>

    <refsect2 id="function-gobject--threads-init">
      <title>gobject.threads_init</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.threads_init</methodname>
        <methodparam><parameter></parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</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 gobject 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-gobject--signal-accumulator-true-handled">
      <title>gobject.signal_accumulator_true_handled</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.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-gobject--add-emission-hook">
      <title>gobject.add_emission_hook</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.add_emission_hook</methodname>
 	<methodparam><parameter>type</parameter></methodparam>
 	<methodparam><parameter>name</parameter></methodparam>
 	<methodparam><parameter>callback</parameter></methodparam>
 	<methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>type</emphasis>&nbsp;:</term>
          <listitem><simpara>a Python GObject instance or
          type</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>name</emphasis>&nbsp;:</term>
          <listitem><simpara>a signal name</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>callback</emphasis>&nbsp;:</term>
          <listitem><simpara>a function</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>...</emphasis>&nbsp;:</term>
          <listitem><simpara>zero or more extra arguments that will be
          passed to callback.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the hook id, for later use with <link
          linkend="function-gobject--signal-remove-emission-hook"><function>gobject.signal_remove_emission_hook</function>()</link>.</simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <function>add_emission_hook</function>() function adds an
      emission hook for the signal specified by <parameter>name</parameter>,
      which will get called for any emission of that signal, independent of
      the instance. This is possible only for signals which don't have the
      <literal>gobject.SIGNAL_NO_HOOKS</literal> flag set.</para>

    </refsect2>

    <refsect2 id="function-gobject--remove-emission-hook">
      <title>gobject.remove_emission_hook</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.remove_emission_hook</methodname>
 	<methodparam><parameter>type</parameter></methodparam>
 	<methodparam><parameter>name</parameter></methodparam>
 	<methodparam><parameter>hook_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>type</emphasis>&nbsp;:</term>
          <listitem><simpara>a Python GObject instance or
          type</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>name</emphasis>&nbsp;:</term>
          <listitem><simpara>a signal name</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>hook_id</emphasis>&nbsp;:</term>
          <listitem><simpara>the id of the emission hook as returned by the
          <link
          linkend="function-gobject--add-emission-hook"><function>gobject.add_emission_hook</function>()</link>)
          function.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara></simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <function>remove_emission_hook</function>() function deletes
      an emission hook.</para>

    </refsect2>

    <refsect2 id="function-gobject---install-metaclass">
      <title>gobject._install_metaclass</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject._install_metaclass</methodname>
 	<methodparam><parameter>metaclass</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>metaclass</emphasis>&nbsp;:</term>
          <listitem><simpara></simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <function>_install_metaclass</function>() function installs
      the metaclass specified by <parameter>metaclass</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gobject--filename-display-name">
      <title>gobject.filename_display_name</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.filename_display_name</methodname>
        <methodparam><parameter>filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>filename</emphasis>&nbsp;:</term>
          <listitem><simpara>a pathname in the file name
          encoding</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>an UTF8 rendition of
          <parameter>filename</parameter>.</simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <function>filename_display_name</function>() function
      converts a filename into a valid UTF-8 string. The conversion is not
      necessarily reversible, so you should keep the original around and use
      the return value of this function only for display purposes. Unlike
      g_filename_to_utf8(), the result is guaranteed to be non-None even if
      the filename actually isn't in the file name encoding.</para>

      <para>If you know the whole pathname of the file you should use the
      <link
      linkend="function-gobject--filename-display-basename"><function>gobject.filename_display_basename</function>()</link>
      function, since that allows location-based translation of
      filenames.</para>

    </refsect2>

    <refsect2 id="function-gobject--filename-display-basename">
      <title>gobject.filename_display_basename</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.filename_display_basename</methodname>
        <methodparam><parameter>filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>filename</emphasis>&nbsp;:</term>
          <listitem><simpara>an absolute pathname in the file name
          encoding</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>an UTF8 rendition of
          <parameter>filename</parameter>.</simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <function>filename_display_basename</function>() function
      returns the display basename for the particular filename, guaranteed
      to be valid UTF-8. The display name might not be identical to the
      filename, for instance there might be problems converting it to UTF-8,
      and some files can be translated in the display.</para>

      <para>You must pass the whole absolute pathname to this functions so
      that translation of well known locations can be done.</para>

      <para>This function is preferred over the <link
      linkend="function-gobject--filename-display-name"><function>gobject.filename_display_name</function>()</link>
      function if you know the whole path, as it allows translation.</para>

    </refsect2>

    <refsect2 id="function-gobject--filename-from-utf8">
      <title>gobject.filename_from_utf8</title>
      
      <programlisting><methodsynopsis language="python">
        <methodname>gobject.filename_from_utf8</methodname>
 	<methodparam><parameter>utf8string</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist role="params">
        <varlistentry>
          <term><emphasis>utf8string</emphasis>&nbsp;:</term>
          <listitem><simpara>a UTF-8 encoded string.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</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>