Add language parameter to Text objects

QuLogic · QuLogic · commit b3cfa4d160fd · 2025-03-22T05:35:27.000-04:00
diff --git a/lib/matplotlib/_text_helpers.py b/lib/matplotlib/_text_helpers.py
@@ -43,7 +43,7 @@ def warn_on_missing_glyph(codepoint, fontnames):
             f"Matplotlib currently does not support {block} natively.")
 
 
-def layout(string, font, *, kern_mode=Kerning.DEFAULT):
+def layout(string, font, language, *, kern_mode=Kerning.DEFAULT):
     """
     Render *string* with *font*.
 
@@ -65,7 +65,7 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
     """
     x = 0
     prev_glyph_idx = None
-    char_to_font = font._get_fontmap(string)
+    char_to_font = font._get_fontmap(string)  # TODO: Pass in language.
     base_font = font
     for char in string:
         # This has done the fallback logic
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -494,7 +494,8 @@ def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
         """
         self._draw_text_as_path(gc, x, y, s, prop, angle, ismath="TeX")
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         """
         Draw a text instance.
 
@@ -516,6 +517,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             If True, use mathtext parser.
         mtext : `~matplotlib.text.Text`
             The original text object to be rendered.
+        language : str or list[tuple[str, int, int]]
+            The language of the text.
 
         Notes
         -----
diff --git a/lib/matplotlib/backend_bases.pyi b/lib/matplotlib/backend_bases.pyi
@@ -116,6 +116,7 @@ class RendererBase:
         angle: float,
         ismath: bool | Literal["TeX"] = ...,
         mtext: Text | None = ...,
+        language: str | list[tuple[str, int, int]] | None = ...,
     ) -> None: ...
     def get_text_width_height_descent(
         self, s: str, prop: FontProperties, ismath: bool | Literal["TeX"]
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -182,14 +182,15 @@ def draw_mathtext(self, gc, x, y, s, prop, angle):
         y = round(y - oy + yd)
         self._renderer.draw_text_image(font_image, x, y + 1, angle, gc)
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         # docstring inherited
         if ismath:
             return self.draw_mathtext(gc, x, y, s, prop, angle)
         font = self._prepare_font(prop)
         # We pass '0' for angle here, since it will be rotated (in raster
         # space) in the following call to draw_text_image).
-        font.set_text(s, 0, flags=get_hinting_flag())
+        font.set_text(s, 0, flags=get_hinting_flag(), language=language)
         font.draw_glyphs_to_bitmap(
             antialiased=gc.get_antialiased())
         d = font.get_descent() / 64.0
@@ -203,7 +204,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
         y = round(y + yo + yd)
         self._renderer.draw_text_image(font, x, y + 1, angle, gc)
 
-    def get_text_width_height_descent(self, s, prop, ismath):
+    def get_text_width_height_descent(self, s, prop, ismath, language=None):
         # docstring inherited
 
         _api.check_in_list(["TeX", True, False], ismath=ismath)
@@ -216,7 +217,7 @@ def get_text_width_height_descent(self, s, prop, ismath):
             return width, height, descent
 
         font = self._prepare_font(prop)
-        font.set_text(s, 0.0, flags=get_hinting_flag())
+        font.set_text(s, 0.0, flags=get_hinting_flag(), language=language)
         w, h = font.get_width_height()  # width and height of unrotated string
         d = font.get_descent()
         w /= 64.0  # convert from subpixels
diff --git a/lib/matplotlib/backends/backend_cairo.py b/lib/matplotlib/backends/backend_cairo.py
@@ -214,7 +214,8 @@ def draw_image(self, gc, x, y, im):
         ctx.paint()
         ctx.restore()
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):  # TODO: Apply language tag, if possible.
         # docstring inherited
 
         # Note: (x, y) are device/display coords, not user-coords, unlike other
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -2327,7 +2327,8 @@ def encode_string(self, s, fonttype):
             return s.encode('cp1252', 'replace')
         return s.encode('utf-16be', 'replace')
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         # docstring inherited
 
         # TODO: combine consecutive texts into one BT/ET delimited section
@@ -2347,7 +2348,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             fonttype = mpl.rcParams['pdf.fonttype']
 
         if gc.get_url() is not None:
-            font.set_text(s)
+            font.set_text(s, language=language)
             width, height = font.get_width_height()
             self.file._annotations[-1][1].append(_get_link_annotation(
                 gc, x, y, width / 64, height / 64, angle))
@@ -2381,7 +2382,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             multibyte_glyphs = []
             prev_was_multibyte = True
             prev_font = font
-            for item in _text_helpers.layout(s, font, kern_mode=Kerning.UNFITTED):
+            for item in _text_helpers.layout(s, font, language,
+                                             kern_mode=Kerning.UNFITTED):
                 if _font_supports_glyph(fonttype, ord(item.char)):
                     if prev_was_multibyte or item.ft_object != prev_font:
                         singlebyte_chunks.append((item.ft_object, item.x, []))
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -673,7 +673,8 @@ def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
         # docstring inherited
         self.draw_text(gc, x, y, s, prop, angle, ismath="TeX", mtext=mtext)
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):  # TODO: Implement language if possible.
         # docstring inherited
 
         # prepare string for tex
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -758,7 +758,8 @@ def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
         self.textcnt += 1
 
     @_log_if_debug_on
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         # docstring inherited
 
         if self._is_transparent(gc.get_rgb()):
@@ -795,7 +796,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
         else:
             font = self._get_font_ttf(prop)
             self._character_tracker.track(font, s)
-            for item in _text_helpers.layout(s, font):
+            for item in _text_helpers.layout(s, font, language):
                 ps_name = (item.ft_object.postscript_name
                            .encode("ascii", "replace").decode("ascii"))
                 glyph_name = item.ft_object.get_glyph_name(item.glyph_idx)
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -1035,7 +1035,8 @@ def _update_glyph_map_defs(self, glyph_map_new):
     def _adjust_char_id(self, char_id):
         return char_id.replace("%20", "_")
 
-    def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath, mtext=None):
+    def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath, mtext=None,
+                           language=None):
         # docstring inherited
         writer = self.writer
 
@@ -1106,7 +1107,8 @@ def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath, mtext=None):
 
         writer.end('g')
 
-    def _draw_text_as_text(self, gc, x, y, s, prop, angle, ismath, mtext=None):
+    def _draw_text_as_text(self, gc, x, y, s, prop, angle, ismath, mtext=None,
+                           language=None):
         # NOTE: If you change the font styling CSS, then be sure the check for
         # svg.fonttype = none in `lib/matplotlib/testing/compare.py::convert` remains in
         # sync. Also be sure to re-generate any SVG using this mode, or else such tests
@@ -1263,7 +1265,8 @@ def _get_all_quoted_names(prop):
 
             writer.end('g')
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         # docstring inherited
 
         clip_attrs = self._get_clip_attrs(gc)
@@ -1276,9 +1279,9 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             self.writer.start('a', {'xlink:href': gc.get_url()})
 
         if mpl.rcParams['svg.fonttype'] == 'path':
-            self._draw_text_as_path(gc, x, y, s, prop, angle, ismath, mtext)
+            self._draw_text_as_path(gc, x, y, s, prop, angle, ismath, mtext, language)
         else:
-            self._draw_text_as_text(gc, x, y, s, prop, angle, ismath, mtext)
+            self._draw_text_as_text(gc, x, y, s, prop, angle, ismath, mtext, language)
 
         if gc.get_url() is not None:
             self.writer.end('a')
diff --git a/lib/matplotlib/backends/backend_template.py b/lib/matplotlib/backends/backend_template.py
@@ -79,7 +79,8 @@ def draw_path(self, gc, path, transform, rgbFace=None):
     def draw_image(self, gc, x, y, im):
         pass
 
-    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None,
+                  language=None):
         pass
 
     def flipy(self):
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -3,9 +3,11 @@
 """
 
 import functools
+import inspect
 import logging
 import math
 from numbers import Real
+import warnings
 import weakref
 
 import numpy as np
@@ -136,6 +138,7 @@ def __init__(self,
         super().__init__()
         self._x, self._y = x, y
         self._text = ''
+        self._language = None
         self._reset_visual_defaults(
             text=text,
             color=color,
@@ -791,6 +794,7 @@ def draw(self, renderer):
 
             angle = self.get_rotation()
 
+            lang = self._language  # TODO: Split this by line.
             for line, wh, x, y in info:
 
                 mtext = self if len(info) == 1 else None
@@ -812,9 +816,19 @@ def draw(self, renderer):
                                           self._fontproperties, angle,
                                           mtext=mtext)
                 else:
-                    textrenderer.draw_text(gc, x, y, clean_line,
-                                           self._fontproperties, angle,
-                                           ismath=ismath, mtext=mtext)
+                    params = inspect.signature(textrenderer.draw_text).parameters
+                    if 'language' in params:
+                        textrenderer.draw_text(gc, x, y, clean_line,
+                                               self._fontproperties, angle,
+                                               ismath=ismath, mtext=mtext,
+                                               language=lang)
+                    else:
+                        warnings.warn(
+                            f'{textrenderer.__class__.__name__} missing language '
+                            f'parameter to draw_text method')
+                        textrenderer.draw_text(gc, x, y, clean_line,
+                                               self._fontproperties, angle,
+                                               ismath=ismath, mtext=mtext)
 
         gc.restore()
         renderer.close_group('text')
@@ -1410,6 +1424,36 @@ def _va_for_angle(self, angle):
             return 'baseline' if anchor_at_left else 'top'
         return 'top' if anchor_at_left else 'baseline'
 
+    def get_language(self):
+        """Return the language this Text is in."""
+        return self._language
+
+    def set_language(self, language):
+        """
+        Set the language of the text.
+
+        Parameters
+        ----------
+        language : str or list[tuple[str, int, int]]
+
+        """
+        _api.check_isinstance((list, str, None), language=language)
+        if isinstance(language, list):
+            for val in language:
+                if not isinstance(val, tuple) or len(val) != 3:
+                    raise ValueError('language must be list of tuple, not {language!r}')
+                sublang, start, end = val
+                if not isinstance(sublang, str):
+                    raise ValueError(
+                        'sub-language specifcation must be str, not {sublang!r}')
+                if not isinstance(start, int):
+                    raise ValueError('start location must be int, not {start!r}')
+                if not isinstance(end, int):
+                    raise ValueError('end location must be int, not {end!r}')
+
+        self._language = language
+        self.stale = True
+
 
 class OffsetFrom:
     """Callable helper class for working with `Annotation`."""
diff --git a/lib/matplotlib/text.pyi b/lib/matplotlib/text.pyi
@@ -108,6 +108,8 @@ class Text(Artist):
     def set_antialiased(self, antialiased: bool) -> None: ...
     def _ha_for_angle(self, angle: Any) -> Literal['center', 'right', 'left'] | None: ...
     def _va_for_angle(self, angle: Any) -> Literal['center', 'top', 'baseline'] | None: ...
+    def get_language(self) -> str | list[tuple[str, int, int]] | None: ...
+    def set_language(self, language: str | list[tuple[str, int, int]] | None) -> None: ...
 
 class OffsetFrom:
     def __init__(
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -45,7 +45,7 @@ def _get_char_id(self, font, ccode):
         """
         return urllib.parse.quote(f"{font.postscript_name}-{ccode:x}")
 
-    def get_text_width_height_descent(self, s, prop, ismath):
+    def get_text_width_height_descent(self, s, prop, ismath, language=None):
         fontsize = prop.get_size_in_points()
 
         if ismath == "TeX":
@@ -61,15 +61,15 @@ def get_text_width_height_descent(self, s, prop, ismath):
             return width * scale, height * scale, descent * scale
 
         font = self._get_font(prop)
-        font.set_text(s, 0.0, flags=LoadFlags.NO_HINTING)
+        font.set_text(s, 0.0, flags=LoadFlags.NO_HINTING, language=language)
         w, h = font.get_width_height()
         w /= 64.0  # convert from subpixels
         h /= 64.0
         d = font.get_descent()
         d /= 64.0
         return w * scale, h * scale, d * scale
 
-    def get_text_path(self, prop, s, ismath=False):
+    def get_text_path(self, prop, s, ismath=False, language=None):
         """
         Convert text *s* to path (a tuple of vertices and codes for
         matplotlib.path.Path).
@@ -109,7 +109,8 @@ def get_text_path(self, prop, s, ismath=False):
             glyph_info, glyph_map, rects = self.get_glyphs_tex(prop, s)
         elif not ismath:
             font = self._get_font(prop)
-            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s)
+            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s,
+                                                                     language=language)
         else:
             glyph_info, glyph_map, rects = self.get_glyphs_mathtext(prop, s)
 
@@ -130,7 +131,7 @@ def get_text_path(self, prop, s, ismath=False):
         return verts, codes
 
     def get_glyphs_with_font(self, font, s, glyph_map=None,
-                             return_new_glyphs_only=False):
+                             return_new_glyphs_only=False, language=None):
         """
         Convert string *s* to vertices and codes using the provided ttf font.
         """
@@ -145,7 +146,7 @@ def get_glyphs_with_font(self, font, s, glyph_map=None,
 
         xpositions = []
         glyph_ids = []
-        for item in _text_helpers.layout(s, font):
+        for item in _text_helpers.layout(s, font, language):
             char_id = self._get_char_id(item.ft_object, ord(item.char))
             glyph_ids.append(char_id)
             xpositions.append(item.x)
diff --git a/src/ft2font.cpp b/src/ft2font.cpp
@@ -399,7 +399,8 @@ void FT2Font::set_kerning_factor(int factor)
 }
 
 void FT2Font::set_text(
-    std::u32string_view text, double angle, FT_Int32 flags, std::vector<double> &xys)
+    std::u32string_view text, double angle, FT_Int32 flags, LanguageType languages,
+    std::vector<double> &xys)
 {
     FT_Matrix matrix; /* transformation matrix */
 
diff --git a/src/ft2font.h b/src/ft2font.h
@@ -6,6 +6,7 @@
 #ifndef MPL_FT2FONT_H
 #define MPL_FT2FONT_H
 
+#include <optional>
 #include <set>
 #include <string>
 #include <string_view>
@@ -70,6 +71,9 @@ class FT2Font
     typedef void (*WarnFunc)(FT_ULong charcode, std::set<FT_String*> family_names);
 
   public:
+    using LanguageRange = std::tuple<std::string, int, int>;
+    using LanguageType = std::optional<std::vector<LanguageRange>>;
+
     FT2Font(FT_Open_Args &open_args, long hinting_factor,
             std::vector<FT2Font *> &fallback_list, WarnFunc warn);
     virtual ~FT2Font();
@@ -78,7 +82,7 @@ class FT2Font
     void set_charmap(int i);
     void select_charmap(unsigned long i);
     void set_text(std::u32string_view codepoints, double angle, FT_Int32 flags,
-                  std::vector<double> &xys);
+                  LanguageType languages, std::vector<double> &xys);
     int get_kerning(FT_UInt left, FT_UInt right, FT_Kerning_Mode mode, bool fallback);
     int get_kerning(FT_UInt left, FT_UInt right, FT_Kerning_Mode mode, FT_Vector &delta);
     void set_kerning_factor(int factor);
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
