Use CallbackRegistry for all Widget event observers.

QuLogic · QuLogic · commit b9d9049ff8a5 · 2020-08-14T01:09:57.000-04:00
This simplifies processing, fixes memory leaks with weak references, and
fixes bugs like being unable to disconnect a callback in its own code.
diff --git a/doc/api/next_api_changes/behavior/18226-ES.rst b/doc/api/next_api_changes/behavior/18226-ES.rst
@@ -0,0 +1,10 @@
+Widgets use ``CallbackRegistry`` to save callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`.Widget`\s with event observers now use a `.CallbackRegistry` for storing
+callbacks. This is consistent with canvas event callbacks, and fixes some bugs
+in widget callback handling.
+
+Due to this change, callback methods are now stored as weak references, which
+means you must keep a reference to the associated object. Otherwise it may be
+garbage collected.
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -180,8 +180,7 @@ def __init__(self, ax, label, image=None,
                              horizontalalignment='center',
                              transform=ax.transAxes)
 
-        self._cnt = 0
-        self._observers = {}
+        self._observers = cbook.CallbackRegistry()
 
         self.connect_event('button_press_event', self._click)
         self.connect_event('button_release_event', self._release)
@@ -196,12 +195,13 @@ def __init__(self, ax, label, image=None,
     @cbook.deprecated("3.4")
     @property
     def cnt(self):
-        return self._cnt
+        # Not real, but close enough.
+        return len(self._observers.callbacks['clicked'])
 
     @cbook.deprecated("3.4")
     @property
     def observers(self):
-        return self._observers
+        return self._observers.callbacks['clicked']
 
     def _click(self, event):
         if (self.ignore(event)
@@ -219,8 +219,7 @@ def _release(self, event):
         if (not self.eventson
                 or event.inaxes != self.ax):
             return
-        for cid, func in self._observers.items():
-            func(event)
+        self._observers.process('clicked', event)
 
     def _motion(self, event):
         if self.ignore(event):
@@ -237,17 +236,11 @@ def on_clicked(self, func):
 
         Returns a connection id, which can be used to disconnect the callback.
         """
-        cid = self._cnt
-        self._observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('clicked', func)
 
     def disconnect(self, cid):
         """Remove the callback function with connection id *cid*."""
-        try:
-            del self._observers[cid]
-        except KeyError:
-            pass
+        self._observers.disconnect(cid)
 
 
 class Slider(AxesWidget):
@@ -397,20 +390,20 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt=None,
                                    verticalalignment='center',
                                    horizontalalignment='left')
 
-        self._cnt = 0
-        self._observers = {}
+        self._observers = cbook.CallbackRegistry()
 
         self.set_val(valinit)
 
     @cbook.deprecated("3.4")
     @property
     def cnt(self):
-        return self._cnt
+        # Not real, but close enough.
+        return len(self._observers.callbacks['changed'])
 
     @cbook.deprecated("3.4")
     @property
     def observers(self):
-        return self._observers
+        return self._observers.callbacks['changed']
 
     def _value_in_bounds(self, val):
         """Makes sure *val* is with given bounds."""
@@ -494,8 +487,7 @@ def set_val(self, val):
         self.val = val
         if not self.eventson:
             return
-        for cid, func in self._observers.items():
-            func(val)
+        self._observers.process('changed', val)
 
     def on_changed(self, func):
         """
@@ -513,10 +505,7 @@ def on_changed(self, func):
         int
             Connection id (which can be used to disconnect *func*)
         """
-        cid = self._cnt
-        self._observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('changed', func)
 
     def disconnect(self, cid):
         """
@@ -527,10 +516,7 @@ def disconnect(self, cid):
         cid : int
             Connection id of the observer to be removed
         """
-        try:
-            del self._observers[cid]
-        except KeyError:
-            pass
+        self._observers.disconnect(cid)
 
     def reset(self):
         """Reset the slider to the initial value"""
@@ -625,18 +611,18 @@ def __init__(self, ax, labels, actives=None):
 
         self.connect_event('button_press_event', self._clicked)
 
-        self._cnt = 0
-        self._observers = {}
+        self._observers = cbook.CallbackRegistry()
 
     @cbook.deprecated("3.4")
     @property
     def cnt(self):
-        return self._cnt
+        # Not real, but close enough.
+        return len(self._observers.callbacks['clicked'])
 
     @cbook.deprecated("3.4")
     @property
     def observers(self):
-        return self._observers
+        return self._observers.callbacks['clicked']
 
     def _clicked(self, event):
         if self.ignore(event) or event.button != 1 or event.inaxes != self.ax:
@@ -675,8 +661,7 @@ def set_active(self, index):
 
         if not self.eventson:
             return
-        for cid, func in self._observers.items():
-            func(self.labels[index].get_text())
+        self._observers.process('clicked', self.labels[index].get_text())
 
     def get_status(self):
         """
@@ -690,17 +675,11 @@ def on_clicked(self, func):
 
         Returns a connection id, which can be used to disconnect the callback.
         """
-        cid = self._cnt
-        self._observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('clicked', func)
 
     def disconnect(self, cid):
         """Remove the observer with connection id *cid*."""
-        try:
-            del self._observers[cid]
-        except KeyError:
-            pass
+        self._observers.disconnect(cid)
 
 
 class TextBox(AxesWidget):
@@ -760,9 +739,7 @@ def __init__(self, ax, label, initial='',
             self.DIST_FROM_LEFT, 0.5, initial, transform=self.ax.transAxes,
             verticalalignment='center', horizontalalignment='left')
 
-        self._cnt = 0
-        self._change_observers = {}
-        self._submit_observers = {}
+        self._observers = cbook.CallbackRegistry()
 
         ax.set(
             xlim=(0, 1), ylim=(0, 1),  # s.t. cursor appears from first click.
@@ -788,17 +765,18 @@ def __init__(self, ax, label, initial='',
     @cbook.deprecated("3.4")
     @property
     def cnt(self):
-        return self._cnt
+        # Not real, but close enough.
+        return sum(len(d) for d in self._observers.callbacks.values())
 
     @cbook.deprecated("3.4")
     @property
     def change_observers(self):
-        return self._change_observers
+        return self._observers.callbacks['change']
 
     @cbook.deprecated("3.4")
     @property
     def submit_observers(self):
-        return self._submit_observers
+        return self._observers.callbacks['submit']
 
     @property
     def text(self):
@@ -828,11 +806,6 @@ def _rendercursor(self):
 
         self.ax.figure.canvas.draw()
 
-    def _notify_submit_observers(self):
-        if self.eventson:
-            for cid, func in self._submit_observers.items():
-                func(self.text)
-
     def _release(self, event):
         if self.ignore(event):
             return
@@ -871,23 +844,20 @@ def _keypress(self, event):
                             text[self.cursor_index + 1:])
             self.text_disp.set_text(text)
             self._rendercursor()
-            self._notify_change_observers()
-            if key == "enter":
-                self._notify_submit_observers()
+            if self.eventson:
+                self._observers.process('change', self.text)
+                if key == "enter":
+                    self._observers.process('submit', self.text)
 
     def set_val(self, val):
         newval = str(val)
         if self.text == newval:
             return
         self.text_disp.set_text(newval)
         self._rendercursor()
-        self._notify_change_observers()
-        self._notify_submit_observers()
-
-    def _notify_change_observers(self):
         if self.eventson:
-            for cid, func in self._change_observers.items():
-                func(self.text)
+            self._observers.process('change', self.text)
+            self._observers.process('submit', self.text)
 
     def begin_typing(self, x):
         self.capturekeystrokes = True
@@ -920,10 +890,10 @@ def stop_typing(self):
         self.capturekeystrokes = False
         self.cursor.set_visible(False)
         self.ax.figure.canvas.draw()
-        if notifysubmit:
-            # Because _notify_submit_observers might throw an error in the
-            # user's code, only call it once we've already done our cleanup.
-            self._notify_submit_observers()
+        if notifysubmit and self.eventson:
+            # Because process() might throw an error in the user's code, only
+            # call it once we've already done our cleanup.
+            self._observers.process('submit', self.text)
 
     def position_cursor(self, x):
         # now, we have to figure out where the cursor goes.
@@ -968,10 +938,7 @@ def on_text_change(self, func):
 
         A connection id is returned which can be used to disconnect.
         """
-        cid = self._cnt
-        self._change_observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('change', func)
 
     def on_submit(self, func):
         """
@@ -980,18 +947,11 @@ def on_submit(self, func):
 
         A connection id is returned which can be used to disconnect.
         """
-        cid = self._cnt
-        self._submit_observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('submit', func)
 
     def disconnect(self, cid):
         """Remove the observer with connection id *cid*."""
-        for reg in [self._change_observers, self._submit_observers]:
-            try:
-                del reg[cid]
-            except KeyError:
-                pass
+        self._observers.disconnect(cid)
 
 
 class RadioButtons(AxesWidget):
@@ -1072,18 +1032,18 @@ def __init__(self, ax, labels, active=0, activecolor='blue'):
 
         self.connect_event('button_press_event', self._clicked)
 
-        self._cnt = 0
-        self._observers = {}
+        self._observers = cbook.CallbackRegistry()
 
     @cbook.deprecated("3.4")
     @property
     def cnt(self):
-        return self._cnt
+        # Not real, but close enough.
+        return len(self._observers.callbacks['clicked'])
 
     @cbook.deprecated("3.4")
     @property
     def observers(self):
-        return self._observers
+        return self._observers.callbacks['clicked']
 
     def _clicked(self, event):
         if self.ignore(event) or event.button != 1 or event.inaxes != self.ax:
@@ -1121,26 +1081,19 @@ def set_active(self, index):
 
         if not self.eventson:
             return
-        for cid, func in self._observers.items():
-            func(self.labels[index].get_text())
+        self._observers.process('clicked', self.labels[index].get_text())
 
     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.
         """
-        cid = self._cnt
-        self._observers[cid] = func
-        self._cnt += 1
-        return cid
+        return self._observers.connect('clicked', func)
 
     def disconnect(self, cid):
         """Remove the observer with connection id *cid*."""
-        try:
-            del self._observers[cid]
-        except KeyError:
-            pass
+        self._observers.disconnect(cid)
 
 
 class SubplotTool(Widget):
