From c0cb163c627fe52e38311954226e3349f34f6914 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 11 Nov 2021 00:32:34 +0100 Subject: [PATCH] Document text alignment Closes #21571. --- .../text_alignment.py | 46 +++++++++++++++++-- lib/matplotlib/text.py | 17 +++++-- 2 files changed, 54 insertions(+), 9 deletions(-) diff --git a/examples/text_labels_and_annotations/text_alignment.py b/examples/text_labels_and_annotations/text_alignment.py index 6ad79fb18fb8..a12002972233 100644 --- a/examples/text_labels_and_annotations/text_alignment.py +++ b/examples/text_labels_and_annotations/text_alignment.py @@ -1,12 +1,48 @@ """ -=================== -Precise text layout -=================== +============== +Text alignment +============== + +Texts are aligned relative to their anchor point depending on the properties +``horizontalalignment`` and ``verticalalignment``. + +.. plot:: + + import matplotlib.pyplot as plt + import numpy as np + + y = [0.22, 0.34, 0.5, 0.56, 0.78] + x = [0.17, 0.5, 0.855] + X, Y = np.meshgrid(x, y) + + fig, ax = plt.subplots(figsize=(6, 4), dpi=100) + ax.set(xlim=(0, 1), ylim=(0, 1), xticks=[], yticks=[]) + ax.spines[:].set_visible(False) + ax.text(0.5, 0.5, 'plot', fontsize=128, ha='center', va='center', zorder=1) + ax.hlines(y, x[0], x[-1], color='grey') + ax.vlines(x, y[0], y[-1], color='grey') + ax.plot(X.ravel(), Y.ravel(), 'o') + pad_x = 0.02 + pad_y = 0.04 + ax.text(x[0] - pad_x, y[0], 'bottom', ha='right', va='center') + ax.text(x[0] - pad_x, y[1], 'baseline', ha='right', va='center') + ax.text(x[0] - pad_x, y[2], 'center', ha='right', va='center') + ax.text(x[0] - pad_x, y[3], 'center_baseline', ha='right', va='center') + ax.text(x[0] - pad_x, y[4], 'top', ha='right', va='center') + ax.text(x[0], y[0] - pad_y, 'left', ha='center', va='top') + ax.text(x[1], y[0] - pad_y, 'center', ha='center', va='top') + ax.text(x[2], y[0] - pad_y, 'right', ha='center', va='top') + ax.set_xlabel('horizontalalignment', fontsize=14) + ax.set_ylabel('verticalalignment', fontsize=14, labelpad=35) + ax.set_title( + 'Relative position of text anchor point depending on alignment') + plt.show() -You can precisely layout text in data or axes coordinates. This example shows -you some of the alignment and rotation specifications for text layout. """ +############################################################################# +# The following plot uses this to align text relative to a plotted rectangle. + import matplotlib.pyplot as plt fig, ax = plt.subplots() diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py index be26b14d0026..e607c04e38f0 100644 --- a/lib/matplotlib/text.py +++ b/lib/matplotlib/text.py @@ -148,6 +148,11 @@ def __init__(self, """ Create a `.Text` instance at *x*, *y* with string *text*. + The text is aligned relative to the anchor point (*x*, *y*) according + to ``horizontalalignment`` (default: 'left') and ``verticalalignment`` + (default: 'bottom'). See also + :doc:`/gallery/text_labels_and_annotations/text_alignment`. + While Text accepts the 'label' keyword argument, by default it is not added to the handles of a legend. @@ -956,11 +961,13 @@ def set_color(self, color): def set_horizontalalignment(self, align): """ - Set the horizontal alignment to one of + Set the horizontal alignment relative to the anchor point. + + See also :doc:`/gallery/text_labels_and_annotations/text_alignment`. Parameters ---------- - align : {'center', 'right', 'left'} + align : {'left', 'center', 'right'} """ _api.check_in_list(['center', 'right', 'left'], align=align) self._horizontalalignment = align @@ -1202,11 +1209,13 @@ def set_transform_rotates_text(self, t): def set_verticalalignment(self, align): """ - Set the vertical alignment. + Set the vertical alignment relative to the anchor point. + + See also :doc:`/gallery/text_labels_and_annotations/text_alignment`. Parameters ---------- - align : {'center', 'top', 'bottom', 'baseline', 'center_baseline'} + align : {'bottom', 'baseline', 'center', 'center_baseline', 'top'} """ _api.check_in_list( ['top', 'bottom', 'center', 'baseline', 'center_baseline'],