docs/reference/gobject/html/signal.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Signals</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="chapter-signal.html" title="The GObject messaging system">
   9 <link rel="prev" href="chapter-signal.html" title="The GObject messaging system">
  10 <link rel="next" href="rn01.html" title="API Reference">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="chapter-signal.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="chapter-signal.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GObject Reference Manual</th>
  20 <td><a accesskey="n" href="rn01.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="sect1">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="signal"></a>Signals</h2></div></div></div>
  25 <p>
  26       GObject's signals have nothing to do with standard UNIX signals: they connect
  27       arbitrary application-specific events with any number of listeners.
  28       For example, in GTK+, every user event (keystroke or mouse move) is received
  29       from the X server and generates a GTK+ event under the form of a signal emission
  30       on a given object instance.
  31     </p>
  32 <p>
  33       Each signal is registered in the type system together with the type on which
  34       it can be emitted: users of the type are said to <span class="emphasis"><em>connect</em></span>
  35       to the signal on a given type instance when they register a closure to be
  36       invoked upon the signal emission. Users can also emit the signal by themselves
  37       or stop the emission of the signal from within one of the closures connected
  38       to the signal.
  39     </p>
  40 <p>
  41       When a signal is emitted on a given type instance, all the closures
  42       connected to this signal on this type instance will be invoked. All the closures
  43       connected to such a signal represent callbacks whose signature looks like:
  44 </p>
  45 <pre class="programlisting">
  46 return_type function_callback (gpointer instance, ... , gpointer user_data);
  47 </pre>
  48 <p>
  49     </p>
  50 <div class="sect2">
  51 <div class="titlepage"><div><div><h3 class="title">
  52 <a name="signal-registration"></a>Signal registration</h3></div></div></div>
  53 <p>
  54                 To register a new signal on an existing type, we can use any of <code class="function"><a class="link" href="gobject-Signals.html#g-signal-newv" title="g_signal_newv ()">g_signal_newv</a></code>,
  55                 <code class="function"><a class="link" href="gobject-Signals.html#g-signal-new-valist" title="g_signal_new_valist ()">g_signal_new_valist</a></code> or <code class="function"><a class="link" href="gobject-Signals.html#g-signal-new" title="g_signal_new ()">g_signal_new</a></code> functions:
  56 </p>
  57 <pre class="programlisting">
  58 guint g_signal_newv (const gchar        *signal_name,
  59                      GType               itype,
  60                      GSignalFlags        signal_flags,
  61                      GClosure           *class_closure,
  62                      GSignalAccumulator  accumulator,
  63                      gpointer            accu_data,
  64                      GSignalCMarshaller  c_marshaller,
  65                      GType               return_type,
  66                      guint               n_params,
  67                      GType              *param_types);
  68 </pre>
  69 <p>
  70                 The number of parameters to these functions is a bit intimidating but they are relatively
  71                 simple:
  72                 </p>
  73 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  74 <li class="listitem"><p>
  75                           signal_name: is a string which can be used to uniquely identify a given signal.
  76                         </p></li>
  77 <li class="listitem"><p>
  78                           itype: is the instance type on which this signal can be emitted.
  79                         </p></li>
  80 <li class="listitem"><p>
  81                           signal_flags: partly defines the order in which closures which were connected to the
  82                           signal are invoked.
  83                         </p></li>
  84 <li class="listitem"><p>
  85                           class_closure: this is the default closure for the signal: if it is not NULL upon
  86                           the signal emission, it will be invoked upon this emission of the signal. The
  87                           moment where this closure is invoked compared to other closures connected to that
  88                           signal depends partly on the signal_flags.
  89                         </p></li>
  90 <li class="listitem"><p>
  91                           accumulator: this is a function pointer which is invoked after each closure
  92                           has been invoked. If it returns FALSE, signal emission is stopped. If it returns
  93                           TRUE, signal emission proceeds normally. It is also used to compute the return
  94                           value of the signal based on the return value of all the invoked closures.
  95                         </p></li>
  96 <li class="listitem"><p>
  97                           accumulator_data: this pointer will be passed down to each invocation of the
  98                           accumulator during emission.
  99                         </p></li>
 100 <li class="listitem"><p>
 101                           c_marshaller: this is the default C marshaller for any closure which is connected to
 102                         this signal.
 103                         </p></li>
 104 <li class="listitem"><p>
 105                           return_type: this is the type of the return value of the signal.
 106                         </p></li>
 107 <li class="listitem"><p>
 108                           n_params: this is the number of parameters this signal takes.
 109                         </p></li>
 110 <li class="listitem"><p>
 111                           param_types: this is an array of GTypes which indicate the type of each parameter
 112                           of the signal. The length of this array is indicated by n_params.
 113                         </p></li>
 114 </ul></div>
 115 <p>
 116       </p>
 117 <p>
 118                 As you can see from the above definition, a signal is basically a description
 119                 of the closures which can be connected to this signal and a description of the
 120                 order in which the closures connected to this signal will be invoked.
 121           </p>
 122 </div>
 123 <div class="sect2">
 124 <div class="titlepage"><div><div><h3 class="title">
 125 <a name="signal-connection"></a>Signal connection</h3></div></div></div>
 126 <p>
 127                 If you want to connect to a signal with a closure, you have three possibilities:
 128                 </p>
 129 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 130 <li class="listitem"><p>
 131                   You can register a class closure at signal registration: this is a
 132                   system-wide operation. i.e.: the class_closure will be invoked during each emission
 133                   of a given signal on all the instances of the type which supports that signal.
 134                         </p></li>
 135 <li class="listitem"><p>
 136                   You can use <code class="function"><a class="link" href="gobject-Signals.html#g-signal-override-class-closure" title="g_signal_override_class_closure ()">g_signal_override_class_closure</a></code> which
 137                   overrides the class_closure of a given type. It is possible to call this function
 138                   only on a derived type of the type on which the signal was registered.
 139                   This function is of use only to language bindings.
 140                         </p></li>
 141 <li class="listitem"><p>
 142                   You can register a closure with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code>
 143                   family of functions. This is an instance-specific operation: the closure
 144                   will be invoked only during emission of a given signal on a given instance.
 145                         </p></li>
 146 </ul></div>
 147 <p>
 148                 It is also possible to connect a different kind of callback on a given signal:
 149                 emission hooks are invoked whenever a given signal is emitted whatever the instance on
 150                 which it is emitted. Emission hooks are used for example to get all mouse_clicked
 151                 emissions in an application to be able to emit the small mouse click sound.
 152                 Emission hooks are connected with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-add-emission-hook" title="g_signal_add_emission_hook ()">g_signal_add_emission_hook</a></code>
 153                 and removed with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-remove-emission-hook" title="g_signal_remove_emission_hook ()">g_signal_remove_emission_hook</a></code>.
 154           </p>
 155 </div>
 156 <div class="sect2">
 157 <div class="titlepage"><div><div><h3 class="title">
 158 <a name="signal-emission"></a>Signal emission</h3></div></div></div>
 159 <p>
 160                 Signal emission is done through the use of the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit" title="g_signal_emit ()">g_signal_emit</a></code> family
 161                 of functions.
 162 </p>
 163 <pre class="programlisting">
 164 void g_signal_emitv (const GValue *instance_and_params,
 165                      guint         signal_id,
 166                      GQuark        detail,
 167                      GValue       *return_value);
 168 </pre>
 169 <p>
 170                 </p>
 171 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 172 <li class="listitem"><p>
 173                         The instance_and_params array of GValues contains the list of input
 174                         parameters to the signal. The first element of the array is the
 175                         instance pointer on which to invoke the signal. The following elements of
 176                         the array contain the list of parameters to the signal.
 177                         </p></li>
 178 <li class="listitem"><p>
 179                         signal_id identifies the signal to invoke.
 180                         </p></li>
 181 <li class="listitem"><p>
 182                         detail identifies the specific detail of the signal to invoke. A detail is a kind of
 183                         magic token/argument which is passed around during signal emission and which is used
 184                         by closures connected to the signal to filter out unwanted signal emissions. In most
 185                         cases, you can safely set this value to zero. See <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The <span class="emphasis"><em>detail</em></span> argument”</a> for
 186                         more details about this parameter.
 187                         </p></li>
 188 <li class="listitem"><p>
 189                         return_value holds the return value of the last closure invoked during emission if
 190                         no accumulator was specified. If an accumulator was specified during signal creation,
 191                         this accumulator is used to calculate the return_value as a function of the return
 192                         values of all the closures invoked during emission.
 193                         <sup>[<a name="idp36611392" href="#ftn.idp36611392" class="footnote">8</a>]</sup>
 194                         If no closure is invoked during
 195                         emission, the return_value is nonetheless initialized to zero/null.
 196                         </p></li>
 197 </ul></div>
 198 <p>
 199                 </p>
 200 <p>
 201                 Internally, the GValue array is passed to the emission function proper,
 202                 <code class="function">signal_emit_unlocked_R</code> (implemented in <code class="filename">gsignal.c</code>).
 203                 Signal emission can be decomposed in 5 steps:
 204                 </p>
 205 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 206 <li class="listitem"><p>
 207                         <span class="emphasis"><em>RUN_FIRST</em></span>: if the G_SIGNAL_RUN_FIRST flag was used
 208                         during signal registration and if there exist a class_closure for this signal,
 209                         the class_closure is invoked. Jump to <span class="emphasis"><em>EMISSION_HOOK</em></span> state.
 210                         </p></li>
 211 <li class="listitem"><p>
 212                         <span class="emphasis"><em>EMISSION_HOOK</em></span>: if any emission hook was added to
 213                         the signal, they are invoked from first to last added. Accumulate return values
 214                         and jump to <span class="emphasis"><em>HANDLER_RUN_FIRST</em></span> state.
 215                         </p></li>
 216 <li class="listitem"><p>
 217                         <span class="emphasis"><em>HANDLER_RUN_FIRST</em></span>: if any closure were connected
 218                         with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code> family of
 219                         functions, and if they are not blocked (with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-handler-block" title="g_signal_handler_block ()">g_signal_handler_block</a></code>
 220                         family of functions) they are run here, from first to last connected.
 221                         Jump to <span class="emphasis"><em>RUN_LAST</em></span> state.
 222                         </p></li>
 223 <li class="listitem"><p>
 224                         <span class="emphasis"><em>RUN_LAST</em></span>: if the G_SIGNAL_RUN_LAST
 225                         flag was set during registration and if a class_closure
 226                         was set, it is invoked here. Jump to
 227                         <span class="emphasis"><em>HANDLER_RUN_LAST</em></span> state.
 228                         </p></li>
 229 <li class="listitem"><p>
 230                         <span class="emphasis"><em>HANDLER_RUN_LAST</em></span>: if any closure were connected
 231                         with the <code class="function">g_signal_connect_after</code> family of
 232                         functions, if they were not invoked during HANDLER_RUN_FIRST and if they
 233                         are not blocked, they are run here, from first to last connected.
 234                         Jump to  <span class="emphasis"><em>RUN_CLEANUP</em></span> state.
 235                         </p></li>
 236 <li class="listitem"><p>
 237                         <span class="emphasis"><em>RUN_CLEANUP</em></span>: if the G_SIGNAL_RUN_CLEANUP flag
 238                         was set during registration and if a class_closure was set,
 239                         it is invoked here. Signal emission is completed here.
 240                         </p></li>
 241 </ul></div>
 242 <p>
 243           </p>
 244 <p>
 245                 If, at any point during emission (except in RUN_CLEANUP state), one of the
 246                 closures or emission hook stops the signal emission with
 247                 <code class="function"><a class="link" href="gobject-Signals.html#g-signal-stop-emission" title="g_signal_stop_emission ()">g_signal_stop_emission</a></code>,
 248                 emission jumps to CLEANUP state.
 249           </p>
 250 <p>
 251                 If, at any point during emission, one of the closures or emission hook
 252                 emits the same signal on the same instance, emission is restarted from
 253                 the RUN_FIRST state.
 254           </p>
 255 <p>
 256                 The accumulator function is invoked in all states, after invocation
 257                 of each closure (except in EMISSION_HOOK and CLEANUP). It accumulates
 258                 the closure return value into the signal return value and returns TRUE or
 259                 FALSE. If, at any point, it does not return TRUE, emission jumps to CLEANUP state.
 260           </p>
 261 <p>
 262                 If no accumulator function was provided, the value returned by the last handler
 263                 run will be returned by <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit" title="g_signal_emit ()">g_signal_emit</a></code>.
 264           </p>
 265 </div>
 266 <div class="sect2">
 267 <div class="titlepage"><div><div><h3 class="title">
 268 <a name="signal-detail"></a>The <span class="emphasis"><em>detail</em></span> argument</h3></div></div></div>
 269 <p>All the functions related to signal emission or signal connection have a parameter
 270                 named the <span class="emphasis"><em>detail</em></span>. Sometimes, this parameter is hidden by the API
 271                 but it is always there, under one form or another.
 272           </p>
 273 <p>
 274             Of the three main connection functions,
 275                 only one has an explicit detail parameter as a <a href="./../glib/glib/glib-Quarks.html#GQuark"><span class="type">GQuark</span></a>
 276                 <sup>[<a name="idp36635936" href="#ftn.idp36635936" class="footnote">9</a>]</sup>:
 277 </p>
 278 <pre class="programlisting">
 279 gulong     g_signal_connect_closure_by_id          (gpointer          instance,
 280                            guint          signal_id,
 281                            GQuark          detail,
 282                            GClosure         *closure,
 283                            gboolean          after);
 284 </pre>
 285 <p>
 286         The two other functions hide the detail parameter in the signal name identification:
 287 </p>
 288 <pre class="programlisting">
 289 gulong     g_signal_connect_closure          (gpointer          instance,
 290                            const gchar       *detailed_signal,
 291                            GClosure         *closure,
 292                            gboolean          after);
 293 gulong     g_signal_connect_data              (gpointer          instance,
 294                            const gchar     *detailed_signal,
 295                            GCallback      c_handler,
 296                            gpointer          data,
 297                            GClosureNotify      destroy_data,
 298                            GConnectFlags      connect_flags);
 299 </pre>
 300 <p>
 301                 Their detailed_signal parameter is a string which identifies the name of the signal
 302                 to connect to. However, the format of this string is structured to look like
 303                 <span class="emphasis"><em>signal_name::detail_name</em></span>. Connecting to the signal
 304                 named <span class="emphasis"><em>notify::cursor_position</em></span> will actually connect to the signal
 305                 named <span class="emphasis"><em>notify</em></span> with the <span class="emphasis"><em>cursor_position</em></span> name.
 306                 Internally, the detail string is transformed to a GQuark if it is present.
 307           </p>
 308 <p>
 309                 Of the four main signal emission functions, three have an explicit detail parameter as a
 310                 <a href="./../glib/glib/glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> again:
 311 </p>
 312 <pre class="programlisting">
 313 void                  g_signal_emitv        (const GValue       *instance_and_params,
 314                          guint               signal_id,
 315                          GQuark              detail,
 316                          GValue             *return_value);
 317 void                  g_signal_emit_valist  (gpointer            instance,
 318                          guint               signal_id,
 319                          GQuark              detail,
 320                          va_list             var_args);
 321 void                  g_signal_emit         (gpointer            instance,
 322                          guint               signal_id,
 323                          GQuark              detail,
 324                          ...);
 325 </pre>
 326 <p>
 327         The fourth function hides it in its signal name parameter:
 328 </p>
 329 <pre class="programlisting">
 330 void                  g_signal_emit_by_name (gpointer            instance,
 331                          const gchar        *detailed_signal,
 332                          ...);
 333 </pre>
 334 <p>
 335         The format of the detailed_signal parameter is exactly the same as the format used by
 336         the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code> functions: <span class="emphasis"><em>signal_name::detail_name</em></span>.
 337           </p>
 338 <p>
 339         If a detail is provided by the user to the emission function, it is used during emission to match
 340         against the closures which also provide a detail.
 341         If the closures' detail does not match the detail provided by the user, they will not be invoked
 342         (even though they are connected to a signal which is being emitted).
 343           </p>
 344 <p>
 345                 This completely optional filtering mechanism is mainly used as an optimization for signals
 346                 which are often emitted for many different reasons: the clients can filter out which events they are
 347                 interested in before the closure's marshalling code runs. For example, this is used extensively
 348                 by the <span class="emphasis"><em>notify</em></span> signal of GObject: whenever a property is modified on a GObject,
 349                 instead of just emitting the <span class="emphasis"><em>notify</em></span> signal, GObject associates as a detail to this
 350                 signal emission the name of the property modified. This allows clients who wish to be notified of changes
 351                 to only one property to filter most events before receiving them.
 352           </p>
 353 <p>
 354                 As a simple rule, users can and should set the detail parameter to zero: this will disable completely
 355         this optional filtering.
 356           </p>
 357 </div>
 358 <div class="footnotes">
 359 <br><hr width="100" align="left">
 360 <div class="footnote"><p><sup>[<a id="ftn.idp36611392" href="#idp36611392" class="para">8</a>] </sup>
 361                           James (again!!) gives a few non-trivial examples of accumulators:
 362                           <span class="quote">“<span class="quote">
 363                                 For instance, you may have an accumulator that ignores NULL returns from
 364                                 closures, and only accumulates the non-NULL ones. Another accumulator may try
 365                                 to return the list of values returned by the closures.
 366                           </span>”</span>
 367                         </p></div>
 368 <div class="footnote"><p><sup>[<a id="ftn.idp36635936" href="#idp36635936" class="para">9</a>] </sup>A GQuark is an integer which uniquely represents a string. It is possible to transform
 369                    back and forth between the integer and string representations with the functions
 370                    <code class="function"><a href="./../glib/glib/glib-Quarks.html#g-quark-from-string">g_quark_from_string</a></code> and <code class="function"><a href="./../glib/glib/glib-Quarks.html#g-quark-to-string">g_quark_to_string</a></code>.
 371                   </p></div>
 372 </div>
 373 </div>
 374 <div class="footer">
 375 <hr>
 376           Generated by GTK-Doc V1.18</div>
 377 </body>
 378 </html>