sl@0: /* GObject - GLib Type, Object, Parameter and Signal Library sl@0: * Copyright (C) 2000-2001 Red Hat, Inc. sl@0: * Portions copyright (c) 2006-2009 Nokia Corporation. All rights reserved. sl@0: * This library is free software; you can redistribute it and/or sl@0: * modify it under the terms of the GNU Lesser General Public sl@0: * License as published by the Free Software Foundation; either sl@0: * version 2 of the License, or (at your option) any later version. sl@0: * sl@0: * This library is distributed in the hope that it will be useful, sl@0: * but WITHOUT ANY WARRANTY; without even the implied warranty of sl@0: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU sl@0: * Lesser General Public License for more details. sl@0: * sl@0: * You should have received a copy of the GNU Lesser General sl@0: * Public License along with this library; if not, write to the sl@0: * Free Software Foundation, Inc., 59 Temple Place, Suite 330, sl@0: * Boston, MA 02111-1307, USA. sl@0: */ sl@0: #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) sl@0: #error "Only can be included directly." sl@0: #endif sl@0: sl@0: #ifndef __G_SIGNAL_H__ sl@0: #define __G_SIGNAL_H__ sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: G_BEGIN_DECLS sl@0: sl@0: /* --- typedefs --- */ sl@0: typedef struct _GSignalQuery GSignalQuery; sl@0: typedef struct _GSignalInvocationHint GSignalInvocationHint; sl@0: /** sl@0: * GSignalCMarshaller: sl@0: * sl@0: * This is the signature of marshaller functions, required to marshall sl@0: * arrays of parameter values to signal emissions into C language callback sl@0: * invocations. It is merely an alias to #GClosureMarshal since the #GClosure sl@0: * mechanism takes over responsibility of actual function invocation for the sl@0: * signal system. sl@0: */ sl@0: typedef GClosureMarshal GSignalCMarshaller; sl@0: /** sl@0: * GSignalEmissionHook: sl@0: * @ihint: Signal invocation hint, see #GSignalInvocationHint. sl@0: * @n_param_values: the number of parameters to the function, including sl@0: * the instance on which the signal was emitted. sl@0: * @param_values: the instance on which the signal was emitted, followed by the sl@0: * parameters of the emission. sl@0: * @data: user data associated with the hook. sl@0: * sl@0: * A simple function pointer to get invoked when the signal is emitted. This sl@0: * allows you to tie a hook to the signal type, so that it will trap all sl@0: * emissions of that signal, from any object. sl@0: * sl@0: * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. sl@0: * sl@0: * Returns: whether it wants to stay connected. If it returns %FALSE, the signal sl@0: * hook is disconnected (and destroyed). sl@0: */ sl@0: typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, sl@0: guint n_param_values, sl@0: const GValue *param_values, sl@0: gpointer data); sl@0: /** sl@0: * GSignalAccumulator: sl@0: * @ihint: Signal invocation hint, see #GSignalInvocationHint. sl@0: * @return_accu: Accumulator to collect callback return values in, this sl@0: * is the return value of the current signal emission. sl@0: * @handler_return: A #GValue holding the return value of the signal handler. sl@0: * @data: Callback data that was specified when creating the signal. sl@0: * sl@0: * The signal accumulator is a special callback function that can be used sl@0: * to collect return values of the various callbacks that are called sl@0: * during a signal emission. The signal accumulator is specified at signal sl@0: * creation time, if it is left %NULL, no accumulation of callback return sl@0: * values is performed. The return value of signal emissions is then the sl@0: * value returned by the last callback. sl@0: * sl@0: * Returns: The accumulator function returns whether the signal emission sl@0: * should be aborted. Returning %FALSE means to abort the sl@0: * current emission and %TRUE is returned for continuation. sl@0: */ sl@0: typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, sl@0: GValue *return_accu, sl@0: const GValue *handler_return, sl@0: gpointer data); sl@0: sl@0: sl@0: /* --- run, match and connect types --- */ sl@0: /** sl@0: * GSignalFlags: sl@0: * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. sl@0: * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. sl@0: * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. sl@0: * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in sl@0: * emission for this very object will not be emitted recursively, sl@0: * but instead cause the first emission to be restarted. sl@0: * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name sl@0: * upon handler connections and emissions. sl@0: * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive sl@0: * objects from user code via g_signal_emit() and friends, without sl@0: * the need of being embedded into extra code that performs pre or sl@0: * post emission adjustments on the object. They can also be thought sl@0: * of as object methods which can be called generically by sl@0: * third-party code. sl@0: * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. sl@0: * sl@0: * The signal flags are used to specify a signal's behaviour, the overall sl@0: * signal description outlines how especially the RUN flags control the sl@0: * stages of a signal emission. sl@0: */ sl@0: typedef enum sl@0: { sl@0: G_SIGNAL_RUN_FIRST = 1 << 0, sl@0: G_SIGNAL_RUN_LAST = 1 << 1, sl@0: G_SIGNAL_RUN_CLEANUP = 1 << 2, sl@0: G_SIGNAL_NO_RECURSE = 1 << 3, sl@0: G_SIGNAL_DETAILED = 1 << 4, sl@0: G_SIGNAL_ACTION = 1 << 5, sl@0: G_SIGNAL_NO_HOOKS = 1 << 6 sl@0: } GSignalFlags; sl@0: /** sl@0: * G_SIGNAL_FLAGS_MASK: sl@0: * sl@0: * A mask for all #GSignalFlags bits. sl@0: */ sl@0: #define G_SIGNAL_FLAGS_MASK 0x7f sl@0: /** sl@0: * GConnectFlags: sl@0: * @G_CONNECT_AFTER: whether the handler should be called before or after the sl@0: * default handler of the signal. sl@0: * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when sl@0: * calling the handler. sl@0: * sl@0: * The connection flags are used to specify the behaviour of a signal's sl@0: * connection. sl@0: */ sl@0: typedef enum sl@0: { sl@0: G_CONNECT_AFTER = 1 << 0, sl@0: G_CONNECT_SWAPPED = 1 << 1 sl@0: } GConnectFlags; sl@0: /** sl@0: * GSignalMatchType: sl@0: * @G_SIGNAL_MATCH_ID: The signal id must be equal. sl@0: * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. sl@0: * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. sl@0: * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. sl@0: * @G_SIGNAL_MATCH_DATA: The closure data must be the same. sl@0: * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. sl@0: * sl@0: * The match types specify what g_signal_handlers_block_matched(), sl@0: * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() sl@0: * match signals by. sl@0: */ sl@0: typedef enum sl@0: { sl@0: G_SIGNAL_MATCH_ID = 1 << 0, sl@0: G_SIGNAL_MATCH_DETAIL = 1 << 1, sl@0: G_SIGNAL_MATCH_CLOSURE = 1 << 2, sl@0: G_SIGNAL_MATCH_FUNC = 1 << 3, sl@0: G_SIGNAL_MATCH_DATA = 1 << 4, sl@0: G_SIGNAL_MATCH_UNBLOCKED = 1 << 5 sl@0: } GSignalMatchType; sl@0: /** sl@0: * G_SIGNAL_MATCH_MASK: sl@0: * sl@0: * A mask for all #GSignalMatchType bits. sl@0: */ sl@0: #define G_SIGNAL_MATCH_MASK 0x3f sl@0: /** sl@0: * G_SIGNAL_TYPE_STATIC_SCOPE: sl@0: * sl@0: * This macro flags signal argument types for which the signal system may sl@0: * assume that instances thereof remain persistent across all signal emissions sl@0: * they are used in. This is only useful for non ref-counted, value-copy types. sl@0: * sl@0: * To flag a signal argument in this way, add sl@0: * | G_SIGNAL_TYPE_STATIC_SCOPE to the corresponding argument sl@0: * of g_signal_new(). sl@0: * |[ sl@0: * g_signal_new ("size_request", sl@0: * G_TYPE_FROM_CLASS (gobject_class), sl@0: * G_SIGNAL_RUN_FIRST, sl@0: * G_STRUCT_OFFSET (GtkWidgetClass, size_request), sl@0: * NULL, NULL, sl@0: * _gtk_marshal_VOID__BOXED, sl@0: * G_TYPE_NONE, 1, sl@0: * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); sl@0: * ]| sl@0: */ sl@0: #define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT) sl@0: sl@0: sl@0: /* --- signal information --- */ sl@0: /** sl@0: * GSignalInvocationHint: sl@0: * @signal_id: The signal id of the signal invoking the callback sl@0: * @detail: The detail passed on for this emission sl@0: * @run_type: The stage the signal emission is currently in, this sl@0: * field will contain one of %G_SIGNAL_RUN_FIRST, sl@0: * %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. sl@0: * sl@0: * The #GSignalInvocationHint structure is used to pass on additional information sl@0: * to callbacks during a signal emission. sl@0: */ sl@0: struct _GSignalInvocationHint sl@0: { sl@0: guint signal_id; sl@0: GQuark detail; sl@0: GSignalFlags run_type; sl@0: }; sl@0: /** sl@0: * GSignalQuery: sl@0: * @signal_id: The signal id of the signal being queried, or 0 if the sl@0: * signal to be queried was unknown. sl@0: * @signal_name: The signal name. sl@0: * @itype: The interface/instance type that this signal can be emitted for. sl@0: * @signal_flags: The signal flags as passed in to g_signal_new(). sl@0: * @return_type: The return type for user callbacks. sl@0: * @n_params: The number of parameters that user callbacks take. sl@0: * @param_types: The individual parameter types for user callbacks, note that the sl@0: * effective callback signature is: sl@0: * sl@0: * @return_type callback (#gpointer data1, sl@0: * [#param_types param_names,] sl@0: * #gpointer data2); sl@0: * sl@0: * sl@0: * A structure holding in-depth information for a specific signal. It is sl@0: * filled in by the g_signal_query() function. sl@0: */ sl@0: struct _GSignalQuery sl@0: { sl@0: guint signal_id; sl@0: const gchar *signal_name; sl@0: GType itype; sl@0: GSignalFlags signal_flags; sl@0: GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ sl@0: guint n_params; sl@0: const GType *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ sl@0: }; sl@0: sl@0: sl@0: /* --- signals --- */ sl@0: IMPORT_C guint g_signal_newv (const gchar *signal_name, sl@0: GType itype, sl@0: GSignalFlags signal_flags, sl@0: GClosure *class_closure, sl@0: GSignalAccumulator accumulator, sl@0: gpointer accu_data, sl@0: GSignalCMarshaller c_marshaller, sl@0: GType return_type, sl@0: guint n_params, sl@0: GType *param_types); sl@0: IMPORT_C guint g_signal_new_valist (const gchar *signal_name, sl@0: GType itype, sl@0: GSignalFlags signal_flags, sl@0: GClosure *class_closure, sl@0: GSignalAccumulator accumulator, sl@0: gpointer accu_data, sl@0: GSignalCMarshaller c_marshaller, sl@0: GType return_type, sl@0: guint n_params, sl@0: va_list args); sl@0: IMPORT_C guint g_signal_new (const gchar *signal_name, sl@0: GType itype, sl@0: GSignalFlags signal_flags, sl@0: guint class_offset, sl@0: GSignalAccumulator accumulator, sl@0: gpointer accu_data, sl@0: GSignalCMarshaller c_marshaller, sl@0: GType return_type, sl@0: guint n_params, sl@0: ...); sl@0: IMPORT_C guint g_signal_new_class_handler (const gchar *signal_name, sl@0: GType itype, sl@0: GSignalFlags signal_flags, sl@0: GCallback class_handler, sl@0: GSignalAccumulator accumulator, sl@0: gpointer accu_data, sl@0: GSignalCMarshaller c_marshaller, sl@0: GType return_type, sl@0: guint n_params, sl@0: ...); sl@0: sl@0: IMPORT_C void g_signal_emitv (const GValue *instance_and_params, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GValue *return_value); sl@0: IMPORT_C void g_signal_emit_valist (gpointer instance, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: va_list var_args); sl@0: IMPORT_C void g_signal_emit (gpointer instance, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: ...); sl@0: IMPORT_C void g_signal_emit_by_name (gpointer instance, sl@0: const gchar *detailed_signal, sl@0: ...); sl@0: IMPORT_C guint g_signal_lookup (const gchar *name, sl@0: GType itype); sl@0: IMPORT_C G_CONST_RETURN gchar* g_signal_name (guint signal_id); sl@0: IMPORT_C void g_signal_query (guint signal_id, sl@0: GSignalQuery *query); sl@0: IMPORT_C guint* g_signal_list_ids (GType itype, sl@0: guint *n_ids); sl@0: IMPORT_C gboolean g_signal_parse_name (const gchar *detailed_signal, sl@0: GType itype, sl@0: guint *signal_id_p, sl@0: GQuark *detail_p, sl@0: gboolean force_detail_quark); sl@0: IMPORT_C GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance); sl@0: sl@0: sl@0: /* --- signal emissions --- */ sl@0: IMPORT_C void g_signal_stop_emission (gpointer instance, sl@0: guint signal_id, sl@0: GQuark detail); sl@0: IMPORT_C void g_signal_stop_emission_by_name (gpointer instance, sl@0: const gchar *detailed_signal); sl@0: IMPORT_C gulong g_signal_add_emission_hook (guint signal_id, sl@0: GQuark detail, sl@0: GSignalEmissionHook hook_func, sl@0: gpointer hook_data, sl@0: GDestroyNotify data_destroy); sl@0: IMPORT_C void g_signal_remove_emission_hook (guint signal_id, sl@0: gulong hook_id); sl@0: sl@0: sl@0: /* --- signal handlers --- */ sl@0: IMPORT_C gboolean g_signal_has_handler_pending (gpointer instance, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: gboolean may_be_blocked); sl@0: IMPORT_C gulong g_signal_connect_closure_by_id (gpointer instance, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GClosure *closure, sl@0: gboolean after); sl@0: IMPORT_C gulong g_signal_connect_closure (gpointer instance, sl@0: const gchar *detailed_signal, sl@0: GClosure *closure, sl@0: gboolean after); sl@0: IMPORT_C gulong g_signal_connect_data (gpointer instance, sl@0: const gchar *detailed_signal, sl@0: GCallback c_handler, sl@0: gpointer data, sl@0: GClosureNotify destroy_data, sl@0: GConnectFlags connect_flags); sl@0: IMPORT_C void g_signal_handler_block (gpointer instance, sl@0: gulong handler_id); sl@0: IMPORT_C void g_signal_handler_unblock (gpointer instance, sl@0: gulong handler_id); sl@0: IMPORT_C void g_signal_handler_disconnect (gpointer instance, sl@0: gulong handler_id); sl@0: IMPORT_C gboolean g_signal_handler_is_connected (gpointer instance, sl@0: gulong handler_id); sl@0: IMPORT_C gulong g_signal_handler_find (gpointer instance, sl@0: GSignalMatchType mask, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GClosure *closure, sl@0: gpointer func, sl@0: gpointer data); sl@0: IMPORT_C guint g_signal_handlers_block_matched (gpointer instance, sl@0: GSignalMatchType mask, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GClosure *closure, sl@0: gpointer func, sl@0: gpointer data); sl@0: IMPORT_C guint g_signal_handlers_unblock_matched (gpointer instance, sl@0: GSignalMatchType mask, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GClosure *closure, sl@0: gpointer func, sl@0: gpointer data); sl@0: IMPORT_C guint g_signal_handlers_disconnect_matched (gpointer instance, sl@0: GSignalMatchType mask, sl@0: guint signal_id, sl@0: GQuark detail, sl@0: GClosure *closure, sl@0: gpointer func, sl@0: gpointer data); sl@0: sl@0: sl@0: /* --- overriding and chaining --- */ sl@0: IMPORT_C void g_signal_override_class_closure (guint signal_id, sl@0: GType instance_type, sl@0: GClosure *class_closure); sl@0: IMPORT_C void g_signal_override_class_handler (const gchar *signal_name, sl@0: GType instance_type, sl@0: GCallback class_handler); sl@0: IMPORT_C void g_signal_chain_from_overridden (const GValue *instance_and_params, sl@0: GValue *return_value); sl@0: IMPORT_C void g_signal_chain_from_overridden_handler (gpointer instance, sl@0: ...); sl@0: sl@0: sl@0: /* --- convenience --- */ sl@0: /** sl@0: * g_signal_connect: sl@0: * @instance: the instance to connect to. sl@0: * @detailed_signal: a string of the form "signal-name::detail". sl@0: * @c_handler: the #GCallback to connect. sl@0: * @data: data to pass to @c_handler calls. sl@0: * sl@0: * Connects a #GCallback function to a signal for a particular object. sl@0: * sl@0: * The handler will be called before the default handler of the signal. sl@0: * sl@0: * Returns: the handler id sl@0: */ sl@0: #define g_signal_connect(instance, detailed_signal, c_handler, data) \ sl@0: g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0) sl@0: /** sl@0: * g_signal_connect_after: sl@0: * @instance: the instance to connect to. sl@0: * @detailed_signal: a string of the form "signal-name::detail". sl@0: * @c_handler: the #GCallback to connect. sl@0: * @data: data to pass to @c_handler calls. sl@0: * sl@0: * Connects a #GCallback function to a signal for a particular object. sl@0: * sl@0: * The handler will be called after the default handler of the signal. sl@0: * sl@0: * Returns: the handler id sl@0: */ sl@0: #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ sl@0: g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) sl@0: /** sl@0: * g_signal_connect_swapped: sl@0: * @instance: the instance to connect to. sl@0: * @detailed_signal: a string of the form "signal-name::detail". sl@0: * @c_handler: the #GCallback to connect. sl@0: * @data: data to pass to @c_handler calls. sl@0: * sl@0: * Connects a #GCallback function to a signal for a particular object. sl@0: * sl@0: * The instance on which the signal is emitted and @data will be swapped when sl@0: * calling the handler. sl@0: * sl@0: * Returns: the handler id sl@0: */ sl@0: #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ sl@0: g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED) sl@0: /** sl@0: * g_signal_handlers_disconnect_by_func: sl@0: * @instance: The instance to remove handlers from. sl@0: * @func: The C closure callback of the handlers (useless for non-C closures). sl@0: * @data: The closure data of the handlers' closures. sl@0: * sl@0: * Disconnects all handlers on an instance that match @func and @data. sl@0: * sl@0: * Returns: The number of handlers that matched. sl@0: */ sl@0: #define g_signal_handlers_disconnect_by_func(instance, func, data) \ sl@0: g_signal_handlers_disconnect_matched ((instance), \ sl@0: (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ sl@0: 0, 0, NULL, (func), (data)) sl@0: /** sl@0: * g_signal_handlers_block_by_func: sl@0: * @instance: The instance to block handlers from. sl@0: * @func: The C closure callback of the handlers (useless for non-C closures). sl@0: * @data: The closure data of the handlers' closures. sl@0: * sl@0: * Blocks all handlers on an instance that match @func and @data. sl@0: * sl@0: * Returns: The number of handlers that matched. sl@0: */ sl@0: #define g_signal_handlers_block_by_func(instance, func, data) \ sl@0: g_signal_handlers_block_matched ((instance), \ sl@0: (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ sl@0: 0, 0, NULL, (func), (data)) sl@0: /** sl@0: * g_signal_handlers_unblock_by_func: sl@0: * @instance: The instance to unblock handlers from. sl@0: * @func: The C closure callback of the handlers (useless for non-C closures). sl@0: * @data: The closure data of the handlers' closures. sl@0: * sl@0: * Unblocks all handlers on an instance that match @func and @data. sl@0: * sl@0: * Returns: The number of handlers that matched. sl@0: */ sl@0: #define g_signal_handlers_unblock_by_func(instance, func, data) \ sl@0: g_signal_handlers_unblock_matched ((instance), \ sl@0: (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ sl@0: 0, 0, NULL, (func), (data)) sl@0: sl@0: sl@0: IMPORT_C gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, sl@0: GValue *return_accu, sl@0: const GValue *handler_return, sl@0: gpointer dummy); sl@0: sl@0: /*< private >*/ sl@0: IMPORT_C void g_signal_handlers_destroy (gpointer instance); sl@0: void _g_signals_destroy (GType itype); sl@0: sl@0: G_END_DECLS sl@0: sl@0: #endif /* __G_SIGNAL_H__ */