SelectionList events changes (#4759)

* Dont prevent SelectionToggled messages in bulk SelectionList methods. Its important for callers to know on a per-option basis if one was toggled, and is a reasonable expectation. Also update docs to reflect this..

* Update CHANGELOG

Author: darrenburns

CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Fixed `Tree` and `DirectoryTree` horizontal scrolling off-by-2 https://github.com/Textualize/textual/pull/4744
 - Fixed text-opacity in component styles https://github.com/Textualize/textual/pull/4747
 - Ensure `Tree.select_node` sends `NodeSelected` message https://github.com/Textualize/textual/pull/4753
+- `SelectionList.SelectionToggled` will now be sent for each option when a bulk toggle is performed (e.g. `toggle_all`). Previously no messages were sent at all. https://github.com/Textualize/textual/pull/4759
 
 ### Changed
 

src/textual/widgets/_selection_list.py

@@ -202,6 +202,16 @@ class SelectionHighlighted(SelectionMessage[MessageSelectionType]):
     class SelectionToggled(SelectionMessage[MessageSelectionType]):
         """Message sent when a selection is toggled.
 
+        This is only sent when the value is *explicitly* toggled e.g.
+        via `toggle` or `toggle_all`, or via user interaction.
+        If you programmatically set a value to be selected, this message will
+        not be sent, even if it happens to be the opposite of what was
+        originally selected (i.e. setting a True to a False or vice-versa).
+
+        Since this message indicates a toggle occurring at a per-option level,
+        a message will be sent for each option that is toggled, even when a
+        bulk action is performed (e.g. via `toggle_all`).
+
         Can be handled using `on_selection_list_selection_toggled` in a subclass of
         [`SelectionList`][textual.widgets.SelectionList] or in a parent node in the DOM.
         """
@@ -210,6 +220,13 @@ class SelectionToggled(SelectionMessage[MessageSelectionType]):
     class SelectedChanged(Generic[MessageSelectionType], Message):
         """Message sent when the collection of selected values changes.
 
+        This is sent regardless of whether the change occurred via user interaction
+        or programmatically the the `SelectionList` API.
+
+        When a bulk change occurs, such as through `select_all` or `deselect_all`,
+        only a single `SelectedChanged` message will be sent (rather than one per
+        option).
+
         Can be handled using `on_selection_list_selected_changed` in a subclass of
         [`SelectionList`][textual.widgets.SelectionList] or in a parent node in the DOM.
         """
@@ -316,10 +333,10 @@ def _apply_to_all(self, state_change: Callable[[SelectionType], bool]) -> Self:
         # Keep track of if anything changed.
         changed = False
 
-        # Next we run through everything and apply the change, preventing
-        # the toggled and changed messages because the caller really isn't
-        # going to be expecting a message storm from this.
-        with self.prevent(self.SelectedChanged, self.SelectionToggled):
+        # Apply the state change function to all options.
+        # We don't send a SelectedChanged for each option, and instead
+        # send a single SelectedChanged afterwards if any values change.
+        with self.prevent(self.SelectedChanged):
             for selection in self._options:
                 changed = (
                     state_change(cast(Selection[SelectionType], selection).value)

tests/selection_list/test_selection_messages.py

@@ -101,6 +101,16 @@ async def test_toggle_all() -> None:
         await pilot.pause()
         assert pilot.app.messages == [
             ("SelectionHighlighted", 0),
+            ("SelectionToggled", 0),
+            ("SelectionToggled", 1),
+            ("SelectionToggled", 2),
+            ("SelectionToggled", 3),
+            ("SelectionToggled", 4),
+            ("SelectionToggled", 5),
+            ("SelectionToggled", 6),
+            ("SelectionToggled", 7),
+            ("SelectionToggled", 8),
+            ("SelectionToggled", 9),
             ("SelectedChanged", None),
         ]