1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Object methods and callbacks.
7 <!-- ##### SECTION Long_Description ##### -->
9 <title>What are signals?</title>
11 Signals are a way to get notification when something happens
12 and to customize object behavior according to the
14 Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,
15 "class_name::signal_name", where signal_name might be something like
16 "clicked" and class_name might be "GtkButton". Note that some other class
17 may also define a "clicked" callback, so long as it doesn't derive from
21 When they are created, they are also assigned a unique positive integer,
22 the signal id (1 is the first signal id- 0 is used to flag an error).
23 Each is also tied to an array of types that describes
24 the prototype of the function pointer(s) (handlers) you may
25 connect to the signal. Finally, every signal has
26 a default handler that is given by a function pointer
27 in its class structure: it is run by default whenever the
28 signal is emitted. (It is possible that a signal will
29 be emitted and a user-defined handler will prevent the default handler
33 Signals are used by everyone, but they are only
34 created on a per class basis-- so you should call
35 call gtk_signal_new() unless you are writing
36 a new #GtkObject type. However, if you want to make a new signal
37 for an existing type, you may use gtk_object_class_user_signal_new()
38 to create a signal that doesn't correspond to a class's builtin
43 <title>How are signals used?</title>
45 There are two basic actions in the signal handling game.
46 If you want notification of an event, you must <Emphasis>connect</Emphasis>
47 a function pointer and a data pointer to that signal; the data pointer
48 will be passed as the last argument to the function (so long as you
49 are using the default marshalling functions).
50 You will receive a connection id, a unique positive integer
51 corresponding to that attachment.
54 Functions that want to notify the user of certain actions,
55 <Emphasis>emit</Emphasis> signals.
59 <title>Basic Terminology</title>
64 <listitem><para>A class method, e.g. GtkButton::clicked.
65 More precisely it is a unique class-branch/signal-name pair.
66 This means you may not define a signal handler for a class which
67 derives from GtkButton that is called clicked,
68 but it is okay to share signals names if they are separate in
74 <term>default handler</term>
75 <listitem><para>The object's internal method which is invoked
76 when the signal is emitted.</para>
81 <term>user-defined handler</term>
82 <listitem><para>A function pointer and data connected
83 to a signal (for a particular object).</para>
84 <para>There are really two types: those which are connected
85 normally, and those which are connected by one
86 of the connect_after functions. The connect_after handlers
87 are always run after the default handler.</para>
88 <para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
94 <listitem><para>the whole process of emitting a signal,
95 including the invocation of all
96 the different handler types mentioned above.</para>
101 <term>signal id</term>
102 <listitem><para>The unique positive (nonzero) integer
103 used to identify a signal. It can be used instead of
104 a name to many functions for a slight performance
110 <term>connection id</term>
111 <listitem><para>The unique positive (nonzero) integer
112 used to identify the connection of a user-defined handler
113 to a signal. Notice that it is allowed to connect the
114 same function-pointer/user-data pair twice, so
115 there is no guarantee that a function-pointer/user-data
116 maps to a unique connection id.
124 <refsect2><title>A brief note on how they work.</title>
126 The functions responsible for translating an array of #GtkArgs
127 to your C compiler's normal semantics are called Marshallers.
128 They are identified by
129 gtk_marshal_return_value__parameter_list()
130 for example a C function returning a gboolean and taking a gint
131 can be invoked by using gtk_marshal_BOOL__INT().
132 Not all possibly combinations of return/params are available,
133 of course, so if you are writing a #GtkObject with parameters
134 you might have to write a marshaller.
138 <!-- ##### SECTION See_Also ##### -->
143 <term>#GtkObject</term>
144 <listitem><para>The base class for things which emit signals.</para></listitem>
150 <!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
155 <!-- # Unused Parameters # -->
160 <!-- ##### TYPEDEF GtkEmissionHook ##### -->
162 A simple function pointer to get invoked when the
163 signal is emitted. This allows you tie a hook to the signal type,
164 so that it will trap all emissions of that signal, from any object.
167 You may not attach these to signals created with the
168 #GTK_RUN_NO_HOOKS flag.
172 <!-- ##### ENUM GtkSignalRunType ##### -->
174 These configure the signal's emission. They control
175 whether the signal can be emitted recursively on an object
177 whether to run the default method before or after the user-defined handlers.
183 <term>GTK_RUN_FIRST</term>
184 <listitem><para>Run the default handler before the connected user-defined
190 <term>GTK_RUN_LAST</term>
191 <listitem><para>Run the default handler after the connected
192 user-defined handlers.
193 (Handlers registered as "after" always run after the default handler though)
198 <term>GTK_RUN_BOTH</term>
199 <listitem><para>Run the default handler twice,
200 once before the user-defined handlers,
207 <term>GTK_RUN_NO_RECURSE</term>
208 <listitem><para>Whether to prevent a handler or hook
209 from reemitting the signal from within itself.
211 emit the signal while it is running will result in the signal
212 emission being restarted once it is done with the current processing.
215 careful to avoid having two handlers endlessly reemitting signals,
216 gtk_signal_n_emissions() can be helpful.
221 <term>GTK_RUN_ACTION</term>
222 <listitem><para>The signal is an action you can
223 invoke without any particular setup or cleanup.
224 The signal is treated no differently, but some
225 other code can determine if the signal is appropriate to
226 delegate to user control. For example, key binding sets
227 only allow bindings of ACTION signals to keystrokes.
232 <term>GTK_RUN_NO_HOOKS</term>
233 <listitem><para>This prevents the connection of emission hooks
247 <!-- ##### FUNCTION gtk_signal_new ##### -->
249 Create a new signal type. (This is usually done in the
253 @name: the event name for the signal, e.g. "clicked".
254 @signal_flags: a combination of GTK_RUN flags
255 specifying detail of when the default handler is to be invoked.
256 You should at least specify #GTK_RUN_FIRST
258 @object_type: the type of object this signal pertains to.
259 It will also pertain to derivers of this type automatically.
260 @function_offset: How many bytes the function pointer is in
261 the class structure for this type. Used to invoke a class
263 @marshaller: the function to translate between an array
264 of GtkArgs and the native calling convention. Usually they
265 are identified just by the type of arguments they take:
266 for example, gtk_marshal_BOOL__STRING() describes a marshaller
267 which takes a string and returns a boolean value.
268 @return_val: the type of return value, or GTK_TYPE_NONE for a signal
269 without a return value.
271 @Varargs: a list of GTK_TYPE_*, one for each parameter.
272 @Returns: the signal id.
273 <!-- # Unused Parameters # -->
274 @nparams: the number of parameter the handlers may take.
277 <!-- ##### FUNCTION gtk_signal_newv ##### -->
279 Create a new signal type. (This is usually done in a
283 This function take the types as an array, instead of a list
284 following the arguments. Otherwise the same as gtk_signal_new().
287 @name: the name of the signal to create.
288 @signal_flags: see gtk_signal_new().
289 @object_type: the type of GtkObject to associate the signal with.
290 @function_offset: how many bytes the function pointer is in
291 the class structure for this type.
293 @return_val: the type of the return value, or GTK_TYPE_NONE if
294 you don't want a return value.
297 @Returns: the signal id.
298 <!-- # Unused Parameters # -->
299 @nparams: the number of parameters to the user-defined handlers.
300 @params: an array of GtkTypes, describing the prototype to
304 <!-- ##### MACRO gtk_signal_lookup ##### -->
306 Given the name of the signal and the type of object it connects
307 to, get the signal's identifying integer. Emitting the signal
308 by number is somewhat faster than using the name each time.
311 It also tries the ancestors of the given type.
314 @Returns: the signal's identifying number, or 0 if no signal was found.
315 <!-- # Unused Parameters # -->
316 @name: the signal's name, e.g. clicked.
317 @object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.
320 <!-- ##### MACRO gtk_signal_name ##### -->
322 Given the signal's identifier, find its name.
325 Two different signals may have the same name, if they have differing types.
328 @Returns: the signal name, or NULL if the signal number was invalid.
329 <!-- # Unused Parameters # -->
330 @signal_id: the signal's identifying number.
333 <!-- ##### FUNCTION gtk_signal_emit ##### -->
335 Emit a signal. This causes the default handler and user-defined
339 Here is what gtk_signal_emit() does:
342 1. Calls the default handler and the user-connected handlers.
343 The default handler will be called first if
344 GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.
347 2. Calls all handlers connected with the "after" flag set.
350 @object: the object that emits the signal.
351 @signal_id: the signal identifier.
352 @Varargs: the parameters to the function, followed
353 by a pointer to the return type, if any.
356 <!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
358 Emit a signal. This causes the default handler and user-connected
362 @object: the object that emits the signal.
363 @name: the name of the signal.
364 @Varargs: the parameters to the function, followed
365 by a pointer to the return type, if any.
368 <!-- ##### FUNCTION gtk_signal_emitv ##### -->
370 Emit a signal. This causes the default handler and user-connected
371 handlers to be run. This differs from gtk_signal_emit() by taking
372 an array of GtkArgs instead of using C's varargs mechanism.
375 @object: the object to emit the signal to.
376 @signal_id: the signal identifier.
378 <!-- # Unused Parameters # -->
379 @params: an array of GtkArgs, one for each parameter,
380 followed by one which is a pointer to the return type.
383 <!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
385 Emit a signal by name. This causes the default handler and user-connected
386 handlers to be run. This differs from gtk_signal_emit() by taking
387 an array of GtkArgs instead of using C's varargs mechanism.
390 @object: the object to emit the signal to.
391 @name: the name of the signal.
393 <!-- # Unused Parameters # -->
394 @params: an array of GtkArgs, one for each parameter,
395 followed by one which is a pointer to the return type.
398 <!-- ##### MACRO gtk_signal_emit_stop ##### -->
400 This function aborts a signal's current emission.
403 It will prevent the default method from running,
404 if the signal was #GTK_RUN_LAST and you connected
405 normally (i.e. without the "after" flag).
408 It will print a warning if used on a signal which
414 <!-- # Unused Parameters # -->
415 @object: the object whose signal handlers you wish to stop.
416 @signal_id: the signal identifier, as returned by gtk_signal_lookup().
419 <!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
421 This function aborts a signal's current emission.
423 <para>It is just like
424 gtk_signal_emit_stop()
425 except it will lookup the signal id for you.
428 @object: the object whose signal handlers you wish to stop.
429 @name: the name of the signal you wish to stop.
432 <!-- ##### MACRO gtk_signal_connect ##### -->
434 Attach a function pointer and user data to a signal for
438 The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.
439 It will be the same object as the one you're connecting
440 the hook to. The func_data will be passed as the last parameter
444 All else being equal, signal handlers are invoked in the order
445 connected (see gtk_signal_emit() for the other details of
446 which order things are called in).
449 Here is how one passes an integer as user data,
450 for when you just want to specify a constant int
451 as parameter to your function:
455 static void button_clicked_int(GtkButton* button, gpointer func_data)
457 g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));
460 /* By calling this function, you will make the g_print above
461 * execute, printing the number passed as `to_print'. */
462 static void attach_print_signal(GtkButton* button, gint to_print)
464 gtk_signal_connect(GTK_OBJECT(button), "clicked",
465 GTK_SIGNAL_FUNC(button_clicked_int),
466 GINT_TO_POINTER(to_print));
475 @Returns: the connection id.
476 <!-- # Unused Parameters # -->
477 @object: the object associated with the signal, e.g. if a button
478 is getting pressed, this is that button.
479 @name: name of the signal.
480 @func: function pointer to attach to the signal.
481 @func_data: value to pass as to your function (through the marshaller).
484 <!-- ##### MACRO gtk_signal_connect_after ##### -->
486 Attach a function pointer and user data to a signal
487 so that this handler will be called after the other handlers.
494 @Returns: the unique identifier for this attachment: the connection id.
495 <!-- # Unused Parameters # -->
496 @object: the object associated with the signal.
497 @name: name of the signal.
498 @func: function pointer to attach to the signal.
499 @func_data: value to pass as to your function (through the marshaller).
502 <!-- ##### MACRO gtk_signal_connect_object ##### -->
504 This function is for registering a callback that will
505 call another object's callback. That is,
506 instead of passing the object which is responsible
507 for the event as the first parameter of the callback,
508 it is switched with the user data (so the object which emits
509 the signal will be the last parameter, which is where the
510 user data usually is).
513 This is useful for passing a standard function in as a callback.
514 For example, if you wanted a button's press to gtk_widget_show()
515 some widget, you could write:
519 gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
527 @Returns: the connection id.
528 <!-- # Unused Parameters # -->
529 @object: the object which emits the signal.
530 @name: the name of the signal.
531 @func: the function to callback.
532 @slot_object: the object to pass as the first parameter to func.
533 (Though it pretends to take an object, you can
534 really pass any gpointer as the #slot_object .)
537 <!-- ##### MACRO gtk_signal_connect_object_after ##### -->
539 Attach a signal hook to a signal, passing in an alternate
540 object as the first parameter, and guaranteeing
541 that the default handler and all normal
542 handlers are called first.
549 @Returns: the connection id.
550 <!-- # Unused Parameters # -->
551 @object: the object associated with the signal.
552 @name: name of the signal.
553 @func: function pointer to attach to the signal.
554 @slot_object: the object to pass as the first parameter to #func.
557 <!-- ##### FUNCTION gtk_signal_connect_full ##### -->
559 Attach a function pointer and user data to a signal with
563 @object: the object which emits the signal. For example, a button
564 in the button press signal.
565 @name: the name of the signal.
566 @func: function pointer to attach to the signal.
568 @data: the user data associated with the function.
569 @destroy_func: function to call when this particular hook is
571 @object_signal: whether this is an object signal-- basically an "object
572 signal" is one that wants its user_data and object fields switched,
573 which is useful for calling functions which operate on another
575 @after: whether to invoke the user-defined handler after the signal, or to let
576 the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST
578 @Returns: the connection id.
579 <!-- # Unused Parameters # -->
580 @marshal: the function marshal, see the gtkmarshall documentation for
581 more details, but briefly: the marshaller is a function which takes
582 the #GtkObject which emits the signal, the user data, the number of the
583 arguments, and the array of arguments. It is responsible for
584 calling the function in the appropriate calling convention.
585 gtk_signal_default_marshaller is usually fine.
586 (This shows up, for example, when worrying about matching
587 c++ or other languages' calling conventions.)
590 <!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
592 Attach a function pointer and another GtkObject to a signal.
595 This function takes an object whose "destroy" signal
597 That way, you don't have to clean up the
598 signal handler when you destroy the object.
599 It is a little less efficient though.
602 (Instead you may call gtk_signal_disconnect_by_data(), if you want
603 to explicitly delete all attachments to this object. This
604 is perhaps not recommended since it could be confused
605 with an integer masquerading as a pointer (through GINT_AS_POINTER).)
608 @object: the object that emits the signal.
610 @func: function pointer to attach to the signal.
611 @func_data: pointer to pass to func.
612 @alive_object: object whose death should cause the handler connection
614 <!-- # Unused Parameters # -->
615 @name: name of the signal.
618 <!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
620 These signal connectors are for signals which refer to objects,
621 so they must not be called after the object is deleted.
624 Unlike gtk_signal_connect_while_alive(),
625 this swaps the object and user data, making it suitable for
626 use with functions which primarily operate on the user data.
629 This function acts just like gtk_signal_connect_object() except
630 it traps the "destroy" signal to prevent you from having to
631 clean up the handler.
634 @object: the object associated with the signal.
636 @func: function pointer to attach to the signal.
637 @alive_object: the user data, which must be an object, whose destruction
638 should signal the removal of this signal.
639 <!-- # Unused Parameters # -->
640 @name: name of the signal.
643 <!-- ##### MACRO gtk_signal_disconnect ##### -->
645 Destroy a user-defined handler connection.
648 <!-- # Unused Parameters # -->
649 @object: the object which the handler pertains to.
650 @handler_id: the connection id.
653 <!-- ##### MACRO gtk_signal_disconnect_by_func ##### -->
655 Destroy all connections for a particular object, with
656 the given function-pointer and user-data.
662 <!-- # Unused Parameters # -->
663 @object: the object which emits the signal.
664 @func: the function pointer to search for.
665 @data: the user data to search for.
668 <!-- ##### MACRO gtk_signal_disconnect_by_data ##### -->
670 Destroy all connections for a particular object, with
676 <!-- # Unused Parameters # -->
677 @object: the object which emits the signal.
678 @data: the user data to search for.
681 <!-- ##### MACRO gtk_signal_handler_block ##### -->
683 Prevent an user-defined handler from being invoked. All other
684 signal processing will go on as normal, but this particular
685 handler will ignore it.
688 <!-- # Unused Parameters # -->
689 @object: the object which emits the signal to block.
690 @handler_id: the connection id.
693 <!-- ##### MACRO gtk_signal_handler_block_by_func ##### -->
695 Prevent a user-defined handler from being invoked, by reference to
696 the user-defined handler's function pointer and user data. (It may result in
697 multiple hooks being blocked, if you've called connect multiple times.)
703 <!-- # Unused Parameters # -->
704 @object: the object which emits the signal to block.
705 @func: the function pointer of the handler to block.
706 @data: the user data of the handler to block.
709 <!-- ##### MACRO gtk_signal_handler_block_by_data ##### -->
711 Prevent all user-defined handlers with a certain user data from being invoked.
716 <!-- # Unused Parameters # -->
717 @object: the object which emits the signal we want to block.
718 @data: the user data of the handlers to block.
721 <!-- ##### MACRO gtk_signal_handler_unblock ##### -->
723 Undo a block, by connection id. Note that undoing a block doesn't
724 necessarily make the hook callable, because if you block a
725 hook twice, you must unblock it twice.
728 <!-- # Unused Parameters # -->
729 @object: the object which emits the signal we want to unblock.
730 @handler_id: the emission handler identifier, as returned by
731 gtk_signal_connect(), etc.
734 <!-- ##### MACRO gtk_signal_handler_unblock_by_func ##### -->
736 Undo a block, by function pointer and data.
737 Note that undoing a block doesn't
738 necessarily make the hook callable, because if you block a
739 hook twice, you must unblock it twice.
745 <!-- # Unused Parameters # -->
746 @object: the object which emits the signal we want to unblock.
747 @func: the function pointer to search for.
748 @data: the user data to search for.
751 <!-- ##### MACRO gtk_signal_handler_unblock_by_data ##### -->
753 Undo block(s), to all signals for a particular object
754 with a particular user-data pointer
759 <!-- # Unused Parameters # -->
760 @object: the object which emits the signal we want to unblock.
761 @data: the user data to search for.
764 <!-- ##### MACRO gtk_signal_handler_pending ##### -->
766 Returns a connection id corresponding to a given signal id and object.
769 One example of when you might use this is when the arguments
770 to the signal are difficult to compute. A class implementor
771 may opt to not emit the signal if no one is attached anyway,
772 thus saving the cost of building the arguments.
778 @Returns: the connection id, if a connection was found. 0 otherwise.
779 <!-- # Unused Parameters # -->
780 @object: the object to search for the desired user-defined handler.
781 @signal_id: the number of the signal to search for.
782 @may_be_blocked: whether it is acceptable to return a blocked
786 <!-- ##### MACRO gtk_signal_handler_pending_by_func ##### -->
788 Returns a connection id corresponding to a given signal id, object, function
789 pointer and user data.
797 @Returns: the connection id, if a handler was found. 0 otherwise.
798 <!-- # Unused Parameters # -->
799 @object: the object to search for the desired handler.
800 @signal_id: the number of the signal to search for.
801 @may_be_blocked: whether it is acceptable to return a blocked
803 @func: the function pointer to search for.
804 @data: the user data to search for.
807 <!-- ##### MACRO gtk_signal_add_emission_hook ##### -->
809 Add an emission hook for a type of signal, for any object.
815 @Returns: the id (that you may pass as a parameter
816 to gtk_signal_remove_emission_hook()).
817 <!-- # Unused Parameters # -->
818 @signal_id: the type of signal to hook for.
819 @hook_func: the function to invoke to handle the emission hook.
820 @data: the user data passed in to hook_func.
823 <!-- ##### MACRO gtk_signal_remove_emission_hook ##### -->
825 Delete an emission hook. (see gtk_signal_add_emission_hook())
830 <!-- # Unused Parameters # -->
831 @signal_id: the id of the signal type.
832 @hook_id: the id of the emission handler, returned by add_emission_hook().
835 <!-- ##### MACRO gtk_signal_default_marshaller ##### -->
837 A marshaller that returns void and takes no extra parameters.