* 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 <http://www.gnu.org/licenses/>.
*/
+#ifndef __G_SIGNAL_H__
+#define __G_SIGNAL_H__
+
#if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
#error "Only <glib-object.h> can be included directly."
#endif
-#ifndef __G_SIGNAL_H__
-#define __G_SIGNAL_H__
-
#include <gobject/gclosure.h>
#include <gobject/gvalue.h>
#include <gobject/gparam.h>
*/
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
* the instance on which the signal was emitted.
- * @param_values: the instance on which the signal was emitted, followed by the
- * parameters of the emission.
+ * @param_values: (array length=n_param_values): the instance on which
+ * the signal was emitted, followed by the parameters of the emission.
* @data: user data associated with the hook.
*
* A simple function pointer to get invoked when the signal is emitted. This
* of as object methods which can be called generically by
* third-party code.
* @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
G_SIGNAL_NO_RECURSE = 1 << 3,
G_SIGNAL_DETAILED = 1 << 4,
G_SIGNAL_ACTION = 1 << 5,
- G_SIGNAL_NO_HOOKS = 1 << 6
+ G_SIGNAL_NO_HOOKS = 1 << 6,
+ 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 0x7f
+#define G_SIGNAL_FLAGS_MASK 0x1ff
/**
* GConnectFlags:
* @G_CONNECT_AFTER: whether the handler should be called before or after the
* @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:
* <programlisting>
* @return_type callback (#gpointer data1,
- * [#param_types param_names,]
- * #gpointer data2);
+ * [param_types param_names,]
+ * gpointer data2);
* </programlisting>
*
* A structure holding in-depth information for a specific signal. It is
/* --- signals --- */
+GLIB_AVAILABLE_IN_ALL
guint g_signal_newv (const gchar *signal_name,
GType itype,
GSignalFlags signal_flags,
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,
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,
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,
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);
-G_CONST_RETURN gchar* g_signal_name (guint signal_id);
+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,
GClosure *closure,
gpointer func,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_signal_handlers_block_matched (gpointer instance,
GSignalMatchType mask,
guint signal_id,
GClosure *closure,
gpointer func,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_signal_handlers_unblock_matched (gpointer instance,
GSignalMatchType mask,
guint signal_id,
GClosure *closure,
gpointer func,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_signal_handlers_disconnect_matched (gpointer instance,
GSignalMatchType mask,
guint signal_id,
/* --- 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,
...);
*
* 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)
*
* 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)
* The instance on which the signal is emitted and @data will be swapped when
* calling the handler.
*
- * 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)
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.
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);