X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gobject%2Fgsignal.h;h=c0b068163fa43ba574e60c724721cc8ce9e7afa1;hb=9da85c7262325478e8730ae9f3e76bd0528a9a8c;hp=6c70d5319c25840c123e75632e61a4b61f2b146d;hpb=fd1a12ca4dd164be612fbcd7ab8874b91193cdac;p=platform%2Fupstream%2Fglib.git diff --git a/gobject/gsignal.h b/gobject/gsignal.h index 6c70d53..c0b0681 100644 --- a/gobject/gsignal.h +++ b/gobject/gsignal.h @@ -12,17 +12,15 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General - * Public License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place, Suite 330, - * Boston, MA 02111-1307, USA. + * Public License along with this library; if not, see . */ +#ifndef __G_SIGNAL_H__ +#define __G_SIGNAL_H__ + #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) #error "Only can be included directly." #endif -#ifndef __G_SIGNAL_H__ -#define __G_SIGNAL_H__ - #include #include #include @@ -44,6 +42,14 @@ typedef struct _GSignalInvocationHint GSignalInvocationHint; */ typedef GClosureMarshal GSignalCMarshaller; /** + * GSignalCVaMarshaller: + * + * This is the signature of va_list marshaller functions, an optional + * marshaller that can be used in some situations to avoid + * marshalling the signal argument into GValues. + */ +typedef GVaClosureMarshal GSignalCVaMarshaller; +/** * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. * @n_param_values: the number of parameters to the function, including @@ -110,6 +116,9 @@ typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the * arguments, even if there are no signal handlers connected. Since 2.30. + * @G_SIGNAL_DEPRECATED: The signal is deprecated and will be removed + * in a future version. A warning will be generated if it is connected while + * running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. * * The signal flags are used to specify a signal's behaviour, the overall * signal description outlines how especially the RUN flags control the @@ -124,20 +133,21 @@ typedef enum G_SIGNAL_DETAILED = 1 << 4, G_SIGNAL_ACTION = 1 << 5, G_SIGNAL_NO_HOOKS = 1 << 6, - G_SIGNAL_MUST_COLLECT = 1 << 7 + G_SIGNAL_MUST_COLLECT = 1 << 7, + G_SIGNAL_DEPRECATED = 1 << 8 } GSignalFlags; /** * G_SIGNAL_FLAGS_MASK: * * A mask for all #GSignalFlags bits. */ -#define G_SIGNAL_FLAGS_MASK 0xff +#define G_SIGNAL_FLAGS_MASK 0x1ff /** * GConnectFlags: * @G_CONNECT_AFTER: whether the handler should be called before or after the * default handler of the signal. * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when - * calling the handler. + * calling the handler; see g_signal_connect_swapped() for an example. * * The connection flags are used to specify the behaviour of a signal's * connection. @@ -182,9 +192,8 @@ typedef enum * assume that instances thereof remain persistent across all signal emissions * they are used in. This is only useful for non ref-counted, value-copy types. * - * To flag a signal argument in this way, add - * | G_SIGNAL_TYPE_STATIC_SCOPE to the corresponding argument - * of g_signal_new(). + * To flag a signal argument in this way, add `| G_SIGNAL_TYPE_STATIC_SCOPE` + * to the corresponding argument of g_signal_new(). * |[ * g_signal_new ("size_request", * G_TYPE_FROM_CLASS (gobject_class), @@ -226,13 +235,13 @@ struct _GSignalInvocationHint * @signal_flags: The signal flags as passed in to g_signal_new(). * @return_type: The return type for user callbacks. * @n_params: The number of parameters that user callbacks take. - * @param_types: The individual parameter types for user callbacks, note that the - * effective callback signature is: - * + * @param_types: (array length=n_params): The individual parameter types for + * user callbacks, note that the effective callback signature is: + * |[ * @return_type callback (#gpointer data1, - * [#param_types param_names,] - * #gpointer data2); - * + * [param_types param_names,] + * gpointer data2); + * ]| * * A structure holding in-depth information for a specific signal. It is * filled in by the g_signal_query() function. @@ -250,6 +259,7 @@ struct _GSignalQuery /* --- signals --- */ +GLIB_AVAILABLE_IN_ALL guint g_signal_newv (const gchar *signal_name, GType itype, GSignalFlags signal_flags, @@ -260,6 +270,7 @@ guint g_signal_newv (const gchar *signal_name, GType return_type, guint n_params, GType *param_types); +GLIB_AVAILABLE_IN_ALL guint g_signal_new_valist (const gchar *signal_name, GType itype, GSignalFlags signal_flags, @@ -270,6 +281,7 @@ guint g_signal_new_valist (const gchar *signal_name, GType return_type, guint n_params, va_list args); +GLIB_AVAILABLE_IN_ALL guint g_signal_new (const gchar *signal_name, GType itype, GSignalFlags signal_flags, @@ -280,6 +292,7 @@ guint g_signal_new (const gchar *signal_name, GType return_type, guint n_params, ...); +GLIB_AVAILABLE_IN_ALL guint g_signal_new_class_handler (const gchar *signal_name, GType itype, GSignalFlags signal_flags, @@ -290,80 +303,107 @@ guint g_signal_new_class_handler (const gchar *signal_name, GType return_type, guint n_params, ...); +GLIB_AVAILABLE_IN_ALL +void g_signal_set_va_marshaller (guint signal_id, + GType instance_type, + GSignalCVaMarshaller va_marshaller); +GLIB_AVAILABLE_IN_ALL void g_signal_emitv (const GValue *instance_and_params, guint signal_id, GQuark detail, GValue *return_value); +GLIB_AVAILABLE_IN_ALL void g_signal_emit_valist (gpointer instance, guint signal_id, GQuark detail, va_list var_args); +GLIB_AVAILABLE_IN_ALL void g_signal_emit (gpointer instance, guint signal_id, GQuark detail, ...); +GLIB_AVAILABLE_IN_ALL void g_signal_emit_by_name (gpointer instance, const gchar *detailed_signal, ...); +GLIB_AVAILABLE_IN_ALL guint g_signal_lookup (const gchar *name, GType itype); +GLIB_AVAILABLE_IN_ALL const gchar * g_signal_name (guint signal_id); +GLIB_AVAILABLE_IN_ALL void g_signal_query (guint signal_id, GSignalQuery *query); +GLIB_AVAILABLE_IN_ALL guint* g_signal_list_ids (GType itype, guint *n_ids); +GLIB_AVAILABLE_IN_ALL gboolean g_signal_parse_name (const gchar *detailed_signal, GType itype, guint *signal_id_p, GQuark *detail_p, gboolean force_detail_quark); +GLIB_AVAILABLE_IN_ALL GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance); /* --- signal emissions --- */ +GLIB_AVAILABLE_IN_ALL void g_signal_stop_emission (gpointer instance, guint signal_id, GQuark detail); +GLIB_AVAILABLE_IN_ALL void g_signal_stop_emission_by_name (gpointer instance, const gchar *detailed_signal); +GLIB_AVAILABLE_IN_ALL gulong g_signal_add_emission_hook (guint signal_id, GQuark detail, GSignalEmissionHook hook_func, gpointer hook_data, GDestroyNotify data_destroy); +GLIB_AVAILABLE_IN_ALL void g_signal_remove_emission_hook (guint signal_id, gulong hook_id); /* --- signal handlers --- */ +GLIB_AVAILABLE_IN_ALL gboolean g_signal_has_handler_pending (gpointer instance, guint signal_id, GQuark detail, gboolean may_be_blocked); +GLIB_AVAILABLE_IN_ALL gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, GQuark detail, GClosure *closure, gboolean after); +GLIB_AVAILABLE_IN_ALL gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, GClosure *closure, gboolean after); +GLIB_AVAILABLE_IN_ALL gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer data, GClosureNotify destroy_data, GConnectFlags connect_flags); +GLIB_AVAILABLE_IN_ALL void g_signal_handler_block (gpointer instance, gulong handler_id); +GLIB_AVAILABLE_IN_ALL void g_signal_handler_unblock (gpointer instance, gulong handler_id); +GLIB_AVAILABLE_IN_ALL void g_signal_handler_disconnect (gpointer instance, gulong handler_id); +GLIB_AVAILABLE_IN_ALL gboolean g_signal_handler_is_connected (gpointer instance, gulong handler_id); +GLIB_AVAILABLE_IN_ALL gulong g_signal_handler_find (gpointer instance, GSignalMatchType mask, guint signal_id, @@ -371,6 +411,7 @@ gulong g_signal_handler_find (gpointer instance, GClosure *closure, gpointer func, gpointer data); +GLIB_AVAILABLE_IN_ALL guint g_signal_handlers_block_matched (gpointer instance, GSignalMatchType mask, guint signal_id, @@ -378,6 +419,7 @@ guint g_signal_handlers_block_matched (gpointer instance, GClosure *closure, gpointer func, gpointer data); +GLIB_AVAILABLE_IN_ALL guint g_signal_handlers_unblock_matched (gpointer instance, GSignalMatchType mask, guint signal_id, @@ -385,6 +427,7 @@ guint g_signal_handlers_unblock_matched (gpointer instance, GClosure *closure, gpointer func, gpointer data); +GLIB_AVAILABLE_IN_ALL guint g_signal_handlers_disconnect_matched (gpointer instance, GSignalMatchType mask, guint signal_id, @@ -395,14 +438,18 @@ guint g_signal_handlers_disconnect_matched (gpointer instance, /* --- overriding and chaining --- */ +GLIB_AVAILABLE_IN_ALL void g_signal_override_class_closure (guint signal_id, GType instance_type, GClosure *class_closure); +GLIB_AVAILABLE_IN_ALL void g_signal_override_class_handler (const gchar *signal_name, GType instance_type, GCallback class_handler); +GLIB_AVAILABLE_IN_ALL void g_signal_chain_from_overridden (const GValue *instance_and_params, GValue *return_value); +GLIB_AVAILABLE_IN_ALL void g_signal_chain_from_overridden_handler (gpointer instance, ...); @@ -419,7 +466,7 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * * The handler will be called before the default handler of the signal. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ #define g_signal_connect(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0) @@ -434,7 +481,7 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * * The handler will be called after the default handler of the signal. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) @@ -448,9 +495,31 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * Connects a #GCallback function to a signal for a particular object. * * The instance on which the signal is emitted and @data will be swapped when - * calling the handler. + * calling the handler. This is useful when calling pre-existing functions to + * operate purely on the @data, rather than the @instance: swapping the + * parameters avoids the need to write a wrapper function. + * + * For example, this allows the shorter code: + * |[ + * g_signal_connect_swapped (button, "clicked", + * (GCallback) gtk_widget_hide, other_widget); + * ]| + * + * Rather than the cumbersome: + * |[ + * static void + * button_clicked_cb (GtkButton *button, GtkWidget *other_widget) + * { + * gtk_widget_hide (other_widget); + * } + * + * … + * + * g_signal_connect (button, "clicked", + * (GCallback) button_clicked_cb, other_widget); + * ]| * - * Returns: the handler id + * Returns: the handler ID (always greater than 0 for successful connections) */ #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED) @@ -468,6 +537,21 @@ void g_signal_chain_from_overridden_handler (gpointer instance, g_signal_handlers_disconnect_matched ((instance), \ (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 0, 0, NULL, (func), (data)) + +/** + * g_signal_handlers_disconnect_by_data: + * @instance: The instance to remove handlers from + * @data: the closure data of the handlers' closures + * + * Disconnects all handlers on an instance that match @data. + * + * Returns: The number of handlers that matched. + * + * Since: 2.32 + */ +#define g_signal_handlers_disconnect_by_data(instance, data) \ + g_signal_handlers_disconnect_matched ((instance), G_SIGNAL_MATCH_DATA, 0, 0, NULL, NULL, (data)) + /** * g_signal_handlers_block_by_func: * @instance: The instance to block handlers from. @@ -498,17 +582,20 @@ void g_signal_chain_from_overridden_handler (gpointer instance, 0, 0, NULL, (func), (data)) +GLIB_AVAILABLE_IN_ALL gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy); +GLIB_AVAILABLE_IN_ALL gboolean g_signal_accumulator_first_wins (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy); /*< private >*/ +GLIB_AVAILABLE_IN_ALL void g_signal_handlers_destroy (gpointer instance); void _g_signals_destroy (GType itype);