mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-11 23:16:14 +01:00
More GSignal docs.
This commit is contained in:
Matthias Clasen
parent
90d5b0fced
commit
0b93fa4048
@ -1,3 +1,7 @@
|
||||
2002-12-02 Matthias Clasen <maclas@gmx.de>
|
||||
|
||||
* gobject/tmpl/signals.sgml: Add docs.
|
||||
|
||||
2002-12-01 Matthias Clasen <maclas@gmx.de>
|
||||
|
||||
* gobject/gobject-sections.txt: Mark g_signal_handlers_destroy as
|
||||
|
||||
@ -119,7 +119,8 @@ signal system.
|
||||
A simple function pointer to get invoked when the signal is emitted. This
|
||||
allows you tie a hook to the signal type, so that it will trap all emissions
|
||||
of that signal, from any object.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
|
||||
</para>
|
||||
|
||||
@ -157,15 +158,17 @@ stages of a signal emission.
|
||||
|
||||
<!-- ##### ENUM GSignalMatchType ##### -->
|
||||
<para>
|
||||
|
||||
The match types specify what g_signal_handlers_block_matched(),
|
||||
g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
|
||||
match signals by.
|
||||
</para>
|
||||
|
||||
@G_SIGNAL_MATCH_ID:
|
||||
@G_SIGNAL_MATCH_DETAIL:
|
||||
@G_SIGNAL_MATCH_CLOSURE:
|
||||
@G_SIGNAL_MATCH_FUNC:
|
||||
@G_SIGNAL_MATCH_DATA:
|
||||
@G_SIGNAL_MATCH_UNBLOCKED:
|
||||
@G_SIGNAL_MATCH_ID: The signal id must be equal.
|
||||
@G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
|
||||
@G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
|
||||
@G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
|
||||
@G_SIGNAL_MATCH_DATA: The closure data must be the same.
|
||||
@G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
|
||||
|
||||
<!-- ##### STRUCT GSignalQuery ##### -->
|
||||
<para>
|
||||
@ -190,9 +193,27 @@ filled in by the g_signal_query() function.
|
||||
|
||||
<!-- ##### MACRO G_SIGNAL_TYPE_STATIC_SCOPE ##### -->
|
||||
<para>
|
||||
|
||||
This macro flags signal argument types for which the signal system may
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To flag a signal argument in this way, add
|
||||
<literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
|
||||
of g_signal_new().
|
||||
</para>
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
g_signal_new ("size_request",
|
||||
G_TYPE_FROM_CLASS (gobject_class),
|
||||
G_SIGNAL_RUN_FIRST,
|
||||
G_STRUCT_OFFSET (GtkWidgetClass, size_request),
|
||||
NULL, NULL,
|
||||
_gtk_marshal_VOID__BOXED,
|
||||
G_TYPE_NONE, 1,
|
||||
GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
|
||||
|
||||
<!-- ##### MACRO G_SIGNAL_MATCH_MASK ##### -->
|
||||
@ -344,35 +365,48 @@ filled in by the g_signal_query() function.
|
||||
|
||||
<!-- ##### MACRO g_signal_connect ##### -->
|
||||
<para>
|
||||
|
||||
Connects a #GCallback function to a signal for a particular object.
|
||||
</para>
|
||||
<para>
|
||||
The handler will be called before the default handler of the signal.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@detailed_signal:
|
||||
@c_handler:
|
||||
@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.
|
||||
@Returns: the handler id
|
||||
|
||||
|
||||
<!-- ##### MACRO g_signal_connect_after ##### -->
|
||||
<para>
|
||||
|
||||
Connects a #GCallback function to a signal for a particular object.
|
||||
</para>
|
||||
<para>
|
||||
The handler will be called after the default handler of the signal.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@detailed_signal:
|
||||
@c_handler:
|
||||
@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.
|
||||
@Returns: the handler id
|
||||
|
||||
|
||||
<!-- ##### MACRO g_signal_connect_swapped ##### -->
|
||||
<para>
|
||||
|
||||
Connects a #GCallback function to a signal for a particular object.
|
||||
</para>
|
||||
<para>
|
||||
The instance on which the signal is emitted and @data will be swapped when
|
||||
calling the handler.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@detailed_signal:
|
||||
@c_handler:
|
||||
@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.
|
||||
@Returns: the handler id
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_signal_connect_object ##### -->
|
||||
@ -530,32 +564,35 @@ connection.
|
||||
|
||||
<!-- ##### MACRO g_signal_handlers_block_by_func ##### -->
|
||||
<para>
|
||||
|
||||
Blocks all handlers on an instance that match @func and @data.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@func:
|
||||
@data:
|
||||
|
||||
@instance: The instance to block handlers from.
|
||||
@func: The C closure callback of the handlers (useless for non-C closures).
|
||||
@data: The closure data of the handlers' closures.
|
||||
@Returns: The number of handlers that got blocked.
|
||||
|
||||
<!-- ##### MACRO g_signal_handlers_unblock_by_func ##### -->
|
||||
<para>
|
||||
|
||||
Unblocks all handlers on an instance that match @func and @data.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@func:
|
||||
@data:
|
||||
@instance: The instance to unblock handlers from.
|
||||
@func: The C closure callback of the handlers (useless for non-C closures).
|
||||
@data: The closure data of the handlers' closures.
|
||||
@Returns: The number of handlers that got unblocked.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_signal_handlers_disconnect_by_func ##### -->
|
||||
<para>
|
||||
|
||||
Disconnects all handlers on an instance that match @func and @data.
|
||||
</para>
|
||||
|
||||
@instance:
|
||||
@func:
|
||||
@data:
|
||||
@instance: The instance to remove handlers from.
|
||||
@func: The C closure callback of the handlers (useless for non-C closures).
|
||||
@data: The closure data of the handlers' closures.
|
||||
@Returns: The number of handlers that got disconnected.
|
||||
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
|
||||
|
||||
@ -1,3 +1,7 @@
|
||||
2002-12-02 Matthias Clasen <maclas@gmx.de>
|
||||
|
||||
* gobject.c (g_signal_connect_object): Add docs.
|
||||
|
||||
2002-11-30 Matthias Clasen <maclas@gmx.de>
|
||||
|
||||
* gsignal.c: More docs.
|
||||
|
||||
@ -1563,6 +1563,19 @@ g_value_dup_object (const GValue *value)
|
||||
return value->data[0].v_pointer ? g_object_ref (value->data[0].v_pointer) : NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_signal_connect_object:
|
||||
* @instance: the instance to connect to.
|
||||
* @detailed_signal: a string of the form "signal-name::detail".
|
||||
* @c_handler: the #GCallback to connect.
|
||||
* @gobject: the object to pass as data to @c_handler.
|
||||
* @connect_flags: a combination of #GConnnectFlags.
|
||||
*
|
||||
* This is similar to g_signal_connect_data(), but uses a closure which
|
||||
* ensures that the object stays alive during the call to @c_handler.
|
||||
*
|
||||
* Return value: the handler id.
|
||||
**/
|
||||
gulong
|
||||
g_signal_connect_object (gpointer instance,
|
||||
const gchar *detailed_signal,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user