diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 43d9cce6a..8a44cc0f5 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2002-12-02 Matthias Clasen + + * gobject/tmpl/signals.sgml: Add docs. + 2002-12-01 Matthias Clasen * gobject/gobject-sections.txt: Mark g_signal_handlers_destroy as diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml index 80894ff33..9dd9135a7 100644 --- a/docs/reference/gobject/tmpl/signals.sgml +++ b/docs/reference/gobject/tmpl/signals.sgml @@ -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. - + + You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. @@ -157,15 +158,17 @@ stages of a signal emission. - +The match types specify what g_signal_handlers_block_matched(), +g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() +match signals by. -@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. @@ -190,9 +193,27 @@ filled in by the g_signal_query() function. - +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. - + +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), + 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); + + @@ -344,35 +365,48 @@ filled in by the g_signal_query() function. - +Connects a #GCallback function to a signal for a particular object. + +The handler will be called before the default handler of the signal. + -@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 - +Connects a #GCallback function to a signal for a particular object. + +The handler will be called after the default handler of the signal. + -@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 - +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. -@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 @@ -530,32 +564,35 @@ connection. - +Blocks all handlers on an instance that match @func and @data. -@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. - +Unblocks all handlers on an instance that match @func and @data. -@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. - +Disconnects all handlers on an instance that match @func and @data. -@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. + diff --git a/gobject/ChangeLog b/gobject/ChangeLog index 7202ceb61..a6e02b930 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,3 +1,7 @@ +2002-12-02 Matthias Clasen + + * gobject.c (g_signal_connect_object): Add docs. + 2002-11-30 Matthias Clasen * gsignal.c: More docs. diff --git a/gobject/gobject.c b/gobject/gobject.c index e9c39b92d..0db5ec7a1 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -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,