accent functionality moved into bitmap_label

Author: FoamyGuy

adafruit_display_text/bitmap_label.py

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2020 Kevin Matocha
+# SPDX-FileCopyrightText: 2025 Tim Cocks for Adafruit Industries
 #
 # SPDX-License-Identifier: MIT
 
@@ -27,6 +28,7 @@
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Display_Text.git"
 
 import displayio
+from micropython import const
 
 from adafruit_display_text import LabelBase
 
@@ -43,6 +45,12 @@
 except ImportError:
     pass
 
+# constant indexes for accent_ranges
+ACCENT_START = const(0)
+ACCENT_END = const(1)
+ACCENT_FG = const(2)
+ACCENT_BG = const(3)
+
 
 class Label(LabelBase):
     """A label displaying a string of text that is stored in a bitmap.
@@ -101,13 +109,34 @@ class Label(LabelBase):
         "RTL": (False, False, False),
     }
 
-    def __init__(self, font: FontProtocol, save_text: bool = True, **kwargs) -> None:
+    def __init__(
+        self,
+        font: FontProtocol,
+        save_text: bool = True,
+        color_palette: Optional[displayio.Palette] = None,
+        **kwargs,
+    ) -> None:
         self._bitmap = None
         self._tilegrid = None
         self._prev_label_direction = None
 
         super().__init__(font, **kwargs)
 
+        if color_palette is not None:
+            if len(color_palette) <= 2:
+                raise ValueError(
+                    "color_palette should be at least 3 colors to "
+                    "provide enough for normal and accented text. "
+                    "color_palette argument can be omitted if not "
+                    "using accents."
+                )
+            self._palette = color_palette
+            self.color = self._color
+            self.background_color = self._background_color
+
+        self._accent_ranges = []
+        self._tmp_glyph_bitmap = None
+
         self._save_text = save_text
         self._text = self._replace_tabs(self._text)
 
@@ -381,7 +410,8 @@ def _place_text(
         top = bottom = y_start
         line_spacing = self._line_spacing
 
-        for char in text:
+        for char_idx in range(len(text)):
+            char = text[char_idx]
             if char == "\n":  # newline
                 xposition = x_start  # reset to left column
                 yposition = yposition + self._line_spacing_ypixels(
@@ -390,6 +420,10 @@ def _place_text(
 
             else:
                 my_glyph = font.get_glyph(ord(char))
+                if self._tmp_glyph_bitmap is None and len(self._accent_ranges) > 0:
+                    self._tmp_glyph_bitmap = displayio.Bitmap(
+                        my_glyph.bitmap.width, my_glyph.bitmap.height, len(self._palette)
+                    )
 
                 if my_glyph is None:  # Error checking: no glyph found
                     print(f"Glyph not found: {repr(char)}")
@@ -429,16 +463,37 @@ def _place_text(
                         if self._verbose:
                             print(f'Warning: Glyph clipped, exceeds descent property: "{char}"')
 
+                    accented = False
+                    if len(self._accent_ranges) > 0:
+                        for accent_range in self._accent_ranges:
+                            if accent_range[ACCENT_START] <= char_idx < accent_range[ACCENT_END]:
+                                self._tmp_glyph_bitmap.fill(accent_range[ACCENT_BG])
+
+                                bitmaptools.blit(
+                                    self._tmp_glyph_bitmap,
+                                    my_glyph.bitmap,
+                                    0,
+                                    0,
+                                    skip_source_index=0,
+                                )
+                                bitmaptools.replace_color(
+                                    self._tmp_glyph_bitmap, 1, accent_range[ACCENT_FG]
+                                )
+                                accented = True
+                                break
+
                     self._blit(
                         bitmap,
                         max(xposition + my_glyph.dx, 0),
                         y_blit_target,
-                        my_glyph.bitmap,
+                        my_glyph.bitmap if not accented else self._tmp_glyph_bitmap,
                         x_1=glyph_offset_x,
                         y_1=y_clip,
                         x_2=glyph_offset_x + my_glyph.width,
                         y_2=my_glyph.height,
-                        skip_index=skip_index,  # do not copy over any 0 background pixels
+                        skip_index=skip_index
+                        if not accented
+                        else None,  # do not copy over any 0 background pixels if not accented
                     )
 
                     xposition = xposition + my_glyph.shift_x
@@ -571,3 +626,88 @@ def bitmap(self) -> displayio.Bitmap:
         :rtype: displayio.Bitmap
         """
         return self._bitmap
+
+    def add_accent_range(self, start, end, foreground_color, background_color):
+        """
+        Set a range of text to get accented with the specified colors.
+
+        :param start: The start index of the range of text to accent, inclusive.
+        :param end: The end index of the range of text to accent, exclusive.
+        :param foreground_color: The color index within ``color_palette`` to use for
+          the accent foreground color.
+        :param background_color: The color index within ``color_palette`` to use for
+          the accent background color.
+        :return: None
+        """
+        self._accent_ranges.append((start, end, foreground_color, background_color))
+        self._reset_text(text=str(self._text))
+
+    def remove_accent_range(self, start):
+        """
+        Remove the accent that starts at the specified index within the text.
+
+        :param start: The start index of the range of accented text, inclusive.
+        :return: None
+        """
+        for accent_range in reversed(self._accent_ranges):
+            if accent_range[0] == start:
+                self._accent_ranges.remove(accent_range)
+        self._reset_text(text=str(self._text))
+
+    def add_accent_to_substring(self, substring, foreground_color, background_color, start=0):
+        """
+        Add accent to the first occurrence of ``substring`` found in the labels text,
+        starting from ``start``.
+
+        :param substring: the substring to accent within the text.
+        :param foreground_color: The color index within ``color_palette`` to use for
+          the accent foreground color.
+        :param background_color: The color index within ``color_palette`` to use for
+          the accent background color.
+        :param start: The index within text to start searching for the substring.
+          Defaults is 0 to search the whole text.
+        :return: True if the substring was found, False otherwise.
+        """
+
+        index = self._text.find(substring, start)
+        if index != -1:
+            self.add_accent_range(index, index + len(substring), foreground_color, background_color)
+            return True
+        else:
+            return False
+
+    def remove_accent_from_substring(self, substring, start=0):
+        """
+        Remove the accent for the first instance of the specified ``substring``
+         starting at ``start``.
+
+        :param substring: the substring to accent within the text.
+        :param start: The index within text to start searching for the substring.
+          Defaults is 0 to search the whole text.
+        :return: True if the substring was found, False otherwise.
+        """
+
+        index = self._text.find(substring, start)
+        if index != -1:
+            self.remove_accent_range(index)
+            return True
+        else:
+            return False
+
+    @property
+    def accent_ranges(self):
+        """
+        The list of ranges that are accented.
+        :return: List of Tuples containing (start, end, foreground_color, background_color).
+        """
+        return self._accent_ranges
+
+    def clear_accent_ranges(self):
+        """
+        Remove all accents from the text. All text will return to default
+        foreground and background colors.
+
+        :return: None
+        """
+        self._accent_ranges = []
+        self._reset_text(text=str(self._text))

docs/examples.rst

@@ -133,6 +133,15 @@ Wrap Pixel Test
     :caption: examples/display_text_wrap_pixels_test.py
     :linenos:
 
+Accent Example
+-------------------
+
+Demonstrates the accent feature
+
+.. literalinclude:: ../examples/display_text_accent_example.py
+    :caption: examples/display_text_accent_example.py
+    :linenos:
+
 Library Features Example
 ------------------------
 

examples/display_text_accent_example.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2025 Tim Cocks for Adafruit Industries
+# SPDX-License-Identifier: MIT
+"""
+Demonstrates how to use the AccentLabel to highlight part of the text
+with different foreground and background color.
+"""
+
+import time
+
+import displayio
+import supervisor
+import terminalio
+
+from adafruit_display_text.bitmap_label import Label
+
+display = supervisor.runtime.display
+
+main_group = displayio.Group()
+
+accent_palette = displayio.Palette(6)
+accent_palette[2] = 0x000000
+accent_palette[3] = 0xDDDD00
+accent_palette[4] = 0xFFFFFF
+accent_palette[5] = 0x652F8F
+
+accent_lbl = Label(terminalio.FONT, color_palette=accent_palette, text="", color=0xAAAAAA)
+accent_lbl.anchor_point = (0, 0)
+accent_lbl.anchored_position = (4, 4)
+main_group.append(accent_lbl)
+display.root_group = main_group
+
+text = "CircuitPython is amazing!"
+accent_lbl.text = text
+
+time.sleep(1)
+accent_lbl.add_accent_to_substring("CircuitPython", 4, 5)
+time.sleep(2)
+accent_lbl.remove_accent_from_substring("CircuitPython")
+accent_lbl.add_accent_to_substring("amazing!", 2, 3)
+
+while True:
+    time.sleep(1)