luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'signal-handler-matching-docs' into 'main'

Browse Source 
gsignal: Clarify documentation for GSignalMatchType matching

See merge request GNOME/glib!3377
This commit is contained in:
Marco Trevisan 2023-04-14 13:53:49 +00:00
commit 45300ae6ea
2 changed files with 23 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
gobject/gsignal.c
View File

@ -2946,8 +2946,11 @@ signal_handlers_foreach_matched_unlocked_R (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures. * @data: (nullable) (closure closure): The closure data of the handlers' closures.
* *
* Blocks all handlers on an instance that match a certain selection criteria. * 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. * The criteria mask is passed as a combination of #GSignalMatchType flags, and
* the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be blocked (i.e. the match is conjunctive).
*
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC * 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. * 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 * If no handlers were found, 0 is returned, the number of blocked handlers
@ -2994,8 +2997,12 @@ g_signal_handlers_block_matched (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures. * @data: (nullable) (closure closure): The closure data of the handlers' closures.
* *
* Unblocks all handlers on an instance that match a certain selection * Unblocks all handlers on an instance that match a certain selection
* criteria. The criteria mask is passed as an OR-ed combination of * criteria.
* #GSignalMatchType flags, and the criteria values are passed as arguments. *
* The criteria mask is passed as a combination of #GSignalMatchType flags, and
* the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be unblocked (i.e. the match is conjunctive).
*
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC * 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. * 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 * If no handlers were found, 0 is returned, the number of unblocked handlers
@ -3043,10 +3050,13 @@ g_signal_handlers_unblock_matched (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures. * @data: (nullable) (closure closure): The closure data of the handlers' closures.
* *
* Disconnects all handlers on an instance that match a certain * Disconnects all handlers on an instance that match a certain
* selection criteria. The criteria mask is passed as an OR-ed * selection criteria.
* combination of #GSignalMatchType flags, and the criteria values are *
* passed as arguments. Passing at least one of the * The criteria mask is passed as a combination of #GSignalMatchType flags, and
* %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or * the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be disconnected (i.e. the match is conjunctive).
*
* 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 * %G_SIGNAL_MATCH_DATA match flags is required for successful
* matches. If no handlers were found, 0 is returned, the number of * matches. If no handlers were found, 0 is returned, the number of
* disconnected handlers otherwise. * disconnected handlers otherwise.

5
gobject/tests/signals.c
View File

@ -1487,6 +1487,11 @@ test_block_handler (void)
g_signal_handlers_unblock_matched (test2, G_SIGNAL_MATCH_FUNC, 0, 0, NULL, test_handler, NULL); g_signal_handlers_unblock_matched (test2, G_SIGNAL_MATCH_FUNC, 0, 0, NULL, test_handler, NULL);
/* Match types are conjunctive */
g_assert_cmpuint (g_signal_handlers_block_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, "will not match"), ==, 0);
g_assert_cmpuint (g_signal_handlers_block_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, &count1), ==, 1);
g_assert_cmpuint (g_signal_handlers_unblock_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, &count1), ==, 1);
g_object_unref (test1); g_object_unref (test1);
g_object_unref (test2); g_object_unref (test2);
} }