diff options
Diffstat (limited to 'docs/reference/pygobject.xml')
| -rw-r--r-- | docs/reference/pygobject.xml | 867 |
1 files changed, 867 insertions, 0 deletions
diff --git a/docs/reference/pygobject.xml b/docs/reference/pygobject.xml new file mode 100644 index 0000000..fd75829 --- /dev/null +++ b/docs/reference/pygobject.xml @@ -0,0 +1,867 @@ +<?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> :</term> + <listitem><simpara>a string containing the property name for the +GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a string containing the property +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</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> :</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> :</term> + <listitem><simpara>a string used as the key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a string used as a key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter> :</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> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</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> :</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> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</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> :</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> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</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> :</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> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>the gobject that received the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>property_spec</parameter> :</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> :</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> :</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> |