fix: Qt5Agg support darkmode icon by using svg (matplotlib#30565)

* fix: Qt5Agg support darkmode icon

* fix(qt5agg): scale SVG toolbar icons to toolbar size and safely end QPainter to avoid crash

* Regenerate Qt5 tool icons when device pixel ratio changes

* Remove defensive check for Qt5 tool SVG icon existence

* refactor(backend_qt): Use QIconEngine for on-demand icon rendering

* Enhance SVG icon rendering support for multiple Qt versions

* refactor(backend_qt): Improve code quality based on review feedback

* Move QtSvg import to qt_compat

* Implement Qt toolmanager svg icon

* Simplify dark mode and large image detection

* refactor(backend_qt): Improve the clarity of the code's logic.

* refactor(backend_qt): simplify icon DPR handling in _IconEngine

* refactor(backend_qt): enhance icon loading logic

Author: LangQi99

lib/matplotlib/backends/backend_qt.py

@@ -14,7 +14,7 @@
 import matplotlib.backends.qt_editor.figureoptions as figureoptions
 from . import qt_compat
 from .qt_compat import (
-    QtCore, QtGui, QtWidgets, __version__, QT_API, _to_int, _isdeleted)
+    QtCore, QtGui, QtWidgets, QtSvg, __version__, QT_API, _to_int, _isdeleted)
 
 
 # SPECIAL_KEYS are Qt::Key that do *not* return their Unicode name
@@ -683,6 +683,120 @@ def set_window_title(self, title):
         self.window.setWindowTitle(title)
 
 
+class _IconEngine(QtGui.QIconEngine):
+    """
+    Custom QIconEngine that automatically handles DPI scaling for tools icons.
+
+    This engine provides icons on-demand with proper scaling based on the current
+    device pixel ratio, eliminating the need for manual refresh when DPI changes.
+    """
+
+    def __init__(self, image_path, toolbar=None):
+        super().__init__()
+        self.image_path = image_path
+        self.toolbar = toolbar
+
+    def _is_dark_mode(self):
+        return self.toolbar.palette().color(self.toolbar.backgroundRole()).value() < 128
+
+    def paint(self, painter, rect, mode, state):
+        """Paint the icon at the requested size and state."""
+        pixmap = self.pixmap(rect.size(), mode, state)
+        if not pixmap.isNull():
+            painter.drawPixmap(rect, pixmap)
+
+    def pixmap(self, size, mode, state):
+        """Generate a pixmap for the requested size, mode, and state."""
+        if size.width() <= 0 or size.height() <= 0:
+            return QtGui.QPixmap()
+
+        # Try SVG first, then fall back to PNG
+        svg_path = self.image_path.with_suffix('.svg')
+        if svg_path.exists():
+            pixmap = self._create_pixmap_from_svg(svg_path, size)
+            if not pixmap.isNull():
+                return pixmap
+        return self._create_pixmap_from_png(self.image_path, size)
+
+    def _devicePixelRatio(self):
+        """Return the current device pixel ratio for the toolbar, defaulting to 1."""
+        return (self.toolbar.devicePixelRatioF() or 1) if self.toolbar else 1
+
+    def _create_pixmap_from_svg(self, svg_path, size):
+        """Create a pixmap from SVG with proper scaling and dark mode support."""
+        QSvgRenderer = getattr(QtSvg, "QSvgRenderer", None)
+        if QSvgRenderer is None:
+            return QtGui.QPixmap()
+
+        svg_content = svg_path.read_bytes()
+
+        if self._is_dark_mode():
+            svg_content = svg_content.replace(b'fill:black;', b'fill:white;')
+            svg_content = svg_content.replace(b'stroke:black;', b'stroke:white;')
+
+        renderer = QSvgRenderer(QtCore.QByteArray(svg_content))
+        if not renderer.isValid():
+            return QtGui.QPixmap()
+
+        dpr = self._devicePixelRatio()
+        scaled_size = QtCore.QSize(int(size.width() * dpr), int(size.height() * dpr))
+        pixmap = QtGui.QPixmap(scaled_size)
+        pixmap.setDevicePixelRatio(dpr)
+        pixmap.fill(QtCore.Qt.GlobalColor.transparent)
+
+        painter = QtGui.QPainter()
+        try:
+            painter.begin(pixmap)
+            renderer.render(painter, QtCore.QRectF(0, 0, size.width(), size.height()))
+        finally:
+            if painter.isActive():
+                painter.end()
+
+        return pixmap
+
+    def _create_pixmap_from_png(self, base_path, size):
+        """
+        Create a pixmap from PNG with scaling and dark mode support.
+
+        Prefer to use the *_large.png with the same name; otherwise, use base_path.
+        """
+        large_path = base_path.with_name(base_path.stem + '_large.png')
+        source_pixmap = QtGui.QPixmap()
+        for candidate in (large_path, base_path):
+            if not candidate.exists():
+                continue
+            candidate_pixmap = QtGui.QPixmap(str(candidate))
+            if not candidate_pixmap.isNull():
+                source_pixmap = candidate_pixmap
+                break
+        if source_pixmap.isNull():
+            return source_pixmap
+
+        dpr = self._devicePixelRatio()
+
+        # Scale to requested size
+        scaled_size = QtCore.QSize(int(size.width() * dpr), int(size.height() * dpr))
+        scaled_pixmap = source_pixmap.scaled(
+            scaled_size,
+            QtCore.Qt.AspectRatioMode.KeepAspectRatio,
+            QtCore.Qt.TransformationMode.SmoothTransformation
+        )
+        scaled_pixmap.setDevicePixelRatio(dpr)
+
+        if self._is_dark_mode():
+            # On some platforms (e.g., macOS with Qt5 in dark mode), this may
+            # incorrectly return a black color instead of a light one.
+            # See issue #27590 for details.
+            icon_color = self.toolbar.palette().color(self.toolbar.foregroundRole())
+            mask = scaled_pixmap.createMaskFromColor(
+                QtGui.QColor('black'),
+                QtCore.Qt.MaskMode.MaskOutColor)
+            scaled_pixmap.fill(icon_color)
+            scaled_pixmap.setMask(mask)
+
+        return scaled_pixmap
+
+
 class NavigationToolbar2QT(NavigationToolbar2, QtWidgets.QToolBar):
     toolitems = [*NavigationToolbar2.toolitems]
     toolitems.insert(
@@ -740,25 +854,16 @@ def _icon(self, name):
         """
         Construct a `.QIcon` from an image file *name*, including the extension
         and relative to Matplotlib's "images" data directory.
+
+        Uses _IconEngine for automatic DPI scaling.
         """
-        # use a high-resolution icon with suffix '_large' if available
-        # note: user-provided icons may not have '_large' versions
+        # Get the image path
         path_regular = cbook._get_data_path('images', name)
-        path_large = path_regular.with_name(
-            path_regular.name.replace('.png', '_large.png'))
-        filename = str(path_large if path_large.exists() else path_regular)
-
-        pm = QtGui.QPixmap(filename)
-        pm.setDevicePixelRatio(
-            self.devicePixelRatioF() or 1)  # rarely, devicePixelRatioF=0
-        if self.palette().color(self.backgroundRole()).value() < 128:
-            icon_color = self.palette().color(self.foregroundRole())
-            mask = pm.createMaskFromColor(
-                QtGui.QColor('black'),
-                QtCore.Qt.MaskMode.MaskOutColor)
-            pm.fill(icon_color)
-            pm.setMask(mask)
-        return QtGui.QIcon(pm)
+
+        # Create icon using our custom engine for automatic DPI handling
+        engine = _IconEngine(path_regular, self)
+        return QtGui.QIcon(engine)
+
 
     def edit_parameters(self):
         axes = self.canvas.figure.get_axes()

lib/matplotlib/backends/qt_compat.py

@@ -64,27 +64,27 @@
 
 
 def _setup_pyqt5plus():
-    global QtCore, QtGui, QtWidgets, __version__
+    global QtCore, QtGui, QtWidgets, QtSvg, __version__
     global _isdeleted, _to_int
 
     if QT_API == QT_API_PYQT6:
-        from PyQt6 import QtCore, QtGui, QtWidgets, sip
+        from PyQt6 import QtCore, QtGui, QtWidgets, sip, QtSvg
         __version__ = QtCore.PYQT_VERSION_STR
         QtCore.Signal = QtCore.pyqtSignal
         QtCore.Slot = QtCore.pyqtSlot
         QtCore.Property = QtCore.pyqtProperty
         _isdeleted = sip.isdeleted
         _to_int = operator.attrgetter('value')
     elif QT_API == QT_API_PYSIDE6:
-        from PySide6 import QtCore, QtGui, QtWidgets, __version__
+        from PySide6 import QtCore, QtGui, QtWidgets, QtSvg, __version__
         import shiboken6
         def _isdeleted(obj): return not shiboken6.isValid(obj)
         if parse_version(__version__) >= parse_version('6.4'):
             _to_int = operator.attrgetter('value')
         else:
             _to_int = int
     elif QT_API == QT_API_PYQT5:
-        from PyQt5 import QtCore, QtGui, QtWidgets
+        from PyQt5 import QtCore, QtGui, QtWidgets, QtSvg
         import sip
         __version__ = QtCore.PYQT_VERSION_STR
         QtCore.Signal = QtCore.pyqtSignal
@@ -93,7 +93,7 @@ def _isdeleted(obj): return not shiboken6.isValid(obj)
         _isdeleted = sip.isdeleted
         _to_int = int
     elif QT_API == QT_API_PYSIDE2:
-        from PySide2 import QtCore, QtGui, QtWidgets, __version__
+        from PySide2 import QtCore, QtGui, QtWidgets, QtSvg, __version__
         try:
             from PySide2 import shiboken2
         except ImportError: