path: root/docs/reference/pygtk-gobject.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="class-gobject">
  <refmeta>
    <refentrytitle>gobject.GObject</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>PyGTK Docs</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>gobject.GObject</refname>
      <refpurpose>the base class</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
	<ooclass><classname>gobject.GObject</classname></ooclass>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--get-property">get_property</link></methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--set-property">set_property</link></methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	  <methodparam><parameter>value</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--freeze-notify">freeze_notify</link></methodname>
	  <methodparam></methodparam>  </methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--notify">notify</link></methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--thaw-notify">thaw_notify</link></methodname>
	  <methodparam></methodparam>  </methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--get-data">get_data</link></methodname>
	  <methodparam><parameter>key</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--set-data">set_data</link></methodname>
	  <methodparam><parameter>key</parameter></methodparam>
	  <methodparam><parameter>data</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--connect">connect</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--connect-after">connect_after</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--connect-object">connect_object</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--connect-object-after">connect_object_after</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--disconnect">disconnect</link></methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--handler-disconnect">handler_disconnect</link></methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--handler-is-connected">handler_is_connected</link></methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--handler-block">handler_block</link></methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--handler-unblock">handler_unblock</link></methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--emit">emit</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--stop-emission">stop_emission</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--emit-stop-by-name">emit_stop_by_name</link></methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	</methodsynopsis>
	<methodsynopsis language="python">
	  <methodname><link
linkend="method-gobject--chain">chain</link></methodname>
	  <methodparam></methodparam>  </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	<?dbhtml cellpadding="5"?>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"__doc__"</entry>
	      <entry>Read</entry>
	      <entry>The documentation for the object type. Uses
	      "__gdoc__" if no specific documentation set.</entry>
	    </row>
	    <row valign="top">
	      <entry>"__gdoc__"</entry>
	      <entry>Read</entry>
	      <entry>The generated documentation for the underlying GObject
	      type.</entry>
	    </row>
	    <row valign="top">
	      <entry>"__gtype__"</entry>
	      <entry>Read</entry>
	      <entry>The underlying GObject type.</entry>
	    </row>
	    <row valign="top">
	      <entry>"__grefcount__"</entry>
	      <entry>Read</entry>
	      <entry>The reference count for the underlying GObject.</entry>
	    </row>

	</tbody>
      </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gobject">
    <title>gobject.GObject Signal Prototypes</title>


    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gobject--notify">notify</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>gobject</parameter></methodparam>
            <methodparam><parameter>property_spec</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>
    <para>The <link
    linkend="class-gobject"><classname>gobject.GObject</classname></link>
    class is the base class providing the common attributes and methods for
    the PyGTK classes. The <link
    linkend="class-gobject"><classname>gobject.GObject</classname></link>
    class is not a user interface widget class.</para>

    <para>The <link
    linkend="class-gobject"><classname>gobject.GObject</classname></link>
    class provides the signal management methods, the object property access
    methods and the object data management methods.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gobject--get-property">
      <title>gobject.GObject.get_property</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_property</methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>property_name</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the property name for the
GObject</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a Python object containing the value of the
property</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_property</methodname>() method returns the
value of the property specified by <parameter>property_name</parameter> or
None if there is no value associated with the property.</para>
      <para>The <exceptionname>TypeError</exceptionname> exception is raised
if the property name is not registered with the object class.</para>

    </refsect2>

    <refsect2 id="method-gobject--set-property">
      <title>gobject.GObject.set_property</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_property</methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	  <methodparam><parameter>value</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>property_name</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the property
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>value</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python object containing the property value
to be set</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_property</methodname>() method sets the
property specified by <parameter>property_name</parameter> to the specified
<parameter>value</parameter>.</para>
      <para>The <exceptionname>TypeError</exceptionname> exception is raised
if the property name is not registered with the object class or if the value
specified could not be converted to the property type.</para>

    </refsect2>

    <refsect2 id="method-gobject--freeze-notify">
      <title>gobject.GObject.freeze_notify</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>freeze_notify</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <para>The <methodname>freeze_notify</methodname>() method freezes the
object's property-changed notification queue so that "notify" signals are
blocked until the <methodname>thaw_notify</methodname>() method is
called.</para>

    </refsect2>

    <refsect2 id="method-gobject--notify">
      <title>gobject.GObject.notify</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>notify</methodname>
	  <methodparam><parameter>property_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>property_name</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing a property
name</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>notify</methodname>() method causes the "notify"
signal for the property specified by <parameter>property_name</parameter> to
be emitted.</para>

    </refsect2>

    <refsect2 id="method-gobject--thaw-notify">
      <title>gobject.GObject.thaw_notify</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>thaw_notify</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <para>The <methodname>thaw_notify</methodname>() method thaws the
object's property-changed notification queue so that "notify" signals are
emitted.</para>

    </refsect2>

    <refsect2 id="method-gobject--get-data">
      <title>gobject.GObject.get_data</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_data</methodname>
	  <methodparam><parameter>key</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>key</parameter>&nbsp;:</term>
	  <listitem><simpara>a string used as the key</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a Python object containing the associated
data</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_data</methodname>() method returns the
Python object associated with the specified <parameter>key</parameter> or
None if there is no data associated with the <parameter>key</parameter> or
if there is no key associated with the object.</para>

    </refsect2>

    <refsect2 id="method-gobject--set-data">
      <title>gobject.GObject.set_data</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_data</methodname>
	  <methodparam><parameter>key</parameter></methodparam>
	  <methodparam><parameter>data</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>key</parameter>&nbsp;:</term>
	  <listitem><simpara>a string used as a key</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>data</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python object that is the value to be
associated with the key</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_data</methodname>() method associates the
specified Python object (<parameter>data</parameter>) with
<parameter>key</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gobject--connect">
      <title>gobject.GObject.connect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>handler</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python function or method
object.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional optional
parameters</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>connect</methodname>() method adds a function or
method (<parameter>handler</parameter>)to the end of the list of signal
handlers for the named <parameter>detailed_signal</parameter> but before the
default class signal handler. An optional set of parameters may be specified
after the <parameter>handler</parameter> parameter. These will all be passed
to the signal handler when invoked.</para>
      <para>For example if a function handler was connected to a signal
using:</para>
      <programlisting>
  handler_id = object.connect("signal_name", handler, arg1, arg2, arg3)
</programlisting>
      <para>The handler should be defined as:</para>
      <programlisting>
  def handler(object, arg1, arg2, arg3):
</programlisting>
      <para>A method handler connected to a signal using:</para>
      <programlisting>
  handler_id = object.connect("signal_name", self.handler, arg1, arg2)
</programlisting>
      <para>requires an additional argument when defined:</para>
      <programlisting>
  def handler(self, object, arg1, arg2)
</programlisting>
      <para>A <exceptionname>TypeError</exceptionname> exception is raised
if <parameter>detailed_signal</parameter> identifies a signal name that is
not associated with the object.</para>

    </refsect2>

    <refsect2 id="method-gobject--connect-after">
      <title>gobject.GObject.connect_after</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_after</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>handler</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python function or method
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional optional
parameters</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>connect_after</methodname>() method is similar
to the <methodname>connect</methodname>() method except that the
<parameter>handler</parameter> is added to the signal handler list after the
default class signal handler. Otherwise the details of
<parameter>handler</parameter> definition and invocation are the
same.</para>
    
    </refsect2>

    <refsect2 id="method-gobject--connect-object">
      <title>gobject.GObject.connect_object</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_object</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	  <methodparam><parameter>gobject</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>handler</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python function or method
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>gobject</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>connect_object</methodname>() method is the same
as the <methodname>connect</methodname>() method except that the
<parameter>handler</parameter> is invoked with the specified
<parameter>gobject</parameter> in place of the object invoking the
<methodname>connect_object</methodname>() method. For example, a call with a
function handler:</para>
      <programlisting>
  handler_id = object("signal_name", handler, gobject)
</programlisting>
      <para>will cause the <parameter>handler</parameter> to be invoked
as:</para>
      <programlisting>
  handler(gobject)
</programlisting>
      <para>Likewise a method handler will be invoked as:</para>
      <programlisting>
  self.handler(gobject)
</programlisting>
      <para>This can be helpful in invoking PyGTK widget methods that
require no arguments except the widget itself (e.g.
<methodname>widget.destroy</methodname>()) by using the class method as the
handler. For example, a Button "clicked" signal can be set up to invoke the
Window <methodname>destroy</methodname>() method as:</para>

      <programlisting>
  handler_id = button.connect_object("clicked", Window.destroy, window)
</programlisting>

      <para>When the button is clicked the handler is invoked as:</para>

      <programlisting>
  Window.destroy(window)
</programlisting>

      <para>which is the same as:</para>

      <programlisting>
  window.destroy()
</programlisting>

      <para>Additional arguments may be passed to the handler as with the
<methodname>connect</methodname>() method handler invocations.</para>

    </refsect2>

    <refsect2 id="method-gobject--connect-object-after">
      <title>gobject.GObject.connect_object_after</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_object_after</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>handler</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>handler</parameter>&nbsp;:</term>
	  <listitem><simpara>a Python function or method
object</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>gobject</parameter>&nbsp;:</term>
	  <listitem><simpara>a GObject</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>connect_object_after</methodname>() method is
similar to the <methodname>connect_object</methodname>() method except that
the <parameter>handler</parameter> is added to the signal handler list after
the default class signal handler. Otherwise the details of
<parameter>handler</parameter> definition and invocation are the
same.</para>

    </refsect2>

    <refsect2 id="method-gobject--disconnect">
      <title>gobject.GObject.disconnect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disconnect</methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>handler_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>disconnect</methodname>() method removes the
signal handler with the specified <parameter>handler_id</parameter> from the
list of signal handlers for the object.</para>

    </refsect2>

    <refsect2 id="method-gobject--handler-disconnect">
      <title>gobject.GObject.handler_disconnect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>handler_disconnect</methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>handler_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>handler_disconnect</methodname>() method removes
the signal handler with the specified <parameter>handler_id</parameter> from
the list of signal handlers for the object.</para>

    </refsect2>

    <refsect2 id="method-gobject--handler-is-connected">
      <title>gobject.GObject.handler_is_connected</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>handler_is_connected</methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>handler_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the signal handler
is connected to the object.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>handler_is_connected</methodname>() method
returns <literal>True</literal> if the signal handler with the specified
<parameter>handler_id</parameter> is connected to the object.</para>

    </refsect2>

    <refsect2 id="method-gobject--handler-block">
      <title>gobject.GObject.handler_block</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>handler_block</methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>handler_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>handler_block</methodname>() method blocks the
signal handler with the specified <parameter>handler_id</parameter> from
being invoked until it is unblocked.</para>

    </refsect2>

    <refsect2 id="method-gobject--handler-unblock">
      <title>gobject.GObject.handler_unblock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>handler_unblock</methodname>
	  <methodparam><parameter>handler_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>handler_id</parameter>&nbsp;:</term>
	  <listitem><simpara>an integer handler
identifier</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>handler_unblock</methodname>() method unblocks
the signal handler with the specified <parameter>handler_id</parameter>
thereby allowing it to be invoked when the associated signal is
emitted.</para>

    </refsect2>

    <refsect2 id="method-gobject--emit">
      <title>gobject.GObject.emit</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>emit</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional parameters</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a PyObject*</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>The <methodname>emit</methodname>() method causes the object to
emit the signal specified by <parameter>detailed_signal</parameter>. The
additional parameters must match the number and type of the required signal
handler parameters. In most cases no additional parameters are needed. for
example:</para>
      <programlisting>
  button.emit("clicked")
</programlisting>
      <para>is all that is required to emit the "clicked" signal for a
button. The most common case requiring additional parameters occurs when
emitting an event signal; for example:</para>
      <programlisting>
  button.emit("button_press_event", event)
</programlisting>

    </refsect2>

    <refsect2 id="method-gobject--stop-emission">
      <title>gobject.GObject.stop_emission</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>stop_emission</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>stop_emission</methodname>() method stops the
current emission of the signal specified by
<parameter>detailed_signal</parameter>. Any signal handlers in the list
still to be run will not be invoked.</para>

    </refsect2>

    <refsect2 id="method-gobject--emit-stop-by-name">
      <title>gobject.GObject.emit_stop_by_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>emit_stop_by_name</methodname>
	  <methodparam><parameter>detailed_signal</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>detailed_signal</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the signal
name</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>emit_stop_by_name</methodname>() method stops
the current emission of the signal specified by
<parameter>detailed_signal</parameter>. Any signal handlers in the list
still to be run will not be invoked.</para>

    </refsect2>

    <refsect2 id="method-gobject--chain">
      <title>gobject.GObject.chain</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>chain</methodname>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional parameters</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a Python object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The chain() method does something.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gobject--notify">
      <title>The GObject "notify" Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>gobject</parameter></methodparam>
	  <methodparam><parameter>property_spec</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>gobject</parameter>&nbsp;:</term>
	  <listitem><simpara>the gobject that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>property_spec</parameter>&nbsp;:</term>
          <listitem><simpara>the <link linkend="class-gobjectgparamspec"><classname>gobject.GParamSpec</classname></link> of the property that was
changed</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "notify" signal is emitted on a gobject when one of its
properties has been changed. Note that getting this signal doesn't guarantee
that the value of the property has actually changed, it may also be emitted
when the setter for the property is called to reinstate the previous
value. For example to be notified of the change of the title of a <link
linkend="class-gtkwindow"><classname>gtk.Window</classname></link> you could
connect to the "notify" signal similar to:</para>

      <programlisting>
  window.connect("notify::title", callback)
</programlisting>

    </refsect2>

  </refsect1>

</refentry>