DOC: document fmt_xdata and fmt_ydata

tacaswell · tacaswell · commit 0b7d5328bdf3 · 2023-02-09T18:11:35.000-05:00
Closes #9593
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -522,6 +522,8 @@ Interactive
    Axes.format_cursor_data
    Axes.format_xdata
    Axes.format_ydata
+   Axes.fmt_xdata
+   Axes.fmt_ydata
 
    Axes.mouseover
    Axes.in_axes
diff --git a/doc/users/explain/interactive.rst b/doc/users/explain/interactive.rst
@@ -227,6 +227,29 @@ Preserve aspect ratio              hold **CONTROL** when panning/zooming with mo
 ================================== ===============================
 
 
+Position Format
+---------------
+
+The location of the cursor is show in the UI and generated via the
+`~axes.Axes.format_coord` method which in turn calls the
+`~axes.Axes.format_xdata` and `~axes.Axes.format_ydata` methods.  The hard
+coded format in `~axes.Axes.format_coord` is ``f'x={formtated_x}
+y={formatted_y}'``.
+
+To easily customize how the x and y values are formatted, you can set the
+`.axes.Axes.fmt_xdata` and `.axes.Axes.fmt_ydata` attributes on the
+`~axes.Axes` instance.  The values are expected to be functions that
+take a float and return a string.  For example ::
+
+  fig, ax = plt.subplots()
+  ax.set_ylim(-5, 5)
+  ax.fmt_ydata = lambda v: f'{v:.3g}' if v > 0 else f'({abs(v):.3g})'
+
+will format negative y-values with parenthesis rather than a negative sign.  If
+these attributes are set to `None`, then the `.Formatter.format_data_short`
+method on the major formatter of the respective axes will be used instead.
+
+
 .. _other-shells:
 
 Other Python prompts
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -561,6 +561,20 @@ class _AxesBase(martist.Artist):
 
     _subclass_uses_cla = False
 
+    #: Callable to format the x-data in an interactive window.
+    #:
+    #: The expected signature is ::
+    #:
+    #:     def fmt(val: float,/) -> str: ...
+    fmt_xdata = None
+
+    #: Callable to format the y-data in an interactive window
+    #:
+    #: The expected signature is ::
+    #:
+    #:     def fmt(val: float,/) -> str: ...
+    fmt_ydata = None
+
     @property
     def _axis_map(self):
         """A mapping of axis names, e.g. 'x', to `Axis` instances."""
