diff options
Diffstat (limited to 'gobject/gsignal.c')
| -rw-r--r-- | gobject/gsignal.c | 551 |
1 files changed, 550 insertions, 1 deletions
diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 8ce1b6c6a..8a9a33c2f 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -19,7 +19,67 @@ * this code is based on the original GtkSignal implementation * for the Gtk+ library by Peter Mattis <petm@xcf.berkeley.edu> */ - +/** + * SECTION:signals + * @Short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @Title: Signals + * + * The basic concept of the signal system is that of the <emphasis>emission</emphasis> + * of a signal. + * Signals are introduced per-type and are identified through strings. + * Signals introduced for a parent type are available in derived types as well, + * so basically they are a per-type facility that is inherited. + * A signal emission mainly involves invocation of a certain set of callbacks in + * precisely defined manner. There are two main categories of such callbacks, + * per-object + * i'm referring to those types as "object types" in the following, simply + * because that is the context most users will encounter signals in. + * + * ones and user provided ones. + * The per-object callbacks are most often referred to as "object method + * handler" or "default (signal) handler", while user provided callbacks are + * usually just called "signal handler". + * The object method handler is provided at signal creation time (this most + * frequently happens at the end of an object class' creation), while user + * provided handlers are frequently connected and disconnected to/from a certain + * signal on certain object instances. + * + * A signal emission consists of five stages, unless prematurely stopped: + * <variablelist> + * <varlistentry><term></term><listitem><para> + * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * </para></listitem></varlistentry> + * </variablelist> + * The user-provided signal handlers are called in the order they were + * connected in. + * All handlers may prematurely stop a signal emission, and any number of + * handlers may be connected, disconnected, blocked or unblocked during + * a signal emission. + * There are certain criteria for skipping user handlers in stages 2 and 4 + * of a signal emission. + * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted + * during callback invocation, to return from the "blocked" state, a + * handler has to get unblocked exactly the same amount of times + * it has been blocked before. + * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional + * "detail" argument passed in to g_signal_emit() has to match the detail + * argument of the signal handler currently subject to invocation. + * Specification of no detail argument for signal handlers (omission of the + * detail part of the signal specification upon connection) serves as a + * wildcard and matches any detail argument passed in to emission. + */ /* * MT safe */ @@ -746,6 +806,20 @@ _g_signals_destroy (GType itype) SIGNAL_UNLOCK (); } +/** + * g_signal_stop_emission: + * @instance: the object whose signal handlers you wish to stop. + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail which the signal was emitted with. + * + * Stops a signal's current emission. + * + * This will prevent the default method from running, if the signal was + * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" + * flag). + * + * Prints a warning if used on a signal which isn't being emitted. + */ void g_signal_stop_emission (gpointer instance, guint signal_id, @@ -801,6 +875,20 @@ signal_finalize_hook (GHookList *hook_list, } } +/** + * g_signal_add_emission_hook: + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail on which to call the hook. + * @hook_func: a #GSignalEmissionHook function. + * @hook_data: user data for @hook_func. + * @data_destroy: a #GDestroyNotify for @hook_data. + * + * Adds an emission hook for a signal, which will get called for any emission + * of that signal, independent of the instance. This is possible only + * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * + * Returns: the hook id, for later use with g_signal_remove_emission_hook(). + */ gulong g_signal_add_emission_hook (guint signal_id, GQuark detail, @@ -856,6 +944,14 @@ g_signal_add_emission_hook (guint signal_id, return hook->hook_id; } +/** + * g_signal_remove_emission_hook: + * @signal_id: the id of the signal + * @hook_id: the id of the emission hook, as returned by + * g_signal_add_emission_hook() + * + * Deletes an emission hook. + */ void g_signal_remove_emission_hook (guint signal_id, gulong hook_id) @@ -918,6 +1014,19 @@ signal_parse_name (const gchar *name, return signal_id; } +/** + * g_signal_parse_name: + * @detailed_signal: a string of the form "signal-name::detail". + * @itype: The interface/instance type that introduced "signal-name". + * @signal_id_p: Location to store the signal id. + * @detail_p: Location to store the detail quark. + * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. + * + * Internal function to parse a signal name into its @signal_id + * and @detail quark. + * + * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + */ gboolean g_signal_parse_name (const gchar *detailed_signal, GType itype, @@ -949,6 +1058,16 @@ g_signal_parse_name (const gchar *detailed_signal, return TRUE; } +/** + * g_signal_stop_emission_by_name: + * @instance: the object whose signal handlers you wish to stop. + * @detailed_signal: a string of the form "signal-name::detail". + * + * Stops a signal's current emission. + * + * This is just like g_signal_stop_emission() except it will look up the + * signal id for you. + */ void g_signal_stop_emission_by_name (gpointer instance, const gchar *detailed_signal) @@ -994,6 +1113,21 @@ g_signal_stop_emission_by_name (gpointer instance, SIGNAL_UNLOCK (); } +/** + * g_signal_lookup: + * @name: the signal's name. + * @itype: the type that the signal operates on. + * + * Given the name of the signal and the type of object it connects to, gets + * the signal's identifying integer. Emitting the signal by number is + * somewhat faster than using the name each time. + * + * Also tries the ancestors of the given type. + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal's identifying number, or 0 if no signal was found. + */ guint g_signal_lookup (const gchar *name, GType itype) @@ -1022,6 +1156,17 @@ g_signal_lookup (const gchar *name, return signal_id; } +/** + * g_signal_list_ids: + * @itype: Instance or interface type. + * @n_ids: Location to store the number of signal ids for @itype. + * + * Lists the signals by id that a certain instance or interface type + * created. Further information about the signals can be acquired through + * g_signal_query(). + * + * Returns: Newly allocated array of signal IDs. + */ guint* g_signal_list_ids (GType itype, guint *n_ids) @@ -1069,6 +1214,16 @@ g_signal_list_ids (GType itype, return (guint*) g_array_free (result, FALSE); } +/** + * g_signal_name: + * @signal_id: the signal's identifying number. + * + * Given the signal's identifier, finds its name. + * + * Two different signals may have the same name, if they have differing types. + * + * Returns: the signal name, or %NULL if the signal number was invalid. + */ G_CONST_RETURN gchar* g_signal_name (guint signal_id) { @@ -1083,6 +1238,19 @@ g_signal_name (guint signal_id) return (char*) name; } +/** + * g_signal_query: + * @signal_id: The signal id of the signal to query information for. + * @query: A user provided structure that is filled in with constant + * values upon success. + * + * Queries the signal system for in-depth information about a + * specific signal. This function will fill in a user-provided + * structure to hold signal-specific information. If an invalid + * signal id is passed in, the @signal_id member of the #GSignalQuery + * is 0. All members filled into the #GSignalQuery structure should + * be considered constant and have to be left untouched. + */ void g_signal_query (guint signal_id, GSignalQuery *query) @@ -1108,6 +1276,38 @@ g_signal_query (guint signal_id, SIGNAL_UNLOCK (); } +/** + * g_signal_new: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_offset: The offset of the function pointer in the class structure + * for this type. Used to invoke a class method generically. Pass 0 to + * not associate a class method with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * A signal name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a signal name must be a letter. Names which violate these + * rules lead to undefined behaviour of the GSignal system. + * + * When registering a signal and looking up a signal, either separator can + * be used, but they cannot be mixed. + * + * Returns: the signal id + */ guint g_signal_new (const gchar *signal_name, GType itype, @@ -1210,6 +1410,30 @@ signal_add_class_closure (SignalNode *node, g_closure_set_marshal (closure, node->c_marshaller); } +/** + * g_signal_newv: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_closure: The closure to invoke on signal emission; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the length of @param_types. + * @param_types: an array types, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ guint g_signal_newv (const gchar *signal_name, GType itype, @@ -1344,6 +1568,30 @@ g_signal_newv (const gchar *signal_name, return signal_id; } +/** + * g_signal_new_valist: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_closure: The closure to invoke on signal emission; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the number of parameter types in @args. + * @args: va_list of #GType, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ guint g_signal_new_valist (const gchar *signal_name, GType itype, @@ -1433,6 +1681,17 @@ signal_destroy_R (SignalNode *signal_node) SIGNAL_LOCK (); } +/** + * g_signal_override_class_closure: + * @signal_id: the signal id + * @instance_type: the instance type on which to override the class closure + * for the signal. + * @class_closure: the closure. + * + * Overrides the class closure (i.e. the default handler) for the given signal + * for emissions on instances of @instance_type. @instance_type must be derived + * from the type to which the signal belongs. + */ void g_signal_override_class_closure (guint signal_id, GType instance_type, @@ -1459,6 +1718,17 @@ g_signal_override_class_closure (guint signal_id, SIGNAL_UNLOCK (); } +/** + * g_signal_chain_from_overridden: + * @instance_and_params: the argument list of the signal emission. The first + * element in the array is a #GValue for the instance the signal is being + * emitted on. The rest are any arguments to be passed to the signal. + * @return_value: Location for the return value. + * + * Calls the original class closure of a signal. This function should only + * be called from an overridden class closure; see + * g_signal_override_class_closure(). + */ void g_signal_chain_from_overridden (const GValue *instance_and_params, GValue *return_value) @@ -1518,6 +1788,14 @@ g_signal_chain_from_overridden (const GValue *instance_and_params, SIGNAL_UNLOCK (); } +/** + * g_signal_get_invocation_hint: + * @instance: the instance to query + * + * Returns the invocation hint of the innermost signal emission of instance. + * + * Returns: the invocation hint of the innermost signal emission. + */ GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance) { @@ -1532,6 +1810,19 @@ g_signal_get_invocation_hint (gpointer instance) return emission ? &emission->ihint : NULL; } +/** + * g_signal_connect_closure_by_id: + * @instance: the instance to connect to. + * @signal_id: the id of the signal. + * @detail: the detail. + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the + * default handler of the signal. + * + * Connects a closure to a signal for a particular object. + * + * Returns: the handler id + */ gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, @@ -1574,6 +1865,18 @@ g_signal_connect_closure_by_id (gpointer instance, return handler_seq_no; } +/** + * g_signal_connect_closure: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the + * default handler of the signal. + * + * Connects a closure to a signal for a particular object. + * + * Returns: the handler id + */ gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, @@ -1620,6 +1923,23 @@ g_signal_connect_closure (gpointer instance, return handler_seq_no; } +/** + * g_signal_connect_data: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. + * @destroy_data: a #GClosureNotify for @data. + * @connect_flags: a combination of #GConnectFlags. + * + * Connects a #GCallback function to a signal for a particular object. Similar + * to g_signal_connect(), but allows to provide a #GClosureNotify for the data + * which will be called when the signal handler is disconnected and no longer + * used. Specify @connect_flags if you need <literal>..._after()</literal> or + * <literal>..._swapped()</literal> variants of this function. + * + * Returns: the handler id + */ gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, @@ -1672,6 +1992,20 @@ g_signal_connect_data (gpointer instance, return handler_seq_no; } +/** + * g_signal_handler_block: + * @instance: The instance to block the signal handler of. + * @handler_id: Handler id of the handler to be blocked. + * + * Blocks a handler of an instance so it will not be called during + * any signal emissions unless it is unblocked again. Thus "blocking" + * a signal handler means to temporarily deactive it, a signal handler + * has to be unblocked exactly the same amount of times it has been + * blocked before to become active again. + * + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. + */ void g_signal_handler_block (gpointer instance, gulong handler_id) @@ -1696,6 +2030,25 @@ g_signal_handler_block (gpointer instance, SIGNAL_UNLOCK (); } +/** + * g_signal_handler_unblock: + * @instance: The instance to unblock the signal handler of. + * @handler_id: Handler id of the handler to be unblocked. + * + * Undoes the effect of a previous g_signal_handler_block() call. + * A blocked handler is skipped during signal emissions and will not be + * invoked, unblocking it (for exactly the amount of times it has been + * blocked before) reverts its "blocked" state, so the handler will be + * recognized by the signal system and is called upon future or currently + * ongoing signal emissions (since the order in which handlers are + * called during signal emissions is deterministic, whether the + * unblocked handler in question is called as part of a currently + * ongoing emission depends on how far that emission has proceeded + * yet). + * + * The @handler_id has to be a valid id of a signal handler that is + * connected to a signal of @instance and is currently blocked. + */ void g_signal_handler_unblock (gpointer instance, gulong handler_id) @@ -1719,6 +2072,18 @@ g_signal_handler_unblock (gpointer instance, SIGNAL_UNLOCK (); } +/** + * g_signal_handler_disconnect: + * @instance: The instance to remove the signal handler from. + * @handler_id: Handler id of the handler to be disconnected. + * + * Disconnects a handler from an instance so it will not be called during + * any future or currently ongoing emissions of the signal it has been + * connected to. The @handler_id becomes invalid and may be reused. + * + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. + */ void g_signal_handler_disconnect (gpointer instance, gulong handler_id) @@ -1742,6 +2107,15 @@ g_signal_handler_disconnect (gpointer instance, SIGNAL_UNLOCK (); } +/** + * g_signal_handler_is_connected: + * @instance: The instance where a signal handler is sought. + * @handler_id: the handler id. + * + * Returns whether @handler_id is the id of a handler connected to @instance. + * + * Returns: whether @handler_id identifies a handler connected to @instance. + */ gboolean g_signal_handler_is_connected (gpointer instance, gulong handler_id) @@ -1801,6 +2175,25 @@ g_signal_handlers_destroy (gpointer instance) SIGNAL_UNLOCK (); } +/** + * g_signal_handler_find: + * @instance: The instance owning the signal handler to be found. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handler has to match. + * @signal_id: Signal the handler has to be connected to. + * @detail: Signal detail the handler has to be connected to. + * @closure: The closure the handler will invoke. + * @func: The C closure callback of the handler (useless for non-C closures). + * @data: The closure data of the handler's closure. + * + * Finds the first signal handler that matches certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * The match @mask has to be non-0 for successful matches. + * If no handler was found, 0 is returned. + * + * Returns: A valid non-0 signal handler id for a successful match. + */ gulong g_signal_handler_find (gpointer instance, GSignalMatchType mask, @@ -1862,6 +2255,27 @@ signal_handlers_foreach_matched_R (gpointer instance, return n_handlers; } +/** + * g_signal_handlers_block_matched: + * @instance: The instance to block handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. + * + * Blocks all handlers on an instance that match a certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of blocked handlers + * otherwise. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_block_matched (gpointer instance, GSignalMatchType mask, @@ -1888,6 +2302,28 @@ g_signal_handlers_block_matched (gpointer instance, return n_handlers; } +/** + * g_signal_handlers_unblock_matched: + * @instance: The instance to unblock handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. + * + * Unblocks all handlers on an instance that match a certain selection + * criteria. The criteria mask is passed as an OR-ed combination of + * #GSignalMatchType flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of unblocked handlers + * otherwise. The match criteria should not apply to any handlers that are + * not currently blocked. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_unblock_matched (gpointer instance, GSignalMatchType mask, @@ -1914,6 +2350,27 @@ g_signal_handlers_unblock_matched (gpointer instance, return n_handlers; } +/** + * g_signal_handlers_disconnect_matched: + * @instance: The instance to remove handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. + * + * Disconnects all handlers on an instance that match a certain selection + * criteria. The criteria mask is passed as an OR-ed combination of + * #GSignalMatchType flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of disconnected + * handlers otherwise. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_disconnect_matched (gpointer instance, GSignalMatchType mask, @@ -1940,6 +2397,24 @@ g_signal_handlers_disconnect_matched (gpointer instance, return n_handlers; } +/** + * g_signal_has_handler_pending: + * @instance: the object whose signal handlers are sought. + * @signal_id: the signal id. + * @detail: the detail. + * @may_be_blocked: whether blocked handlers should count as match. + * + * Returns whether there are any handlers connected to @instance for the + * given signal id and detail. + * + * One example of when you might use this is when the arguments to the + * signal are difficult to compute. A class implementor may opt to not emit + * the signal if no one is attached anyway, thus saving the cost of building + * the arguments. + * + * Returns: %TRUE if a handler is connected to the signal, + * %FALSE otherwise. + */ gboolean g_signal_has_handler_pending (gpointer instance, guint signal_id, @@ -2023,6 +2498,21 @@ signal_check_skip_emission (SignalNode *node, return TRUE; } +/** + * g_signal_emitv: + * @instance_and_params: argument list for the signal emission. The first + * element in the array is a #GValue for the instance the signal is + * being emitted on. The rest are any arguments to be passed to the + * signal. + * @signal_id: the signal id + * @detail: the detail + * @return_value: Location to store the return value of the signal emission. + * + * Emits a signal. + * + * Note that g_signal_emitv() doesn't change @return_value if no handlers are + * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). + */ void g_signal_emitv (const GValue *instance_and_params, guint signal_id, @@ -2111,6 +2601,20 @@ g_signal_emitv (const GValue *instance_and_params, signal_emit_unlocked_R (node, detail, instance, return_value, instance_and_params); } +/** + * g_signal_emit_valist: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @var_args: a list of parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. + * + * Emits a signal. + * + * Note that g_signal_emit_valist() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). + */ void g_signal_emit_valist (gpointer instance, guint signal_id, @@ -2231,6 +2735,20 @@ g_signal_emit_valist (gpointer instance, g_free (free_me); } +/** + * g_signal_emit: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. + * + * Emits a signal. + * + * Note that g_signal_emit() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). + */ void g_signal_emit (gpointer instance, guint signal_id, @@ -2244,6 +2762,19 @@ g_signal_emit (gpointer instance, va_end (var_args); } +/** + * g_signal_emit_by_name: + * @instance: the instance the signal is being emitted on. + * @detailed_signal: a string of the form "signal-name::detail". + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. + * + * Emits a signal. + * + * Note that g_signal_emit_by_name() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). + */ void g_signal_emit_by_name (gpointer instance, const gchar *detailed_signal, @@ -2590,6 +3121,24 @@ type_debug_name (GType type) return "<invalid>"; } +/** + * g_signal_accumulator_true_handled: + * @ihint: standard #GSignalAccumulator parameter + * @return_accu: standard #GSignalAccumulator parameter + * @handler_return: standard #GSignalAccumulator parameter + * @dummy: standard #GSignalAccumulator parameter + * + * A predefined #GSignalAccumulator for signals that return a + * boolean values. The behavior that this accumulator gives is + * that a return of %TRUE stops the signal emission: no further + * callbacks will be invoked, while a return of %FALSE allows + * the emission to coninue. The idea here is that a %TRUE return + * indicates that the callback <emphasis>handled</emphasis> the signal, + * and no further handling is needed. + * + * Since: 2.4 + * Returns: standard #GSignalAccumulator result + */ gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, GValue *return_accu, |