Document what pyplot expects from a backend.

anntzer · anntzer · commit d30b372b9bb4 · 2022-10-18T11:31:52.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,73 @@
+=================
+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.  In the old function-based API, it
+  was possible to customize this call by providing a ``draw_if_interactive``
+  module-level function.  In the new canvas-based API, this function is not
+  taken into account anymore; if needed, consider overriding ``draw_idle()``
+  instead, keeping track of whether that method is being called for the first
+  time.
+
+- `.pyplot.show()` calls ``FigureCanvas.manager_class.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.manager_class.start_main_loop()``
+  (a classmethod) to start the main event loop.  Interactive backends should
+  therefore override the ``FigureCanvas.manager_class.start_main_loop``
+  classmethod accordingly (or alternatively, they may also directly override
+  ``FigureCanvas.manager_class.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.
