gobject/gsignal.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 2000-2001 Red Hat, Inc.
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19 #ifndef __G_SIGNAL_H__
  20 #define __G_SIGNAL_H__
  21
  22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
  23 #error "Only <glib-object.h> can be included directly."
  24 #endif
  25
  26 #include        <gobject/gclosure.h>
  27 #include        <gobject/gvalue.h>
  28 #include        <gobject/gparam.h>
  29 #include        <gobject/gmarshal.h>
  30
  31 G_BEGIN_DECLS
  32
  33 /* --- typedefs --- */
  34 typedef struct _GSignalQuery             GSignalQuery;
  35 typedef struct _GSignalInvocationHint    GSignalInvocationHint;
  36 /**
  37  * GSignalCMarshaller:
  38  *
  39  * This is the signature of marshaller functions, required to marshall
  40  * arrays of parameter values to signal emissions into C language callback
  41  * invocations.
  42  *
  43  * It is merely an alias to #GClosureMarshal since the #GClosure mechanism
  44  * takes over responsibility of actual function invocation for the signal
  45  * system.
  46  */
  47 typedef GClosureMarshal                  GSignalCMarshaller;
  48 /**
  49  * GSignalCVaMarshaller:
  50  *
  51  * This is the signature of va_list marshaller functions, an optional
  52  * marshaller that can be used in some situations to avoid
  53  * marshalling the signal argument into GValues.
  54  */
  55 typedef GVaClosureMarshal                GSignalCVaMarshaller;
  56 /**
  57  * GSignalEmissionHook:
  58  * @ihint: Signal invocation hint, see #GSignalInvocationHint.
  59  * @n_param_values: the number of parameters to the function, including
  60  *  the instance on which the signal was emitted.
  61  * @param_values: (array length=n_param_values): the instance on which
  62  *  the signal was emitted, followed by the parameters of the emission.
  63  * @data: user data associated with the hook.
  64  *
  65  * A simple function pointer to get invoked when the signal is emitted.
  66  *
  67  * Emission hooks allow you to tie a hook to the signal type, so that it will
  68  * trap all emissions of that signal, from any object.
  69  *
  70  * You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag.
  71  *
  72  * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
  73  *  hook is disconnected (and destroyed).
  74  */
  75 typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint,
  76                                          guint                  n_param_values,
  77                                          const GValue          *param_values,
  78                                          gpointer               data);
  79 /**
  80  * GSignalAccumulator:
  81  * @ihint: Signal invocation hint, see #GSignalInvocationHint.
  82  * @return_accu: Accumulator to collect callback return values in, this
  83  *  is the return value of the current signal emission.
  84  * @handler_return: A #GValue holding the return value of the signal handler.
  85  * @data: Callback data that was specified when creating the signal.
  86  *
  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.
  90  *
  91  * The signal accumulator is specified at signal creation time, if it is
  92  * left %NULL, no accumulation of callback return values is performed.
  93  * The return value of signal emissions is then the value returned by the
  94  * last callback.
  95  *
  96  * Returns: The accumulator function returns whether the signal emission
  97  *  should be aborted. Returning %TRUE will continue with
  98  *  the signal emission. Returning %FALSE will abort the current emission.
  99  *  Since 2.62, returning %FALSE will skip to the CLEANUP stage. In this case,
 100  *  emission will occur as normal in the CLEANUP stage and the handler's
 101  *  return value will be accumulated.
 102  */
 103 typedef gboolean (*GSignalAccumulator)  (GSignalInvocationHint *ihint,
 104                                          GValue                *return_accu,
 105                                          const GValue          *handler_return,
 106                                          gpointer               data);
 107
 108
 109 /* --- run, match and connect types --- */
 110 /**
 111  * GSignalFlags:
 112  * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
 113  * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
 114  * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
 115  * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in
 116  *  emission for this very object will not be emitted recursively,
 117  *  but instead cause the first emission to be restarted.
 118  * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name
 119  *  upon handler connections and emissions.
 120  * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive
 121  *  objects from user code via g_signal_emit() and friends, without
 122  *  the need of being embedded into extra code that performs pre or
 123  *  post emission adjustments on the object. They can also be thought
 124  *  of as object methods which can be called generically by
 125  *  third-party code.
 126  * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
 127  * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the
 128  *   arguments, even if there are no signal handlers connected.  Since 2.30.
 129  * @G_SIGNAL_DEPRECATED: The signal is deprecated and will be removed
 130  *   in a future version. A warning will be generated if it is connected while
 131  *   running with G_ENABLE_DIAGNOSTIC=1.  Since 2.32.
 132  * @G_SIGNAL_ACCUMULATOR_FIRST_RUN: Only used in #GSignalAccumulator accumulator
 133  *   functions for the #GSignalInvocationHint::run_type field to mark the first
 134  *   call to the accumulator function for a signal emission.  Since 2.68.
 135  *
 136  * The signal flags are used to specify a signal's behaviour.
 137  */
 138 typedef enum
 139 {
 140   G_SIGNAL_RUN_FIRST    = 1 << 0,
 141   G_SIGNAL_RUN_LAST     = 1 << 1,
 142   G_SIGNAL_RUN_CLEANUP  = 1 << 2,
 143   G_SIGNAL_NO_RECURSE   = 1 << 3,
 144   G_SIGNAL_DETAILED     = 1 << 4,
 145   G_SIGNAL_ACTION       = 1 << 5,
 146   G_SIGNAL_NO_HOOKS     = 1 << 6,
 147   G_SIGNAL_MUST_COLLECT = 1 << 7,
 148   G_SIGNAL_DEPRECATED   = 1 << 8,
 149   /* normal signal flags until 1 << 16 */
 150   G_SIGNAL_ACCUMULATOR_FIRST_RUN    = 1 << 17,
 151 } GSignalFlags;
 152 /**
 153  * G_SIGNAL_FLAGS_MASK:
 154  *
 155  * A mask for all #GSignalFlags bits.
 156  */
 157 #define G_SIGNAL_FLAGS_MASK  0x1ff
 158 /**
 159  * GConnectFlags:
 160  * @G_CONNECT_DEFAULT: Default behaviour (no special flags). Since: 2.74
 161  * @G_CONNECT_AFTER: If set, the handler should be called after the
 162  *  default handler of the signal. Normally, the handler is called before
 163  *  the default handler.
 164  * @G_CONNECT_SWAPPED: If set, the instance and data should be swapped when
 165  *  calling the handler; see g_signal_connect_swapped() for an example.
 166  *
 167  * The connection flags are used to specify the behaviour of a signal's
 168  * connection.
 169  */
 170 typedef enum
 171 {
 172   G_CONNECT_DEFAULT GOBJECT_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
 173   G_CONNECT_AFTER       = 1 << 0,
 174   G_CONNECT_SWAPPED     = 1 << 1
 175 } GConnectFlags;
 176 /**
 177  * GSignalMatchType:
 178  * @G_SIGNAL_MATCH_ID: The signal id must be equal.
 179  * @G_SIGNAL_MATCH_DETAIL: The signal detail must be equal.
 180  * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
 181  * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
 182  * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
 183  * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may be matched.
 184  *
 185  * The match types specify what g_signal_handlers_block_matched(),
 186  * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
 187  * match signals by.
 188  */
 189 typedef enum
 190 {
 191   G_SIGNAL_MATCH_ID        = 1 << 0,
 192   G_SIGNAL_MATCH_DETAIL    = 1 << 1,
 193   G_SIGNAL_MATCH_CLOSURE   = 1 << 2,
 194   G_SIGNAL_MATCH_FUNC      = 1 << 3,
 195   G_SIGNAL_MATCH_DATA      = 1 << 4,
 196   G_SIGNAL_MATCH_UNBLOCKED = 1 << 5
 197 } GSignalMatchType;
 198 /**
 199  * G_SIGNAL_MATCH_MASK:
 200  *
 201  * A mask for all #GSignalMatchType bits.
 202  */
 203 #define G_SIGNAL_MATCH_MASK  0x3f
 204 /**
 205  * G_SIGNAL_TYPE_STATIC_SCOPE:
 206  *
 207  * This macro flags signal argument types for which the signal system may
 208  * assume that instances thereof remain persistent across all signal emissions
 209  * they are used in. This is only useful for non ref-counted, value-copy types.
 210  *
 211  * To flag a signal argument in this way, add `| G_SIGNAL_TYPE_STATIC_SCOPE`
 212  * to the corresponding argument of g_signal_new().
 213  * |[
 214  * g_signal_new ("size_request",
 215  *   G_TYPE_FROM_CLASS (gobject_class),
 216  *       G_SIGNAL_RUN_FIRST,
 217  *       G_STRUCT_OFFSET (GtkWidgetClass, size_request),
 218  *       NULL, NULL,
 219  *       _gtk_marshal_VOID__BOXED,
 220  *       G_TYPE_NONE, 1,
 221  *       GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
 222  * ]|
 223  */
 224 #define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT)
 225
 226
 227 /* --- signal information --- */
 228 /**
 229  * GSignalInvocationHint:
 230  * @signal_id: The signal id of the signal invoking the callback
 231  * @detail: The detail passed on for this emission
 232  * @run_type: The stage the signal emission is currently in, this
 233  *  field will contain one of %G_SIGNAL_RUN_FIRST,
 234  *  %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP and %G_SIGNAL_ACCUMULATOR_FIRST_RUN.
 235  *  %G_SIGNAL_ACCUMULATOR_FIRST_RUN is only set for the first run of the accumulator
 236  *  function for a signal emission.
 237  *
 238  * The #GSignalInvocationHint structure is used to pass on additional information
 239  * to callbacks during a signal emission.
 240  */
 241 struct _GSignalInvocationHint
 242 {
 243   guint         signal_id;
 244   GQuark        detail;
 245   GSignalFlags  run_type;
 246 };
 247 /**
 248  * GSignalQuery:
 249  * @signal_id: The signal id of the signal being queried, or 0 if the
 250  *  signal to be queried was unknown.
 251  * @signal_name: The signal name.
 252  * @itype: The interface/instance type that this signal can be emitted for.
 253  * @signal_flags: The signal flags as passed in to g_signal_new().
 254  * @return_type: The return type for user callbacks.
 255  * @n_params: The number of parameters that user callbacks take.
 256  * @param_types: (array length=n_params): The individual parameter types for
 257  *  user callbacks, note that the effective callback signature is:
 258  *  |[<!-- language="C" -->
 259  *  @return_type callback (#gpointer     data1,
 260  *  [param_types param_names,]
 261  *  gpointer     data2);
 262  *  ]|
 263  *
 264  * A structure holding in-depth information for a specific signal.
 265  *
 266  * See also: g_signal_query()
 267  */
 268 struct _GSignalQuery
 269 {
 270   guint         signal_id;
 271   const gchar  *signal_name;
 272   GType         itype;
 273   GSignalFlags  signal_flags;
 274   GType         return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
 275   guint         n_params;
 276   const GType  *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
 277 };
 278
 279
 280 /* --- signals --- */
 281 GOBJECT_AVAILABLE_IN_ALL
 282 guint                 g_signal_newv         (const gchar        *signal_name,
 283                                              GType               itype,
 284                                              GSignalFlags        signal_flags,
 285                                              GClosure           *class_closure,
 286                                              GSignalAccumulator  accumulator,
 287                                              gpointer            accu_data,
 288                                              GSignalCMarshaller  c_marshaller,
 289                                              GType               return_type,
 290                                              guint               n_params,
 291                                              GType              *param_types);
 292 GOBJECT_AVAILABLE_IN_ALL
 293 guint                 g_signal_new_valist   (const gchar        *signal_name,
 294                                              GType               itype,
 295                                              GSignalFlags        signal_flags,
 296                                              GClosure           *class_closure,
 297                                              GSignalAccumulator  accumulator,
 298                                              gpointer            accu_data,
 299                                              GSignalCMarshaller  c_marshaller,
 300                                              GType               return_type,
 301                                              guint               n_params,
 302                                              va_list             args);
 303 GOBJECT_AVAILABLE_IN_ALL
 304 guint                 g_signal_new          (const gchar        *signal_name,
 305                                              GType               itype,
 306                                              GSignalFlags        signal_flags,
 307                                              guint               class_offset,
 308                                              GSignalAccumulator  accumulator,
 309                                              gpointer            accu_data,
 310                                              GSignalCMarshaller  c_marshaller,
 311                                              GType               return_type,
 312                                              guint               n_params,
 313                                              ...);
 314 GOBJECT_AVAILABLE_IN_ALL
 315 guint            g_signal_new_class_handler (const gchar        *signal_name,
 316                                              GType               itype,
 317                                              GSignalFlags        signal_flags,
 318                                              GCallback           class_handler,
 319                                              GSignalAccumulator  accumulator,
 320                                              gpointer            accu_data,
 321                                              GSignalCMarshaller  c_marshaller,
 322                                              GType               return_type,
 323                                              guint               n_params,
 324                                              ...);
 325 GOBJECT_AVAILABLE_IN_ALL
 326 void             g_signal_set_va_marshaller (guint              signal_id,
 327                                              GType              instance_type,
 328                                              GSignalCVaMarshaller va_marshaller);
 329
 330 GOBJECT_AVAILABLE_IN_ALL
 331 void                  g_signal_emitv        (const GValue       *instance_and_params,
 332                                              guint               signal_id,
 333                                              GQuark              detail,
 334                                              GValue             *return_value);
 335 GOBJECT_AVAILABLE_IN_ALL
 336 void                  g_signal_emit_valist  (gpointer            instance,
 337                                              guint               signal_id,
 338                                              GQuark              detail,
 339                                              va_list             var_args);
 340 GOBJECT_AVAILABLE_IN_ALL
 341 void                  g_signal_emit         (gpointer            instance,
 342                                              guint               signal_id,
 343                                              GQuark              detail,
 344                                              ...);
 345 GOBJECT_AVAILABLE_IN_ALL
 346 void                  g_signal_emit_by_name (gpointer            instance,
 347                                              const gchar        *detailed_signal,
 348                                              ...);
 349 GOBJECT_AVAILABLE_IN_ALL
 350 guint                 g_signal_lookup       (const gchar        *name,
 351                                              GType               itype);
 352 GOBJECT_AVAILABLE_IN_ALL
 353 const gchar *         g_signal_name         (guint               signal_id);
 354 GOBJECT_AVAILABLE_IN_ALL
 355 void                  g_signal_query        (guint               signal_id,
 356                                              GSignalQuery       *query);
 357 GOBJECT_AVAILABLE_IN_ALL
 358 guint*                g_signal_list_ids     (GType               itype,
 359                                              guint              *n_ids);
 360 GOBJECT_AVAILABLE_IN_2_66
 361 gboolean              g_signal_is_valid_name (const gchar      *name);
 362 GOBJECT_AVAILABLE_IN_ALL
 363 gboolean              g_signal_parse_name   (const gchar        *detailed_signal,
 364                                              GType               itype,
 365                                              guint              *signal_id_p,
 366                                              GQuark             *detail_p,
 367                                              gboolean            force_detail_quark);
 368 GOBJECT_AVAILABLE_IN_ALL
 369 GSignalInvocationHint* g_signal_get_invocation_hint (gpointer    instance);
 370
 371
 372 /* --- signal emissions --- */
 373 GOBJECT_AVAILABLE_IN_ALL
 374 void    g_signal_stop_emission              (gpointer             instance,
 375                                              guint                signal_id,
 376                                              GQuark               detail);
 377 GOBJECT_AVAILABLE_IN_ALL
 378 void    g_signal_stop_emission_by_name      (gpointer             instance,
 379                                              const gchar         *detailed_signal);
 380 GOBJECT_AVAILABLE_IN_ALL
 381 gulong  g_signal_add_emission_hook          (guint                signal_id,
 382                                              GQuark               detail,
 383                                              GSignalEmissionHook  hook_func,
 384                                              gpointer             hook_data,
 385                                              GDestroyNotify       data_destroy);
 386 GOBJECT_AVAILABLE_IN_ALL
 387 void    g_signal_remove_emission_hook       (guint                signal_id,
 388                                              gulong               hook_id);
 389
 390
 391 /* --- signal handlers --- */
 392 GOBJECT_AVAILABLE_IN_ALL
 393 gboolean g_signal_has_handler_pending         (gpointer           instance,
 394                                                guint              signal_id,
 395                                                GQuark             detail,
 396                                                gboolean           may_be_blocked);
 397 GOBJECT_AVAILABLE_IN_ALL
 398 gulong   g_signal_connect_closure_by_id       (gpointer           instance,
 399                                                guint              signal_id,
 400                                                GQuark             detail,
 401                                                GClosure          *closure,
 402                                                gboolean           after);
 403 GOBJECT_AVAILABLE_IN_ALL
 404 gulong   g_signal_connect_closure             (gpointer           instance,
 405                                                const gchar       *detailed_signal,
 406                                                GClosure          *closure,
 407                                                gboolean           after);
 408 GOBJECT_AVAILABLE_IN_ALL
 409 gulong   g_signal_connect_data                (gpointer           instance,
 410                                                const gchar       *detailed_signal,
 411                                                GCallback          c_handler,
 412                                                gpointer           data,
 413                                                GClosureNotify     destroy_data,
 414                                                GConnectFlags      connect_flags);
 415 GOBJECT_AVAILABLE_IN_ALL
 416 void     g_signal_handler_block               (gpointer           instance,
 417                                                gulong             handler_id);
 418 GOBJECT_AVAILABLE_IN_ALL
 419 void     g_signal_handler_unblock             (gpointer           instance,
 420                                                gulong             handler_id);
 421 GOBJECT_AVAILABLE_IN_ALL
 422 void     g_signal_handler_disconnect          (gpointer           instance,
 423                                                gulong             handler_id);
 424 GOBJECT_AVAILABLE_IN_ALL
 425 gboolean g_signal_handler_is_connected        (gpointer           instance,
 426                                                gulong             handler_id);
 427 GOBJECT_AVAILABLE_IN_ALL
 428 gulong   g_signal_handler_find                (gpointer           instance,
 429                                                GSignalMatchType   mask,
 430                                                guint              signal_id,
 431                                                GQuark             detail,
 432                                                GClosure          *closure,
 433                                                gpointer           func,
 434                                                gpointer           data);
 435 GOBJECT_AVAILABLE_IN_ALL
 436 guint    g_signal_handlers_block_matched      (gpointer           instance,
 437                                                GSignalMatchType   mask,
 438                                                guint              signal_id,
 439                                                GQuark             detail,
 440                                                GClosure          *closure,
 441                                                gpointer           func,
 442                                                gpointer           data);
 443 GOBJECT_AVAILABLE_IN_ALL
 444 guint    g_signal_handlers_unblock_matched    (gpointer           instance,
 445                                                GSignalMatchType   mask,
 446                                                guint              signal_id,
 447                                                GQuark             detail,
 448                                                GClosure          *closure,
 449                                                gpointer           func,
 450                                                gpointer           data);
 451 GOBJECT_AVAILABLE_IN_ALL
 452 guint    g_signal_handlers_disconnect_matched (gpointer           instance,
 453                                                GSignalMatchType   mask,
 454                                                guint              signal_id,
 455                                                GQuark             detail,
 456                                                GClosure          *closure,
 457                                                gpointer           func,
 458                                                gpointer           data);
 459
 460 GOBJECT_AVAILABLE_IN_2_62
 461 void     g_clear_signal_handler               (gulong            *handler_id_ptr,
 462                                                gpointer           instance);
 463
 464 #define  g_clear_signal_handler(handler_id_ptr, instance)           \
 465   G_STMT_START {                                                    \
 466     gpointer const _instance      = (instance);                     \
 467     gulong *const _handler_id_ptr = (handler_id_ptr);               \
 468     const gulong _handler_id      = *_handler_id_ptr;               \
 469                                                                     \
 470     if (_handler_id > 0)                                            \
 471       {                                                             \
 472         *_handler_id_ptr = 0;                                       \
 473         g_signal_handler_disconnect (_instance, _handler_id);       \
 474       }                                                             \
 475   } G_STMT_END                                                      \
 476   GOBJECT_AVAILABLE_MACRO_IN_2_62
 477
 478 /* --- overriding and chaining --- */
 479 GOBJECT_AVAILABLE_IN_ALL
 480 void    g_signal_override_class_closure       (guint              signal_id,
 481                                                GType              instance_type,
 482                                                GClosure          *class_closure);
 483 GOBJECT_AVAILABLE_IN_ALL
 484 void    g_signal_override_class_handler       (const gchar       *signal_name,
 485                                                GType              instance_type,
 486                                                GCallback          class_handler);
 487 GOBJECT_AVAILABLE_IN_ALL
 488 void    g_signal_chain_from_overridden        (const GValue      *instance_and_params,
 489                                                GValue            *return_value);
 490 GOBJECT_AVAILABLE_IN_ALL
 491 void   g_signal_chain_from_overridden_handler (gpointer           instance,
 492                                                ...);
 493
 494
 495 /* --- convenience --- */
 496 /**
 497  * g_signal_connect:
 498  * @instance: the instance to connect to.
 499  * @detailed_signal: a string of the form "signal-name::detail".
 500  * @c_handler: the #GCallback to connect.
 501  * @data: data to pass to @c_handler calls.
 502  *
 503  * Connects a [type@GObject.Callback] function to a signal for a particular object.
 504  *
 505  * The handler will be called synchronously, before the default handler of the signal.
 506  * [func@GObject.signal_emit] will not return control until all handlers are called.
 507  *
 508  * See [memory management of signal handlers](signals.html#Memory_management_of_signal_handlers) for
 509  * details on how to handle the return value and memory management of @data.
 510  *
 511  * This function cannot fail. If the given signal doesn’t exist, a critical
 512  * warning is emitted.
 513  *
 514  * Returns: the handler ID, of type `gulong` (always greater than 0)
 515  */
 516 /* Intentionally not using G_CONNECT_DEFAULT here to avoid deprecation
 517  * warnings with older GLIB_VERSION_MAX_ALLOWED */
 518 #define g_signal_connect(instance, detailed_signal, c_handler, data) \
 519     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0)
 520 /**
 521  * g_signal_connect_after:
 522  * @instance: the instance to connect to.
 523  * @detailed_signal: a string of the form "signal-name::detail".
 524  * @c_handler: the #GCallback to connect.
 525  * @data: data to pass to @c_handler calls.
 526  *
 527  * Connects a #GCallback function to a signal for a particular object.
 528  *
 529  * The handler will be called synchronously, after the default handler of the signal.
 530  *
 531  * This function cannot fail. If the given signal doesn’t exist, a critical
 532  * warning is emitted.
 533  *
 534  * Returns: the handler ID, of type `gulong` (always greater than 0)
 535  */
 536 #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \
 537     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER)
 538 /**
 539  * g_signal_connect_swapped:
 540  * @instance: the instance to connect to.
 541  * @detailed_signal: a string of the form "signal-name::detail".
 542  * @c_handler: the #GCallback to connect.
 543  * @data: data to pass to @c_handler calls.
 544  *
 545  * Connects a #GCallback function to a signal for a particular object.
 546  *
 547  * The instance on which the signal is emitted and @data will be swapped when
 548  * calling the handler. This is useful when calling pre-existing functions to
 549  * operate purely on the @data, rather than the @instance: swapping the
 550  * parameters avoids the need to write a wrapper function.
 551  *
 552  * For example, this allows the shorter code:
 553  * |[<!-- language="C" -->
 554  * g_signal_connect_swapped (button, "clicked",
 555  *                           (GCallback) gtk_widget_hide, other_widget);
 556  * ]|
 557  *
 558  * Rather than the cumbersome:
 559  * |[<!-- language="C" -->
 560  * static void
 561  * button_clicked_cb (GtkButton *button, GtkWidget *other_widget)
 562  * {
 563  *     gtk_widget_hide (other_widget);
 564  * }
 565  *
 566  * ...
 567  *
 568  * g_signal_connect (button, "clicked",
 569  *                   (GCallback) button_clicked_cb, other_widget);
 570  * ]|
 571  *
 572  * This function cannot fail. If the given signal doesn’t exist, a critical
 573  * warning is emitted.
 574  *
 575  * Returns: the handler ID, of type `gulong` (always greater than 0)
 576  */
 577 #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \
 578     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)
 579 /**
 580  * g_signal_handlers_disconnect_by_func:
 581  * @instance: The instance to remove handlers from.
 582  * @func: The C closure callback of the handlers (useless for non-C closures).
 583  * @data: The closure data of the handlers' closures.
 584  *
 585  * Disconnects all handlers on an instance that match @func and @data.
 586  *
 587  * Returns: The number of handlers that matched.
 588  */
 589 #define g_signal_handlers_disconnect_by_func(instance, func, data)                                              \
 590     g_signal_handlers_disconnect_matched ((instance),                                                           \
 591                                           (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),       \
 592                                           0, 0, NULL, (func), (data))
 593
 594 /**
 595  * g_signal_handlers_disconnect_by_data:
 596  * @instance: The instance to remove handlers from
 597  * @data: the closure data of the handlers' closures
 598  *
 599  * Disconnects all handlers on an instance that match @data.
 600  *
 601  * Returns: The number of handlers that matched.
 602  *
 603  * Since: 2.32
 604  */
 605 #define g_signal_handlers_disconnect_by_data(instance, data) \
 606   g_signal_handlers_disconnect_matched ((instance), G_SIGNAL_MATCH_DATA, 0, 0, NULL, NULL, (data))
 607
 608 /**
 609  * g_signal_handlers_block_by_func:
 610  * @instance: The instance to block handlers from.
 611  * @func: The C closure callback of the handlers (useless for non-C closures).
 612  * @data: The closure data of the handlers' closures.
 613  *
 614  * Blocks all handlers on an instance that match @func and @data.
 615  *
 616  * Returns: The number of handlers that matched.
 617  */
 618 #define g_signal_handlers_block_by_func(instance, func, data)                                                   \
 619     g_signal_handlers_block_matched      ((instance),                                                           \
 620                                           (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),       \
 621                                           0, 0, NULL, (func), (data))
 622 /**
 623  * g_signal_handlers_unblock_by_func:
 624  * @instance: The instance to unblock handlers from.
 625  * @func: The C closure callback of the handlers (useless for non-C closures).
 626  * @data: The closure data of the handlers' closures.
 627  *
 628  * Unblocks all handlers on an instance that match @func and @data.
 629  *
 630  * Returns: The number of handlers that matched.
 631  */
 632 #define g_signal_handlers_unblock_by_func(instance, func, data)                                                 \
 633     g_signal_handlers_unblock_matched    ((instance),                                                           \
 634                                           (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),       \
 635                                           0, 0, NULL, (func), (data))
 636
 637
 638 GOBJECT_AVAILABLE_IN_ALL
 639 gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
 640                                             GValue                *return_accu,
 641                                             const GValue          *handler_return,
 642                                             gpointer               dummy);
 643
 644 GOBJECT_AVAILABLE_IN_ALL
 645 gboolean g_signal_accumulator_first_wins   (GSignalInvocationHint *ihint,
 646                                             GValue                *return_accu,
 647                                             const GValue          *handler_return,
 648                                             gpointer               dummy);
 649
 650 /*< private >*/
 651 GOBJECT_AVAILABLE_IN_ALL
 652 void     g_signal_handlers_destroy            (gpointer           instance);
 653 void     _g_signals_destroy                   (GType              itype);
 654
 655 G_END_DECLS
 656
 657 #endif /* __G_SIGNAL_H__ */