* 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
* @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_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.
* 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
- * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> 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),
* @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:
- * <programlisting>
+ * @param_types: (array length=n_params): The individual parameter types for
+ * user callbacks, note that the effective callback signature is:
+ * |[<!-- language="C" -->
* @return_type callback (#gpointer data1,
- * [#param_types param_names,]
- * #gpointer data2);
- * </programlisting>
+ * [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.
/* --- 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);
+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)
* 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:
+ * |[<!-- language="C" -->
+ * g_signal_connect_swapped (button, "clicked",
+ * (GCallback) gtk_widget_hide, other_widget);
+ * ]|
+ *
+ * Rather than the cumbersome:
+ * |[<!-- language="C" -->
+ * 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)
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);
projects / platform / upstream / glib.git / blobdiff