docs/reference/gobject/tmpl/signals.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Signals
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Signals provide a means for customization of object behaviour and are used
   6 as general purpose notification mechanism.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 The basic concept of the signal system is that of the @emission of a signal.
  11 Signals are introduced per-type and are identified through strings.
  12 Signals introduced for a parent type are availale in derived types as well,
  13 so basically they are a per-type facility that is inherited.
  14 A signal emission mainly involves invocation of a certain set of callbacks in
  15 precisely defined manner. There are two main categories of such callbacks,
  16 per-object
  17         <footnote><para> Although signals can deal with any kind of type, i'm
  18         referring to those types as "@object @types" in the following, simply
  19         because that is the context most users will encounter signals in.
  20         </para></footnote>
  21 ones and user provided ones.
  22 The per-object callbacks are most often referred to as "object method
  23 handler" or "default (signal) handler", while user provided callbacks are
  24 usually just called "signal handler".
  25 The object method handler is provided at signal creation time (this most
  26 frequently happens at the end of an object class' creation), while user
  27 provided handlers are frequently connected and disconnected to/from a certain
  28 signal on certain object instances.
  29 </para>
  30 <para>
  31 A signal emission consists of five stages, unless prematurely stopped:
  32 <variablelist>
  33   <varlistentry><term></term><listitem><para>
  34         1 - Invocation of the object method handler for @G_SIGNAL_RUN_FIRST signals
  35   </para></listitem></varlistentry>
  36   <varlistentry><term></term><listitem><para>
  37         2 - Invocation of normal user-provided signal handlers (@after flag @FALSE)
  38   </para></listitem></varlistentry>
  39   <varlistentry><term></term><listitem><para>
  40         3 - Invocation of the object method handler for @G_SIGNAL_RUN_LAST signals
  41   </para></listitem></varlistentry>
  42   <varlistentry><term></term><listitem><para>
  43         4 - Invocation of user provided signal handlers, connected with an @after flag of @TRUE
  44   </para></listitem></varlistentry>
  45   <varlistentry><term></term><listitem><para>
  46         5 - Invocation of the object method handler for @G_SIGNAL_RUN_CLEANUP signals
  47   </para></listitem></varlistentry>
  48 </variablelist>
  49 The user provided signal handlers are called in the order they were
  50 connected in.
  51 All handlers may prematurely stop a signal emission, and any number of
  52 handlers may be connected, disconnected, blocked or unblocked during
  53 a signal emission.
  54 There are certain criteria for skipping user handlers in stages 2 and 4
  55 of a signal emission.
  56 First, user handlers may be @blocked, blocked handlers are omitted
  57 during callback invocation, to return from the "blocked" state, a
  58 handler has to get unblocked exactly the same amount of times
  59 it has been blocked before.
  60 Second, upon emission of a @G_SIGNAL_DETAILED signal, an additional
  61 "detail" argument passed in to g_signal_emit() has to match the detail
  62 argument of the signal handler currently subject to invocation.
  63 Specification of no detail argument for signal handlers (omission of the
  64 detail part of the signal specification upon connection) serves as a
  65 wildcard and matches any detail argument passed in to emission.
  66 </para>
  67
  68 <!-- ##### SECTION See_Also ##### -->
  69 <para>
  70
  71 </para>
  72
  73 <!-- ##### STRUCT GSignalInvocationHint ##### -->
  74 <para>
  75 The @GSignalInvocationHint structure is used to pass on additional information
  76 to callbacks during a signal emission.
  77 </para>
  78
  79 @signal_id:     The signal id of the signal invoking the callback
  80 @detail:        The detail passed on for this emission
  81 @run_type:      The stage the signal emission is currently in, this
  82                 field will contain one of @G_SIGNAL_RUN_FIRST,
  83                 @G_SIGNAL_RUN_LAST or @G_SIGNAL_RUN_CLEANUP.
  84
  85 <!-- ##### USER_FUNCTION GSignalAccumulator ##### -->
  86 <para>
  87 The signal accumulator is a special callback function that can be used
  88 to collect return values of the various callbacks that are called
  89 during a signal emission. The signal accumulator is specified at signal
  90 creation time, if it is left NULL, no accumulation of callback return
  91 values is perfomed. The return value of signal emissions is then the
  92 value returned by the last callback.
  93 </para>
  94
  95 @ihint:         Signal invokation hint, see @GSignalInvocationHint
  96 @return_accu:   Accumulator to collect callback return values in, this
  97                 is the return value of the current signal emission
  98 @return_value:  The return value of the most recent callback function
  99 @Returns:       The accumulator function returns whether the signal emission
 100                 should be aborted. Returning @FALSE means to abort the
 101                 current emission and @TRUE is returned for continuation.
 102
 103
 104 <!-- ##### TYPEDEF GSignalCMarshaller ##### -->
 105 <para>
 106 This is the signature of marshaller functions, required to marshall
 107 arrays of parameter values to signal emissions into C language callback
 108 invocations. It is merely an alias to @GClosureMarshal since the @GClosure
 109 mechanism takes over responsibility of actuall function invocation for the
 110 signal system.
 111 </para>
 112
 113
 114 <!-- ##### USER_FUNCTION GSignalEmissionHook ##### -->
 115 <para>
 116
 117 </para>
 118
 119 @ihint:
 120 @n_param_values:
 121 @param_values:
 122 @Returns:
 123 <!-- # Unused Parameters # -->
 124 @signal_id:
 125 @n_values:
 126 @values:
 127
 128
 129 <!-- ##### ENUM GSignalFlags ##### -->
 130 <para>
 131 The signal flags are used to specify a signal's behaviour, the overrall
 132 signal description outlines how especially the RUN flags controll the
 133 stages of a signal emission.
 134 </para>
 135
 136 @G_SIGNAL_RUN_FIRST:   Invoke the object method handler in the first emission stage.
 137 @G_SIGNAL_RUN_LAST:    Invoke the object method handler in the third emission stage.
 138 @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
 139 @G_SIGNAL_NO_RECURSE:  Signals being emitted for an object while currently being in
 140                        emission for this very object will not be emitted recursively,
 141                        but instead cause the first emission to be restarted.
 142 @G_SIGNAL_DETAILED:    This signal supports "::detail" appendixes to the signal name
 143                        upon hanlder connections and emissions.
 144 @G_SIGNAL_ACTION:      Action signals are signals that may freely be emitted on alive
 145                        objects from user code via g_signal_emit() and friends, without
 146                        the need of being embedded into extra code that performs pre or
 147                        post emission adjustments on the object. They can also be thought
 148                        of as by third-party code generically callable obejct methods.
 149 @G_SIGNAL_NO_HOOKS:    No emissions hooks are supported for this signal.
 150
 151 <!-- ##### ENUM GSignalMatchType ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @G_SIGNAL_MATCH_ID:
 157 @G_SIGNAL_MATCH_DETAIL:
 158 @G_SIGNAL_MATCH_CLOSURE:
 159 @G_SIGNAL_MATCH_FUNC:
 160 @G_SIGNAL_MATCH_DATA:
 161 @G_SIGNAL_MATCH_UNBLOCKED:
 162
 163 <!-- ##### STRUCT GSignalQuery ##### -->
 164 <para>
 165 A structure holding in-depth information for a specific signal. It is
 166 filled in by the g_signal_query() function.
 167 </para>
 168
 169 @signal_id:     The signal id of the signal being querried, or 0 if the
 170                 signal to be querried was unknown
 171 @signal_name:   The signal name
 172 @itype:         The interface/instance type that this signal can be emitted for
 173 @signal_flags:  The signal flags as passed in to @g_signal_new()
 174 @return_type:   The return type for user callbacks
 175 @n_params:      The number of parameters that user callbacks take
 176 @param_types:   The individual parameter types for user callbacks, note that the
 177                 effective callback signature is:
 178 <msgtext><programlisting>
 179 @return_type callback (@gpointer     data1,
 180                       [@param_types param_names,]
 181                       @gpointer     data2);
 182 </programlisting></msgtext>
 183
 184 <!-- ##### FUNCTION g_signal_newc ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @signal_name:
 190 @itype:
 191 @signal_flags:
 192 @class_offset:
 193 @accumulator:
 194 @c_marshaller:
 195 @return_type:
 196 @n_params:
 197 @Varargs:
 198 @Returns:
 199
 200
 201 <!-- ##### FUNCTION g_signal_newv ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @signal_name:
 207 @itype:
 208 @signal_flags:
 209 @class_closure:
 210 @accumulator:
 211 @c_marshaller:
 212 @return_type:
 213 @n_params:
 214 @param_types:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION g_signal_new_valist ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @signal_name:
 224 @itype:
 225 @signal_flags:
 226 @class_closure:
 227 @accumulator:
 228 @c_marshaller:
 229 @return_type:
 230 @n_params:
 231 @args:
 232 @Returns:
 233
 234
 235 <!-- ##### FUNCTION g_signal_query ##### -->
 236 <para>
 237 Query the signal system for in-depth information about a
 238 specific signal. This function will fill in a user-provided
 239 structure to hold signal-specific information. If an invalid
 240 dignal id is passed in, the @signal_id member of the @GSignalQuery
 241 is 0. All members filled into the @GSignalQuery structure should
 242 be considered constant and have to be left untouched.
 243 </para>
 244
 245 @signal_id:     The signal id of the signal to query information for
 246 @query:         A user provided structure that is filled in with constant
 247                 values upon success.
 248
 249
 250 <!-- ##### FUNCTION g_signal_lookup ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @name:
 256 @itype:
 257 @Returns:
 258
 259
 260 <!-- ##### FUNCTION g_signal_name ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @signal_id:
 266 @Returns:
 267
 268
 269 <!-- ##### FUNCTION g_signal_list_ids ##### -->
 270 <para>
 271 List the signals by id, that a certain instance or interface type
 272 created. Further information about the signals can be aquired through
 273 g_signal_query().
 274 </para>
 275
 276 @itype:         Instance or interface type
 277 @n_ids:         Location to store the number of signal ids for @itype
 278 @Returns:       Newly allocated array of signal ids
 279
 280
 281 <!-- ##### FUNCTION g_signal_emit ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @instance:
 287 @signal_id:
 288 @detail:
 289 @Varargs:
 290
 291
 292 <!-- ##### FUNCTION g_signal_emit_by_name ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @instance:
 298 @detailed_signal:
 299 @Varargs:
 300
 301
 302 <!-- ##### FUNCTION g_signal_emitv ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @instance_and_params:
 308 @signal_id:
 309 @detail:
 310 @return_value:
 311
 312
 313 <!-- ##### FUNCTION g_signal_emit_valist ##### -->
 314 <para>
 315
 316 </para>
 317
 318 @instance:
 319 @signal_id:
 320 @detail:
 321 @var_args:
 322
 323
 324 <!-- ##### FUNCTION g_signal_connect_data ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @instance:
 330 @detailed_signal:
 331 @c_handler:
 332 @data:
 333 @destroy_data:
 334 @swapped:
 335 @after:
 336 @Returns:
 337
 338
 339 <!-- ##### FUNCTION g_signal_connect_object ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @instance:
 345 @detailed_signal:
 346 @c_handler:
 347 @gobject:
 348 @swapped:
 349 @after:
 350 @Returns:
 351
 352
 353 <!-- ##### FUNCTION g_signal_connect_closure ##### -->
 354 <para>
 355
 356 </para>
 357
 358 @instance:
 359 @detailed_signal:
 360 @closure:
 361 @after:
 362 @Returns:
 363 <!-- # Unused Parameters # -->
 364 @signal_id:
 365 @detail:
 366
 367
 368 <!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @instance:
 374 @signal_id:
 375 @detail:
 376 @closure:
 377 @after:
 378 @Returns:
 379
 380
 381 <!-- ##### FUNCTION g_signal_handler_block ##### -->
 382 <para>
 383 g_signal_handler_block() blocks a handler of an
 384 instance so it will not be called during any signal emissions
 385 unless it is unblocked again. Thus "blocking" a signal handler
 386 means to temporarily deactive it, a signal handler has to be
 387 unblocked exactly the same amount of times it has been blocked
 388 before to become active again.
 389 The @handler_id passed into g_signal_handler_block() has
 390 to be a valid signal handler id, connected to a signal of
 391 @instance.
 392 </para>
 393
 394 @instance:      The instance to block the signal handler of
 395 @handler_id:    Handler id of the handler to be blocked
 396
 397
 398 <!-- ##### FUNCTION g_signal_handler_unblock ##### -->
 399 <para>
 400 g_signal_handler_unblock() undoes the effect of a previous
 401 g_signal_handler_block() call. A blocked handler is skipped
 402 during signal emissions and will not be invoked, unblocking
 403 it (for exactly the amount of times it has been blocked before)
 404 reverts its "blocked" state, so the handler will be recognized
 405 by the signal system and is called upon future or currently
 406 ongoing signal emissions (since the order in which handlers are
 407 called during signal emissions is deterministic, whether the
 408 unblocked handler in question is called as part of a currently
 409 ongoing emission depends on how far that emission has proceeded
 410 yet).
 411 The @handler_id passed into g_signal_handler_unblock() has
 412 to be a valid id of a signal handler that is connected to a
 413 signal of @instance and is currently blocked.
 414 </para>
 415
 416 @instance:      The instance to unblock the signal handler of
 417 @handler_id:    Handler id of the handler to be unblocked
 418
 419
 420 <!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
 421 <para>
 422 g_signal_handler_disconnect() disconnects a handler from an
 423 instance so it will not be called during any future or currently
 424 ongoing emissions of the signal it has been connected to.
 425 The @handler_id becomes invalid and may be reused.
 426 The @handler_id passed into g_signal_handler_disconnect() has
 427 to be a valid signal handler id, connected to a signal of
 428 @instance.
 429 </para>
 430
 431 @instance:      The instance to remove the signal handler from
 432 @handler_id:    Handler id of the handler to be disconnected
 433
 434
 435 <!-- ##### FUNCTION g_signal_handler_find ##### -->
 436 <para>
 437 Find the first signal handler that matches certain selection criteria.
 438 The criteria mask is passed as an OR-ed combination of #GSignalMatchType
 439 flags, and the criteria values are passed as arguments.
 440 The match @mask has to be non-0 for successfull matches.
 441 If no handler was found, 0 is returned.
 442 </para>
 443
 444 @instance:      The instance owning the signal handler to be found
 445 @mask:          Mask indicating which of @signal_id, @detail,
 446                 @closure, @func and/or @data the handler has to match
 447 @signal_id:     Signal the handler has to be connected to
 448 @detail:        Signal detail the handler has to be connected to
 449 @closure:       The closure the handler will invoke
 450 @func:          The C closure callback of the handler (useless for non-C closures)
 451 @data:          The closure data of the handler's closure
 452 @Returns:       A valid non-0 signal handler id for a successfull match
 453
 454
 455 <!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
 456 <para>
 457 This function blocks all handlers on an instance that match a certain
 458 selection criteria. The criteria mask is passed as an OR-ed combination of
 459 #GSignalMatchType flags, and the criteria values are passed as arguments.
 460 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 461 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 462 If no handlers were found, 0 is returned, the number of blocked handlers
 463 otherwise.
 464 </para>
 465
 466 @instance:      The instance to block handlers from
 467 @mask:          Mask indicating which of @signal_id, @detail,
 468                 @closure, @func and/or @data the handlers have to match
 469 @signal_id:     Signal the handlers have to be connected to
 470 @detail:        Signal detail the handlers have to be connected to
 471 @closure:       The closure the handlers will invoke
 472 @func:          The C closure callback of the handlers (useless for non-C closures)
 473 @data:          The closure data of the handlers' closures
 474 @Returns:       The amount of handlers that got blocked
 475
 476
 477 <!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
 478 <para>
 479 This function unblocks all handlers on an instance that match a certain
 480 selection criteria. The criteria mask is passed as an OR-ed combination of
 481 #GSignalMatchType flags, and the criteria values are passed as arguments.
 482 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 483 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 484 If no handlers were found, 0 is returned, the number of unblocked handlers
 485 otherwise. The match criteria should not apply to any handlers that are
 486 not currently blocked.
 487 </para>
 488
 489 @instance:      The instance to unblock handlers from
 490 @mask:          Mask indicating which of @signal_id, @detail,
 491                 @closure, @func and/or @data the handlers have to match
 492 @signal_id:     Signal the handlers have to be connected to
 493 @detail:        Signal detail the handlers have to be connected to
 494 @closure:       The closure the handlers will invoke
 495 @func:          The C closure callback of the handlers (useless for non-C closures)
 496 @data:          The closure data of the handlers' closures
 497 @Returns:       The amount of handlers that got unblocked
 498
 499
 500 <!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
 501 <para>
 502 This function disconnects all handlers on an instance that match a certain
 503 selection criteria. The criteria mask is passed as an OR-ed combination of
 504 #GSignalMatchType flags, and the criteria values are passed as arguments.
 505 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 506 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 507 If no handlers were found, 0 is returned, the number of disconnected handlers
 508 otherwise.
 509 </para>
 510
 511 @instance:      The instance to remove handlers from
 512 @mask:          Mask indicating which of @signal_id, @detail,
 513                 @closure, @func and/or @data the handlers have to match
 514 @signal_id:     Signal the handlers have to be connected to
 515 @detail:        Signal detail the handlers have to be connected to
 516 @closure:       The closure the handlers will invoke
 517 @func:          The C closure callback of the handlers (useless for non-C closures)
 518 @data:          The closure data of the handlers' closures
 519 @Returns:       The amount of handlers that got disconnected
 520
 521
 522 <!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
 523 <para>
 524
 525 </para>
 526
 527 @instance:
 528 @signal_id:
 529 @detail:
 530 @may_be_blocked:
 531 @Returns:
 532
 533
 534 <!-- ##### FUNCTION g_signal_stop_emission ##### -->
 535 <para>
 536
 537 </para>
 538
 539 @instance:
 540 @signal_id:
 541 @detail:
 542
 543
 544 <!-- ##### FUNCTION g_signal_add_emission_hook_full ##### -->
 545 <para>
 546
 547 </para>
 548
 549 @signal_id:
 550 @closure:
 551 @Returns:
 552
 553
 554 <!-- ##### FUNCTION g_signal_remove_emission_hook ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @signal_id:
 560 @hook_id:
 561
 562
 563 <!-- ##### FUNCTION g_signal_parse_name ##### -->
 564 <para>
 565 Internal function to parse a signal names into its @signal_id
 566 and @detail quark.
 567 </para>
 568
 569 @detailed_signal:       A string of the form "signal-name::detail"
 570 @itype:                 The interface/instance type taht introduced "signal-name"
 571 @signal_id_p:           Location to store the signal id
 572 @detail_p:              Location to stroe the detail quark
 573 @force_detail_quark:    %TRUE forces creation of a GQuark for the detail
 574 @Returns:               Whether the signal name could successfully be parsed and
 575                         @signal_id_p and @detail_p contain valid return values.
 576
 577
 578 <!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
 579 <para>
 580
 581 </para>
 582
 583 @instance:
 584
 585
 586 <!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->
 587 <para>
 588
 589 </para>
 590
 591 @itype:
 592 @struct_offset:
 593 @Returns:
 594
 595