Document what pyplot expects from a backend.

anntzer · anntzer · commit 6670d0df4123 · 2022-05-23T08:23:30.000+02:00
diff --git a/doc/users/explain/backends.rst b/doc/users/explain/backends.rst
@@ -252,3 +252,6 @@ More generally, any importable backend can be selected by using any of the
 methods above. If ``name.of.the.backend`` is the module containing the
 backend, use ``module://name.of.the.backend`` as the backend name, e.g.
 ``matplotlib.use('module://name.of.the.backend')``.
+
+Information for backend implementers is available at
+:doc:`/users/explain/writing_a_backend`.
diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst
@@ -10,6 +10,7 @@ Explanations
 
     api_interfaces.rst
     backends.rst
+    writing_a_backend.rst
     interactive.rst
     fonts.rst
     event_handling.rst
diff --git a/doc/users/explain/writing_a_backend.rst b/doc/users/explain/writing_a_backend.rst
@@ -0,0 +1,70 @@
+=================
+Writing a backend
+=================
+
+**This is a work in progress.**
+
+This page assumes general understanding of the information in the
+:doc:`/users/explain/backends` page, and is instead intended as reference for
+third-party backend implementers.  It also only deals with the interaction
+between backends and `.pyplot`, not with the rendering side, which is described
+in `.backend_template`.
+
+There are two APIs for defining backends: a new canvas-based API (introduced
+in Matplotlib 3.6), and an older function-based API.  The newer API should
+be preferred if back-compatibility is not a concern (because of better
+composability: many methods can be inherited from "parent backends"), and is
+therefore described first, but the older API is also briefly described here.
+
+Fundamentally, a backend module needs to provide information to `.pyplot`, so
+that
+
+- `.pyplot.figure()` can attach a newly created `.Figure` to an instance of a
+  backend-provided canvas class, itself hosted in an instance of a
+  backend-provided manager class.
+- `.pyplot.show()` can show all figures and start the GUI event loop (if any).
+
+To do so, the backend module must define a class accessible as
+``backend_module.FigureCanvas``.  In the canvas-based API, this is the only
+strict requirement for backend modules.  (The function-based API additionally
+requires many module-level functions to be defined.)
+
+- `.pyplot.figure()` calls ``FigureCanvas.new_manager(Figure(), num)`` (a
+  classmethod) to attach a canvas and a manager.  Figure unpickling uses the
+  same approach, but replaces the ``Figure()`` instantiation by the unpickled
+  figure.
+
+  Interactive backends should customize the effect of ``new_manager``
+  by setting a ``manager_class`` attribute on their ``FigureCanvas``,
+  and additionally (if the canvas cannot be created before the
+  manager, as in the case of the wx backend) by overriding the
+  ``FigureManager.create_with_canvas`` classmethod.  (Non-interactive backends
+  can normally use a trivial ``FigureManagerBase`` and can therefore skip this
+  step.)
+
+  In the old function-based API, this customization point was provided by
+  two functions, ``new_figure_manager(num, *args, **kwargs)`` (for
+  `.pyplot.figure`) and ``new_figure_manager_given_figure`` (for unpickling).
+
+- After a new figure is registered with `.pyplot` (either via
+  `.pyplot.figure()` or via unpickling), if in interactive mode, `.pyplot` will
+  call its canvas' ``draw_idle()`` method.  This call can be customized by
+  providing a ``draw_if_interactive`` module-level function, but this is now
+  discouraged (if needed, consider overriding ``draw_idle()`` instead, keeping
+  track of whether this is the first call that method).
+
+- `.pyplot.show()` calls ``FigureCanvas.pyplot_show()`` (a classmethod),
+  forwarding any arguments, to start the main event loop.
+
+  By default, ``pyplot_show()`` checks whether there are any ``managers``
+  registered with `.pyplot` (exiting early if not), calls ``manager.show()``
+  on all such managers, and then, if called with ``block=True`` (or with the
+  default ``block=None`` and out of IPython's pylab mode and not in interactive
+  mode), calls ``FigureCanvas.start_main_loop()`` (a classmethod) to start the
+  main event loop.  Interactive backends should therefore override the
+  ``FigureCanvas.start_main_loop`` classmethod accordingly (or alternatively,
+  they may also directly override ``FigureCanvas.pyplot_show`` directly).
+
+  In the old function-based API, this customization point was provided via a
+  ``show`` callable generated via the ``ShowBase`` class and its ``mainloop``
+  method.
