feat(base): set_window_title, set the title of a figure's window if it has one (#263)

## Summary

Adds `spatialmath.base.set_window_title(fig, title)`, which sets the
title of the window that contains a figure, if it has one.

A figure has a window only if it is managed by pyplot and the backend
provides one. On a headless backend (`Agg`), or for a figure made
directly with `matplotlib.figure.Figure`, there is no window:
`canvas.manager` is `None`, or the manager has no `set_window_title`.
The function then does nothing and returns `False`, so callers do not
need a `try`/`except` or a guard.

## Why

The Robotics Toolbox for Python and the Machine Vision Toolbox for
Python each set window titles, in several places, with different guards:
RTB reached into `figure.canvas.manager` directly in some places, and
MVTB has a helper on `plt.gcf()` with a bare `except:` as well as direct
calls. Both already depend on `spatialmath.base.graphics` for
`axes_logic` and `plotvol2`, so this is the natural home for one copy.

## Changes
- `spatialmath/base/graphics.py`: `set_window_title`, and a stub that
raises `NotImplementedError` without Matplotlib, as for the other
plotting functions.
- `spatialmath/base/__init__.py`: lazily exported with the other
graphics names.
- `tests/base/test_graphics.py`: a managed figure, a pyplot figure, a
figure without a manager, a manager without the method.

No change to any existing behaviour.

## Test plan
- [x] `pytest tests` (384 passed, 3 skipped)

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: petercorke

spatialmath/base/__init__.py

@@ -42,6 +42,7 @@
     "plot_cone": "graphics",
     "plot_cuboid": "graphics",
     "axes_logic": "graphics",
+    "set_window_title": "graphics",
     "plotvol2": "graphics",
     "plotvol3": "graphics",
     "expand_dims": "graphics",
@@ -391,6 +392,7 @@ def __getattr__(name):
     "plot_cone",
     "plot_cuboid",
     "axes_logic",
+    "set_window_title",
     "expand_dims",
     "isnotebook",
     # spatial.base.numeric

spatialmath/base/graphics.py

@@ -1791,6 +1791,37 @@ def expand_dims(dim: ArrayLike = None, nd: int = 2) -> NDArray:
         else:
             raise ValueError("nd is 2 or 3")
 
+    def set_window_title(fig: plt.Figure, title: str) -> bool:
+        """
+        Set the title of the window containing a figure, if it has one
+
+        :param fig: the figure
+        :type fig: Figure
+        :param title: the window title
+        :type title: str
+        :return: True if the title was set
+        :rtype: bool
+
+        A figure has a window only if it is managed by pyplot and the backend
+        provides one.  A figure on a headless backend such as ``Agg``, or one
+        created directly with ``matplotlib.figure.Figure``, does not, and then
+        nothing is done and False is returned.
+
+        Example::
+
+            >>> from spatialmath.base import plotvol2, set_window_title
+            >>> ax = plotvol2(5)
+            >>> set_window_title(ax.figure, "my plot")
+
+        .. note:: The title of the window is not the title of the axes, see
+            :meth:`matplotlib.axes.Axes.set_title`.
+        """
+        manager = getattr(fig.canvas, "manager", None)
+        if manager is not None and hasattr(manager, "set_window_title"):
+            manager.set_window_title(title)
+            return True
+        return False
+
     def isnotebook() -> bool:
         """
         Determine if code is being run from a Jupyter notebook
@@ -1857,3 +1888,6 @@ def plot_cone(*args, **kwargs) -> None:
 
     def plot_cylinder(*args, **kwargs) -> None:
         raise NotImplementedError("Matplotlib is not installed: pip install matplotlib")
+
+    def set_window_title(*args, **kwargs) -> None:
+        raise NotImplementedError("Matplotlib is not installed: pip install matplotlib")

tests/base/test_graphics.py

@@ -9,6 +9,39 @@
 # TODO check they actually create artists
 
 
+class TestWindowTitle(unittest.TestCase):
+    def teardown_method(self, method):
+        plt.close("all")
+
+    def test_sets_the_title_of_a_managed_figure(self):
+        from types import SimpleNamespace
+        from unittest import mock
+
+        manager = mock.Mock()
+        fig = SimpleNamespace(canvas=SimpleNamespace(manager=manager))
+        self.assertTrue(set_window_title(fig, "a title"))
+        manager.set_window_title.assert_called_once_with("a title")
+
+    def test_pyplot_figure(self):
+        # the Agg manager has no window, but does accept a title
+        fig = plt.figure()
+        self.assertIsInstance(set_window_title(fig, "a title"), bool)
+
+    def test_figure_without_a_manager(self):
+        from matplotlib.figure import Figure
+
+        self.assertFalse(set_window_title(Figure(), "a title"))
+
+    def test_manager_without_the_method(self):
+        from types import SimpleNamespace
+
+        class Manager:
+            pass
+
+        fig = SimpleNamespace(canvas=SimpleNamespace(manager=Manager()))
+        self.assertFalse(set_window_title(fig, "a title"))
+
+
 class TestGraphics(unittest.TestCase):
     def teardown_method(self, method):
         plt.close("all")