allow slider to snap to an array of values

ianhi · ianhi · commit 413e851f717e · 2020-10-22T23:31:54.000-04:00
diff --git a/doc/users/next_whats_new/slider_snap_to_array.rst b/doc/users/next_whats_new/slider_snap_to_array.rst
@@ -0,0 +1,7 @@
+Sliders can now snap to arbitrary values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `~matplotlib.widgets.Slider` UI widget now accepts the optional
+argument *valsnap*. This generalizes the discrete value snapping introduced
+by the *valstep* argument, allowing the user to pass an array of values,
+to snap to.
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -267,6 +267,17 @@ def test_slider_valmin_valmax():
     assert slider.val == slider.valmax
 
 
+def test_slider_valstep_valsnap():
+    fig, ax = plt.subplots()
+    slider = widgets.Slider(ax=ax, label='', valmin=0.0, valmax=24.0,
+                            valinit=11.4, valstep=1)
+    assert slider.val == 11
+
+    slider = widgets.Slider(ax=ax, label='', valmin=0.0, valmax=24.0,
+                            valinit=11.4, valsnap=[0, 1, 5.5, 19.7])
+    assert slider.val == 5.5
+
+
 def test_slider_horizontal_vertical():
     fig, ax = plt.subplots()
     slider = widgets.Slider(ax=ax, label='', valmin=0, valmax=24,
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -255,7 +255,7 @@ class Slider(AxesWidget):
     def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt=None,
                  closedmin=True, closedmax=True, slidermin=None,
                  slidermax=None, dragging=True, valstep=None,
-                 orientation='horizontal', **kwargs):
+                 orientation='horizontal', valsnap=None, **kwargs):
         """
         Parameters
         ----------
@@ -297,10 +297,15 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt=None,
 
         valstep : float, default: None
             If given, the slider will snap to multiples of *valstep*.
+            If both *valsnap* and *valstep* are set an error is raised.
 
         orientation : {'horizontal', 'vertical'}, default: 'horizontal'
             The orientation of the slider.
 
+        valsnap : 1D array-like, default: None
+            If given, the slider will snap to nearest value in *valsnap*.
+            If both *valsnap* and *valstep* are set an error is raised.
+
         Notes
         -----
         Additional kwargs are passed on to ``self.poly`` which is the
@@ -319,6 +324,9 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt=None,
         if slidermax is not None and not hasattr(slidermax, 'val'):
             raise ValueError(
                 f"Argument slidermax ({type(slidermax)}) has no 'val'")
+        if valstep is not None and valsnap is not None:
+            raise ValueError("kwargs 'valsnap' and 'valstep' cannot "
+                                "be used simultaneously. ")
         _api.check_in_list(['horizontal', 'vertical'], orientation=orientation)
 
         self.orientation = orientation
@@ -330,6 +338,15 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt=None,
         self.valmin = valmin
         self.valmax = valmax
         self.valstep = valstep
+        self.valsnap = valsnap
+        if self.valsnap is not None:
+            self.valsnap = np.sort(self.valsnap)
+        elif self.valstep is not None:
+            self.valsnap = np.arange(
+                                self.valmin,
+                                self.valmax + self.valstep,
+                                self.valstep
+                                )
         valinit = self._value_in_bounds(valinit)
         if valinit is None:
             valinit = valmin
@@ -401,9 +418,10 @@ def observers(self):
 
     def _value_in_bounds(self, val):
         """Makes sure *val* is with given bounds."""
-        if self.valstep:
-            val = (self.valmin
-                   + round((val - self.valmin) / self.valstep) * self.valstep)
+        if self.valsnap is not None:
+            idx = np.searchsorted(self.valsnap, val, side="left")
+            candidates = self.valsnap[[idx-1, min(idx, self.valsnap.size-1)]]
+            val = candidates[np.argmin(np.abs(candidates - val))]
 
         if val <= self.valmin:
             if not self.closedmin:
