classes.c40_text_composer

  1from typing import Literal
  2import drawBot
  3from drawBot import _drawBotDrawingTool as drawBot
  4import copy
  5
  6from lib import content, fonts
  7from .c20_box import KBox
  8from .c32_pool import KPool
  9from datatypes import DFontProps
 10
 11
 12class KTextComposer:
 13    """Composes and manages formatted text within a given frame."""
 14
 15    def __init__(
 16        self,
 17        frame: KBox,
 18        fontProps: DFontProps,
 19        pool: KPool,
 20        formattedArgs: dict = None,
 21    ):
 22        """
 23        Initializes the text composer with a frame, font properties, and a word pool.
 24
 25        Args:
 26            frame: The frame within which the text will be composed.
 27            fontProps: The font properties to be applied to the text.
 28            pool: The word pool to be used for text composition.
 29            formattedArgs: Additional arguments for formatting the text.
 30        """
 31        self.frame = frame
 32        self.fontProps = fontProps.apply()
 33        self.formattedArgs = formattedArgs if formattedArgs else dict()
 34        self.fString = drawBot.FormattedString(
 35            **self.fontProps.calc(), **self.formattedArgs
 36        )
 37        self.pool = pool
 38
 39    def setPool(self, pool: KPool):
 40        """
 41        Sets the word pool for the composer.
 42        """
 43        self.pool = pool
 44        return self
 45
 46    def setOpenTypeFeatures(self, **features: dict[fonts.FontFeature, bool]):
 47        """
 48        Sets OpenType features for the formatted string.
 49        """
 50        drawBot.openTypeFeatures(**features)
 51        self.fString.openTypeFeatures(**features)
 52        return self
 53
 54    def addWord(
 55        self,
 56        width: float,
 57        shape: str = None,
 58        tokens: list[content.CharacterToken] = None,
 59    ):
 60        """
 61        Adds a word from the pool that fits the specified width and optional filters.
 62        """
 63        if not self.pool:
 64            raise AttributeError("No pool set. Use setPool() to set a pool.")
 65
 66        linePool = copy.copy(self.pool)  # ? Create a pool for this line
 67
 68        if shape:
 69            linePool = linePool.filterWithRegex(shape)
 70
 71        if tokens:
 72            linePool = linePool.filterTokens(tokens)
 73
 74        word = linePool.getItemByWidth(self.frame.width * width)
 75        # Skip removing from the main pool: Commit June 14, 2025
 76        self._append(word)
 77        return self
 78
 79    def addString(self, string: str):
 80        """
 81        Appends a string to the formatted text.
 82        """
 83        self._append(string)
 84        return self
 85
 86    def _append(self, string: str):
 87        """
 88        Appends a string to the formatted text.
 89        """
 90        # ? Reapply formatted args: spacing needs to be explicit in case it changed
 91        self.fString.append(string, **self.fontProps.calc(), **self.formattedArgs)
 92
 93    def breakLine(self):
 94        """
 95        Inserts a line break in the formatted text.
 96        """
 97        self.fString.append("\n")
 98        return self
 99
100    def setTab(self, width: float, alignment: Literal["left", "center", "right"]):
101        """
102        Sets a tab stop at the given width and alignment, then inserts a tab.
103        """
104        self.fString.tabs((self.frame.width * width, alignment))
105        self.fString.append("\t")
106        return self
107
108    def fitForString(self, string: str):
109        """
110        Adjusts font size to fit the string on a single line within the frame. Updates `fontProps` as a side effect.
111        """
112        fs, *_ = fonts.fitBinary(
113            string,
114            self.frame.coords,
115            leading=self.fontProps.leading,
116            letterSpacing=self.fontProps.letterSpacing,
117            precision=1,
118        )
119        self.fontProps.updateFontSize(fs).apply()
120        return self
121
122    def draw(self):
123        """
124        Draws the composed text into the frame.
125        """
126        drawBot.textBox(self.fString, self.frame.coords)