datatypes.data_fontprops

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