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