path: root/docs/reference/pygtk-gobject-constants.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-constants">
  <refnamediv>
    <refname>gobject Constants</refname>
    <refpurpose>the built-in constants of the gobject module</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <programlisting>
<xref linkend="gobject-io-condition-constants" endterm="gobject-io-condition-constants-title"></xref>
<xref linkend="gobject-param-constants" endterm="gobject-param-constants-title"></xref>
<xref linkend="gobject-priority-constants" endterm="gobject-priority-constants-title"></xref>
<xref linkend="gobject-signal-constants" endterm="gobject-signal-constants-title"></xref>
<xref linkend="gobject-spawn-flag-constants" endterm="gobject-spawn-flag-constants-title"></xref>
<xref linkend="gobject-type-constants" endterm="gobject-type-constants-title"></xref>
<xref linkend="gobject-version-constants" endterm="gobject-version-constants-title"></xref>
</programlisting>

  </refsect1>

  <refsect1 id="gobject-constants-description">
    <title>Description</title>

    <refsect2 id="gobject-io-condition-constants">
      <title id="gobject-io-condition-constants-title">GObject IO Condition Constants</title>

      <para>The IO Condition constants are a set of bit-flags that specify a
condition to watch for on an event source.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.IO_IN</literal></term>
	  <listitem>
	    <simpara>There is data to read</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.IO_OUT</literal></term>
	  <listitem>
	    <simpara>Data can be written (without blocking).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.IO_PRI</literal></term>
	  <listitem>
	    <simpara>There is urgent data to read.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.IO_ERR</literal></term>
	  <listitem>
	    <simpara>Error condition.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.IO_HUP</literal></term>
	  <listitem>
	    <simpara>Hung up (the connection has been broken, usually for
	    pipes and sockets).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.IO_NVAL</literal></term>
	  <listitem>
	    <simpara>Invalid request. The file descriptor is not
	    open.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

    <refsect2 id="gobject-param-constants">
      <title id="gobject-param-constants-title">GObject Param Flag Constants</title>

      <para>The Param Flag constants are a set of bit-flags that specify
certain aspects of parameters that can be configured.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.PARAM_READABLE</literal></term>
	  <listitem>
	    <simpara>The parameter is readable</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PARAM_WRITABLE</literal></term>
	  <listitem>
	    <simpara>The parameter is writable</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PARAM_CONSTRUCT</literal></term>
	  <listitem>
	    <simpara>The parameter will be set upon object
	    construction</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PARAM_CONSTRUCT_ONLY</literal></term>
	  <listitem>
	    <simpara>The parameter will only be set upon object
	    construction</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PARAM_LAX_VALIDATION</literal></term>
	  <listitem>
	    <simpara>Upon parameter conversion strict validation is not
	    required</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

    <refsect2 id="gobject-priority-constants">
      <title id="gobject-priority-constants-title">GObject Priority Constants</title>

      <para>The Priority constants specify </para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.PRIORITY_HIGH</literal></term>
	  <listitem>
	    <simpara>Use this for high priority event sources.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PRIORITY_DEFAULT</literal></term>
	  <listitem>
	    <simpara>Use this for default priority event sources.  This
	    priority is used when adding timeout functions with the <link
	    linkend="function-gobject--timeout-add"><function>gobject.timeout_add</function>()</link>
	    function. This priority is also used for events from the X
	    server.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PRIORITY_HIGH_IDLE</literal></term>
	  <listitem>
	    <simpara>Use this for high priority idle functions. For example,
	    gobject.PRIORITY_HIGH_IDLE + 10 is used for resizing operations;
	    and, gobject.PRIORITY_HIGH_IDLE + 20, for redrawing
	    operations. (This is done to ensure that any pending resizes are
	    processed before any pending redraws, so that widgets are not
	    redrawn twice unnecessarily.)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PRIORITY_DEFAULT_IDLE</literal></term>
	  <listitem>
	    <simpara>Use this for default priority idle functions. This
	    priority is used when adding idle functions with the <link
	    linkend="function-gobject--idle-add"><function>gobject.idle_add</function>()</link>
	    function.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.PRIORITY_LOW</literal></term>
	  <listitem>
	    <simpara>Use this for very low priority background
	    tasks.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

    <refsect2 id="gobject-signal-constants">
      <title id="gobject-signal-constants-title">GObject Signal Flag Constants</title>

      <para>The Signal Flag constants are a set of bit-flags that specify a
signal's behavior. The overall signal description outlines how especially
the <literal>RUN</literal> flags control the stages of a signal
emission.</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" appendices 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 the <link
	    linkend="method-gobject--emit"><methodname>gobject.emit</methodname>()</link>
	    method 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 object methods which can
	    be called generically by third-party code.</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>

    </refsect2>

    <refsect2 id="gobject-spawn-flag-constants">
      <title id="gobject-spawn-flag-constants-title">GObject Spawn Flag Constants</title>

      <para>The Spawn Flag constants are a set of bit-flags that can be
passed to the <link
linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>
function.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal></term>
	  <listitem>
	    <simpara>the parent's open file descriptors will be inherited by
the child; otherwise all descriptors except stdin/stdout/stderr will be
closed before calling <function>exec</function>() in the child.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal></term>
	  <listitem>
	    <simpara>the child will not be automatically reaped; you must
call <function>waitpid</function>() or handle <literal>SIGCHLD</literal>
yourself, or the child will become a zombie.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_SEARCH_PATH</literal></term>
	  <listitem>
	    <simpara><parameter>argv</parameter>[0] need not be an absolute
path, it will be looked for in the user's <envar>PATH</envar>.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal></term>
	  <listitem>
	    <simpara>the child's standard output will be discarded, instead
of going to the same location as the parent's standard output.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal></term>
	  <listitem>
	    <simpara>the child's standard error will be discarded.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal></term>
	  <listitem>
	    <simpara>the child will inherit the parent's standard input (by
default, the child's standard input is attached to /dev/null).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal></term>
	  <listitem>
	    <simpara>the first element of <parameter>argv</parameter> is the
file to execute, while the remaining elements are the actual argument vector
to pass to the file. Normally <link
linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link>
uses <parameter>argv</parameter>[0] as the file to execute, and passes all
of <parameter>argv</parameter> to the child.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

    <refsect2 id="gobject-type-constants">
      <title id="gobject-type-constants-title">GObject Built-in Type Constants</title>

      <para>The Built-in Type constants specify the pre-defined types used
by gobject.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.TYPE_INVALID</literal></term>
	  <listitem>
	    <simpara>An invalid type, used as error return value in some
	    functions.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_NONE</literal></term>
	  <listitem>
	    <simpara>A fundamental type indicating no type.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_INTERFACE</literal></term>
	  <listitem>
	    <simpara>The fundamental type from which all interfaces are
	    derived.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_CHAR</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a
	    character. This maps to a string in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_UCHAR</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an unsigned
	    character. This maps to a string in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_BOOLEAN</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a True or False
	    value. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_INT</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an
	    integer. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_UINT</literal></term>
	  <listitem>
	    <simpara>he fundamental type corresponding to an unsigned
	    integer. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_LONG</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a long
	    integer. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_ULONG</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an unsigned
	    integer. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_INT64</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an long long
	    integer. This maps to a long integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_UINT64</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an unsigned long
	    long integer. This maps to a long integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_ENUM</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to an enumeration
	    type. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_FLAGS</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a flag
	    type. This maps to an integer in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_FLOAT</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a floating point
	    number. This maps to a float in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_DOUBLE</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a double
	    floating point number. This maps to a float in Python.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_STRING</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a string.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_POINTER</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a pointer to an
	    anonymous type. This has no corresponding Python type.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_BOXED</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a boxed object
	    type.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_PARAM</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a GParamSpec
	    type.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gobject.TYPE_OBJECT</literal></term>
	  <listitem>
	    <simpara>The fundamental type corresponding to a GObject
	    type.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

    <refsect2 id="gobject-version-constants">
      <title id="gobject-version-constants-title">GObject Version Constants</title>

      <para>The Version constants specify the version of
<literal>GLIB</literal> used by PyGTK as a 3-tuple containing the major,
minor and patch release numbers.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gobject.glib_version</literal></term>
	  <listitem>
	    <simpara>A 3-tuple containing (major, minor, patch) release
	    numbers.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

    </refsect2>

  </refsect1>

</refentry>