mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-26 07:26:15 +01:00
gsignal: Clarify documentation for GSignalMatchType matching
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:
parent
2f828ef2d4
commit
2d8e38c00d
@ -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.
|
||||
|
@ -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);
|
||||
}
|
||||
|
Loading…
Reference in New Issue
Block a user