<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="gtk-Signals">
<refmeta>
<refentrytitle role="top_of_page" id="gtk-Signals.top_of_page">Signals</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Signals</refname>
<refpurpose>Object methods and callbacks</refpurpose>
</refnamediv>

<refsynopsisdiv id="gtk-Signals.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gtk/gtk.h&gt;

#define             <link linkend="GTK-SIGNAL-OFFSET--CAPS">GTK_SIGNAL_OFFSET</link>
enum                <link linkend="GtkSignalRunType">GtkSignalRunType</link>;
<link linkend="guint">guint</link>               <link linkend="gtk-signal-new">gtk_signal_new</link>                      (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkSignalRunType">GtkSignalRunType</link> signal_flags,
                                                         <link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> function_offset,
                                                         <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> marshaller,
                                                         <link linkend="GType">GType</link> return_val,
                                                         <link linkend="guint">guint</link> n_args,
                                                         ...);
<link linkend="guint">guint</link>               <link linkend="gtk-signal-newv">gtk_signal_newv</link>                     (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkSignalRunType">GtkSignalRunType</link> signal_flags,
                                                         <link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> function_offset,
                                                         <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> marshaller,
                                                         <link linkend="GType">GType</link> return_val,
                                                         <link linkend="guint">guint</link> n_args,
                                                         <link linkend="GType">GType</link> *args);
#define             <link linkend="gtk-signal-lookup">gtk_signal_lookup</link>                   (name,object_type)
#define             <link linkend="gtk-signal-name">gtk_signal_name</link>                     (signal_id)
<link linkend="void">void</link>                <link linkend="gtk-signal-emit">gtk_signal_emit</link>                     (<link linkend="GtkObject">GtkObject</link> *object,
                                                         <link linkend="guint">guint</link> signal_id,
                                                         ...);
<link linkend="void">void</link>                <link linkend="gtk-signal-emit-by-name">gtk_signal_emit_by_name</link>             (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         ...);
<link linkend="void">void</link>                <link linkend="gtk-signal-emitv">gtk_signal_emitv</link>                    (<link linkend="GtkObject">GtkObject</link> *object,
                                                         <link linkend="guint">guint</link> signal_id,
                                                         <link linkend="GtkArg">GtkArg</link> *args);
<link linkend="void">void</link>                <link linkend="gtk-signal-emitv-by-name">gtk_signal_emitv_by_name</link>            (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkArg">GtkArg</link> *args);
#define             <link linkend="gtk-signal-emit-stop">gtk_signal_emit_stop</link>                (object,signal_id)
<link linkend="void">void</link>                <link linkend="gtk-signal-emit-stop-by-name">gtk_signal_emit_stop_by_name</link>        (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name);
#define             <link linkend="gtk-signal-connect">gtk_signal_connect</link>                  (object,name,func,func_data)
#define             <link linkend="gtk-signal-connect-after">gtk_signal_connect_after</link>            (object,name,func,func_data)
#define             <link linkend="gtk-signal-connect-object">gtk_signal_connect_object</link>           (object,name,func,slot_object)
#define             <link linkend="gtk-signal-connect-object-after">gtk_signal_connect_object_after</link>     (object,name,func,slot_object)
<link linkend="gulong">gulong</link>              <link linkend="gtk-signal-connect-full">gtk_signal_connect_full</link>             (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> unsupported,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func,
                                                         <link linkend="gint">gint</link> object_signal,
                                                         <link linkend="gint">gint</link> after);
<link linkend="void">void</link>                <link linkend="gtk-signal-connect-while-alive">gtk_signal_connect_while_alive</link>      (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="gpointer">gpointer</link> func_data,
                                                         <link linkend="GtkObject">GtkObject</link> *alive_object);
<link linkend="void">void</link>                <link linkend="gtk-signal-connect-object-while-alive">gtk_signal_connect_object_while_alive</link>
                                                        (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="GtkObject">GtkObject</link> *alive_object);
#define             <link linkend="gtk-signal-disconnect">gtk_signal_disconnect</link>               (object,handler_id)
#define             <link linkend="gtk-signal-disconnect-by-func">gtk_signal_disconnect_by_func</link>       (object,func,data)
#define             <link linkend="gtk-signal-disconnect-by-data">gtk_signal_disconnect_by_data</link>       (object,data)
#define             <link linkend="gtk-signal-handler-block">gtk_signal_handler_block</link>            (object,handler_id)
#define             <link linkend="gtk-signal-handler-block-by-func">gtk_signal_handler_block_by_func</link>    (object,func,data)
#define             <link linkend="gtk-signal-handler-block-by-data">gtk_signal_handler_block_by_data</link>    (object,data)
#define             <link linkend="gtk-signal-handler-unblock">gtk_signal_handler_unblock</link>          (object,handler_id)
#define             <link linkend="gtk-signal-handler-unblock-by-func">gtk_signal_handler_unblock_by_func</link>  (object,func,data)
#define             <link linkend="gtk-signal-handler-unblock-by-data">gtk_signal_handler_unblock_by_data</link>  (object,data)
#define             <link linkend="gtk-signal-handler-pending">gtk_signal_handler_pending</link>          (object,signal_id,may_be_blocked)
#define             <link linkend="gtk-signal-handler-pending-by-func">gtk_signal_handler_pending_by_func</link>  (object,signal_id,may_be_blocked,func,data)
#define             <link linkend="gtk-signal-default-marshaller">gtk_signal_default_marshaller</link>
</synopsis>
</refsynopsisdiv>









<refsect1 id="gtk-Signals.description" role="desc">
<title role="desc.title">Description</title>
<para>
The GTK+ signal system merely proxies the GLib signal system now. For future
usage, direct use of the <link linkend="gobject-Signals">GSignal</link> API is recommended, this avoids significant
performance hits where <link linkend="GtkArg"><type>GtkArg</type></link> structures have to be converted into <link linkend="GValue"><type>GValue</type></link><!-- -->s.
</para>
<refsect2>
<title>What are signals?</title>
<para>
Signals are a way to get notification when something happens
and to customize object behavior according to the
user's needs.
Every <wordasword>signal</wordasword> is uniquely identified by a name,
"class_name::signal_name", where signal_name might be something like
"clicked" and class_name might be "GtkButton".  Note that some other class
may also define a "clicked" callback, so long as it doesn't derive from
<link linkend="GtkButton"><type>GtkButton</type></link>.
</para>
<para>
When they are created, they are also assigned a unique positive integer,
the signal id (1 is the first signal id- 0 is used to flag an error).
Each is also tied to an array of types that describes
the prototype of the function pointer(s) (handlers) you may
connect to the signal.  Finally, every signal has
a default handler that is given by a function pointer
in its class structure:  it is run by default whenever the
signal is emitted.  (It is possible that a signal will
be emitted and a user-defined handler will prevent the default handler
from being run.)
</para>
<para>
Signals are used by everyone, but they are only
created on a per class basis -- so you should not call
call <link linkend="gtk-signal-new"><function>gtk_signal_new()</function></link> unless you are writing
a new <link linkend="GtkObject"><type>GtkObject</type></link> type.  However, if you want to make a new signal
for an existing type, you may use <link linkend="gtk-object-class-user-signal-new"><function>gtk_object_class_user_signal_new()</function></link>
to create a signal that doesn't correspond to a class's builtin
methods.
</para>
</refsect2>
<refsect2>
<title>How are signals used?</title>
<para>
There are two basic actions in the signal handling game.
If you want notification of an event, you must <emphasis>connect</emphasis>
a function pointer and a data pointer to that signal;  the data pointer
will be passed as the last argument to the function (so long as you
are using the default marshalling functions).
You will receive a connection id, a unique positive integer
corresponding to that attachment.
</para>
<para>
Functions that want to notify the user of certain actions,
<emphasis>emit</emphasis> signals.
</para>
</refsect2>
<refsect2>
<title>Basic Terminology</title>
<variablelist>
<varlistentry>
<term>signal</term>
<listitem><para>A class method, e.g. GtkButton::clicked.
More precisely it is a unique class-branch/signal-name pair.
This means you may not define a signal handler for a class which
derives from <link linkend="GtkButton"><type>GtkButton</type></link> that is called clicked,
but it is okay to share signals names if they are separate in
the class tree.
</para></listitem>
</varlistentry>
<varlistentry>
<term>default handler</term>
<listitem><para>The object's internal method which is invoked
when the signal is emitted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>user-defined handler</term>
<listitem><para>A function pointer and data connected
to a signal (for a particular object).</para>
<para>There are really two types: those which are connected
normally, and those which are connected by one
of the connect_after functions.  The connect_after handlers
are always run after the default handler.</para>
<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>emission</term>
<listitem><para>the whole process of emitting a signal,
including the invocation of all
the different handler types mentioned above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>signal id</term>
<listitem><para>The unique positive (nonzero) integer
used to identify a signal.  It can be used instead of
a name to many functions for a slight performance
improvement.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>connection id</term>
<listitem><para>The unique positive (nonzero) integer
used to identify the connection of a user-defined handler
to a signal.  Notice that it is allowed to connect the
same function-pointer/user-data pair twice, so
there is no guarantee that a function-pointer/user-data
maps to a unique connection id.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>A brief note on how they work.</title>
<para>
The functions responsible for translating an array of <link linkend="GtkArgs"><type>GtkArgs</type></link>
to your C compiler's normal semantics are called Marshallers.
They are identified by
gtk_marshal_<replaceable>return_value</replaceable>__<replaceable>parameter_list</replaceable>()
for example a C function returning a gboolean and taking a gint
can be invoked by using <link linkend="gtk-marshal-BOOL--INT"><function>gtk_marshal_BOOL__INT()</function></link>.
Not all possibly combinations of return/params are available,
of course, so if you are writing a <link linkend="GtkObject"><type>GtkObject</type></link> with parameters
you might have to write a marshaller.
</para>
</refsect2>
</refsect1>

<refsect1 id="gtk-Signals.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GTK-SIGNAL-OFFSET--CAPS" role="macro" condition="deprecated:">
<title>GTK_SIGNAL_OFFSET</title>
<indexterm zone="GTK-SIGNAL-OFFSET--CAPS" role="deprecated"><primary sortas="SIGNAL_OFFSET">GTK_SIGNAL_OFFSET</primary></indexterm><programlisting>#define GTK_SIGNAL_OFFSET	                      G_STRUCT_OFFSET
</programlisting>
<warning><para><literal>GTK_SIGNAL_OFFSET</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Use in place of <function><link linkend="offsetof"><function>offsetof()</function></link></function>, which is used if it exists.
</para></refsect2>
<refsect2 id="GtkSignalRunType" role="enum" condition="deprecated:">
<title>enum GtkSignalRunType</title>
<indexterm zone="GtkSignalRunType" role="deprecated"><primary sortas="SignalRunType">GtkSignalRunType</primary></indexterm><programlisting>typedef enum			/*&lt; flags &gt;*/
{
  GTK_RUN_FIRST      = G_SIGNAL_RUN_FIRST,
  GTK_RUN_LAST       = G_SIGNAL_RUN_LAST,
  GTK_RUN_BOTH       = (GTK_RUN_FIRST | GTK_RUN_LAST),
  GTK_RUN_NO_RECURSE = G_SIGNAL_NO_RECURSE,
  GTK_RUN_ACTION     = G_SIGNAL_ACTION,
  GTK_RUN_NO_HOOKS   = G_SIGNAL_NO_HOOKS
} GtkSignalRunType;
</programlisting>
<warning><para><literal>GtkSignalRunType</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
These configure the signal's emission.  They control
whether the signal can be emitted recursively on an object
and
whether to run the default method before or after the user-defined handlers.
</para>
<variablelist>
<varlistentry>
<term>GTK_RUN_FIRST</term>
<listitem><para>Run the default handler before the connected user-defined
handlers.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK_RUN_LAST</term>
<listitem><para>Run the default handler after the connected
user-defined handlers.
(Handlers registered as "after" always run after the default handler though)
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK_RUN_BOTH</term>
<listitem><para>Run the default handler twice,
once before the user-defined handlers,
and
once after.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK_RUN_NO_RECURSE</term>
<listitem><para>Whether to prevent a handler or hook
from reemitting the signal from within itself.
Attempts to
emit the signal while it is running will result in the signal
emission being restarted once it is done with the current processing.
</para><para>
You must be
careful to avoid having two handlers endlessly reemitting signals,
<link linkend="gtk-signal-n-emissions"><function>gtk_signal_n_emissions()</function></link> can be helpful.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK_RUN_ACTION</term>
<listitem><para>The signal is an action you can
invoke without any particular setup or cleanup.
The signal is treated no differently, but some
other code can determine if the signal is appropriate to
delegate to user control.  For example, key binding sets
only allow bindings of ACTION signals to keystrokes.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK_RUN_NO_HOOKS</term>
<listitem><para>This prevents the connection of emission hooks
to the signal.
</para></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-new" role="function" condition="deprecated:Use g_signal_new() instead.">
<title>gtk_signal_new ()</title>
<indexterm zone="gtk-signal-new" role="deprecated"><primary sortas="signal_new">gtk_signal_new</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_signal_new                      (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkSignalRunType">GtkSignalRunType</link> signal_flags,
                                                         <link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> function_offset,
                                                         <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> marshaller,
                                                         <link linkend="GType">GType</link> return_val,
                                                         <link linkend="guint">guint</link> n_args,
                                                         ...);</programlisting>
<warning><para><literal>gtk_signal_new</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-new"><function>g_signal_new()</function></link> instead.</para></warning>
<para>
Creates a new signal type.  (This is usually done in the
class initializer.)
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the event name for the signal, e.g. "clicked".
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_flags</parameter>&#160;:</term>
<listitem><simpara>a combination of <link linkend="GTK-RUN--CAPS"><type>GTK_RUN</type></link> flags
specifying detail of when the default handler is to be invoked.
You should at least specify <link linkend="GTK-RUN-FIRST--CAPS"><type>GTK_RUN_FIRST</type></link>
or <link linkend="GTK-RUN-LAST--CAPS"><type>GTK_RUN_LAST</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara>the type of object this signal pertains to.
It will also pertain to derivers of this type automatically.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function_offset</parameter>&#160;:</term>
<listitem><simpara>How many bytes the function pointer is in
the class structure for this type.  Used to invoke a class
method generically.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshaller</parameter>&#160;:</term>
<listitem><simpara>the function to translate between an array
of GtkArgs and the native calling convention.  Usually they
are identified just by the type of arguments they take:
for example, <link linkend="gtk-marshal-BOOL--STRING"><function>gtk_marshal_BOOL__STRING()</function></link> describes a marshaller
which takes a string and returns a boolean value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>return_val</parameter>&#160;:</term>
<listitem><simpara>the type of return value, or <link linkend="GTK-TYPE-NONE--CAPS"><type>GTK_TYPE_NONE</type></link> for a signal
without a return value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_args</parameter>&#160;:</term>
<listitem><simpara>the number of parameter the handlers may take.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>a list of <link linkend="GTK-TYPE---CAPS"><type>GTK_TYPE_</type></link>*, one for each parameter.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the signal id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-newv" role="function" condition="deprecated:Use g_signal_newv() instead.">
<title>gtk_signal_newv ()</title>
<indexterm zone="gtk-signal-newv" role="deprecated"><primary sortas="signal_newv">gtk_signal_newv</primary></indexterm><programlisting><link linkend="guint">guint</link>               gtk_signal_newv                     (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkSignalRunType">GtkSignalRunType</link> signal_flags,
                                                         <link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> function_offset,
                                                         <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> marshaller,
                                                         <link linkend="GType">GType</link> return_val,
                                                         <link linkend="guint">guint</link> n_args,
                                                         <link linkend="GType">GType</link> *args);</programlisting>
<warning><para><literal>gtk_signal_newv</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-newv"><function>g_signal_newv()</function></link> instead.</para></warning>
<para>
Creates a new signal type.  (This is usually done in a
class initializer.)
</para>
<para>
This function take the types as an array, instead of a list
following the arguments.  Otherwise the same as <link linkend="gtk-signal-new"><function>gtk_signal_new()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal to create.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_flags</parameter>&#160;:</term>
<listitem><simpara>see <link linkend="gtk-signal-new"><function>gtk_signal_new()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara>the type of <link linkend="GtkObject"><type>GtkObject</type></link> to associate the signal with.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function_offset</parameter>&#160;:</term>
<listitem><simpara>how many bytes the function pointer is in
the class structure for this type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>marshaller</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>return_val</parameter>&#160;:</term>
<listitem><simpara>the type of the return value, or <link linkend="GTK-TYPE-NONE--CAPS"><type>GTK_TYPE_NONE</type></link> if
you don't want a return value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_args</parameter>&#160;:</term>
<listitem><simpara>the number of parameters to the user-defined handlers.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>an array of <link linkend="GtkType"><type>GtkType</type></link><!---->s, describing the prototype to
the callbacks.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the signal id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-lookup" role="macro" condition="deprecated:Use g_signal_lookup() instead.">
<title>gtk_signal_lookup()</title>
<indexterm zone="gtk-signal-lookup" role="deprecated"><primary sortas="signal_lookup">gtk_signal_lookup</primary></indexterm><programlisting>#define             gtk_signal_lookup(name,object_type)</programlisting>
<warning><para><literal>gtk_signal_lookup</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-lookup"><function>g_signal_lookup()</function></link> instead.</para></warning>
<para>
Given the name of the signal and the type of object it connects
to, get the signal's identifying integer.  Emitting the signal
by number is somewhat faster than using the name each time.
</para>
<para>
It also tries the ancestors of the given type.
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the signal's name, e.g. clicked.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara>the type that the signal operates on, e.g. <link linkend="GTK-TYPE-BUTTON--CAPS"><type>GTK_TYPE_BUTTON</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the signal's identifying number, or 0 if no signal was found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-name" role="macro" condition="deprecated:Use g_signal_name() instead.">
<title>gtk_signal_name()</title>
<indexterm zone="gtk-signal-name" role="deprecated"><primary sortas="signal_name">gtk_signal_name</primary></indexterm><programlisting>#define             gtk_signal_name(signal_id)</programlisting>
<warning><para><literal>gtk_signal_name</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-name"><function>g_signal_name()</function></link> instead.</para></warning>
<para>
Given the signal's identifier, finds its name.
</para>
<para>
Two different signals may have the same name, if they have differing types.
</para><variablelist role="params">
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the signal's identifying number.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the signal name, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the signal number was invalid.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emit" role="function" condition="deprecated:Use g_signal_emit() instead.">
<title>gtk_signal_emit ()</title>
<indexterm zone="gtk-signal-emit" role="deprecated"><primary sortas="signal_emit">gtk_signal_emit</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_emit                     (<link linkend="GtkObject">GtkObject</link> *object,
                                                         <link linkend="guint">guint</link> signal_id,
                                                         ...);</programlisting>
<warning><para><literal>gtk_signal_emit</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-emit"><function>g_signal_emit()</function></link> instead.</para></warning>
<para>
Emits a signal.  This causes the default handler and user-defined
handlers to be run.
</para>
<para>
Here is what <link linkend="gtk-signal-emit"><function>gtk_signal_emit()</function></link> does:
</para>
<para>
1.  Calls the default handler and the user-connected handlers.
The default handler will be called first if
<link linkend="GTK-RUN-FIRST--CAPS"><type>GTK_RUN_FIRST</type></link> is set, and last if <link linkend="GTK-RUN-LAST--CAPS"><type>GTK_RUN_LAST</type></link> is set.
</para>
<para>
2.  Calls all handlers connected with the "after" flag set.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object that emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the signal identifier.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to the function, followed
by a pointer to the return type, if any.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emit-by-name" role="function" condition="deprecated:Use g_signal_emit_by_name() instead.">
<title>gtk_signal_emit_by_name ()</title>
<indexterm zone="gtk-signal-emit-by-name" role="deprecated"><primary sortas="signal_emit_by_name">gtk_signal_emit_by_name</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_emit_by_name             (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         ...);</programlisting>
<warning><para><literal>gtk_signal_emit_by_name</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-emit-by-name"><function>g_signal_emit_by_name()</function></link> instead.</para></warning>
<para>
Emits a signal.  This causes the default handler and user-connected
handlers to be run.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object that emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to the function, followed
by a pointer to the return type, if any.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emitv" role="function" condition="deprecated:Use g_signal_emitv() instead.">
<title>gtk_signal_emitv ()</title>
<indexterm zone="gtk-signal-emitv" role="deprecated"><primary sortas="signal_emitv">gtk_signal_emitv</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_emitv                    (<link linkend="GtkObject">GtkObject</link> *object,
                                                         <link linkend="guint">guint</link> signal_id,
                                                         <link linkend="GtkArg">GtkArg</link> *args);</programlisting>
<warning><para><literal>gtk_signal_emitv</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-emitv"><function>g_signal_emitv()</function></link> instead.</para></warning>
<para>
Emits a signal.  This causes the default handler and user-connected
handlers to be run.  This differs from <link linkend="gtk-signal-emit"><function>gtk_signal_emit()</function></link> by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object to emit the signal to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the signal identifier.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>an array of GtkArgs, one for each parameter,
followed by one which is a pointer to the return type.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emitv-by-name" role="function" condition="deprecated:Use g_signal_emitv() and g_signal_lookup() instead.">
<title>gtk_signal_emitv_by_name ()</title>
<indexterm zone="gtk-signal-emitv-by-name" role="deprecated"><primary sortas="signal_emitv_by_name">gtk_signal_emitv_by_name</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_emitv_by_name            (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GtkArg">GtkArg</link> *args);</programlisting>
<warning><para><literal>gtk_signal_emitv_by_name</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-emitv"><function>g_signal_emitv()</function></link> and <link linkend="g-signal-lookup"><function>g_signal_lookup()</function></link> instead.</para></warning>
<para>
Emits a signal by name.  This causes the default handler and user-connected
handlers to be run.  This differs from <link linkend="gtk-signal-emit"><function>gtk_signal_emit()</function></link> by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object to emit the signal to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>an array of GtkArgs, one for each parameter,
followed by one which is a pointer to the return type.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emit-stop" role="macro" condition="deprecated:Use g_signal_stop_emission() instead.">
<title>gtk_signal_emit_stop()</title>
<indexterm zone="gtk-signal-emit-stop" role="deprecated"><primary sortas="signal_emit_stop">gtk_signal_emit_stop</primary></indexterm><programlisting>#define             gtk_signal_emit_stop(object,signal_id)</programlisting>
<warning><para><literal>gtk_signal_emit_stop</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-stop-emission"><function>g_signal_stop_emission()</function></link> instead.</para></warning>
<para>
This function aborts a signal's current emission.
</para>
<para>
It will prevent the default method from running,
if the signal was <link linkend="GTK-RUN-LAST--CAPS"><type>GTK_RUN_LAST</type></link> and you connected
normally (i.e. without the "after" flag).
</para>
<para>
It will print a warning if used on a signal which
isn't being emitted.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object whose signal handlers you wish to stop.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the signal identifier, as returned by <link linkend="g-signal-lookup"><function>g_signal_lookup()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-emit-stop-by-name" role="function" condition="deprecated:Use g_signal_stop_emission_by_name() instead.">
<title>gtk_signal_emit_stop_by_name ()</title>
<indexterm zone="gtk-signal-emit-stop-by-name" role="deprecated"><primary sortas="signal_emit_stop_by_name">gtk_signal_emit_stop_by_name</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_emit_stop_by_name        (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name);</programlisting>
<warning><para><literal>gtk_signal_emit_stop_by_name</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-stop-emission-by-name"><function>g_signal_stop_emission_by_name()</function></link> instead.</para></warning>
<para>
This function aborts a signal's current emission.
</para>
<para>
It is just like <link linkend="gtk-signal-emit-stop"><function>gtk_signal_emit_stop()</function></link>
except it will lookup the signal id for you.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object whose signal handlers you wish to stop.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal you wish to stop.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect" role="macro" condition="deprecated:Use g_signal_connect() instead.">
<title>gtk_signal_connect()</title>
<indexterm zone="gtk-signal-connect" role="deprecated"><primary sortas="signal_connect">gtk_signal_connect</primary></indexterm><programlisting>#define             gtk_signal_connect(object,name,func,func_data)</programlisting>
<warning><para><literal>gtk_signal_connect</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect"><function>g_signal_connect()</function></link> instead.</para></warning>
<para>
Attaches a function pointer and user data to a signal for
a particular object.
</para>
<para>
The <link linkend="GtkSignalFunction"><type>GtkSignalFunction</type></link> takes a <link linkend="GtkObject"><type>GtkObject</type></link> as its first parameter.
It will be the same object as the one you're connecting
the hook to.  The <parameter>func_data</parameter> will be passed as the last parameter
to the hook.
</para>
<para>
All else being equal, signal handlers are invoked in the order
connected (see <link linkend="gtk-signal-emit"><function>gtk_signal_emit()</function></link> for the other details of
which order things are called in).
</para>
<para>
Here is how one passes an integer as user data,
for when you just want to specify a constant int
as parameter to your function:
</para>
<informalexample>
<programlisting>
static void button_clicked_int (GtkButton* button, gpointer func_data)
{
	g_print ("button pressed: &percnt;d\n", GPOINTER_TO_INT (func_data));
}
/* By calling this function, you will make the g_print above
 * execute, printing the number passed as `to_print'. */
static void attach_print_signal (GtkButton* button, gint to_print)
{
	gtk_signal_connect (GTK_OBJECT (button), "clicked",
		GTK_SIGNAL_FUNC (button_clicked_int),
		GINT_TO_POINTER (to_print));
}
</programlisting>
</informalexample><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object associated with the signal, e.g. if a button
is getting pressed, this is that button.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func_data</parameter>&#160;:</term>
<listitem><simpara>value to pass as to your function (through the marshaller).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-after" role="macro" condition="deprecated:Use g_signal_connect_after() instead.">
<title>gtk_signal_connect_after()</title>
<indexterm zone="gtk-signal-connect-after" role="deprecated"><primary sortas="signal_connect_after">gtk_signal_connect_after</primary></indexterm><programlisting>#define             gtk_signal_connect_after(object,name,func,func_data)</programlisting>
<warning><para><literal>gtk_signal_connect_after</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-after"><function>g_signal_connect_after()</function></link> instead.</para></warning>
<para>
Attaches a function pointer and user data to a signal
so that this handler will be called after the other handlers.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object associated with the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func_data</parameter>&#160;:</term>
<listitem><simpara>value to pass as to your function (through the marshaller).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the unique identifier for this attachment:  the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-object" role="macro" condition="deprecated:Use g_signal_connect_swapped() instead.">
<title>gtk_signal_connect_object()</title>
<indexterm zone="gtk-signal-connect-object" role="deprecated"><primary sortas="signal_connect_object">gtk_signal_connect_object</primary></indexterm><programlisting>#define             gtk_signal_connect_object(object,name,func,slot_object)</programlisting>
<warning><para><literal>gtk_signal_connect_object</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-swapped"><function>g_signal_connect_swapped()</function></link> instead.</para></warning>
<para>
This function is for registering a callback that will
call another object's callback.  That is,
instead of passing the object which is responsible
for the event as the first parameter of the callback,
it is switched with the user data (so the object which emits
the signal will be the last parameter, which is where the
user data usually is).
</para>
<para>
This is useful for passing a standard function in as a callback.
For example, if you wanted a button's press to <link linkend="gtk-widget-show"><function>gtk_widget_show()</function></link>
some widget, you could write:
</para>
<informalexample>
<programlisting>
gtk_signal_connect_object (button, "clicked", gtk_widget_show, window);
</programlisting>
</informalexample><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the function to callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>slot_object</parameter>&#160;:</term>
<listitem><simpara>the object to pass as the first parameter to func.
(Though it pretends to take an object, you can
really pass any gpointer as the <link linkend="slot-object"><type>slot_object</type></link> .)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-object-after" role="macro" condition="deprecated">
<title>gtk_signal_connect_object_after()</title>
<indexterm zone="gtk-signal-connect-object-after" role="deprecated"><primary sortas="signal_connect_object_after">gtk_signal_connect_object_after</primary></indexterm><programlisting>#define             gtk_signal_connect_object_after(object,name,func,slot_object)</programlisting>
<warning><para><literal>gtk_signal_connect_object_after</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-data"><function>g_signal_connect_data()</function></link> instead, passing
<literal>G_CONNECT_AFTER|G_CONNECT_SWAPPED</literal> as <parameter>connect_flags</parameter>.</para></warning>
<para>
Attaches a signal hook to a signal, passing in an alternate
object as the first parameter, and guaranteeing
that the default handler and all normal
handlers are called first.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object associated with the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>slot_object</parameter>&#160;:</term>
<listitem><simpara>the object to pass as the first parameter to <link linkend="func"><type>func</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-full" role="function" condition="deprecated:Use g_signal_connect_data() instead.">
<title>gtk_signal_connect_full ()</title>
<indexterm zone="gtk-signal-connect-full" role="deprecated"><primary sortas="signal_connect_full">gtk_signal_connect_full</primary></indexterm><programlisting><link linkend="gulong">gulong</link>              gtk_signal_connect_full             (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="GtkCallbackMarshal">GtkCallbackMarshal</link> unsupported,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func,
                                                         <link linkend="gint">gint</link> object_signal,
                                                         <link linkend="gint">gint</link> after);</programlisting>
<warning><para><literal>gtk_signal_connect_full</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-data"><function>g_signal_connect_data()</function></link> instead.</para></warning>
<para>
Attaches a function pointer and user data to a signal with
more control.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal.  For example, a button
in the button press signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>the name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>unsupported</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data associated with the function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_func</parameter>&#160;:</term>
<listitem><simpara>function to call when this particular hook is 
disconnected.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>object_signal</parameter>&#160;:</term>
<listitem><simpara>whether this is an object signal-- basically an "object
signal" is one that wants its user_data and object fields switched,
which is useful for calling functions which operate on another
object primarily.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>after</parameter>&#160;:</term>
<listitem><simpara>whether to invoke the user-defined handler after the signal, or to let 
the signal's default behavior preside (i.e. depending on <link linkend="GTK-RUN-FIRST--CAPS"><type>GTK_RUN_FIRST</type></link>
and <link linkend="GTK-RUN-LAST--CAPS"><type>GTK_RUN_LAST</type></link>).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-while-alive" role="function" condition="deprecated:Use g_signal_connect_object() instead.">
<title>gtk_signal_connect_while_alive ()</title>
<indexterm zone="gtk-signal-connect-while-alive" role="deprecated"><primary sortas="signal_connect_while_alive">gtk_signal_connect_while_alive</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_connect_while_alive      (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="gpointer">gpointer</link> func_data,
                                                         <link linkend="GtkObject">GtkObject</link> *alive_object);</programlisting>
<warning><para><literal>gtk_signal_connect_while_alive</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-object"><function>g_signal_connect_object()</function></link> instead.</para></warning>
<para>
Attaches a function pointer and another <link linkend="GtkObject"><type>GtkObject</type></link> to a signal.
</para>
<para>
This function takes an object whose "destroy" signal
should be trapped.
That way, you don't have to clean up the
signal handler when you destroy the object.
It is a little less efficient though.
</para>
<para>
(Instead you may call <link linkend="gtk-signal-disconnect-by-data"><function>gtk_signal_disconnect_by_data()</function></link>, if you want
to explicitly delete all attachments to this object.  This
is perhaps not recommended since it could be confused
with an integer masquerading as a pointer (through <link linkend="GINT-TO-POINTER--CAPS"><function>GINT_TO_POINTER()</function></link>).)
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object that emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func_data</parameter>&#160;:</term>
<listitem><simpara>pointer to pass to func.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>alive_object</parameter>&#160;:</term>
<listitem><simpara>object whose death should cause the handler connection
to be destroyed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-connect-object-while-alive" role="function" condition="deprecated">
<title>gtk_signal_connect_object_while_alive ()</title>
<indexterm zone="gtk-signal-connect-object-while-alive" role="deprecated"><primary sortas="signal_connect_object_while_alive">gtk_signal_connect_object_while_alive</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_signal_connect_object_while_alive
                                                        (<link linkend="GtkObject">GtkObject</link> *object,
                                                         const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GCallback">GCallback</link> func,
                                                         <link linkend="GtkObject">GtkObject</link> *alive_object);</programlisting>
<warning><para><literal>gtk_signal_connect_object_while_alive</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-connect-object"><function>g_signal_connect_object()</function></link> instead, passing
<literal>G_CONNECT_SWAPPED</literal> as <parameter>connect_flags</parameter>.</para></warning>
<para>
These signal connectors are for signals which refer to objects,
so they must not be called after the object is deleted.
</para>
<para>
Unlike <link linkend="gtk-signal-connect-while-alive"><function>gtk_signal_connect_while_alive()</function></link>,
this swaps the object and user data, making it suitable for
use with functions which primarily operate on the user data.
</para>
<para>
This function acts just like <link linkend="gtk-signal-connect-object"><function>gtk_signal_connect_object()</function></link> except
it traps the "destroy" signal to prevent you from having to
clean up the handler.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object associated with the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara>name of the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>function pointer to attach to the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>alive_object</parameter>&#160;:</term>
<listitem><simpara>the user data, which must be an object, whose destruction
should signal the removal of this signal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-disconnect" role="macro" condition="deprecated:Use g_signal_handler_disconnect() instead.">
<title>gtk_signal_disconnect()</title>
<indexterm zone="gtk-signal-disconnect" role="deprecated"><primary sortas="signal_disconnect">gtk_signal_disconnect</primary></indexterm><programlisting>#define             gtk_signal_disconnect(object,handler_id)</programlisting>
<warning><para><literal>gtk_signal_disconnect</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handler-disconnect"><function>g_signal_handler_disconnect()</function></link> instead.</para></warning>
<para>
Destroys a user-defined handler connection.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which the handler pertains to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler_id</parameter>&#160;:</term>
<listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-disconnect-by-func" role="macro" condition="deprecated:Use g_signal_handlers_disconnect_by_func() instead.">
<title>gtk_signal_disconnect_by_func()</title>
<indexterm zone="gtk-signal-disconnect-by-func" role="deprecated"><primary sortas="signal_disconnect_by_func">gtk_signal_disconnect_by_func</primary></indexterm><programlisting>#define             gtk_signal_disconnect_by_func(object,func,data)</programlisting>
<warning><para><literal>gtk_signal_disconnect_by_func</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-disconnect-by-func"><function>g_signal_handlers_disconnect_by_func()</function></link> instead.</para></warning>
<para>
Destroys all connections for a particular object, with
the given function-pointer and user-data.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the function pointer to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data to search for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-disconnect-by-data" role="macro" condition="deprecated:Use g_signal_handlers_disconnect_matched() instead.">
<title>gtk_signal_disconnect_by_data()</title>
<indexterm zone="gtk-signal-disconnect-by-data" role="deprecated"><primary sortas="signal_disconnect_by_data">gtk_signal_disconnect_by_data</primary></indexterm><programlisting>#define             gtk_signal_disconnect_by_data(object,data)</programlisting>
<warning><para><literal>gtk_signal_disconnect_by_data</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-disconnect-matched"><function>g_signal_handlers_disconnect_matched()</function></link> instead.</para></warning>
<para>
Destroys all connections for a particular object, with
the given user-data.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data to search for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-block" role="macro" condition="deprecated:Use g_signal_handler_block() instead.">
<title>gtk_signal_handler_block()</title>
<indexterm zone="gtk-signal-handler-block" role="deprecated"><primary sortas="signal_handler_block">gtk_signal_handler_block</primary></indexterm><programlisting>#define             gtk_signal_handler_block(object,handler_id)</programlisting>
<warning><para><literal>gtk_signal_handler_block</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handler-block"><function>g_signal_handler_block()</function></link> instead.</para></warning>
<para>
Prevents a user-defined handler from being invoked.  All other
signal processing will go on as normal, but this particular
handler will ignore it.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal to block.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler_id</parameter>&#160;:</term>
<listitem><simpara>the connection id.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-block-by-func" role="macro" condition="deprecated:Use g_signal_handlers_block_by_func() instead.">
<title>gtk_signal_handler_block_by_func()</title>
<indexterm zone="gtk-signal-handler-block-by-func" role="deprecated"><primary sortas="signal_handler_block_by_func">gtk_signal_handler_block_by_func</primary></indexterm><programlisting>#define             gtk_signal_handler_block_by_func(object,func,data)</programlisting>
<warning><para><literal>gtk_signal_handler_block_by_func</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-block-by-func"><function>g_signal_handlers_block_by_func()</function></link> instead.</para></warning>
<para>
Prevents a user-defined handler from being invoked, by reference to
the user-defined handler's function pointer and user data.  (It may result in
multiple hooks being blocked, if you've called connect multiple times.)
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal to block.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the function pointer of the handler to block.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data of the handler to block.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-block-by-data" role="macro" condition="deprecated:Use g_signal_handlers_block_matched() instead.">
<title>gtk_signal_handler_block_by_data()</title>
<indexterm zone="gtk-signal-handler-block-by-data" role="deprecated"><primary sortas="signal_handler_block_by_data">gtk_signal_handler_block_by_data</primary></indexterm><programlisting>#define             gtk_signal_handler_block_by_data(object,data)</programlisting>
<warning><para><literal>gtk_signal_handler_block_by_data</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-block-matched"><function>g_signal_handlers_block_matched()</function></link> instead.</para></warning>
<para>
Prevents all user-defined handlers with a certain user data from being invoked.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal we want to block.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data of the handlers to block.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-unblock" role="macro" condition="deprecated:Use g_signal_handler_unblock() instead.">
<title>gtk_signal_handler_unblock()</title>
<indexterm zone="gtk-signal-handler-unblock" role="deprecated"><primary sortas="signal_handler_unblock">gtk_signal_handler_unblock</primary></indexterm><programlisting>#define             gtk_signal_handler_unblock(object,handler_id)</programlisting>
<warning><para><literal>gtk_signal_handler_unblock</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handler-unblock"><function>g_signal_handler_unblock()</function></link> instead.</para></warning>
<para>
Undoes a block, by connection id.  Note that undoing a block doesn't
necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal we want to unblock.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler_id</parameter>&#160;:</term>
<listitem><simpara>the emission handler identifier, as returned by
<link linkend="gtk-signal-connect"><function>gtk_signal_connect()</function></link>, etc.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-unblock-by-func" role="macro" condition="deprecated:Use g_signal_handlers_unblock_by_func() instead.">
<title>gtk_signal_handler_unblock_by_func()</title>
<indexterm zone="gtk-signal-handler-unblock-by-func" role="deprecated"><primary sortas="signal_handler_unblock_by_func">gtk_signal_handler_unblock_by_func</primary></indexterm><programlisting>#define             gtk_signal_handler_unblock_by_func(object,func,data)</programlisting>
<warning><para><literal>gtk_signal_handler_unblock_by_func</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-unblock-by-func"><function>g_signal_handlers_unblock_by_func()</function></link> instead.</para></warning>
<para>
Undoes a block, by function pointer and data.
Note that undoing a block doesn't
necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal we want to unblock.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the function pointer to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data to search for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-unblock-by-data" role="macro" condition="deprecated:Use g_signal_handlers_unblock_matched() instead.">
<title>gtk_signal_handler_unblock_by_data()</title>
<indexterm zone="gtk-signal-handler-unblock-by-data" role="deprecated"><primary sortas="signal_handler_unblock_by_data">gtk_signal_handler_unblock_by_data</primary></indexterm><programlisting>#define             gtk_signal_handler_unblock_by_data(object,data)</programlisting>
<warning><para><literal>gtk_signal_handler_unblock_by_data</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-handlers-unblock-matched"><function>g_signal_handlers_unblock_matched()</function></link> instead.</para></warning>
<para>
Undoes block(s), to all signals for a particular object
with a particular user-data pointer
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object which emits the signal we want to unblock.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data to search for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-pending" role="macro" condition="deprecated:Use g_signal_has_handler_pending() instead.">
<title>gtk_signal_handler_pending()</title>
<indexterm zone="gtk-signal-handler-pending" role="deprecated"><primary sortas="signal_handler_pending">gtk_signal_handler_pending</primary></indexterm><programlisting>#define             gtk_signal_handler_pending(object,signal_id,may_be_blocked)</programlisting>
<warning><para><literal>gtk_signal_handler_pending</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-signal-has-handler-pending"><function>g_signal_has_handler_pending()</function></link> instead.</para></warning>
<para>
Returns a connection id corresponding to a given signal id and object.
</para>
<para>
One example of when you might use this is when the arguments
to the signal are difficult to compute.  A class implementor
may opt to not emit the signal if no one is attached anyway,
thus saving the cost of building the arguments.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object to search for the desired user-defined handler.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the number of the signal to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>may_be_blocked</parameter>&#160;:</term>
<listitem><simpara>whether it is acceptable to return a blocked
handler.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id, if a connection was found.  0 otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-handler-pending-by-func" role="macro" condition="deprecated:">
<title>gtk_signal_handler_pending_by_func()</title>
<indexterm zone="gtk-signal-handler-pending-by-func" role="deprecated"><primary sortas="signal_handler_pending_by_func">gtk_signal_handler_pending_by_func</primary></indexterm><programlisting>#define             gtk_signal_handler_pending_by_func(object,signal_id,may_be_blocked,func,data)</programlisting>
<warning><para><literal>gtk_signal_handler_pending_by_func</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Returns a connection id corresponding to a given signal id, object, function
pointer and user data.
</para><variablelist role="params">
<varlistentry><term><parameter>object</parameter>&#160;:</term>
<listitem><simpara>the object to search for the desired handler.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>signal_id</parameter>&#160;:</term>
<listitem><simpara>the number of the signal to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>may_be_blocked</parameter>&#160;:</term>
<listitem><simpara>whether it is acceptable to return a blocked
handler.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the function pointer to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the user data to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the connection id, if a handler was found.  0 otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-signal-default-marshaller" role="macro" condition="deprecated:">
<title>gtk_signal_default_marshaller</title>
<indexterm zone="gtk-signal-default-marshaller" role="deprecated"><primary sortas="signal_default_marshaller">gtk_signal_default_marshaller</primary></indexterm><programlisting>#define	gtk_signal_default_marshaller	g_cclosure_marshal_VOID__VOID
</programlisting>
<warning><para><literal>gtk_signal_default_marshaller</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
A marshaller that returns void and takes no extra parameters.
</para></refsect2>

</refsect1>



<refsect1 id="gtk-Signals.see-also">
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<term><link linkend="GtkObject"><type>GtkObject</type></link></term>
<listitem><para>The base class for things which emit signals.</para></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="gobject-Signals">GSignal</link></term>
<listitem><para>The GLib signal system.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

</refentry>
