1 /* GObject - GLib Type, Object, Parameter and Signal Library

     2  * Copyright (C) 2000-2001 Red Hat, Inc.

     3  * Portions copyright (c) 2006-2009 Nokia Corporation.  All rights reserved.

     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 IMPORT_C 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 IMPORT_C 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 IMPORT_C 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 IMPORT_C 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 IMPORT_C void                  g_signal_emitv        (const GValue       *instance_and_params,

   292 					     guint               signal_id,

   293 					     GQuark              detail,

   294 					     GValue             *return_value);

   295 IMPORT_C void                  g_signal_emit_valist  (gpointer            instance,

   296 					     guint               signal_id,

   297 					     GQuark              detail,

   298 					     va_list             var_args);

   299 IMPORT_C void                  g_signal_emit         (gpointer            instance,

   300 					     guint               signal_id,

   301 					     GQuark              detail,

   302 					     ...);

   303 IMPORT_C void                  g_signal_emit_by_name (gpointer            instance,

   304 					     const gchar        *detailed_signal,

   305 					     ...);

   306 IMPORT_C guint                 g_signal_lookup       (const gchar        *name,

   307 					     GType               itype);

   308 IMPORT_C G_CONST_RETURN gchar* g_signal_name         (guint               signal_id);

   309 IMPORT_C void                  g_signal_query        (guint               signal_id,

   310 					     GSignalQuery       *query);

   311 IMPORT_C guint*                g_signal_list_ids     (GType               itype,

   312 					     guint              *n_ids);

   313 IMPORT_C 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 IMPORT_C GSignalInvocationHint* g_signal_get_invocation_hint (gpointer    instance);

   319 

   320 

   321 /* --- signal emissions --- */

   322 IMPORT_C void	g_signal_stop_emission		    (gpointer		  instance,

   323 					     guint		  signal_id,

   324 					     GQuark		  detail);

   325 IMPORT_C void	g_signal_stop_emission_by_name	    (gpointer		  instance,

   326 					     const gchar	 *detailed_signal);

   327 IMPORT_C 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 IMPORT_C void	g_signal_remove_emission_hook	    (guint		  signal_id,

   333 					     gulong		  hook_id);

   334 

   335 

   336 /* --- signal handlers --- */

   337 IMPORT_C gboolean g_signal_has_handler_pending	      (gpointer		  instance,

   338 					       guint		  signal_id,

   339 					       GQuark		  detail,

   340 					       gboolean		  may_be_blocked);

   341 IMPORT_C gulong	 g_signal_connect_closure_by_id	      (gpointer		  instance,

   342 					       guint		  signal_id,

   343 					       GQuark		  detail,

   344 					       GClosure		 *closure,

   345 					       gboolean		  after);

   346 IMPORT_C gulong	 g_signal_connect_closure	      (gpointer		  instance,

   347 					       const gchar       *detailed_signal,

   348 					       GClosure		 *closure,

   349 					       gboolean		  after);

   350 IMPORT_C 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 IMPORT_C void	 g_signal_handler_block		      (gpointer		  instance,

   357 					       gulong		  handler_id);

   358 IMPORT_C void	 g_signal_handler_unblock	      (gpointer		  instance,

   359 					       gulong		  handler_id);

   360 IMPORT_C void	 g_signal_handler_disconnect	      (gpointer		  instance,

   361 					       gulong		  handler_id);

   362 IMPORT_C gboolean g_signal_handler_is_connected	      (gpointer		  instance,

   363 					       gulong		  handler_id);

   364 IMPORT_C 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 IMPORT_C 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 IMPORT_C 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 IMPORT_C 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 IMPORT_C void    g_signal_override_class_closure       (guint              signal_id,

   396                                                GType              instance_type,

   397                                                GClosure          *class_closure);

   398 IMPORT_C void    g_signal_override_class_handler       (const gchar       *signal_name,

   399                                                GType              instance_type,

   400                                                GCallback          class_handler);

   401 IMPORT_C void    g_signal_chain_from_overridden        (const GValue      *instance_and_params,

   402                                                GValue            *return_value);

   403 IMPORT_C 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 IMPORT_C gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,

   499 					    GValue                *return_accu,

   500 					    const GValue          *handler_return,

   501 					    gpointer               dummy);

   502 

   503 /*< private >*/

   504 IMPORT_C 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__ */