datatypes.data_fontprops

  1from typing import List, Literal
  2from drawBot import _drawBotDrawingTool as drawBot
  3from dataclasses import dataclass, asdict
  4from functools import cached_property
  5
  6from lib import helpers, fonts
  7from classes import KFont
  8
  9# TODO: Add RGB/CMYK fill property
 10
 11
 12# NamedTuple doesn’t allow custom init or internal properties
 13# Dataclass to allow cached_property
 14@dataclass
 15class DFontProps:
 16    """Data structure for font properties used in DrawBot."""
 17
 18    fontSize: int = 24
 19    """The font size in points."""
 20
 21    leading: float = 1.25
 22    """The leading (line spacing) multiplier."""
 23
 24    letterSpacing: int = 0
 25    """Relative letter spacing unit, behaves similar to Adobe."""
 26
 27    fontData: KFont | list[KFont] = None
 28    """The font data or list of font data."""
 29
 30    align: str = None
 31    """Text alignment option."""
 32
 33    openType: fonts.FontFeature | list[fonts.FontFeature] = None
 34    """OpenType font features."""
 35
 36    @property
 37    def lineHeight(self):
 38        """The calculated line height.
 39
 40        Returns:
 41            The product of fontSize and leading, or None if fontSize undefined.
 42        """
 43        try:
 44            return self.fontSize * self.leading
 45        except Exception:
 46            return
 47
 48    @cached_property
 49    def blockHeight(self) -> float:
 50        """The height of one line of text."""
 51        with drawBot.savedState():
 52            self.apply()
 53            _, h = drawBot.textSize("H")
 54        return h
 55
 56    @property
 57    def tracking(self):
 58        """The absolute tracking value, scales with fontSize.
 59
 60        Returns:
 61            The calculated tracking value, or None if calculation fails.
 62        """
 63        try:
 64            return self.letterSpacing * (self.fontSize / 1000)
 65        except Exception:
 66            return
 67
 68    @property
 69    def fontPath(self):
 70        """The file path of the font.
 71
 72        Returns:
 73            The path to the font file, or the fontData if path is unavailable.
 74        """
 75        try:
 76            return self.fontData.path
 77        except Exception:
 78            return self.fontData
 79
 80    @property
 81    def isSingleFont(self) -> bool:
 82        """Whether fontData is a single font.
 83
 84        Returns:
 85            True if fontData is a string or KFont instance, False otherwise.
 86        """
 87        return isinstance(self.fontData, (str, KFont))
 88
 89    @property
 90    def openTypeFeatures(self):
 91        """OpenType features as a dictionary.
 92
 93        Returns:
 94            Dictionary of OpenType features set to True, or None if unavailable.
 95        """
 96        try:
 97            return {key: True for key in helpers.coerceList(self.openType)}
 98        except Exception:
 99            pass
100
101    def getArgs(self, clean=False, pick: list[str] = None) -> dict:
102        """
103        Get properties as a dictionary.
104
105        Args:
106            clean: If True, remove falsy properties.
107            pick: List of property keys to include.
108
109        Returns:
110            Dictionary of font properties.
111        """
112        asDict = asdict(self)
113        asDict["lineHeight"] = self.lineHeight
114        asDict["tracking"] = self.tracking
115        asDict["openTypeFeatures"] = self.openTypeFeatures
116
117        if self.align:
118            asDict["align"] = self.align
119
120        if self.isSingleFont:
121            asDict["font"] = self.fontPath
122
123        if pick:
124            asDict = helpers.pick(asDict, pick)
125
126        if clean:
127            return helpers.omitBy(asDict)
128        else:
129            return asDict
130
131    def calc(self, clean=True) -> dict:
132        """
133        Calculate keyword arguments for FormattedString().
134
135        Args:
136            clean: If True, remove falsy properties.
137
138        Returns:
139            Dictionary of keyword arguments for FormattedString().
140        """
141
142        return self.getArgs(
143            clean=clean,
144            pick=[
145                "font",
146                "fontSize",
147                "lineHeight",
148                "tracking",
149                "align",
150                "openTypeFeatures",
151            ],
152        )
153
154    def activateFont(self):
155        """
156        Set the font for DrawBot.
157
158        Returns:
159            The current instance.
160        """
161        if self.isSingleFont:
162            drawBot.font(self.fontPath)
163        return self
164
165    def apply(self):
166        """
167        Set DrawBot properties for the current font settings.
168
169        Returns:
170            The current instance.
171        """
172        drawBot.fontSize(self.fontSize)
173        drawBot.lineHeight(self.lineHeight)
174        drawBot.tracking(self.tracking)
175
176        self.activateFont()
177
178        if self.openTypeFeatures:
179            drawBot.openTypeFeatures(**self.openTypeFeatures)
180        else:
181            drawBot.openTypeFeatures(resetFeatures=True)
182
183        return self
184
185    def describe(self, format: Literal["string", "list"] = "string"):
186        """
187        Return human-friendly font properties.
188
189        Args:
190            format: Return as 'str' or 'list[str]'.
191
192        Returns:
193            Human-readable font properties.
194        """
195
196        props: List[float | int] = [self.fontSize]
197        lh, t = self.lineHeight, self.letterSpacing
198
199        if lh and lh != self.fontSize:
200            props.append(lh)
201        if t:
202            props.append(t)
203
204        rounded = [str(round(p)) for p in props]
205        return rounded if format == "list" else " ".join(rounded)
206
207    def updateFont(self, value: KFont) -> "DFontProps":
208        """
209        Update font and return self.
210
211        Args:
212            value: The new font.
213
214        Example:
215            `props.updateFont(newFont)`
216        """
217        self.fontData = value
218        return self
219
220    def updateFontSize(self, value: int) -> "DFontProps":
221        """
222        Update fontSize and return self.
223
224        Args:
225            value: The new font size.
226
227        Example:
228            `props.updateFontSize(12)`
229        """
230        self.fontSize = value
231        return self