document how to use text.Annotation for figure annotations and rainbow texts

story645 · tacaswell · story645 · commit c6eedb1650d0 · 2024-08-23T14:36:12.000-04:00
Co-authored-by: Thomas A Caswell &lt;tcaswell@gmail.com&gt;
diff --git a/galleries/examples/text_labels_and_annotations/rainbow_text.py b/galleries/examples/text_labels_and_annotations/rainbow_text.py
@@ -13,6 +13,7 @@
 import matplotlib.pyplot as plt
 
 plt.rcParams["font.size"] = 20
+
 ax = plt.figure().add_subplot(xticks=[], yticks=[])
 
 # The first word, created with text().
@@ -29,3 +30,42 @@
     color="blue", family="serif")  # custom properties
 
 plt.show()
+
+# %%
+#
+# Figure Text
+# -----------
+#
+# Figure text can be concatenated in a similar manner by creating a `~.text.Annotation`
+# object and adding it to the figure:
+
+
+import matplotlib.text as mtext
+
+fig, ax = plt.subplots(subplot_kw=dict(visible=False))
+
+text = fig.text(.1, .5, "Matplotlib", color="red")
+
+text = mtext.Annotation(" says,", xycoords=text, xy=(1, 0),
+                        va="bottom", color="gold", weight="bold")
+fig.add_artist(text)  # manually add artist to figure
+
+text = mtext.Annotation(" hello", xycoords=text, xy=(1, 0),
+                        va="bottom", color="green", style="italic")
+fig.add_artist(text)
+
+text = mtext.Annotation(" world!", xycoords=text, xy=(1, 0),
+                        va="bottom", color="blue", family="serif")
+fig.add_artist(text)
+
+# %%
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.axes.Axes.annotate`
+#    - `matplotlib.text.Annotation`
+#
+# .. tags:: component: annotation, component: text, styling: color
diff --git a/galleries/users_explain/text/annotations.py b/galleries/users_explain/text/annotations.py
@@ -586,7 +586,37 @@ def __call__(self, x0, y0, width, height, mutation_size):
                                   connectionstyle="arc3,rad=-0.2",
                                   relpos=(1., 0.),
                                   fc="w"))
+# %%
+# Create Annotation Artist
+# ^^^^^^^^^^^^^^^^^^^^^^^^
+#
+# An annotation artist may also be created using `.text.Annotation` and then added to
+# the figure. This can be used to annotate other artists that are added to directly
+# to the figure. For example:
+
+import matplotlib.patches as mpatches
+import matplotlib.text as mtext
+
+fig, ax = plt.subplots(subplot_kw=dict(visible=False), figsize=(3, 3))
+
+# add a circle and a square
+circle = mpatches.Circle((.25, .75), radius=.15, fc='gold', ec='navy')
+fig.add_artist(circle)
+square = mpatches.Rectangle((.75, .25), height=.25, width=.25, fc='navy', ec='gold')
+fig.add_artist(square)
+
+# position annotation line between both artists
+con = mtext.Annotation("", xy=(.95, .25), xytext=(0, 1),
+                       xycoords=circle, textcoords=square,
+                       arrowprops=dict(arrowstyle="-", lw=3, ls='--', color='navy'))
+fig.add_artist(con)
 
+# Position text relative to annotation
+label = mtext.Annotation("connection", xy=(.5, .5), xytext=(1, 1),
+                         xycoords=con, textcoords=fig.transFigure,
+                         arrowprops=dict(arrowstyle="->", lw=3, ls=':', color='gold'),
+                         size=20, color='navy', va='top', ha='right')
+fig.add_artist(label)
 # %%
 # Placing Artist at anchored Axes locations
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/pyproject.toml b/pyproject.toml
@@ -179,6 +179,7 @@ convention = "numpy"
 "galleries/examples/style_sheets/bmh.py" = ["E501"]
 "galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py" = ["E402"]
 "galleries/examples/text_labels_and_annotations/custom_legends.py" = ["E402"]
+"galleries/examples/text_labels_and_annotations/rainbow_text.py" = ["E402"]
 "galleries/examples/ticks/date_concise_formatter.py" = ["E402"]
 "galleries/examples/ticks/date_formatters_locators.py" = ["F401"]
 "galleries/examples/user_interfaces/embedding_in_gtk3_panzoom_sgskip.py" = ["E402"]
