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 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, write to the 16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 17 * Boston, MA 02111-1307, USA. 18 */ 19 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) 20 #error "Only <glib-object.h> can be included directly." 21 #endif 22 23 #ifndef __G_SIGNAL_H__ 24 #define __G_SIGNAL_H__ 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. It is merely an alias to #GClosureMarshal since the #GClosure 42 * mechanism takes over responsibility of actual function invocation for the 43 * signal system. 44 */ 45 typedef GClosureMarshal GSignalCMarshaller; 46 /** 47 * GSignalEmissionHook: 48 * @ihint: Signal invocation hint, see #GSignalInvocationHint. 49 * @n_param_values: the number of parameters to the function, including 50 * the instance on which the signal was emitted. 51 * @param_values: the instance on which the signal was emitted, followed by the 52 * parameters of the emission. 53 * @data: user data associated with the hook. 54 * 55 * A simple function pointer to get invoked when the signal is emitted. This 56 * allows you to tie a hook to the signal type, so that it will trap all 57 * emissions of that signal, from any object. 58 * 59 * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. 60 * 61 * Returns: whether it wants to stay connected. If it returns %FALSE, the signal 62 * hook is disconnected (and destroyed). 63 */ 64 typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, 65 guint n_param_values, 66 const GValue *param_values, 67 gpointer data); 68 /** 69 * GSignalAccumulator: 70 * @ihint: Signal invocation hint, see #GSignalInvocationHint. 71 * @return_accu: Accumulator to collect callback return values in, this 72 * is the return value of the current signal emission. 73 * @handler_return: A #GValue holding the return value of the signal handler. 74 * @data: Callback data that was specified when creating the signal. 75 * 76 * The signal accumulator is a special callback function that can be used 77 * to collect return values of the various callbacks that are called 78 * during a signal emission. The signal accumulator is specified at signal 79 * creation time, if it is left %NULL, no accumulation of callback return 80 * values is performed. The return value of signal emissions is then the 81 * value returned by the last callback. 82 * 83 * Returns: The accumulator function returns whether the signal emission 84 * should be aborted. Returning %FALSE means to abort the 85 * current emission and %TRUE is returned for continuation. 86 */ 87 typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, 88 GValue *return_accu, 89 const GValue *handler_return, 90 gpointer data); 91 92 93 /* --- run, match and connect types --- */ 94 /** 95 * GSignalFlags: 96 * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. 97 * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. 98 * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. 99 * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in 100 * emission for this very object will not be emitted recursively, 101 * but instead cause the first emission to be restarted. 102 * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name 103 * upon handler connections and emissions. 104 * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive 105 * objects from user code via g_signal_emit() and friends, without 106 * the need of being embedded into extra code that performs pre or 107 * post emission adjustments on the object. They can also be thought 108 * of as object methods which can be called generically by 109 * third-party code. 110 * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. 111 * 112 * The signal flags are used to specify a signal's behaviour, the overall 113 * signal description outlines how especially the RUN flags control the 114 * stages of a signal emission. 115 */ 116 typedef enum 117 { 118 G_SIGNAL_RUN_FIRST = 1 << 0, 119 G_SIGNAL_RUN_LAST = 1 << 1, 120 G_SIGNAL_RUN_CLEANUP = 1 << 2, 121 G_SIGNAL_NO_RECURSE = 1 << 3, 122 G_SIGNAL_DETAILED = 1 << 4, 123 G_SIGNAL_ACTION = 1 << 5, 124 G_SIGNAL_NO_HOOKS = 1 << 6 125 } GSignalFlags; 126 /** 127 * G_SIGNAL_FLAGS_MASK: 128 * 129 * A mask for all #GSignalFlags bits. 130 */ 131 #define G_SIGNAL_FLAGS_MASK 0x7f 132 /** 133 * GConnectFlags: 134 * @G_CONNECT_AFTER: whether the handler should be called before or after the 135 * default handler of the signal. 136 * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when 137 * calling the handler. 138 * 139 * The connection flags are used to specify the behaviour of a signal's 140 * connection. 141 */ 142 typedef enum 143 { 144 G_CONNECT_AFTER = 1 << 0, 145 G_CONNECT_SWAPPED = 1 << 1 146 } GConnectFlags; 147 /** 148 * GSignalMatchType: 149 * @G_SIGNAL_MATCH_ID: The signal id must be equal. 150 * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. 151 * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. 152 * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. 153 * @G_SIGNAL_MATCH_DATA: The closure data must be the same. 154 * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. 155 * 156 * The match types specify what g_signal_handlers_block_matched(), 157 * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() 158 * match signals by. 159 */ 160 typedef enum 161 { 162 G_SIGNAL_MATCH_ID = 1 << 0, 163 G_SIGNAL_MATCH_DETAIL = 1 << 1, 164 G_SIGNAL_MATCH_CLOSURE = 1 << 2, 165 G_SIGNAL_MATCH_FUNC = 1 << 3, 166 G_SIGNAL_MATCH_DATA = 1 << 4, 167 G_SIGNAL_MATCH_UNBLOCKED = 1 << 5 168 } GSignalMatchType; 169 /** 170 * G_SIGNAL_MATCH_MASK: 171 * 172 * A mask for all #GSignalMatchType bits. 173 */ 174 #define G_SIGNAL_MATCH_MASK 0x3f 175 /** 176 * G_SIGNAL_TYPE_STATIC_SCOPE: 177 * 178 * This macro flags signal argument types for which the signal system may 179 * assume that instances thereof remain persistent across all signal emissions 180 * they are used in. This is only useful for non ref-counted, value-copy types. 181 * 182 * To flag a signal argument in this way, add 183 * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument 184 * of g_signal_new(). 185 * |[ 186 * g_signal_new ("size_request", 187 * G_TYPE_FROM_CLASS (gobject_class), 188 * G_SIGNAL_RUN_FIRST, 189 * G_STRUCT_OFFSET (GtkWidgetClass, size_request), 190 * NULL, NULL, 191 * _gtk_marshal_VOID__BOXED, 192 * G_TYPE_NONE, 1, 193 * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); 194 * ]| 195 */ 196 #define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT) 197 198 199 /* --- signal information --- */ 200 /** 201 * GSignalInvocationHint: 202 * @signal_id: The signal id of the signal invoking the callback 203 * @detail: The detail passed on for this emission 204 * @run_type: The stage the signal emission is currently in, this 205 * field will contain one of %G_SIGNAL_RUN_FIRST, 206 * %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. 207 * 208 * The #GSignalInvocationHint structure is used to pass on additional information 209 * to callbacks during a signal emission. 210 */ 211 struct _GSignalInvocationHint 212 { 213 guint signal_id; 214 GQuark detail; 215 GSignalFlags run_type; 216 }; 217 /** 218 * GSignalQuery: 219 * @signal_id: The signal id of the signal being queried, or 0 if the 220 * signal to be queried was unknown. 221 * @signal_name: The signal name. 222 * @itype: The interface/instance type that this signal can be emitted for. 223 * @signal_flags: The signal flags as passed in to g_signal_new(). 224 * @return_type: The return type for user callbacks. 225 * @n_params: The number of parameters that user callbacks take. 226 * @param_types: The individual parameter types for user callbacks, note that the 227 * effective callback signature is: 228 * <programlisting> 229 * @return_type callback (#gpointer data1, 230 * [#param_types param_names,] 231 * #gpointer data2); 232 * </programlisting> 233 * 234 * A structure holding in-depth information for a specific signal. It is 235 * filled in by the g_signal_query() function. 236 */ 237 struct _GSignalQuery 238 { 239 guint signal_id; 240 const gchar *signal_name; 241 GType itype; 242 GSignalFlags signal_flags; 243 GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ 244 guint n_params; 245 const GType *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ 246 }; 247 248 249 /* --- signals --- */ 250 guint g_signal_newv (const gchar *signal_name, 251 GType itype, 252 GSignalFlags signal_flags, 253 GClosure *class_closure, 254 GSignalAccumulator accumulator, 255 gpointer accu_data, 256 GSignalCMarshaller c_marshaller, 257 GType return_type, 258 guint n_params, 259 GType *param_types); 260 guint g_signal_new_valist (const gchar *signal_name, 261 GType itype, 262 GSignalFlags signal_flags, 263 GClosure *class_closure, 264 GSignalAccumulator accumulator, 265 gpointer accu_data, 266 GSignalCMarshaller c_marshaller, 267 GType return_type, 268 guint n_params, 269 va_list args); 270 guint g_signal_new (const gchar *signal_name, 271 GType itype, 272 GSignalFlags signal_flags, 273 guint class_offset, 274 GSignalAccumulator accumulator, 275 gpointer accu_data, 276 GSignalCMarshaller c_marshaller, 277 GType return_type, 278 guint n_params, 279 ...); 280 guint g_signal_new_class_handler (const gchar *signal_name, 281 GType itype, 282 GSignalFlags signal_flags, 283 GCallback class_handler, 284 GSignalAccumulator accumulator, 285 gpointer accu_data, 286 GSignalCMarshaller c_marshaller, 287 GType return_type, 288 guint n_params, 289 ...); 290 291 void g_signal_emitv (const GValue *instance_and_params, 292 guint signal_id, 293 GQuark detail, 294 GValue *return_value); 295 void g_signal_emit_valist (gpointer instance, 296 guint signal_id, 297 GQuark detail, 298 va_list var_args); 299 void g_signal_emit (gpointer instance, 300 guint signal_id, 301 GQuark detail, 302 ...); 303 void g_signal_emit_by_name (gpointer instance, 304 const gchar *detailed_signal, 305 ...); 306 guint g_signal_lookup (const gchar *name, 307 GType itype); 308 G_CONST_RETURN gchar* g_signal_name (guint signal_id); 309 void g_signal_query (guint signal_id, 310 GSignalQuery *query); 311 guint* g_signal_list_ids (GType itype, 312 guint *n_ids); 313 gboolean g_signal_parse_name (const gchar *detailed_signal, 314 GType itype, 315 guint *signal_id_p, 316 GQuark *detail_p, 317 gboolean force_detail_quark); 318 GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance); 319 320 321 /* --- signal emissions --- */ 322 void g_signal_stop_emission (gpointer instance, 323 guint signal_id, 324 GQuark detail); 325 void g_signal_stop_emission_by_name (gpointer instance, 326 const gchar *detailed_signal); 327 gulong g_signal_add_emission_hook (guint signal_id, 328 GQuark detail, 329 GSignalEmissionHook hook_func, 330 gpointer hook_data, 331 GDestroyNotify data_destroy); 332 void g_signal_remove_emission_hook (guint signal_id, 333 gulong hook_id); 334 335 336 /* --- signal handlers --- */ 337 gboolean g_signal_has_handler_pending (gpointer instance, 338 guint signal_id, 339 GQuark detail, 340 gboolean may_be_blocked); 341 gulong g_signal_connect_closure_by_id (gpointer instance, 342 guint signal_id, 343 GQuark detail, 344 GClosure *closure, 345 gboolean after); 346 gulong g_signal_connect_closure (gpointer instance, 347 const gchar *detailed_signal, 348 GClosure *closure, 349 gboolean after); 350 gulong g_signal_connect_data (gpointer instance, 351 const gchar *detailed_signal, 352 GCallback c_handler, 353 gpointer data, 354 GClosureNotify destroy_data, 355 GConnectFlags connect_flags); 356 void g_signal_handler_block (gpointer instance, 357 gulong handler_id); 358 void g_signal_handler_unblock (gpointer instance, 359 gulong handler_id); 360 void g_signal_handler_disconnect (gpointer instance, 361 gulong handler_id); 362 gboolean g_signal_handler_is_connected (gpointer instance, 363 gulong handler_id); 364 gulong g_signal_handler_find (gpointer instance, 365 GSignalMatchType mask, 366 guint signal_id, 367 GQuark detail, 368 GClosure *closure, 369 gpointer func, 370 gpointer data); 371 guint g_signal_handlers_block_matched (gpointer instance, 372 GSignalMatchType mask, 373 guint signal_id, 374 GQuark detail, 375 GClosure *closure, 376 gpointer func, 377 gpointer data); 378 guint g_signal_handlers_unblock_matched (gpointer instance, 379 GSignalMatchType mask, 380 guint signal_id, 381 GQuark detail, 382 GClosure *closure, 383 gpointer func, 384 gpointer data); 385 guint g_signal_handlers_disconnect_matched (gpointer instance, 386 GSignalMatchType mask, 387 guint signal_id, 388 GQuark detail, 389 GClosure *closure, 390 gpointer func, 391 gpointer data); 392 393 394 /* --- overriding and chaining --- */ 395 void g_signal_override_class_closure (guint signal_id, 396 GType instance_type, 397 GClosure *class_closure); 398 void g_signal_override_class_handler (const gchar *signal_name, 399 GType instance_type, 400 GCallback class_handler); 401 void g_signal_chain_from_overridden (const GValue *instance_and_params, 402 GValue *return_value); 403 void g_signal_chain_from_overridden_handler (gpointer instance, 404 ...); 405 406 407 /* --- convenience --- */ 408 /** 409 * g_signal_connect: 410 * @instance: the instance to connect to. 411 * @detailed_signal: a string of the form "signal-name::detail". 412 * @c_handler: the #GCallback to connect. 413 * @data: data to pass to @c_handler calls. 414 * 415 * Connects a #GCallback function to a signal for a particular object. 416 * 417 * The handler will be called before the default handler of the signal. 418 * 419 * Returns: the handler id 420 */ 421 #define g_signal_connect(instance, detailed_signal, c_handler, data) \ 422 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0) 423 /** 424 * g_signal_connect_after: 425 * @instance: the instance to connect to. 426 * @detailed_signal: a string of the form "signal-name::detail". 427 * @c_handler: the #GCallback to connect. 428 * @data: data to pass to @c_handler calls. 429 * 430 * Connects a #GCallback function to a signal for a particular object. 431 * 432 * The handler will be called after the default handler of the signal. 433 * 434 * Returns: the handler id 435 */ 436 #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ 437 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) 438 /** 439 * g_signal_connect_swapped: 440 * @instance: the instance to connect to. 441 * @detailed_signal: a string of the form "signal-name::detail". 442 * @c_handler: the #GCallback to connect. 443 * @data: data to pass to @c_handler calls. 444 * 445 * Connects a #GCallback function to a signal for a particular object. 446 * 447 * The instance on which the signal is emitted and @data will be swapped when 448 * calling the handler. 449 * 450 * Returns: the handler id 451 */ 452 #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ 453 g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED) 454 /** 455 * g_signal_handlers_disconnect_by_func: 456 * @instance: The instance to remove handlers from. 457 * @func: The C closure callback of the handlers (useless for non-C closures). 458 * @data: The closure data of the handlers' closures. 459 * 460 * Disconnects all handlers on an instance that match @func and @data. 461 * 462 * Returns: The number of handlers that matched. 463 */ 464 #define g_signal_handlers_disconnect_by_func(instance, func, data) \ 465 g_signal_handlers_disconnect_matched ((instance), \ 466 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 467 0, 0, NULL, (func), (data)) 468 /** 469 * g_signal_handlers_block_by_func: 470 * @instance: The instance to block handlers from. 471 * @func: The C closure callback of the handlers (useless for non-C closures). 472 * @data: The closure data of the handlers' closures. 473 * 474 * Blocks all handlers on an instance that match @func and @data. 475 * 476 * Returns: The number of handlers that matched. 477 */ 478 #define g_signal_handlers_block_by_func(instance, func, data) \ 479 g_signal_handlers_block_matched ((instance), \ 480 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 481 0, 0, NULL, (func), (data)) 482 /** 483 * g_signal_handlers_unblock_by_func: 484 * @instance: The instance to unblock handlers from. 485 * @func: The C closure callback of the handlers (useless for non-C closures). 486 * @data: The closure data of the handlers' closures. 487 * 488 * Unblocks all handlers on an instance that match @func and @data. 489 * 490 * Returns: The number of handlers that matched. 491 */ 492 #define g_signal_handlers_unblock_by_func(instance, func, data) \ 493 g_signal_handlers_unblock_matched ((instance), \ 494 (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 495 0, 0, NULL, (func), (data)) 496 497 498 gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, 499 GValue *return_accu, 500 const GValue *handler_return, 501 gpointer dummy); 502 503 /*< private >*/ 504 void g_signal_handlers_destroy (gpointer instance); 505 void _g_signals_destroy (GType itype); 506 507 G_END_DECLS 508 509 #endif /* __G_SIGNAL_H__ */ 510