<!-- ##### SECTION Title ##### -->Signals<!-- ##### SECTION Short_Description ##### -->Object methods and callbacks<!-- ##### SECTION Long_Description ##### --><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 #GtkArg structures have to be converted into #GValue<!-- -->s.</para><refsect2><title>What are signals?</title><para>Signals are a way to get notification when something happensand to customize object behavior according to theuser'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 classmay also define a "clicked" callback, so long as it doesn't derive from#GtkButton.</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 describesthe prototype of the function pointer(s) (handlers) you mayconnect to the signal.  Finally, every signal hasa default handler that is given by a function pointerin its class structure:  it is run by default whenever thesignal is emitted.  (It is possible that a signal willbe emitted and a user-defined handler will prevent the default handlerfrom being run.)</para><para>Signals are used by everyone, but they are onlycreated on a per class basis -- so you should not callcall gtk_signal_new() unless you are writinga new #GtkObject type.  However, if you want to make a new signalfor an existing type, you may use gtk_object_class_user_signal_new()to create a signal that doesn't correspond to a class's builtinmethods.</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 pointerwill be passed as the last argument to the function (so long as youare using the default marshalling functions).You will receive a connection id, a unique positive integercorresponding 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 whichderives from #GtkButton that is called clicked,but it is okay to share signals names if they are separate inthe class tree.</para></listitem></varlistentry><varlistentry><term>default handler</term><listitem><para>The object's internal method which is invokedwhen the signal is emitted.</para></listitem></varlistentry><varlistentry><term>user-defined handler</term><listitem><para>A function pointer and data connectedto a signal (for a particular object).</para><para>There are really two types: those which are connectednormally, and those which are connected by one of the connect_after functions.  The connect_after handlersare 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 allthe different handler types mentioned above.</para></listitem></varlistentry><varlistentry><term>signal id</term><listitem><para>The unique positive (nonzero) integerused to identify a signal.  It can be used instead of a name to many functions for a slight performanceimprovement.</para></listitem></varlistentry><varlistentry><term>connection id</term><listitem><para>The unique positive (nonzero) integerused to identify the connection of a user-defined handlerto a signal.  Notice that it is allowed to connect thesame function-pointer/user-data pair twice, sothere is no guarantee that a function-pointer/user-datamaps 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 #GtkArgsto your C compiler's normal semantics are called Marshallers.They are identified bygtk_marshal_<replaceable>return_value</replaceable>__<replaceable>parameter_list</replaceable>()for example a C function returning a gboolean and taking a gintcan be invoked by using gtk_marshal_BOOL__INT().Not all possibly combinations of return/params are available,of course, so if you are writing a #GtkObject with parametersyou might have to write a marshaller.</para></refsect2><!-- ##### SECTION See_Also ##### --><para><variablelist><varlistentry><term>#GtkObject</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><!-- ##### SECTION Stability_Level ##### --><!-- ##### MACRO GTK_SIGNAL_OFFSET ##### --><para>Use in place of <function>offsetof()</function>, which is used if it exists.</para><!-- # Unused Parameters # -->@struct: @field: <!-- ##### ENUM GtkSignalRunType ##### --><para>These configure the signal's emission.  They controlwhether the signal can be emitted recursively on an objectandwhether 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-definedhandlers.</para></listitem></varlistentry><varlistentry><term>GTK_RUN_LAST</term><listitem><para>Run the default handler after the connecteduser-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,andonce after.</para></listitem></varlistentry><varlistentry><term>GTK_RUN_NO_RECURSE</term><listitem><para>Whether to prevent a handler or hookfrom reemitting the signal from within itself.Attempts toemit the signal while it is running will result in the signalemission being restarted once it is done with the current processing.</para><para>You must becareful to avoid having two handlers endlessly reemitting signals,gtk_signal_n_emissions() 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 someother code can determine if the signal is appropriate todelegate to user control.  For example, key binding setsonly 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 hooksto the signal.</para></listitem></varlistentry></variablelist>@GTK_RUN_FIRST: @GTK_RUN_LAST: @GTK_RUN_BOTH: @GTK_RUN_NO_RECURSE: @GTK_RUN_ACTION: @GTK_RUN_NO_HOOKS: <!-- ##### FUNCTION gtk_signal_new ##### --><para>Creates a new signal type.  (This is usually done in theclass initializer.)</para>@name: the event name for the signal, e.g. "clicked".@signal_flags: a combination of #GTK_RUN flagsspecifying detail of when the default handler is to be invoked.You should at least specify #GTK_RUN_FIRSTor #GTK_RUN_LAST.@object_type: the type of object this signal pertains to.It will also pertain to derivers of this type automatically.@function_offset: How many bytes the function pointer is inthe class structure for this type.  Used to invoke a classmethod generically.@marshaller: the function to translate between an arrayof GtkArgs and the native calling convention.  Usually theyare identified just by the type of arguments they take:for example, gtk_marshal_BOOL__STRING() describes a marshallerwhich takes a string and returns a boolean value.@return_val: the type of return value, or #GTK_TYPE_NONE for a signalwithout a return value.@n_args: the number of parameter the handlers may take.@Varargs: a list of #GTK_TYPE_*, one for each parameter.@Returns: the signal id.@Deprecated: Use g_signal_new() instead.<!-- ##### FUNCTION gtk_signal_newv ##### --><para>Creates a new signal type.  (This is usually done in aclass initializer.)</para><para>This function take the types as an array, instead of a listfollowing the arguments.  Otherwise the same as gtk_signal_new().</para>@name: the name of the signal to create.@signal_flags: see gtk_signal_new().@object_type: the type of #GtkObject to associate the signal with.@function_offset: how many bytes the function pointer is inthe class structure for this type.@marshaller: @return_val: the type of the return value, or #GTK_TYPE_NONE ifyou don't want a return value.@n_args: the number of parameters to the user-defined handlers.@args: an array of #GtkType<!---->s, describing the prototype tothe callbacks.@Returns: the signal id.@Deprecated: Use g_signal_newv() instead.<!-- ##### MACRO gtk_signal_lookup ##### --><para>Given the name of the signal and the type of object it connectsto, get the signal's identifying integer.  Emitting the signalby number is somewhat faster than using the name each time.</para><para>It also tries the ancestors of the given type.</para>@name: the signal's name, e.g. clicked.@object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.@Returns: the signal's identifying number, or 0 if no signal was found.@Deprecated: Use g_signal_lookup() instead.<!-- ##### MACRO gtk_signal_name ##### --><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>@signal_id: the signal's identifying number.@Returns: the signal name, or %NULL if the signal number was invalid.@Deprecated: Use g_signal_name() instead.<!-- ##### FUNCTION gtk_signal_emit ##### --><para>Emits a signal.  This causes the default handler and user-definedhandlers to be run.</para><para>Here is what gtk_signal_emit() does:</para><para>1.  Calls the default handler and the user-connected handlers.The default handler will be called first if#GTK_RUN_FIRST is set, and last if #GTK_RUN_LAST is set.</para><para>2.  Calls all handlers connected with the "after" flag set.</para>@object: the object that emits the signal.@signal_id: the signal identifier.@Varargs: the parameters to the function, followedby a pointer to the return type, if any.@Deprecated: Use g_signal_emit() instead.<!-- ##### FUNCTION gtk_signal_emit_by_name ##### --><para>Emits a signal.  This causes the default handler and user-connectedhandlers to be run.</para>@object: the object that emits the signal.@name: the name of the signal.@Varargs: the parameters to the function, followedby a pointer to the return type, if any.@Deprecated: Use g_signal_emit_by_name() instead.<!-- ##### FUNCTION gtk_signal_emitv ##### --><para>Emits a signal.  This causes the default handler and user-connectedhandlers to be run.  This differs from gtk_signal_emit() by takingan array of GtkArgs instead of using C's varargs mechanism.</para>@object: the object to emit the signal to.@signal_id: the signal identifier.@args: an array of GtkArgs, one for each parameter,followed by one which is a pointer to the return type.@Deprecated: Use g_signal_emitv() instead.<!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->