Add clear methods for check and radio buttons

raamana · QuLogic · QuLogic · commit 67ac54f72db5 · 2023-05-10T00:05:01.000-04:00
Co-authored-by: Elliott Sales de Andrade &lt;quantum.analyst@gmail.com&gt;
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -999,10 +999,23 @@ def test_lasso_selector_set_props(ax):
 
 
 def test_CheckButtons(ax):
-    check = widgets.CheckButtons(ax, ('a', 'b', 'c'), (True, False, True))
+    labels = ('a', 'b', 'c')
+    check = widgets.CheckButtons(ax, labels, (True, False, True))
     assert check.get_status() == [True, False, True]
     check.set_active(0)
     assert check.get_status() == [False, False, True]
+    assert check.get_checked_labels() == ['c']
+    check.clear()
+    assert not any(check.get_status())
+    assert len(check.get_checked_labels()) == 0
+
+    for invalid_index in [-1, len(labels), len(labels)+5]:
+        with pytest.raises(ValueError):
+            check.set_active(index=invalid_index)
+
+    for invalid_value in ['invalid', -1]:
+        with pytest.raises(TypeError):
+            check.set_active(1, state=invalid_value)
 
     cid = check.on_clicked(lambda: None)
     check.disconnect(cid)
@@ -1040,6 +1053,16 @@ def test_TextBox(ax, toolbar):
     assert text_change_event.call_count == 3
 
 
+def test_RadioButtons(ax):
+    radio = widgets.RadioButtons(ax, ('Radio 1', 'Radio 2', 'Radio 3'))
+    radio.set_active(1)
+    assert radio.value_selected == 'Radio 2'
+    assert radio.index_selected == 1
+    radio.clear()
+    assert radio.value_selected is None
+    assert radio.index_selected is None
+
+
 @image_comparison(['check_radio_buttons.png'], style='mpl20', remove_text=True)
 def test_check_radio_buttons_image():
     ax = get_ax()
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -1196,7 +1196,7 @@ def set_check_props(self, props):
         # If new colours are supplied, then we must re-apply the status.
         self._init_status(actives)
 
-    def set_active(self, index):
+    def set_active(self, index, state=None):
         """
         Toggle (activate or deactivate) a check button by index.
 
@@ -1207,22 +1207,27 @@ def set_active(self, index):
         index : int
             Index of the check button to toggle.
 
+        state : bool, optional
+            Sets the target state of the button. If a boolean value, set the
+            state explicitly. If no value is provided, the state is toggled.
+
         Raises
         ------
         ValueError
             If *index* is invalid.
+        TypeError
+            If *state* is not boolean.
         """
         if index not in range(len(self.labels)):
             raise ValueError(f'Invalid CheckButton index: {index}')
+        _api.check_isinstance((bool, None), state=state)
 
         invisible = colors.to_rgba('none')
 
         facecolors = self._checks.get_facecolor()
-        facecolors[index] = (
-            self._active_check_colors[index]
-            if colors.same_color(facecolors[index], invisible)
-            else invisible
-        )
+        if state is None:
+            state = colors.same_color(facecolors[index], invisible)
+        facecolors[index] = self._active_check_colors[index] if state else invisible
         self._checks.set_facecolor(facecolors)
 
         if hasattr(self, "_lines"):
@@ -1262,18 +1267,55 @@ def _init_status(self, actives):
             [ec if active else "none"
              for ec, active in zip(self._active_check_colors, actives)])
 
+    def clear(self):
+        """Clear all checkboxes."""
+
+        self._checks.set_facecolor(['none'] * len(self._active_check_colors))
+
+        if hasattr(self, '_lines'):
+            for l1, l2 in self._lines:
+                l1.set_visible(False)
+                l2.set_visible(False)
+
+        if self.drawon:
+            self.canvas.draw()
+
+        if self.eventson:
+            # Call with no label, as all checkboxes are being cleared.
+            self._observers.process('clicked', None)
+
     def get_status(self):
         """
         Return a list of the status (True/False) of all of the check buttons.
         """
         return [not colors.same_color(color, colors.to_rgba("none"))
                 for color in self._checks.get_facecolors()]
 
+    def get_checked_labels(self):
+        """Return a list of labels currently checked by user."""
+
+        return [l.get_text() for l, box_checked in
+                zip(self.labels, self.get_status())
+                if box_checked]
+
     def on_clicked(self, func):
         """
         Connect the callback function *func* to button click events.
 
-        Returns a connection id, which can be used to disconnect the callback.
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
         """
         return self._observers.connect('clicked', lambda text: func(text))
 
@@ -1618,6 +1660,8 @@ class RadioButtons(AxesWidget):
         The buttons.
     value_selected : str
         The label text of the currently selected button.
+    index_selected : int
+        The index of the selected button.
     """
 
     def __init__(self, ax, labels, active=0, activecolor=None, *,
@@ -1676,6 +1720,7 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
 
         self._activecolor = activecolor
         self.value_selected = labels[active]
+        self.index_selected = active
 
         ax.set_xticks([])
         ax.set_yticks([])
@@ -1814,10 +1859,21 @@ def set_active(self, index):
         Select button with number *index*.
 
         Callbacks will be triggered if :attr:`eventson` is True.
+
+        Parameters
+        ----------
+        index : int
+            The index of the button to activate.
+
+        Raises
+        ------
+        ValueError
+            If the index is invalid.
         """
         if index not in range(len(self.labels)):
             raise ValueError(f'Invalid RadioButton index: {index}')
         self.value_selected = self.labels[index].get_text()
+        self.index_selected = index
         button_facecolors = self._buttons.get_facecolor()
         button_facecolors[:] = colors.to_rgba("none")
         button_facecolors[index] = colors.to_rgba(self._active_colors[index])
@@ -1842,11 +1898,39 @@ def set_active(self, index):
         if self.eventson:
             self._observers.process('clicked', self.labels[index].get_text())
 
+    def clear(self):
+        """Deactivate any previously activated button."""
+        if self.index_selected is not None:
+            button_facecolors = self._buttons.get_facecolor()
+            button_facecolors[:] = colors.to_rgba('none')
+            self._buttons.set_facecolor(button_facecolors)
+            if hasattr(self, '_circles'):  # Remove once circles is removed.
+                self._circles[self.index_selected].set_facecolor('none')
+        self.value_selected = None
+        self.index_selected = None
+
+        # calling it with no label, as all buttons are being cleared
+        if self.eventson:
+            self._observers.process('clicked', None)
+
     def on_clicked(self, func):
         """
         Connect the callback function *func* to button click events.
 
-        Returns a connection id, which can be used to disconnect the callback.
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
         """
         return self._observers.connect('clicked', func)
 
diff --git a/lib/matplotlib/widgets.pyi b/lib/matplotlib/widgets.pyi
@@ -12,7 +12,7 @@ from .transforms import Affine2D, TransformedPatchPath
 import PIL
 
 from collections.abc import Callable, Collection, Iterable, Sequence
-from typing import Any, Literal
+from typing import Any, Literal, Optional
 from numpy.typing import ArrayLike
 from .typing import ColorType
 import numpy as np
@@ -161,9 +161,11 @@ class CheckButtons(AxesWidget):
     def set_label_props(self, props: dict[str, Any]) -> None: ...
     def set_frame_props(self, props: dict[str, Any]) -> None: ...
     def set_check_props(self, props: dict[str, Any]) -> None: ...
-    def set_active(self, index: int) -> None: ...
+    def set_active(self, index: int, state: Optional[bool]) -> None: ...
+    def clear(self) -> None: ...
     def get_status(self) -> list[bool]: ...
-    def on_clicked(self, func: Callable[[str], Any]) -> int: ...
+    def get_checked_labels(self) -> list[str]: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
     def disconnect(self, cid: int) -> None: ...
     @property
     def lines(self) -> list[tuple[Line2D, Line2D]]: ...
@@ -215,7 +217,8 @@ class RadioButtons(AxesWidget):
     def set_label_props(self, props: dict[str, Any]) -> None: ...
     def set_radio_props(self, props: dict[str, Any]) -> None: ...
     def set_active(self, index: int) -> None: ...
-    def on_clicked(self, func: Callable[[str], Any]) -> int: ...
+    def clear(self) -> None: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
     def disconnect(self, cid: int) -> None: ...
     @property
     def circles(self) -> list[Circle]: ...
