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
 107 </para>
 108
 109
 110 <!-- ##### USER_FUNCTION GSignalEmissionHook ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @ihint:
 116 @n_param_values:
 117 @param_values:
 118 @Returns:
 119 <!-- # Unused Parameters # -->
 120 @signal_id:
 121 @n_values:
 122 @values:
 123
 124
 125 <!-- ##### ENUM GSignalFlags ##### -->
 126 <para>
 127
 128 </para>
 129
 130 @G_SIGNAL_RUN_FIRST:
 131 @G_SIGNAL_RUN_LAST:
 132 @G_SIGNAL_RUN_CLEANUP:
 133 @G_SIGNAL_NO_RECURSE:
 134 @G_SIGNAL_DETAILED:
 135 @G_SIGNAL_ACTION:
 136 @G_SIGNAL_NO_HOOKS:
 137
 138 <!-- ##### ENUM GSignalMatchType ##### -->
 139 <para>
 140
 141 </para>
 142
 143 @G_SIGNAL_MATCH_ID:
 144 @G_SIGNAL_MATCH_DETAIL:
 145 @G_SIGNAL_MATCH_CLOSURE:
 146 @G_SIGNAL_MATCH_FUNC:
 147 @G_SIGNAL_MATCH_DATA:
 148 @G_SIGNAL_MATCH_UNBLOCKED:
 149
 150 <!-- ##### STRUCT GSignalQuery ##### -->
 151 <para>
 152 A structure holding in-depth information for a specific signal. It is
 153 filled in by the g_signal_query() function.
 154 </para>
 155
 156 @signal_id:     The signal id of the signal being querried, or 0 if the
 157                 signal to be querried was unknown
 158 @signal_name:   The signal name
 159 @itype:         The interface/instance type that this signal can be emitted for
 160 @signal_flags:  The signal flags as passed in to @g_signal_new()
 161 @return_type:   The return type for user callbacks
 162 @n_params:      The number of parameters that user callbacks take
 163 @param_types:   The individual parameter types for user callbacks, note that the
 164                 effective callback signature is:
 165 <msgtext><programlisting>
 166 @return_type callback (@gpointer     data1,
 167                       [@param_types param_names,]
 168                       @gpointer     data2);
 169 </programlisting></msgtext>
 170
 171 <!-- ##### FUNCTION g_signal_newv ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @signal_name:
 177 @itype:
 178 @signal_flags:
 179 @class_closure:
 180 @accumulator:
 181 @c_marshaller:
 182 @return_type:
 183 @n_params:
 184 @param_types:
 185 @Returns:
 186
 187
 188 <!-- ##### FUNCTION g_signal_emitv ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @instance_and_params:
 194 @signal_id:
 195 @detail:
 196 @return_value:
 197
 198
 199 <!-- ##### FUNCTION g_signal_lookup ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @name:
 205 @itype:
 206 @Returns:
 207
 208
 209 <!-- ##### FUNCTION g_signal_name ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @signal_id:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION g_signal_query ##### -->
 219 <para>
 220 Query the signal system for in-depth information about a
 221 specific signal. This function will fill in a user-provided
 222 structure to hold signal-specific information. If an invalid
 223 dignal id is passed in, the @signal_id member of the @GSignalQuery
 224 is 0. All members filled into the @GSignalQuery structure should
 225 be considered constant and have to be left untouched.
 226 </para>
 227
 228 @signal_id:     The signal id of the signal to query information for
 229 @query:         A user provided structure that is filled in with constant
 230                 values upon success.
 231
 232
 233 <!-- ##### FUNCTION g_signal_list_ids ##### -->
 234 <para>
 235 List the signals by id, that a certain instance or interface type
 236 created. Further information about the signals can be aquired through
 237 g_signal_query().
 238 </para>
 239
 240 @itype:         Instance or interface type
 241 @n_ids:         Location to store the number of signal ids for @itype
 242 @Returns:       Newly allocated array of signal ids
 243
 244
 245 <!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @instance:
 251 @signal_id:
 252 @detail:
 253 @closure:
 254 @after:
 255 @Returns:
 256
 257
 258 <!-- ##### FUNCTION g_signal_handler_block ##### -->
 259 <para>
 260 g_signal_handler_block() blocks a handler of an
 261 instance so it will not be called during any signal emissions
 262 unless it is unblocked again. Thus "blocking" a signal handler
 263 means to temporarily deactive it, a signal handler has to be
 264 unblocked exactly the same amount of times it has been blocked
 265 before to become active again.
 266 The @handler_id passed into g_signal_handler_block() has
 267 to be a valid signal handler id, connected to a signal of
 268 @instance.
 269 </para>
 270
 271 @instance:      The instance to block the signal handler of
 272 @handler_id:    Handler id of the handler to be blocked
 273
 274
 275 <!-- ##### FUNCTION g_signal_handler_unblock ##### -->
 276 <para>
 277 g_signal_handler_unblock() undoes the effect of a previous
 278 g_signal_handler_block() call. A blocked handler is skipped
 279 during signal emissions and will not be invoked, unblocking
 280 it (for exactly the amount of times it has been blocked before)
 281 reverts its "blocked" state, so the handler will be recognized
 282 by the signal system and is called upon future or currently
 283 ongoing signal emissions (since the order in which handlers are
 284 called during signal emissions is deterministic, whether the
 285 unblocked handler in question is called as part of a currently
 286 ongoing emission depends on how far that emission has proceeded
 287 yet).
 288 The @handler_id passed into g_signal_handler_unblock() has
 289 to be a valid id of a signal handler that is connected to a
 290 signal of @instance and is currently blocked.
 291 </para>
 292
 293 @instance:      The instance to unblock the signal handler of
 294 @handler_id:    Handler id of the handler to be unblocked
 295
 296
 297 <!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
 298 <para>
 299 g_signal_handler_disconnect() disconnects a handler from an
 300 instance so it will not be called during any future or currently
 301 ongoing emissions of the signal it has been connected to.
 302 The @handler_id becomes invalid and may be reused.
 303 The @handler_id passed into g_signal_handler_disconnect() has
 304 to be a valid signal handler id, connected to a signal of
 305 @instance.
 306 </para>
 307
 308 @instance:      The instance to remove the signal handler from
 309 @handler_id:    Handler id of the handler to be disconnected
 310
 311
 312 <!-- ##### FUNCTION g_signal_handler_find ##### -->
 313 <para>
 314 Find the first signal handler that matches certain selection criteria.
 315 The criteria mask is passed as an OR-ed combination of #GSignalMatchType
 316 flags, and the criteria values are passed as arguments.
 317 The match @mask has to be non-0 for successfull matches.
 318 If no handler was found, 0 is returned.
 319 </para>
 320
 321 @instance:      The instance owning the signal handler to be found
 322 @mask:          Mask indicating which of @signal_id, @detail,
 323                 @closure, @func and/or @data the handler has to match
 324 @signal_id:     Signal the handler has to be connected to
 325 @detail:        Signal detail the handler has to be connected to
 326 @closure:       The closure the handler will invoke
 327 @func:          The C closure callback of the handler (useless for non-C closures)
 328 @data:          The closure data of the handler's closure
 329 @Returns:       A valid non-0 signal handler id for a successfull match
 330
 331
 332 <!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
 333 <para>
 334 This function blocks all handlers on an instance that match a certain
 335 selection criteria. The criteria mask is passed as an OR-ed combination of
 336 #GSignalMatchType flags, and the criteria values are passed as arguments.
 337 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 338 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 339 If no handlers were found, 0 is returned, the number of blocked handlers
 340 otherwise.
 341 </para>
 342
 343 @instance:      The instance to block handlers from
 344 @mask:          Mask indicating which of @signal_id, @detail,
 345                 @closure, @func and/or @data the handlers have to match
 346 @signal_id:     Signal the handlers have to be connected to
 347 @detail:        Signal detail the handlers have to be connected to
 348 @closure:       The closure the handlers will invoke
 349 @func:          The C closure callback of the handlers (useless for non-C closures)
 350 @data:          The closure data of the handlers' closures
 351 @Returns:       The amount of handlers that got blocked
 352
 353
 354 <!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
 355 <para>
 356 This function unblocks all handlers on an instance that match a certain
 357 selection criteria. The criteria mask is passed as an OR-ed combination of
 358 #GSignalMatchType flags, and the criteria values are passed as arguments.
 359 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 360 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 361 If no handlers were found, 0 is returned, the number of unblocked handlers
 362 otherwise. The match criteria should not apply to any handlers that are
 363 not currently blocked.
 364 </para>
 365
 366 @instance:      The instance to unblock handlers from
 367 @mask:          Mask indicating which of @signal_id, @detail,
 368                 @closure, @func and/or @data the handlers have to match
 369 @signal_id:     Signal the handlers have to be connected to
 370 @detail:        Signal detail the handlers have to be connected to
 371 @closure:       The closure the handlers will invoke
 372 @func:          The C closure callback of the handlers (useless for non-C closures)
 373 @data:          The closure data of the handlers' closures
 374 @Returns:       The amount of handlers that got unblocked
 375
 376
 377 <!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
 378 <para>
 379 This function disconnects all handlers on an instance that match a certain
 380 selection criteria. The criteria mask is passed as an OR-ed combination of
 381 #GSignalMatchType flags, and the criteria values are passed as arguments.
 382 Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
 383 or %G_SIGNAL_MATCH_DATA match flags is required for successfull matches.
 384 If no handlers were found, 0 is returned, the number of disconnected handlers
 385 otherwise.
 386 </para>
 387
 388 @instance:      The instance to remove handlers from
 389 @mask:          Mask indicating which of @signal_id, @detail,
 390                 @closure, @func and/or @data the handlers have to match
 391 @signal_id:     Signal the handlers have to be connected to
 392 @detail:        Signal detail the handlers have to be connected to
 393 @closure:       The closure the handlers will invoke
 394 @func:          The C closure callback of the handlers (useless for non-C closures)
 395 @data:          The closure data of the handlers' closures
 396 @Returns:       The amount of handlers that got disconnected
 397
 398
 399 <!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
 400 <para>
 401
 402 </para>
 403
 404 @instance:
 405 @signal_id:
 406 @detail:
 407 @may_be_blocked:
 408 @Returns:
 409
 410
 411 <!-- ##### FUNCTION g_signal_stop_emission ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @instance:
 417 @signal_id:
 418 @detail:
 419
 420
 421 <!-- ##### FUNCTION g_signal_type_closure_new ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @itype:
 427 @struct_offset:
 428 @Returns:
 429
 430
 431 <!-- ##### FUNCTION g_signal_add_emission_hook_full ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @signal_id:
 437 @closure:
 438 @Returns:
 439
 440
 441 <!-- ##### FUNCTION g_signal_remove_emission_hook ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @signal_id:
 447 @hook_id:
 448
 449
 450 <!-- ##### FUNCTION g_signal_parse_name ##### -->
 451 <para>
 452 Internal function to parse a signal names into its @signal_id
 453 and @detail quark.
 454 </para>
 455
 456 @detailed_signal:       A string of the form "signal-name::detail"
 457 @itype:                 The interface/instance type taht introduced "signal-name"
 458 @signal_id_p:           Location to store the signal id
 459 @detail_p:              Location to stroe the detail quark
 460 @force_detail_quark:    %TRUE forces creation of a GQuark for the detail
 461 @Returns:               Whether the signal name could successfully be parsed and
 462                         @signal_id_p and @detail_p contain valid return values.
 463
 464