MNT: Towards standardizing widget blitting

To have standard logical framework for blitting of widgets, we pull some
logic up into AxesWidget:
- Most widgets held a _useblit variable. This is now part of AxesWidget.
- AxesWidget._should_use_blit() returns whether blitting should
*currently* be done - i.e. the user/widget requested it and the canvas
supports it. This is used to guard all blitting-related code.

Note: This is a well-defined and limited step towards standardization.
Not all widgets are already using it. Some still have special logic. I
anticipate that migrating them will be easier when this infrastructure
and logical concept is present. Changes here are limited to obvious
cases. The rest will be handled in a follow-up PR.

Author: timhoffm

lib/matplotlib/widgets.py

@@ -113,12 +113,21 @@ class AxesWidget(Widget):
         The parent figure canvas for the widget.
     active : bool
         If False, the widget does not respond to events.
+    useblit : bool
+        Whether usage of blitting is desired. The actual usage of
+        blitting also depends on the canvas supporting it.
+
+        Once set, this is read-only, as some widgets currently still
+        depend on the state statically. They still query _useblit.
+
+        .. versionadded:: 3.11
     """
 
-    def __init__(self, ax):
+    def __init__(self, ax, useblit=False):
         self.ax = ax
         self._cids = []
         self._blit_background_id = None
+        self._useblit = useblit
 
     def __del__(self):
         if self._blit_background_id is not None:
@@ -151,6 +160,34 @@ def _set_cursor(self, cursor):
         """Update the canvas cursor."""
         self.ax.get_figure(root=True).canvas.set_cursor(cursor)
 
+    def _may_use_blit(self):
+        """
+        Return whether blitting could potentially be used.
+
+        This is defined by the *useblit* parameter upon initialization
+        and currently cannot be changed afterwards. Widgets can
+        set up differently depending on this value. In particular they
+        can create Artists with ``animated=self._may_use_blit()``.
+        This makes sure these Artists properly work with blitting if
+        that is applied, but is also safe to use if blitting is not
+        applied.
+
+        Note: We define this separately from _useblit for semantic
+        clarity. Eventually, we want to migrate widget code away from
+        directly accessing _useblit.
+        """
+        return self._useblit
+
+    def _should_use_blit(self):
+        """
+        Return whether blitting should be used.
+
+        All blitting-related code must be guarded by this because
+        not all canvases support blit and canvases may be swapped
+        out during the lifetime of the widget.
+        """
+        return self._useblit and self.canvas.supports_blit
+
     def _save_blit_background(self, background):
         """
         Save a blit background.
@@ -239,7 +276,7 @@ def __init__(self, ax, label, image=None,
 
             .. versionadded:: 3.7
         """
-        super().__init__(ax)
+        super().__init__(ax, useblit=useblit)
 
         if image is not None:
             ax.imshow(image)
@@ -248,8 +285,6 @@ def __init__(self, ax, label, image=None,
                              horizontalalignment='center',
                              transform=ax.transAxes)
 
-        self._useblit = useblit
-
         self._observers = cbook.CallbackRegistry(signals=["clicked"])
 
         self.connect_event('button_press_event', self._click)
@@ -285,7 +320,7 @@ def _motion(self, event):
         if not colors.same_color(c, self.ax.get_facecolor()):
             self.ax.set_facecolor(c)
             if self.drawon:
-                if self._useblit and self.canvas.supports_blit:
+                if self._should_use_blit():
                     self.ax.draw_artist(self.ax)
                     self.canvas.blit(self.ax.bbox)
                 else:
@@ -1096,7 +1131,7 @@ def __init__(self, ax, labels, actives=None, *, useblit=True,
 
             .. versionadded:: 3.7
         """
-        super().__init__(ax)
+        super().__init__(ax, useblit=useblit)
 
         _api.check_isinstance((dict, None), label_props=label_props,
                               frame_props=frame_props, check_props=check_props)
@@ -1108,8 +1143,6 @@ def __init__(self, ax, labels, actives=None, *, useblit=True,
         if actives is None:
             actives = [False] * len(labels)
 
-        self._useblit = useblit
-
         ys = np.linspace(1, 0, len(labels)+2)[1:-1]
 
         label_props = _expand_text_props(label_props)
@@ -1158,7 +1191,7 @@ def _clear(self, event):
         """Internal event handler to clear the buttons."""
         if self.ignore(event) or self.canvas.is_saving():
             return
-        if self._useblit and self.canvas.supports_blit:
+        if self._should_use_blit():
             self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
         self.ax.draw_artist(self._checks)
 
@@ -1264,7 +1297,7 @@ def set_active(self, index, state=None):
         self._checks.set_facecolor(facecolors)
 
         if self.drawon:
-            if self._useblit and self.canvas.supports_blit:
+            if self._should_use_blit():
                 background = self._load_blit_background()
                 if background is not None:
                     self.canvas.restore_region(background)
@@ -1678,7 +1711,7 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
 
             .. versionadded:: 3.7
         """
-        super().__init__(ax)
+        super().__init__(ax, useblit=useblit)
 
         _api.check_isinstance((dict, None), label_props=label_props,
                               radio_props=radio_props)
@@ -1705,8 +1738,6 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
 
         ys = np.linspace(1, 0, len(labels) + 2)[1:-1]
 
-        self._useblit = useblit
-
         label_props = _expand_text_props(label_props)
         self.labels = [
             ax.text(0.25, y, label, transform=ax.transAxes,
@@ -1751,7 +1782,7 @@ def _clear(self, event):
         """Internal event handler to clear the buttons."""
         if self.ignore(event) or self.canvas.is_saving():
             return
-        if self._useblit and self.canvas.supports_blit:
+        if self._should_use_blit():
             self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
         self.ax.draw_artist(self._buttons)
 
@@ -1845,7 +1876,7 @@ def set_active(self, index):
         self._buttons.set_facecolor(button_facecolors)
 
         if self.drawon:
-            if self._useblit and self.canvas.supports_blit:
+            if self._should_use_blit():
                 background = self._load_blit_background()
                 if background is not None:
                     self.canvas.restore_region(background)
@@ -1989,7 +2020,7 @@ class Cursor(AxesWidget):
     """
     def __init__(self, ax, *, horizOn=True, vertOn=True, useblit=False,
                  **lineprops):
-        super().__init__(ax)
+        super().__init__(ax, useblit=useblit)
 
         self.connect_event('motion_notify_event', self.onmove)
         self.connect_event('draw_event', self.clear)
@@ -2010,7 +2041,7 @@ def clear(self, event):
         """Internal event handler to clear the cursor."""
         if self.ignore(event) or self.canvas.is_saving():
             return
-        if self.useblit:
+        if self._should_use_blit():
             self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
 
     @_call_with_reparented_event
@@ -2035,7 +2066,7 @@ def onmove(self, event):
         if not (self.visible and (self.vertOn or self.horizOn)):
             return
         # Redraw.
-        if self.useblit:
+        if self._should_use_blit():
             background = self._load_blit_background()
             if background is not None:
                 self.canvas.restore_region(background)
@@ -2205,14 +2236,13 @@ class _SelectorWidget(AxesWidget):
 
     def __init__(self, ax, onselect=None, useblit=False, button=None,
                  state_modifier_keys=None, use_data_coordinates=False):
-        super().__init__(ax)
+        super().__init__(ax, useblit=useblit)
 
         self._visible = True
         if onselect is None:
             self.onselect = lambda *args: None
         else:
             self.onselect = onselect
-        self._useblit = useblit
         self.connect_default_events()
 
         self._state_modifier_keys = dict(move=' ', clear='escape',
@@ -2239,7 +2269,7 @@ def __init__(self, ax, onselect=None, useblit=False, button=None,
     @property
     def useblit(self):
         """Return whether blitting is used (requested and supported by canvas)."""
-        return self._useblit and self.canvas.supports_blit
+        return self._should_use_blit()
 
     def set_active(self, active):
         super().set_active(active)
@@ -2262,7 +2292,7 @@ def update_background(self, event):
         """Force an update of the background."""
         # If you add a call to `ignore` here, you'll want to check edge case:
         # `release` can call a draw event even when `ignore` is True.
-        if not self.useblit:
+        if not self._should_use_blit():
             return
         if self.canvas.is_saving():
             return  # saving does not use blitting
@@ -2323,11 +2353,11 @@ def ignore(self, event):
                 event.button != self._eventpress.button)
 
     def update(self):
-        """Draw using blit() or draw_idle(), depending on ``self.useblit``."""
+        """Draw using blit() or draw_idle(), depending on blitting support."""
         if (not self.ax.get_visible() or
                 self.ax.get_figure(root=True)._get_renderer() is None):
             return
-        if self.useblit:
+        if self._should_use_blit():
             background = self._load_blit_background()
             if background is not None:
                 self.canvas.restore_region(background)
@@ -2500,7 +2530,7 @@ def set_props(self, **props):
         artist = self._selection_artist
         props = cbook.normalize_kwargs(props, artist)
         artist.set(**props)
-        if self.useblit:
+        if self._should_use_blit():
             self.update()
 
     def set_handle_props(self, **handle_props):
@@ -2516,7 +2546,7 @@ def set_handle_props(self, **handle_props):
         handle_props = cbook.normalize_kwargs(handle_props, artist)
         for handle in self._handles_artists:
             handle.set(**handle_props)
-        if self.useblit:
+        if self._should_use_blit():
             self.update()
         self._handle_props.update(handle_props)
 
@@ -2675,7 +2705,7 @@ def __init__(self, ax, onselect, direction, *, minspan=0, useblit=False,
         #       This relies on the current behavior that the request for
         #       useblit is fixed during initialization and cannot be changed
         #       afterwards.
-        props['animated'] = self._useblit
+        props['animated'] = self._may_use_blit()
 
         self.direction = direction
         self._extents_on_press = None
@@ -2741,7 +2771,7 @@ def _setup_edge_handles(self, props):
         self._edge_handles = ToolLineHandles(self.ax, positions,
                                              direction=self.direction,
                                              line_props=props,
-                                             useblit=self._useblit)
+                                             useblit=self._may_use_blit())
 
     @property
     def _handles_artists(self):
@@ -3315,7 +3345,7 @@ def __init__(self, ax, onselect=None, *, minspanx=0,
         if props is None:
             props = dict(facecolor='red', edgecolor='black',
                          alpha=0.2, fill=True)
-        props = {**props, 'animated': self._useblit}
+        props = {**props, 'animated': self._may_use_blit()}
         self._visible = props.pop('visible', self._visible)
         to_draw = self._init_shape(**props)
         self.ax.add_patch(to_draw)
@@ -3340,18 +3370,18 @@ def __init__(self, ax, onselect=None, *, minspanx=0,
             xc, yc = self.corners
             self._corner_handles = ToolHandles(self.ax, xc, yc,
                                                marker_props=self._handle_props,
-                                               useblit=self._useblit)
+                                               useblit=self._may_use_blit())
 
             self._edge_order = ['W', 'S', 'E', 'N']
             xe, ye = self.edge_centers
             self._edge_handles = ToolHandles(self.ax, xe, ye, marker='s',
                                              marker_props=self._handle_props,
-                                             useblit=self._useblit)
+                                             useblit=self._may_use_blit())
 
             xc, yc = self.center
             self._center_handle = ToolHandles(self.ax, [xc], [yc], marker='s',
                                               marker_props=self._handle_props,
-                                              useblit=self._useblit)
+                                              useblit=self._may_use_blit())
 
             self._active_handle = None
 
@@ -3856,9 +3886,7 @@ def __init__(self, ax, onselect=None, *, useblit=True, props=None, button=None):
         self.verts = None
         props = {
             **(props if props is not None else {}),
-            # Note that self.useblit may be != useblit, if the canvas doesn't
-            # support blitting.
-            'animated': self._useblit, 'visible': False,
+            'animated': self._may_use_blit(), 'visible': False,
         }
         line = Line2D([], [], **props)
         self.ax.add_line(line)
@@ -3983,7 +4011,7 @@ def __init__(self, ax, onselect=None, *, useblit=False,
 
         if props is None:
             props = dict(color='k', linestyle='-', linewidth=2, alpha=0.5)
-        props = {**props, 'animated': self._useblit}
+        props = {**props, 'animated': self._may_use_blit()}
         self._selection_artist = line = Line2D([], [], **props)
         self.ax.add_line(line)
 
@@ -3992,7 +4020,7 @@ def __init__(self, ax, onselect=None, *, useblit=False,
                                 markerfacecolor=props.get('color', 'k'))
         self._handle_props = handle_props
         self._polygon_handles = ToolHandles(self.ax, [], [],
-                                            useblit=self._useblit,
+                                            useblit=self._may_use_blit(),
                                             marker_props=self._handle_props)
 
         self._active_handle_idx = -1
@@ -4012,7 +4040,7 @@ def _get_bbox(self):
 
     def _add_box(self):
         self._box = RectangleSelector(self.ax,
-                                      useblit=self._useblit,
+                                      useblit=self._may_use_blit(),
                                       grab_range=self.grab_range,
                                       handle_props=self._box_handle_props,
                                       props=self._box_props,

lib/matplotlib/widgets.pyi

@@ -34,13 +34,15 @@ class Widget:
 
 class AxesWidget(Widget):
     ax: Axes
-    def __init__(self, ax: Axes) -> None: ...
+    def __init__(self, ax: Axes, useblit: bool = ...) -> None: ...
     def __del__(self) -> None: ...
     @property
     def canvas(self) -> FigureCanvasBase | None: ...
     def connect_event(self, event: Event, callback: Callable) -> None: ...
     def disconnect_events(self) -> None: ...
     def _set_cursor(self, cursor: Cursors) -> None: ...
+    def _may_use_blit(self) -> bool: ...
+    def _should_use_blit(self) -> bool: ...
 
 class Button(AxesWidget):
     label: Text