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 happens
and to customize object behavior according to the
user's needs.
-Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,
+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
</para>
<para>
Signals are used by everyone, but they are only
-created on a per class basis-- so you should not call
+created on a per class basis -- so you should not call
call gtk_signal_new() unless you are writing
a new #GtkObject type. However, if you want to make a new signal
for an existing type, you may use gtk_object_class_user_signal_new()
<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>
+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).
</para>
<para>
Functions that want to notify the user of certain actions,
-<Emphasis>emit</Emphasis> signals.
+<emphasis>emit</emphasis> signals.
</para>
</refsect2>
<refsect2>
<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 GtkButton that is called clicked,
+derives from #GtkButton that is called clicked,
but it is okay to share signals names if they are separate in
the class tree.
</para></listitem>
The functions responsible for translating an array of #GtkArgs
to your C compiler's normal semantics are called Marshallers.
They are identified by
-gtk_marshal_return_value__parameter_list()
+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 gtk_marshal_BOOL__INT().
Not all possibly combinations of return/params are available,
<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>
<!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
<para>
-
+Use in place of <function>offsetof()</function>, which is used if it exists.
</para>
<!-- # Unused Parameters # -->
<!-- ##### FUNCTION gtk_signal_new ##### -->
<para>
-Create a new signal type. (This is usually done in the
+Creates a new signal type. (This is usually done in the
class initializer.)
</para>
@name: the event name for the signal, e.g. "clicked".
-@signal_flags: a combination of GTK_RUN flags
+@signal_flags: a combination of #GTK_RUN flags
specifying detail of when the default handler is to be invoked.
You should at least specify #GTK_RUN_FIRST
or #GTK_RUN_LAST.
are identified just by the type of arguments they take:
for example, gtk_marshal_BOOL__STRING() describes a marshaller
which takes a string and returns a boolean value.
-@return_val: the type of return value, or GTK_TYPE_NONE for a signal
+@return_val: the type of return value, or #GTK_TYPE_NONE for a signal
without a return value.
@n_args:
-@Varargs: a list of GTK_TYPE_*, one for each parameter.
+@Varargs: a list of #GTK_TYPE_*, one for each parameter.
@Returns: the signal id.
<!-- # Unused Parameters # -->
@nparams: the number of parameter the handlers may take.
<!-- ##### FUNCTION gtk_signal_newv ##### -->
<para>
-Create a new signal type. (This is usually done in a
+Creates a new signal type. (This is usually done in a
class initializer.)
</para>
<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.
+@object_type: the type of #GtkObject to associate the signal with.
@function_offset: how many bytes the function pointer is in
the class structure for this type.
@marshaller:
-@return_val: the type of the return value, or GTK_TYPE_NONE if
+@return_val: the type of the return value, or #GTK_TYPE_NONE if
you don't want a return value.
@n_args:
@args:
<!-- ##### MACRO gtk_signal_name ##### -->
<para>
-Given the signal's identifier, find its name.
+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.
+@Returns: the signal name, or %NULL if the signal number was invalid.
<!-- ##### FUNCTION gtk_signal_emit ##### -->
<para>
-Emit a signal. This causes the default handler and user-defined
+Emits a signal. This causes the default handler and user-defined
handlers to be run.
</para>
<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.
+#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.
<!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
<para>
-Emit a signal. This causes the default handler and user-connected
+Emits a signal. This causes the default handler and user-connected
handlers to be run.
</para>
<!-- ##### FUNCTION gtk_signal_emitv ##### -->
<para>
-Emit a signal. This causes the default handler and user-connected
+Emits a signal. This causes the default handler and user-connected
handlers to be run. This differs from gtk_signal_emit() by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para>
<!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
<para>
-Emit a signal by name. This causes the default handler and user-connected
+Emits a signal by name. This causes the default handler and user-connected
handlers to be run. This differs from gtk_signal_emit() by taking
an array of GtkArgs instead of using C's varargs mechanism.
</para>
</para>
@object: the object whose signal handlers you wish to stop.
-@signal_id: the signal identifier, as returned by gtk_signal_lookup().
+@signal_id: the signal identifier, as returned by g_signal_lookup().
<!-- # Unused Parameters # -->
@i:
@s:
<!-- ##### MACRO gtk_signal_connect ##### -->
<para>
-Attach a function pointer and user data to a signal for
+Attaches a function pointer and user data to a signal for
a particular object.
</para>
<para>
-The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.
+The #GtkSignalFunction takes a #GtkObject as its first parameter.
It will be the same object as the one you're connecting
-the hook to. The func_data will be passed as the last parameter
+the hook to. The @func_data will be passed as the last parameter
to the hook.
</para>
<para>
</para>
<informalexample>
<programlisting>
-static void button_clicked_int(GtkButton* button, gpointer func_data)
+static void button_clicked_int (GtkButton* button, gpointer func_data)
{
- g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));
+ g_print ("button pressed: &percent;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)
+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));
+ gtk_signal_connect (GTK_OBJECT (button), "clicked",
+ GTK_SIGNAL_FUNC (button_clicked_int),
+ GINT_TO_POINTER (to_print));
}
</programlisting>
</informalexample>
<!-- ##### MACRO gtk_signal_connect_after ##### -->
<para>
-Attach a function pointer and user data to a signal
+Attaches a function pointer and user data to a signal
so that this handler will be called after the other handlers.
</para>
</para>
<informalexample>
<programlisting>
-gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
+gtk_signal_connect_object (button, "clicked", gtk_widget_show, window);
</programlisting>
</informalexample>
<!-- ##### MACRO gtk_signal_connect_object_after ##### -->
<para>
-Attach a signal hook to a signal, passing in an alternate
+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.
<!-- ##### FUNCTION gtk_signal_connect_full ##### -->
<para>
-Attach a function pointer and user data to a signal with
+Attaches a function pointer and user data to a signal with
more control.
</para>
<!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
<para>
-Attach a function pointer and another GtkObject to a signal.
+Attaches a function pointer and another #GtkObject to a signal.
</para>
<para>
This function takes an object whose "destroy" signal
(Instead you may call gtk_signal_disconnect_by_data(), 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 GINT_AS_POINTER).)
+with an integer masquerading as a pointer (through GINT_TO_POINTER()).)
</para>
@object: the object that emits the signal.
-@signal:
+@name: name of the signal.
@func: function pointer to attach to the signal.
@func_data: pointer to pass to func.
@alive_object: object whose death should cause the handler connection
to be destroyed.
<!-- # Unused Parameters # -->
-@name: name of the signal.
+@signal:
<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
</para>
@object: the object associated with the signal.
-@signal:
+@name: name of the signal.
@func: function pointer to attach to the signal.
@alive_object: the user data, which must be an object, whose destruction
should signal the removal of this signal.
<!-- # Unused Parameters # -->
-@name: name of the signal.
+@signal:
<!-- ##### MACRO gtk_signal_disconnect ##### -->
<para>
-Destroy a user-defined handler connection.
+Destroys a user-defined handler connection.
</para>
@object: the object which the handler pertains to.
<!-- ##### MACRO gtk_signal_disconnect_by_func ##### -->
<para>
-Destroy all connections for a particular object, with
+Destroys all connections for a particular object, with
the given function-pointer and user-data.
</para>
<!-- ##### MACRO gtk_signal_disconnect_by_data ##### -->
<para>
-Destroy all connections for a particular object, with
+Destroys all connections for a particular object, with
the given user-data.
</para>
<!-- ##### MACRO gtk_signal_handler_block ##### -->
<para>
-Prevent an user-defined handler from being invoked. All other
+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>
<!-- ##### MACRO gtk_signal_handler_block_by_func ##### -->
<para>
-Prevent a user-defined handler from being invoked, by reference to
+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>
<!-- ##### MACRO gtk_signal_handler_block_by_data ##### -->
<para>
-Prevent all user-defined handlers with a certain user data from being invoked.
+Prevents all user-defined handlers with a certain user data from being invoked.
</para>
@object: the object which emits the signal we want to block.
<!-- ##### MACRO gtk_signal_handler_unblock ##### -->
<para>
-Undo a block, by connection id. Note that undoing a block doesn't
+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>
<!-- ##### MACRO gtk_signal_handler_unblock_by_func ##### -->
<para>
-Undo a block, by function pointer and data.
+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.
<!-- ##### MACRO gtk_signal_handler_unblock_by_data ##### -->
<para>
-Undo block(s), to all signals for a particular object
+Undoes block(s), to all signals for a particular object
with a particular user-data pointer
</para>
projects / ~andy / gtk / blobdiff