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
31G_BEGIN_DECLS
32
33/* --- typedefs --- */
34typedef struct _GSignalQuery GSignalQuery;
35typedef 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 */
47typedef 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 */
55typedef 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 */
75typedef 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 */
103typedef 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 *
128 * The signal flags are used to specify a signal's behaviour.
129 */
130typedef enum
131{
132 G_SIGNAL_RUN_FIRST = 1 << 0,
133 G_SIGNAL_RUN_LAST = 1 << 1,
134 G_SIGNAL_RUN_CLEANUP = 1 << 2,
135 G_SIGNAL_NO_RECURSE = 1 << 3,
136 G_SIGNAL_DETAILED = 1 << 4,
137 G_SIGNAL_ACTION = 1 << 5,
138 G_SIGNAL_NO_HOOKS = 1 << 6,
139 G_SIGNAL_MUST_COLLECT = 1 << 7,
140 G_SIGNAL_DEPRECATED = 1 << 8,
141 /* normal signal flags until 1 << 16 */
142 G_SIGNAL_ACCUMULATOR_FIRST_RUN = 1 << 17,
143} GSignalFlags;
144
145/**
146 * G_SIGNAL_MUST_COLLECT:
147 *
148 * Varargs signal emission will always collect the arguments, even if there
149 * are no signal handlers connected.
150 *
151 * Since: 2.30
152 */
153
154/**
155 * G_SIGNAL_DEPRECATED:
156 *
157 * The signal is deprecated and will be removed in a future version.
158 *
159 * A warning will be generated if it is connected while running with
160 * `G_ENABLE_DIAGNOSTIC=1`.
161 *
162 * Since: 2.32
163 */
164
165/**
166 * G_SIGNAL_ACCUMULATOR_FIRST_RUN:
167 *
168 * The signal accumulator was invoked for the first time.
169 *
170 * This flag is only used in [callback@GObject.SignalAccumulator][accumulator functions]
171 * for the `run_type` field of the [struct@GObject.SignalInvocationHint], to
172 * mark the first call to the accumulator function for a signal emission.
173 *
174 * Since: 2.68
175 */
176
177/**
178 * G_SIGNAL_FLAGS_MASK:
179 *
180 * A mask for all #GSignalFlags bits.
181 */
182#define G_SIGNAL_FLAGS_MASK 0x1ff
183/**
184 * GConnectFlags:
185 * @G_CONNECT_DEFAULT: Default behaviour (no special flags). Since: 2.74
186 * @G_CONNECT_AFTER: If set, the handler should be called after the
187 * default handler of the signal. Normally, the handler is called before
188 * the default handler.
189 * @G_CONNECT_SWAPPED: If set, the instance and data should be swapped when
190 * calling the handler; see g_signal_connect_swapped() for an example.
191 *
192 * The connection flags are used to specify the behaviour of a signal's
193 * connection.
194 */
195typedef enum
196{
197 G_CONNECT_DEFAULT GOBJECT_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
198 G_CONNECT_AFTER = 1 << 0,
199 G_CONNECT_SWAPPED = 1 << 1
200} GConnectFlags;
201/**
202 * GSignalMatchType:
203 * @G_SIGNAL_MATCH_ID: The signal id must be equal.
204 * @G_SIGNAL_MATCH_DETAIL: The signal detail must be equal.
205 * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
206 * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
207 * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
208 * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may be matched.
209 *
210 * The match types specify what g_signal_handlers_block_matched(),
211 * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
212 * match signals by.
213 */
214typedef enum
215{
216 G_SIGNAL_MATCH_ID = 1 << 0,
217 G_SIGNAL_MATCH_DETAIL = 1 << 1,
218 G_SIGNAL_MATCH_CLOSURE = 1 << 2,
219 G_SIGNAL_MATCH_FUNC = 1 << 3,
220 G_SIGNAL_MATCH_DATA = 1 << 4,
221 G_SIGNAL_MATCH_UNBLOCKED = 1 << 5
222} GSignalMatchType;
223/**
224 * G_SIGNAL_MATCH_MASK:
225 *
226 * A mask for all #GSignalMatchType bits.
227 */
228#define G_SIGNAL_MATCH_MASK 0x3f
229/**
230 * G_SIGNAL_TYPE_STATIC_SCOPE:
231 *
232 * This macro flags signal argument types for which the signal system may
233 * assume that instances thereof remain persistent across all signal emissions
234 * they are used in. This is only useful for non ref-counted, value-copy types.
235 *
236 * To flag a signal argument in this way, add `| G_SIGNAL_TYPE_STATIC_SCOPE`
237 * to the corresponding argument of g_signal_new().
238 * |[
239 * g_signal_new ("size_request",
240 * G_TYPE_FROM_CLASS (gobject_class),
241 * G_SIGNAL_RUN_FIRST,
242 * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
243 * NULL, NULL,
244 * _gtk_marshal_VOID__BOXED,
245 * G_TYPE_NONE, 1,
246 * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
247 * ]|
248 */
249#define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT)
250
251
252/* --- signal information --- */
253/**
254 * GSignalInvocationHint:
255 * @signal_id: The signal id of the signal invoking the callback
256 * @detail: The detail passed on for this emission
257 * @run_type: The stage the signal emission is currently in, this
258 * field will contain one of %G_SIGNAL_RUN_FIRST,
259 * %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP and %G_SIGNAL_ACCUMULATOR_FIRST_RUN.
260 * %G_SIGNAL_ACCUMULATOR_FIRST_RUN is only set for the first run of the accumulator
261 * function for a signal emission.
262 *
263 * The #GSignalInvocationHint structure is used to pass on additional information
264 * to callbacks during a signal emission.
265 */
266struct _GSignalInvocationHint
267{
268 guint signal_id;
269 GQuark detail;
270 GSignalFlags run_type;
271};
272/**
273 * GSignalQuery:
274 * @signal_id: The signal id of the signal being queried, or 0 if the
275 * signal to be queried was unknown.
276 * @signal_name: The signal name.
277 * @itype: The interface/instance type that this signal can be emitted for.
278 * @signal_flags: The signal flags as passed in to g_signal_new().
279 * @return_type: The return type for user callbacks.
280 * @n_params: The number of parameters that user callbacks take.
281 * @param_types: (array length=n_params): The individual parameter types for
282 * user callbacks, note that the effective callback signature is:
283 * |[<!-- language="C" -->
284 * @return_type callback (#gpointer data1,
285 * [param_types param_names,]
286 * gpointer data2);
287 * ]|
288 *
289 * A structure holding in-depth information for a specific signal.
290 *
291 * See also: g_signal_query()
292 */
293struct _GSignalQuery
294{
295 guint signal_id;
296 const gchar *signal_name;
297 GType itype;
298 GSignalFlags signal_flags;
299 GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
300 guint n_params;
301 const GType *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
302};
303
304
305/* --- signals --- */
306GOBJECT_AVAILABLE_IN_ALL
307guint g_signal_newv (const gchar *signal_name,
308 GType itype,
309 GSignalFlags signal_flags,
310 GClosure *class_closure,
311 GSignalAccumulator accumulator,
312 gpointer accu_data,
313 GSignalCMarshaller c_marshaller,
314 GType return_type,
315 guint n_params,
316 GType *param_types);
317GOBJECT_AVAILABLE_IN_ALL
318guint g_signal_new_valist (const gchar *signal_name,
319 GType itype,
320 GSignalFlags signal_flags,
321 GClosure *class_closure,
322 GSignalAccumulator accumulator,
323 gpointer accu_data,
324 GSignalCMarshaller c_marshaller,
325 GType return_type,
326 guint n_params,
327 va_list args);
328GOBJECT_AVAILABLE_IN_ALL
329guint g_signal_new (const gchar *signal_name,
330 GType itype,
331 GSignalFlags signal_flags,
332 guint class_offset,
333 GSignalAccumulator accumulator,
334 gpointer accu_data,
335 GSignalCMarshaller c_marshaller,
336 GType return_type,
337 guint n_params,
338 ...);
339GOBJECT_AVAILABLE_IN_ALL
340guint g_signal_new_class_handler (const gchar *signal_name,
341 GType itype,
342 GSignalFlags signal_flags,
343 GCallback class_handler,
344 GSignalAccumulator accumulator,
345 gpointer accu_data,
346 GSignalCMarshaller c_marshaller,
347 GType return_type,
348 guint n_params,
349 ...);
350GOBJECT_AVAILABLE_IN_ALL
351void g_signal_set_va_marshaller (guint signal_id,
352 GType instance_type,
353 GSignalCVaMarshaller va_marshaller);
354
355GOBJECT_AVAILABLE_IN_ALL
356void g_signal_emitv (const GValue *instance_and_params,
357 guint signal_id,
358 GQuark detail,
359 GValue *return_value);
360GOBJECT_AVAILABLE_IN_ALL
361void g_signal_emit_valist (gpointer instance,
362 guint signal_id,
363 GQuark detail,
364 va_list var_args);
365GOBJECT_AVAILABLE_IN_ALL
366void g_signal_emit (gpointer instance,
367 guint signal_id,
368 GQuark detail,
369 ...);
370GOBJECT_AVAILABLE_IN_ALL
371void g_signal_emit_by_name (gpointer instance,
372 const gchar *detailed_signal,
373 ...);
374GOBJECT_AVAILABLE_IN_ALL
375guint g_signal_lookup (const gchar *name,
376 GType itype);
377GOBJECT_AVAILABLE_IN_ALL
378const gchar * g_signal_name (guint signal_id);
379GOBJECT_AVAILABLE_IN_ALL
380void g_signal_query (guint signal_id,
381 GSignalQuery *query);
382GOBJECT_AVAILABLE_IN_ALL
383guint* g_signal_list_ids (GType itype,
384 guint *n_ids);
385GOBJECT_AVAILABLE_IN_2_66
386gboolean g_signal_is_valid_name (const gchar *name);
387GOBJECT_AVAILABLE_IN_ALL
388gboolean g_signal_parse_name (const gchar *detailed_signal,
389 GType itype,
390 guint *signal_id_p,
391 GQuark *detail_p,
392 gboolean force_detail_quark);
393GOBJECT_AVAILABLE_IN_ALL
394GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance);
395
396
397/* --- signal emissions --- */
398GOBJECT_AVAILABLE_IN_ALL
399void g_signal_stop_emission (gpointer instance,
400 guint signal_id,
401 GQuark detail);
402GOBJECT_AVAILABLE_IN_ALL
403void g_signal_stop_emission_by_name (gpointer instance,
404 const gchar *detailed_signal);
405GOBJECT_AVAILABLE_IN_ALL
406gulong g_signal_add_emission_hook (guint signal_id,
407 GQuark detail,
408 GSignalEmissionHook hook_func,
409 gpointer hook_data,
410 GDestroyNotify data_destroy);
411GOBJECT_AVAILABLE_IN_ALL
412void g_signal_remove_emission_hook (guint signal_id,
413 gulong hook_id);
414
415
416/* --- signal handlers --- */
417GOBJECT_AVAILABLE_IN_ALL
418gboolean g_signal_has_handler_pending (gpointer instance,
419 guint signal_id,
420 GQuark detail,
421 gboolean may_be_blocked);
422GOBJECT_AVAILABLE_IN_ALL
423gulong g_signal_connect_closure_by_id (gpointer instance,
424 guint signal_id,
425 GQuark detail,
426 GClosure *closure,
427 gboolean after);
428GOBJECT_AVAILABLE_IN_ALL
429gulong g_signal_connect_closure (gpointer instance,
430 const gchar *detailed_signal,
431 GClosure *closure,
432 gboolean after);
433GOBJECT_AVAILABLE_IN_ALL
434gulong g_signal_connect_data (gpointer instance,
435 const gchar *detailed_signal,
436 GCallback c_handler,
437 gpointer data,
438 GClosureNotify destroy_data,
439 GConnectFlags connect_flags);
440GOBJECT_AVAILABLE_IN_ALL
441void g_signal_handler_block (gpointer instance,
442 gulong handler_id);
443GOBJECT_AVAILABLE_IN_ALL
444void g_signal_handler_unblock (gpointer instance,
445 gulong handler_id);
446GOBJECT_AVAILABLE_IN_ALL
447void g_signal_handler_disconnect (gpointer instance,
448 gulong handler_id);
449GOBJECT_AVAILABLE_IN_ALL
450gboolean g_signal_handler_is_connected (gpointer instance,
451 gulong handler_id);
452GOBJECT_AVAILABLE_IN_ALL
453gulong g_signal_handler_find (gpointer instance,
454 GSignalMatchType mask,
455 guint signal_id,
456 GQuark detail,
457 GClosure *closure,
458 gpointer func,
459 gpointer data);
460GOBJECT_AVAILABLE_IN_ALL
461guint g_signal_handlers_block_matched (gpointer instance,
462 GSignalMatchType mask,
463 guint signal_id,
464 GQuark detail,
465 GClosure *closure,
466 gpointer func,
467 gpointer data);
468GOBJECT_AVAILABLE_IN_ALL
469guint g_signal_handlers_unblock_matched (gpointer instance,
470 GSignalMatchType mask,
471 guint signal_id,
472 GQuark detail,
473 GClosure *closure,
474 gpointer func,
475 gpointer data);
476GOBJECT_AVAILABLE_IN_ALL
477guint g_signal_handlers_disconnect_matched (gpointer instance,
478 GSignalMatchType mask,
479 guint signal_id,
480 GQuark detail,
481 GClosure *closure,
482 gpointer func,
483 gpointer data);
484
485GOBJECT_AVAILABLE_IN_2_62
486void g_clear_signal_handler (gulong *handler_id_ptr,
487 gpointer instance);
488
489#define g_clear_signal_handler(handler_id_ptr, instance) \
490 G_STMT_START { \
491 gpointer const _instance = (instance); \
492 gulong *const _handler_id_ptr = (handler_id_ptr); \
493 const gulong _handler_id = *_handler_id_ptr; \
494 \
495 if (_handler_id > 0) \
496 { \
497 *_handler_id_ptr = 0; \
498 g_signal_handler_disconnect (_instance, _handler_id); \
499 } \
500 } G_STMT_END \
501 GOBJECT_AVAILABLE_MACRO_IN_2_62
502
503/* --- overriding and chaining --- */
504GOBJECT_AVAILABLE_IN_ALL
505void g_signal_override_class_closure (guint signal_id,
506 GType instance_type,
507 GClosure *class_closure);
508GOBJECT_AVAILABLE_IN_ALL
509void g_signal_override_class_handler (const gchar *signal_name,
510 GType instance_type,
511 GCallback class_handler);
512GOBJECT_AVAILABLE_IN_ALL
513void g_signal_chain_from_overridden (const GValue *instance_and_params,
514 GValue *return_value);
515GOBJECT_AVAILABLE_IN_ALL
516void g_signal_chain_from_overridden_handler (gpointer instance,
517 ...);
518
519
520/* --- convenience --- */
521/**
522 * g_signal_connect:
523 * @instance: the instance to connect to.
524 * @detailed_signal: a string of the form "signal-name::detail".
525 * @c_handler: the #GCallback to connect.
526 * @data: data to pass to @c_handler calls.
527 *
528 * Connects a [type@GObject.Callback] function to a signal for a particular object.
529 *
530 * The handler will be called synchronously, before the default handler of the signal.
531 * [func@GObject.signal_emit] will not return control until all handlers are called.
532 *
533 * See [memory management of signal handlers](signals.html#memory-management-of-signal-handlers) for
534 * details on how to handle the return value and memory management of @data.
535 *
536 * This function cannot fail. If the given signal name doesn’t exist,
537 * a critical warning is emitted. No validation is performed on the
538 * ‘detail’ string when specified in @detailed_signal, other than a
539 * non-empty check.
540 *
541 * Refer to the [signals documentation](signals.html) for more
542 * details.
543 *
544 * Returns: the handler ID, of type `gulong` (always greater than 0)
545 */
546/* Intentionally not using G_CONNECT_DEFAULT here to avoid deprecation
547 * warnings with older GLIB_VERSION_MAX_ALLOWED */
548#define g_signal_connect(instance, detailed_signal, c_handler, data) \
549 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0)
550/**
551 * g_signal_connect_after:
552 * @instance: the instance to connect to.
553 * @detailed_signal: a string of the form "signal-name::detail".
554 * @c_handler: the #GCallback to connect.
555 * @data: data to pass to @c_handler calls.
556 *
557 * Connects a #GCallback function to a signal for a particular object.
558 *
559 * The handler will be called synchronously, after the default handler of the signal.
560 *
561 * This function cannot fail. If the given signal name doesn’t exist,
562 * a critical warning is emitted. No validation is performed on the
563 * ‘detail’ string when specified in @detailed_signal, other than a
564 * non-empty check.
565 *
566 * Refer to the [signals documentation](signals.html) for more
567 * details.
568 *
569 * Returns: the handler ID, of type `gulong` (always greater than 0)
570 */
571#define g_signal_connect_after(instance, detailed_signal, c_handler, data) \
572 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER)
573/**
574 * g_signal_connect_swapped:
575 * @instance: the instance to connect to.
576 * @detailed_signal: a string of the form "signal-name::detail".
577 * @c_handler: the #GCallback to connect.
578 * @data: data to pass to @c_handler calls.
579 *
580 * Connects a #GCallback function to a signal for a particular object.
581 *
582 * The instance on which the signal is emitted and @data will be swapped when
583 * calling the handler. This is useful when calling pre-existing functions to
584 * operate purely on the @data, rather than the @instance: swapping the
585 * parameters avoids the need to write a wrapper function.
586 *
587 * For example, this allows the shorter code:
588 * |[<!-- language="C" -->
589 * g_signal_connect_swapped (button, "clicked",
590 * (GCallback) gtk_widget_hide, other_widget);
591 * ]|
592 *
593 * Rather than the cumbersome:
594 * |[<!-- language="C" -->
595 * static void
596 * button_clicked_cb (GtkButton *button, GtkWidget *other_widget)
597 * {
598 * gtk_widget_hide (other_widget);
599 * }
600 *
601 * ...
602 *
603 * g_signal_connect (button, "clicked",
604 * (GCallback) button_clicked_cb, other_widget);
605 * ]|
606 *
607 * This function cannot fail. If the given signal name doesn’t exist,
608 * a critical warning is emitted. No validation is performed on the
609 * ‘detail’ string when specified in @detailed_signal, other than a
610 * non-empty check.
611 *
612 * Refer to the [signals documentation](signals.html) for more
613 * details.
614 *
615 * Returns: the handler ID, of type `gulong` (always greater than 0)
616 */
617#define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \
618 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)
619/**
620 * g_signal_handlers_disconnect_by_func:
621 * @instance: The instance to remove handlers from.
622 * @func: The C closure callback of the handlers (useless for non-C closures).
623 * @data: The closure data of the handlers' closures.
624 *
625 * Disconnects all handlers on an instance that match @func and @data.
626 *
627 * Returns: The number of handlers that matched.
628 */
629#define g_signal_handlers_disconnect_by_func(instance, func, data) \
630 g_signal_handlers_disconnect_matched ((instance), \
631 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \
632 0, 0, NULL, (func), (data))
633
634/**
635 * g_signal_handlers_disconnect_by_data:
636 * @instance: The instance to remove handlers from
637 * @data: the closure data of the handlers' closures
638 *
639 * Disconnects all handlers on an instance that match @data.
640 *
641 * Returns: The number of handlers that matched.
642 *
643 * Since: 2.32
644 */
645#define g_signal_handlers_disconnect_by_data(instance, data) \
646 g_signal_handlers_disconnect_matched ((instance), G_SIGNAL_MATCH_DATA, 0, 0, NULL, NULL, (data))
647
648/**
649 * g_signal_handlers_block_by_func:
650 * @instance: The instance to block handlers from.
651 * @func: The C closure callback of the handlers (useless for non-C closures).
652 * @data: The closure data of the handlers' closures.
653 *
654 * Blocks all handlers on an instance that match @func and @data.
655 *
656 * Returns: The number of handlers that matched.
657 */
658#define g_signal_handlers_block_by_func(instance, func, data) \
659 g_signal_handlers_block_matched ((instance), \
660 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \
661 0, 0, NULL, (func), (data))
662/**
663 * g_signal_handlers_unblock_by_func:
664 * @instance: The instance to unblock handlers from.
665 * @func: The C closure callback of the handlers (useless for non-C closures).
666 * @data: The closure data of the handlers' closures.
667 *
668 * Unblocks all handlers on an instance that match @func and @data.
669 *
670 * Returns: The number of handlers that matched.
671 */
672#define g_signal_handlers_unblock_by_func(instance, func, data) \
673 g_signal_handlers_unblock_matched ((instance), \
674 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \
675 0, 0, NULL, (func), (data))
676
677
678GOBJECT_AVAILABLE_IN_ALL
679gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
680 GValue *return_accu,
681 const GValue *handler_return,
682 gpointer dummy);
683
684GOBJECT_AVAILABLE_IN_ALL
685gboolean g_signal_accumulator_first_wins (GSignalInvocationHint *ihint,
686 GValue *return_accu,
687 const GValue *handler_return,
688 gpointer dummy);
689
690/*< private >*/
691GOBJECT_AVAILABLE_IN_ALL
692void g_signal_handlers_destroy (gpointer instance);
693void _g_signals_destroy (GType itype);
694
695G_END_DECLS
696
697#endif /* __G_SIGNAL_H__ */
698