luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

gsignal: Clarify documentation for GSignalMatchType matching

Browse Source 
The use of ‘OR’ in the existing documentation suggests that the matching
is disjunctive, but it’s actually conjunctive. Clarify that in the
documentation and add a test.

Spotted while reviewing
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3376.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2023-04-14 13:55:20 +01:00
parent 2f828ef2d4
commit 2d8e38c00d
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.
*
* 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
* 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
@ -2994,8 +2997,12 @@ g_signal_handlers_block_matched (gpointer instance,
* @data: (nullable) (closure closure): 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.
* criteria.
*
* 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
* 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
@ -3043,10 +3050,13 @@ g_signal_handlers_unblock_matched (gpointer instance,
* @data: (nullable) (closure closure): 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
* selection criteria.
*
* 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 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
* matches. If no handlers were found, 0 is returned, the number of
* 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);
/* 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 (test2);
}