1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Object methods and callbacks
7 <!-- ##### SECTION Long_Description ##### -->
9 The GTK+ signal system merely proxies the GLib signal system now. For future
10 usage, direct use of the <link linkend="gobject-Signals">GSignal</link> API is recommended, this avoids significant
11 performance hits where #GtkArg structures have to be converted into #GValue<!-- -->s.
15 <title>What are signals?</title>
17 Signals are a way to get notification when something happens
18 and to customize object behavior according to the
20 Every <wordasword>signal</wordasword> is uniquely identified by a name,
21 "class_name::signal_name", where signal_name might be something like
22 "clicked" and class_name might be "GtkButton". Note that some other class
23 may also define a "clicked" callback, so long as it doesn't derive from
27 When they are created, they are also assigned a unique positive integer,
28 the signal id (1 is the first signal id- 0 is used to flag an error).
29 Each is also tied to an array of types that describes
30 the prototype of the function pointer(s) (handlers) you may
31 connect to the signal. Finally, every signal has
32 a default handler that is given by a function pointer
33 in its class structure: it is run by default whenever the
34 signal is emitted. (It is possible that a signal will
35 be emitted and a user-defined handler will prevent the default handler
39 Signals are used by everyone, but they are only
40 created on a per class basis -- so you should not call
41 call gtk_signal_new() unless you are writing
42 a new #GtkObject type. However, if you want to make a new signal
43 for an existing type, you may use gtk_object_class_user_signal_new()
44 to create a signal that doesn't correspond to a class's builtin
49 <title>How are signals used?</title>
51 There are two basic actions in the signal handling game.
52 If you want notification of an event, you must <emphasis>connect</emphasis>
53 a function pointer and a data pointer to that signal; the data pointer
54 will be passed as the last argument to the function (so long as you
55 are using the default marshalling functions).
56 You will receive a connection id, a unique positive integer
57 corresponding to that attachment.
60 Functions that want to notify the user of certain actions,
61 <emphasis>emit</emphasis> signals.
65 <title>Basic Terminology</title>
70 <listitem><para>A class method, e.g. GtkButton::clicked.
71 More precisely it is a unique class-branch/signal-name pair.
72 This means you may not define a signal handler for a class which
73 derives from #GtkButton that is called clicked,
74 but it is okay to share signals names if they are separate in
80 <term>default handler</term>
81 <listitem><para>The object's internal method which is invoked
82 when the signal is emitted.</para>
87 <term>user-defined handler</term>
88 <listitem><para>A function pointer and data connected
89 to a signal (for a particular object).</para>
90 <para>There are really two types: those which are connected
91 normally, and those which are connected by one
92 of the connect_after functions. The connect_after handlers
93 are always run after the default handler.</para>
94 <para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
100 <listitem><para>the whole process of emitting a signal,
101 including the invocation of all
102 the different handler types mentioned above.</para>
107 <term>signal id</term>
108 <listitem><para>The unique positive (nonzero) integer
109 used to identify a signal. It can be used instead of
110 a name to many functions for a slight performance
116 <term>connection id</term>
117 <listitem><para>The unique positive (nonzero) integer
118 used to identify the connection of a user-defined handler
119 to a signal. Notice that it is allowed to connect the
120 same function-pointer/user-data pair twice, so
121 there is no guarantee that a function-pointer/user-data
122 maps to a unique connection id.
130 <refsect2><title>A brief note on how they work.</title>
132 The functions responsible for translating an array of #GtkArgs
133 to your C compiler's normal semantics are called Marshallers.
134 They are identified by
135 gtk_marshal_<replaceable>return_value</replaceable>__<replaceable>parameter_list</replaceable>()
136 for example a C function returning a gboolean and taking a gint
137 can be invoked by using gtk_marshal_BOOL__INT().
138 Not all possibly combinations of return/params are available,
139 of course, so if you are writing a #GtkObject with parameters
140 you might have to write a marshaller.
144 <!-- ##### SECTION See_Also ##### -->
149 <term>#GtkObject</term>
150 <listitem><para>The base class for things which emit signals.</para></listitem>
154 <term><link linkend="gobject-Signals">GSignal</link></term>
155 <listitem><para>The GLib signal system.</para></listitem>
160 <!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
162 Use in place of <function>offsetof()</function>, which is used if it exists.
165 <!-- # Unused Parameters # -->
170 <!-- ##### ENUM GtkSignalRunType ##### -->
172 These configure the signal's emission. They control
173 whether the signal can be emitted recursively on an object
175 whether to run the default method before or after the user-defined handlers.
181 <term>GTK_RUN_FIRST</term>
182 <listitem><para>Run the default handler before the connected user-defined
188 <term>GTK_RUN_LAST</term>
189 <listitem><para>Run the default handler after the connected
190 user-defined handlers.
191 (Handlers registered as "after" always run after the default handler though)
196 <term>GTK_RUN_BOTH</term>
197 <listitem><para>Run the default handler twice,
198 once before the user-defined handlers,
205 <term>GTK_RUN_NO_RECURSE</term>
206 <listitem><para>Whether to prevent a handler or hook
207 from reemitting the signal from within itself.
209 emit the signal while it is running will result in the signal
210 emission being restarted once it is done with the current processing.
213 careful to avoid having two handlers endlessly reemitting signals,
214 gtk_signal_n_emissions() can be helpful.
219 <term>GTK_RUN_ACTION</term>
220 <listitem><para>The signal is an action you can
221 invoke without any particular setup or cleanup.
222 The signal is treated no differently, but some
223 other code can determine if the signal is appropriate to
224 delegate to user control. For example, key binding sets
225 only allow bindings of ACTION signals to keystrokes.
230 <term>GTK_RUN_NO_HOOKS</term>
231 <listitem><para>This prevents the connection of emission hooks
245 <!-- ##### FUNCTION gtk_signal_new ##### -->
247 Creates a new signal type. (This is usually done in the
251 @name: the event name for the signal, e.g. "clicked".
252 @signal_flags: a combination of #GTK_RUN flags
253 specifying detail of when the default handler is to be invoked.
254 You should at least specify #GTK_RUN_FIRST
256 @object_type: the type of object this signal pertains to.
257 It will also pertain to derivers of this type automatically.
258 @function_offset: How many bytes the function pointer is in
259 the class structure for this type. Used to invoke a class
261 @marshaller: the function to translate between an array
262 of GtkArgs and the native calling convention. Usually they
263 are identified just by the type of arguments they take:
264 for example, gtk_marshal_BOOL__STRING() describes a marshaller
265 which takes a string and returns a boolean value.
266 @return_val: the type of return value, or #GTK_TYPE_NONE for a signal
267 without a return value.
268 @n_args: the number of parameter the handlers may take.
269 @Varargs: a list of #GTK_TYPE_*, one for each parameter.
270 @Returns: the signal id.
271 @Deprecated: Use g_signal_new() instead.
274 <!-- ##### FUNCTION gtk_signal_newv ##### -->
276 Creates a new signal type. (This is usually done in a
280 This function take the types as an array, instead of a list
281 following the arguments. Otherwise the same as gtk_signal_new().
284 @name: the name of the signal to create.
285 @signal_flags: see gtk_signal_new().
286 @object_type: the type of #GtkObject to associate the signal with.
287 @function_offset: how many bytes the function pointer is in
288 the class structure for this type.
290 @return_val: the type of the return value, or #GTK_TYPE_NONE if
291 you don't want a return value.
292 @n_args: the number of parameters to the user-defined handlers.
293 @args: an array of #GtkType<!---->s, describing the prototype to
295 @Returns: the signal id.
296 @Deprecated: Use g_signal_newv() instead.
299 <!-- ##### MACRO gtk_signal_lookup ##### -->
301 Given the name of the signal and the type of object it connects
302 to, get the signal's identifying integer. Emitting the signal
303 by number is somewhat faster than using the name each time.
306 It also tries the ancestors of the given type.
309 @name: the signal's name, e.g. clicked.
310 @object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.
311 @Returns: the signal's identifying number, or 0 if no signal was found.
312 @Deprecated: Use g_signal_lookup() instead.
315 <!-- ##### MACRO gtk_signal_name ##### -->
317 Given the signal's identifier, finds its name.
320 Two different signals may have the same name, if they have differing types.
323 @signal_id: the signal's identifying number.
324 @Returns: the signal name, or %NULL if the signal number was invalid.
325 @Deprecated: Use g_signal_name() instead.
328 <!-- ##### FUNCTION gtk_signal_emit ##### -->
330 Emits a signal. This causes the default handler and user-defined
334 Here is what gtk_signal_emit() does:
337 1. Calls the default handler and the user-connected handlers.
338 The default handler will be called first if
339 #GTK_RUN_FIRST is set, and last if #GTK_RUN_LAST is set.
342 2. Calls all handlers connected with the "after" flag set.
345 @object: the object that emits the signal.
346 @signal_id: the signal identifier.
347 @Varargs: the parameters to the function, followed
348 by a pointer to the return type, if any.
349 @Deprecated: Use g_signal_emit() instead.
352 <!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
354 Emits a signal. This causes the default handler and user-connected
358 @object: the object that emits the signal.
359 @name: the name of the signal.
360 @Varargs: the parameters to the function, followed
361 by a pointer to the return type, if any.
362 @Deprecated: Use g_signal_emit_by_name() instead.
365 <!-- ##### FUNCTION gtk_signal_emitv ##### -->
367 Emits a signal. This causes the default handler and user-connected
368 handlers to be run. This differs from gtk_signal_emit() by taking
369 an array of GtkArgs instead of using C's varargs mechanism.
372 @object: the object to emit the signal to.
373 @signal_id: the signal identifier.
374 @args: an array of GtkArgs, one for each parameter,
375 followed by one which is a pointer to the return type.
376 @Deprecated: Use g_signal_emitv() instead.
379 <!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
381 Emits a signal by name. This causes the default handler and user-connected
382 handlers to be run. This differs from gtk_signal_emit() by taking
383 an array of GtkArgs instead of using C's varargs mechanism.
386 @object: the object to emit the signal to.
387 @name: the name of the signal.
388 @args: an array of GtkArgs, one for each parameter,
389 followed by one which is a pointer to the return type.
390 @Deprecated: Use g_signal_emitv() and g_signal_lookup() instead.
393 <!-- ##### MACRO gtk_signal_emit_stop ##### -->
395 This function aborts a signal's current emission.
398 It will prevent the default method from running,
399 if the signal was #GTK_RUN_LAST and you connected
400 normally (i.e. without the "after" flag).
403 It will print a warning if used on a signal which
407 @object: the object whose signal handlers you wish to stop.
408 @signal_id: the signal identifier, as returned by g_signal_lookup().
409 @Deprecated: Use g_signal_stop_emission() instead.
412 <!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
414 This function aborts a signal's current emission.
417 It is just like gtk_signal_emit_stop()
418 except it will lookup the signal id for you.
421 @object: the object whose signal handlers you wish to stop.
422 @name: the name of the signal you wish to stop.
423 @Deprecated: Use g_signal_stop_emission_by_name() instead.
426 <!-- ##### MACRO gtk_signal_connect ##### -->
428 Attaches a function pointer and user data to a signal for
432 The #GtkSignalFunction takes a #GtkObject as its first parameter.
433 It will be the same object as the one you're connecting
434 the hook to. The @func_data will be passed as the last parameter
438 All else being equal, signal handlers are invoked in the order
439 connected (see gtk_signal_emit() for the other details of
440 which order things are called in).
443 Here is how one passes an integer as user data,
444 for when you just want to specify a constant int
445 as parameter to your function:
449 static void button_clicked_int (GtkButton* button, gpointer func_data)
451 g_print ("button pressed: %d\n", GPOINTER_TO_INT (func_data));
454 /* By calling this function, you will make the g_print above
455 * execute, printing the number passed as `to_print'. */
456 static void attach_print_signal (GtkButton* button, gint to_print)
458 gtk_signal_connect (GTK_OBJECT (button), "clicked",
459 GTK_SIGNAL_FUNC (button_clicked_int),
460 GINT_TO_POINTER (to_print));
465 @object: the object associated with the signal, e.g. if a button
466 is getting pressed, this is that button.
467 @name: name of the signal.
468 @func: function pointer to attach to the signal.
469 @func_data: value to pass as to your function (through the marshaller).
470 @Returns: the connection id.
471 @Deprecated: Use g_signal_connect() instead.
474 <!-- ##### MACRO gtk_signal_connect_after ##### -->
476 Attaches a function pointer and user data to a signal
477 so that this handler will be called after the other handlers.
480 @object: the object associated with the signal.
481 @name: name of the signal.
482 @func: function pointer to attach to the signal.
483 @func_data: value to pass as to your function (through the marshaller).
484 @Returns: the unique identifier for this attachment: the connection id.
485 @Deprecated: Use g_signal_connect_after() instead.
488 <!-- ##### MACRO gtk_signal_connect_object ##### -->
490 This function is for registering a callback that will
491 call another object's callback. That is,
492 instead of passing the object which is responsible
493 for the event as the first parameter of the callback,
494 it is switched with the user data (so the object which emits
495 the signal will be the last parameter, which is where the
496 user data usually is).
499 This is useful for passing a standard function in as a callback.
500 For example, if you wanted a button's press to gtk_widget_show()
501 some widget, you could write:
505 gtk_signal_connect_object (button, "clicked", gtk_widget_show, window);
509 @object: the object which emits the signal.
510 @name: the name of the signal.
511 @func: the function to callback.
512 @slot_object: the object to pass as the first parameter to func.
513 (Though it pretends to take an object, you can
514 really pass any gpointer as the #slot_object .)
515 @Returns: the connection id.
516 @Deprecated: Use g_signal_connect_swapped() instead.
519 <!-- ##### MACRO gtk_signal_connect_object_after ##### -->
521 Attaches a signal hook to a signal, passing in an alternate
522 object as the first parameter, and guaranteeing
523 that the default handler and all normal
524 handlers are called first.
527 @object: the object associated with the signal.
528 @name: name of the signal.
529 @func: function pointer to attach to the signal.
530 @slot_object: the object to pass as the first parameter to #func.
531 @Returns: the connection id.
532 @Deprecated: Use g_signal_connect_data() instead, passing
533 <literal>G_CONNECT_AFTER|G_CONNECT_SWAPPED</literal> as @connect_flags.
536 <!-- ##### FUNCTION gtk_signal_connect_full ##### -->
538 Attaches a function pointer and user data to a signal with
542 @object: the object which emits the signal. For example, a button
543 in the button press signal.
544 @name: the name of the signal.
545 @func: function pointer to attach to the signal.
547 @data: the user data associated with the function.
548 @destroy_func: function to call when this particular hook is
550 @object_signal: whether this is an object signal-- basically an "object
551 signal" is one that wants its user_data and object fields switched,
552 which is useful for calling functions which operate on another
554 @after: whether to invoke the user-defined handler after the signal, or to let
555 the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST
557 @Returns: the connection id.
558 @Deprecated: Use g_signal_connect_data() instead.
561 <!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
563 Attaches a function pointer and another #GtkObject to a signal.
566 This function takes an object whose "destroy" signal
568 That way, you don't have to clean up the
569 signal handler when you destroy the object.
570 It is a little less efficient though.
573 (Instead you may call gtk_signal_disconnect_by_data(), if you want
574 to explicitly delete all attachments to this object. This
575 is perhaps not recommended since it could be confused
576 with an integer masquerading as a pointer (through GINT_TO_POINTER()).)
579 @object: the object that emits the signal.
580 @name: name of the signal.
581 @func: function pointer to attach to the signal.
582 @func_data: pointer to pass to func.
583 @alive_object: object whose death should cause the handler connection
585 @Deprecated: Use g_signal_connect_object() instead.
588 <!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
590 These signal connectors are for signals which refer to objects,
591 so they must not be called after the object is deleted.
594 Unlike gtk_signal_connect_while_alive(),
595 this swaps the object and user data, making it suitable for
596 use with functions which primarily operate on the user data.
599 This function acts just like gtk_signal_connect_object() except
600 it traps the "destroy" signal to prevent you from having to
601 clean up the handler.
604 @object: the object associated with the signal.
605 @name: name of the signal.
606 @func: function pointer to attach to the signal.
607 @alive_object: the user data, which must be an object, whose destruction
608 should signal the removal of this signal.
609 @Deprecated: Use g_signal_connect_object() instead, passing
610 <literal>G_CONNECT_SWAPPED</literal> as @connect_flags.
613 <!-- ##### MACRO gtk_signal_disconnect ##### -->
615 Destroys a user-defined handler connection.
618 @object: the object which the handler pertains to.
619 @handler_id: the connection id.
620 @Deprecated: Use g_signal_handler_disconnect() instead.
623 <!-- ##### MACRO gtk_signal_disconnect_by_func ##### -->
625 Destroys all connections for a particular object, with
626 the given function-pointer and user-data.
629 @object: the object which emits the signal.
630 @func: the function pointer to search for.
631 @data: the user data to search for.
632 @Deprecated: Use g_signal_handlers_disconnect_by_func() instead.
635 <!-- ##### MACRO gtk_signal_disconnect_by_data ##### -->
637 Destroys all connections for a particular object, with
641 @object: the object which emits the signal.
642 @data: the user data to search for.
643 @Deprecated: Use g_signal_handlers_disconnect_matched() instead.
646 <!-- ##### MACRO gtk_signal_handler_block ##### -->
648 Prevents a user-defined handler from being invoked. All other
649 signal processing will go on as normal, but this particular
650 handler will ignore it.
653 @object: the object which emits the signal to block.
654 @handler_id: the connection id.
655 @Deprecated: Use g_signal_handler_block() instead.
658 <!-- ##### MACRO gtk_signal_handler_block_by_func ##### -->
660 Prevents a user-defined handler from being invoked, by reference to
661 the user-defined handler's function pointer and user data. (It may result in
662 multiple hooks being blocked, if you've called connect multiple times.)
665 @object: the object which emits the signal to block.
666 @func: the function pointer of the handler to block.
667 @data: the user data of the handler to block.
668 @Deprecated: Use g_signal_handlers_block_by_func() instead.
671 <!-- ##### MACRO gtk_signal_handler_block_by_data ##### -->
673 Prevents all user-defined handlers with a certain user data from being invoked.
676 @object: the object which emits the signal we want to block.
677 @data: the user data of the handlers to block.
678 @Deprecated: Use g_signal_handlers_block_matched() instead.
681 <!-- ##### MACRO gtk_signal_handler_unblock ##### -->
683 Undoes a block, by connection id. Note that undoing a block doesn't
684 necessarily make the hook callable, because if you block a
685 hook twice, you must unblock it twice.
688 @object: the object which emits the signal we want to unblock.
689 @handler_id: the emission handler identifier, as returned by
690 gtk_signal_connect(), etc.
691 @Deprecated: Use g_signal_handler_unblock() instead.
694 <!-- ##### MACRO gtk_signal_handler_unblock_by_func ##### -->
696 Undoes a block, by function pointer and data.
697 Note that undoing a block doesn't
698 necessarily make the hook callable, because if you block a
699 hook twice, you must unblock it twice.
702 @object: the object which emits the signal we want to unblock.
703 @func: the function pointer to search for.
704 @data: the user data to search for.
705 @Deprecated: Use g_signal_handlers_unblock_by_func() instead.
708 <!-- ##### MACRO gtk_signal_handler_unblock_by_data ##### -->
710 Undoes block(s), to all signals for a particular object
711 with a particular user-data pointer
714 @object: the object which emits the signal we want to unblock.
715 @data: the user data to search for.
716 @Deprecated: Use g_signal_handlers_unblock_matched() instead.
719 <!-- ##### MACRO gtk_signal_handler_pending ##### -->
721 Returns a connection id corresponding to a given signal id and object.
724 One example of when you might use this is when the arguments
725 to the signal are difficult to compute. A class implementor
726 may opt to not emit the signal if no one is attached anyway,
727 thus saving the cost of building the arguments.
730 @object: the object to search for the desired user-defined handler.
731 @signal_id: the number of the signal to search for.
732 @may_be_blocked: whether it is acceptable to return a blocked
734 @Returns: the connection id, if a connection was found. 0 otherwise.
735 @Deprecated: Use g_signal_has_handler_pending() instead.
738 <!-- ##### MACRO gtk_signal_handler_pending_by_func ##### -->
740 Returns a connection id corresponding to a given signal id, object, function
741 pointer and user data.
744 @object: the object to search for the desired handler.
745 @signal_id: the number of the signal to search for.
746 @may_be_blocked: whether it is acceptable to return a blocked
748 @func: the function pointer to search for.
749 @data: the user data to search for.
750 @Returns: the connection id, if a handler was found. 0 otherwise.
753 <!-- ##### MACRO gtk_signal_default_marshaller ##### -->
755 A marshaller that returns void and takes no extra parameters.