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