DOC: Improve Image Slices Viewer example

timhoffm · timhoffm · commit a04e13693ae9 · 2022-11-04T21:12:37.000+01:00
diff --git a/examples/event_handling/image_slices_viewer.py b/examples/event_handling/image_slices_viewer.py
@@ -12,48 +12,43 @@
 
     You can copy and paste individual parts, or download the entire example
     using the link at the bottom of the page.
+
+The example illustrates how to connect a function to the scroll wheel event.
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 
 
-# Fixing random state for reproducibility
-np.random.seed(19680801)
-
-
 class IndexTracker:
     def __init__(self, ax, X):
-        self.ax = ax
-        ax.set_title('use scroll wheel to navigate images')
-
+        self.index = 0
         self.X = X
-        rows, cols, self.slices = X.shape
-        self.ind = self.slices//2
-
-        self.im = ax.imshow(self.X[:, :, self.ind])
+        self.ax = ax
+        self.im = ax.imshow(self.X[:, :, self.index])
         self.update()
 
     def on_scroll(self, event):
-        print("%s %s" % (event.button, event.step))
-        if event.button == 'up':
-            self.ind = (self.ind + 1) % self.slices
-        else:
-            self.ind = (self.ind - 1) % self.slices
+        print(event.button, event.step)
+        increment = 1 if event.button == 'up' else -1
+        max_index = self.X.shape[-1] - 1
+        self.index = np.clip(self.index + increment, 0, max_index)
         self.update()
 
     def update(self):
-        self.im.set_data(self.X[:, :, self.ind])
-        self.ax.set_ylabel('slice %s' % self.ind)
+        self.im.set_data(self.X[:, :, self.index])
+        self.ax.set_title(
+            f'Use scroll wheel to navigate\nimage {self.index}')
         self.im.axes.figure.canvas.draw()
 
 
-fig, ax = plt.subplots(1, 1)
-
-X = np.random.rand(20, 20, 40)
+x, y, z = np.ogrid[-10:10:100j, -10:10:100j, 1:10:20j]
+X = np.sin(x * y * z) / (x * y * z)
 
+fig, ax = plt.subplots()
+# create an IndexTracker and make sure it lives during the whole
+# lifetime of the figure by assigning it to a variable
 tracker = IndexTracker(ax, X)
 
-
 fig.canvas.mpl_connect('scroll_event', tracker.on_scroll)
 plt.show()
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2440,6 +2440,14 @@ def func(event: Event) -> Any
             be set to the mouse location in data coordinates.  See `.KeyEvent`
             and `.MouseEvent` for more info.
 
+            .. note::
+
+                If func is a method, this only stores a weak reference to the
+                method. Thus, the figure does not influence the lifetime of
+                the associated object. Usually, you want to make sure that the
+                object is kept alive throughout the lifetime of the figure by
+                holding a reference to it.
+
         Returns
         -------
         cid
