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__ */ |
658 | |