From fbca556a2b68a22d4b5c24cdb632ac5f5f9f12af Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 4 Nov 2022 21:12:37 +0100
Subject: [PATCH] DOC: Improve Image Slices Viewer example

---
 .../event_handling/image_slices_viewer.py     | 46 ++++++++-----------
 lib/matplotlib/backend_bases.py               |  8 ++++
 2 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/examples/event_handling/image_slices_viewer.py b/examples/event_handling/image_slices_viewer.py
index 6431d38ac541..8a2860902bce 100644
--- a/examples/event_handling/image_slices_viewer.py
+++ b/examples/event_handling/image_slices_viewer.py
@@ -1,9 +1,10 @@
 """
-===================
-Image Slices Viewer
-===================
+============
+Scroll event
+============
 
-Scroll through 2D image slices of a 3D array.
+In this example a scroll wheel event is used to scroll through 2D slices of
+3D data.
 
 .. note::
     This example exercises the interactive capabilities of Matplotlib, and this
@@ -18,42 +19,35 @@
 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\nindex {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
index e4688f8abb69..5954381085ee 100644
--- 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