classes.c20_box

  1from typing import Literal, Union
  2from loguru import logger
  3import colorama
  4import drawBot
  5
  6from lib import layout, helpers, color, fonts
  7
  8
  9class KBox:
 10    "A layout primitive with coordinates, dimensions and spatial utilities."
 11
 12    def __init__(self, coords: tuple, text: str | None = None) -> None:
 13        """
 14        Initialize a KBox with given coordinates.
 15
 16        See `lib.layout.parsePageSize` for possible coordinate types.
 17
 18        Args:
 19            coords: A tuple of (x, y, width, height) coordinates.
 20
 21        Example:
 22        ```python
 23        # Create a new box with coordinates
 24        box = KBox((10, 10, 100, 50))  # x, y, width, height
 25
 26        # Move the box
 27        box.move(x=20, y=10)
 28
 29        # Grow the box by adding margin
 30        box.grow((5, 5, 5, 5))  # left, bottom, right, top margins
 31        ```
 32        """
 33        self.x, self.y, self.width, self.height = layout.toCoords(coords)
 34        self.text = text
 35
 36    def __str__(self) -> str:
 37        """Return a string representation of the KBox instance."""
 38        x = f"{colorama.Fore.LIGHTYELLOW_EX}X {self.x}"
 39        y = f"{colorama.Fore.LIGHTBLUE_EX}Y {self.y}"
 40        w = f"{colorama.Fore.LIGHTMAGENTA_EX}W {self.width}"
 41        h = f"{colorama.Fore.LIGHTCYAN_EX}H {self.height}"
 42        t = f"{colorama.Fore.LIGHTWHITE_EX}T {self.text}" if self.text else ""
 43        return f"{colorama.Fore.BLACK}{colorama.Back.LIGHTGREEN_EX}KBox{colorama.Style.RESET_ALL} {x} {y} {w} {h} {t}{colorama.Style.RESET_ALL}"
 44
 45    @staticmethod
 46    def fromDimension(unit: layout.UnitSource) -> "KBox":
 47        """
 48        Create a square KBox with the same width and height.
 49
 50        Implicit unit is `pt` but can be changed by passing a string like `10mm`.
 51        """
 52        value = layout.parseUnit(unit, implicitUnit="pt")
 53        return KBox((0, 0, value, value))
 54
 55    @staticmethod
 56    def fromDimensions(width: layout.UnitSource, height: layout.UnitSource) -> "KBox":
 57        """
 58        Create a KBox from width and height, with x and y set to 0.
 59
 60        Implicit unit is `pt` but can be changed by passing a string like `10mm`.
 61        """
 62        width, height = [
 63            layout.parseUnit(d, implicitUnit="pt") for d in (width, height)
 64        ]
 65        return KBox((0, 0, width, height))
 66
 67    @staticmethod
 68    def fromText(str: str, textWidth: float = None) -> "KBox":
 69        """
 70        Create a KBox that fits the given text. Font settings must be already set.
 71
 72        Args:
 73            str: The text to fit.
 74            textWidth: Optional maximum width for the text box. If provided, the text will wrap to fit within this width.
 75
 76        Returns:
 77            A new KBox instance that fits the text.
 78        """
 79        return KBox((0, 0, *drawBot.textSize(str, width=textWidth)), text=str)
 80
 81    @property
 82    def position(self) -> tuple[int, int]:
 83        """
 84        Returns the x and y coordinates of the bottom-left corner.
 85        """
 86        return self.x, self.y
 87
 88    @position.setter
 89    def position(self, value: tuple[int, int]) -> None:
 90        """
 91        Set the position (x, y) of the box.
 92        """
 93        try:
 94            self.x, self.y = value
 95        except Exception as e:
 96            logger.warning("Unable to set KBox position: {}. Error: {}", value, e)
 97
 98    @property
 99    def dimensions(self) -> tuple[int, int]:
100        """
101        Returns the dimensions (width, height) of the box in points.
102        """
103        return self.width, self.height
104
105    @dimensions.setter
106    def dimensions(self, value: tuple[int, int]) -> None:
107        """
108        Set the dimensions (width, height) of the box in points.
109        """
110        try:
111            self.width, self.height = value
112        except Exception as e:
113            logger.warning("Unable to set KBox dimensions: {}. Error: {}", value, e)
114
115    @property
116    def coords(self) -> tuple[int, int, int, int]:
117        """
118        Returns the complete coordinates (x, y, width, height) of the box.
119        """
120        return self.x, self.y, self.width, self.height
121
122    @coords.setter
123    def coords(self, value: tuple[int, int, int, int]) -> None:
124        """
125        Set the complete coordinates (x, y, width, height) of the box.
126        """
127        try:
128            self.x, self.y, self.width, self.height = value
129        except Exception as e:
130            logger.warning("Unable to set KBox coords: {}. Error: {}", value, e)
131
132    @property
133    def left(self) -> int:
134        """
135        Returns the x-coordinate of the left edge of the box.
136        """
137        return self.x
138
139    @property
140    def right(self) -> int:
141        """
142        Returns the x-coordinate of the right edge of the box.
143        """
144        return self.x + self.width
145
146    @property
147    def top(self) -> int:
148        """
149        Returns the y-coordinate of the top edge of the box.
150        """
151        return self.y + self.height
152
153    @property
154    def bottom(self) -> int:
155        """
156        Returns the y-coordinate of the bottom edge of the box.
157        """
158        return self.y
159
160    @property
161    def middle(self) -> tuple[int, int]:
162        """
163        Returns the (x, y) coordinates of the middle point of the box.
164        """
165        return (self.middleX, self.middleY)
166
167    @property
168    def middleX(self) -> int:
169        """
170        Returns the x-coordinate of the middle of the box.
171        """
172        return self.x + self.width / 2
173
174    @property
175    def middleY(self) -> int:
176        """
177        Returns the y-coordinate of the middle of the box.
178        """
179        return self.y + self.height / 2
180
181    def xray(self, draw: bool = True) -> "KBox":
182        """
183        Visualize the box using `lib.layout.xray` function.
184
185        Args:
186            draw: Whether to draw the box. Defaults to True.
187        """
188        if draw:
189            layout.xray(self.coords)
190        return self
191
192    def draw(self, align: fonts.TextAlign = "left"):
193        """
194        Draw the box's text content using `drawBot.textBox`. Font settings must be already set.
195
196        Args:
197            align: Text alignment within the box. Defaults to "left". Can be "left", "center", or "right".
198
199        Returns:
200            The result of `drawBot.textBox` which is overset text (if any).
201        """
202        if not self.text:
203            raise ValueError(
204                "No text to draw in this KBox. Set the 'text' attribute first."
205            )
206        return drawBot.textBox(self.text, self.coords, align=align)
207
208    def move(
209        self,
210        x: layout.ImplicitUnit = 0,
211        y: layout.ImplicitUnit = 0,
212        implicitUnit: layout.ImplicitUnit = "mm",
213    ) -> "KBox":
214        """
215        Move the box by the specified amounts in x and y directions.
216
217        Args:
218            x: Horizontal offset. Positive values move right, negative values move left.
219            y: Vertical offset. Positive values move up, negative values move down.
220        """
221        self.coords = layout.move(self.coords, x=x, y=y, implicitUnit=implicitUnit)
222        return self
223
224    def grow(
225        self,
226        margin: tuple[layout.UnitSource],
227        implicitUnit: layout.ImplicitUnit = "mm",
228    ) -> "KBox":
229        """
230        Grow the box by adding margins via CSS-style tuple or single value.
231
232        Args:
233            margin: A tuple of (left, bottom, right, top) margins to add.
234        """
235        self.coords = layout.grow(self.coords, margin=margin, implicitUnit=implicitUnit)
236        return self
237
238    def shrink(
239        self,
240        margin: tuple[layout.UnitSource],
241        implicitUnit: layout.ImplicitUnit = "mm",
242    ) -> "KBox":
243        """
244        Shrink the box by adding padding via CSS-style tuple or single value.
245
246        Args:
247            margin: A tuple of (left, bottom, right, top) margins to subtract.
248        """
249        self.coords = layout.shrink(
250            self.coords,
251            margin=margin,
252            implicitUnit=implicitUnit,
253        )
254        return self
255
256    def offsetFrame(
257        self,
258        moveX: layout.UnitSource = 0,
259        moveY: layout.UnitSource = 0,
260        grow: layout.UnitSource = None,
261        shrink: layout.UnitSource = None,
262        implicitUnit: layout.ImplicitUnit = "mm",
263    ) -> layout.Coordinates:
264        """
265        Return a derived frame without mutating this box.
266
267        `grow` and `shrink` are optional, but mutually exclusive.
268
269        Args:
270            moveX: Horizontal offset of the derived frame.
271            moveY: Vertical offset of the derived frame.
272            grow: Margin to grow outward.
273            shrink: Margin to inset inward.
274            implicitUnit: Implicit unit for all numeric values.
275
276        Returns:
277            Offset frame as (x, y, w, h).
278        """
279        if grow is not None and shrink is not None:
280            raise ValueError("offsetFrame() allows only one of 'grow' or 'shrink'.")
281
282        frame = layout.move(self.coords, x=moveX, y=moveY, implicitUnit=implicitUnit)
283
284        if grow is not None:
285            return layout.grow(frame, margin=grow, implicitUnit=implicitUnit)
286
287        if shrink is not None:
288            return layout.shrink(frame, margin=shrink, implicitUnit=implicitUnit)
289
290        return frame
291
292    def duplicate(
293        self,
294        moveX: layout.UnitSource = 0,
295        moveY: layout.UnitSource = 0,
296        grow: layout.UnitSource = None,
297        shrink: layout.UnitSource = None,
298        implicitUnit: layout.ImplicitUnit = "mm",
299    ) -> "KBox":
300        """
301        Create a duplicate of this box with optional offset and size adjustments.
302
303        Args:
304            moveX: Horizontal offset for the duplicate box.
305            moveY: Vertical offset for the duplicate box.
306            grow: Margin to grow the duplicate box outward.
307            shrink: Margin to shrink the duplicate box inward.
308            implicitUnit: Implicit unit for all numeric values.
309
310        Returns:
311            A new KBox instance with the applied transformations.
312        """
313        newCoords = self.offsetFrame(
314            moveX=moveX,
315            moveY=moveY,
316            grow=grow,
317            shrink=shrink,
318            implicitUnit=implicitUnit,
319        )
320        return KBox(newCoords)
321
322    def shrinkWidth(
323        self,
324        amount: layout.UnitSource,
325        origin: Literal["left", "right"] = "left",
326        implicitUnit: layout.ImplicitUnit = "decimal",
327    ) -> "KBox":
328        """
329        Shrink the width of the box by a specified amount.
330
331        Args:
332            amount: The amount to shrink the width by.
333            origin: The side from which to shrink. Defaults to "left".
334        """
335        self.coords = layout.shrinkWidth(
336            self.coords,
337            amount=amount,
338            origin=origin,
339            implicitUnit=implicitUnit,
340        )
341        return self
342
343    def shrinkHeight(
344        self,
345        amount: layout.UnitSource,
346        origin: Literal["top", "bottom"] = "top",
347        implicitUnit: layout.ImplicitUnit = "decimal",
348    ) -> "KBox":
349        """
350        Shrink the height of the box by a specified amount.
351
352        Args:
353            amount: The amount to shrink the height by.
354            origin: The side from which to shrink. Defaults to "top".
355        """
356        self.coords = layout.shrinkHeight(
357            self.coords,
358            amount=amount,
359            origin=origin,
360            implicitUnit=implicitUnit,
361        )
362        return self
363
364    def splitRelative(
365        self,
366        formula: str = "1/1",
367        gap: layout.UnitSource = 5,
368        gapImplicitUnit: layout.ImplicitUnit = "mm",
369        create: layout.LayoutFlow = "columns",
370    ) -> list["KBox"]:
371        """Split into child boxes by specified ratio. See `layout.splitRelative`."""
372        return map(
373            KBox,
374            layout.splitRelative(self.coords, formula, gap, gapImplicitUnit, create),
375        )
376
377    def splitAbsolute(
378        self,
379        create: layout.LayoutFlow,
380        origin: layout.LayoutOrigin,
381        size: layout.UnitSource,
382        gap: layout.UnitSource,
383        implicitUnit: layout.ImplicitUnit = "mm",
384    ) -> list["KBox"]:
385        """Split into child boxes by absolute size. See `layout.splitAbsolute`."""
386        return map(
387            KBox,
388            layout.splitAbsolute(self.coords, create, origin, size, gap, implicitUnit),
389        )
390
391    def partition(
392        self,
393        create: layout.LayoutFlow,
394        origin: layout.LayoutOrigin,
395        size: layout.UnitSource,
396        gap: layout.UnitSource,
397        implicitUnit: layout.ImplicitUnit = "pt",
398        mutate: bool = True,
399    ) -> "KBox":
400        """Partition the box by carving out a new box of specified size from a specified edge.
401
402        Args:
403            create: Whether to split into "rows" or "columns".
404            origin: Logical edge from which to partition: "start" (top/left) or "end" (bottom/right).
405            size: The size of the new box to carve out.
406            gap: The gap between the new box and the remaining box.
407            implicitUnit: The implicit unit for size and gap values.
408            mutate: If True, modify this box in place. If False, keep this box unchanged.
409
410        Returns:
411            The new KBox that was carved out.
412        """
413        # ! Handle percentage-based size by converting to absolute value based on box dimensions
414        if layout.isInPercent(size):
415            size = layout.parseUnit(
416                size, base=self.height if create == "rows" else self.width
417            )
418
419        new_rect, remainder_rect = layout.splitAbsolute(
420            self.coords, create, origin, size, gap, implicitUnit
421        )
422        if mutate:
423            self.coords = remainder_rect
424        return KBox(new_rect)
425
426    def addHeader(
427        self, gap: layout.UnitSource = "5mm", lines: int = 1, mutate: bool = True
428    ) -> "KBox":
429        """
430        Add a header box and optionally modify this box in place (shorthand for partition).
431
432        Args:
433            gap: Space between header and body.
434            lines: Number of lines in the header. Font properties must be set beforehand.
435            mutate: If True, modify this box in place. If False, keep this box unchanged.
436
437        Returns:
438            The header KBox.
439        """
440        return self.partition(
441            "rows", "start", layout.inferBlockHeight(lines), gap=gap, mutate=mutate
442        )
443
444    def addFooter(
445        self, gap: layout.UnitSource = "5mm", lines: int = 1, mutate: bool = True
446    ) -> "KBox":
447        """
448        Add a footer box and optionally modify this box in place (shorthand for partition).
449
450        Args:
451            gap: Space between footer and body.
452            lines: Number of lines in the footer. Font properties must be set beforehand.
453            mutate: If True, modify this box in place. If False, keep this box unchanged.
454
455        Returns:
456            The footer KBox.
457        """
458        return self.partition(
459            "rows", "end", layout.inferBlockHeight(lines), gap=gap, mutate=mutate
460        )
461
462    def makeGrid(
463        self,
464        rows: int = 1,
465        cols: int = 1,
466        gutter: layout.UnitSource = "5mm",
467        debug: bool = False,
468    ) -> list["KBox"]:
469        """Split into a grid of specified `KBox` rows and columns with gutter. See `layout.makeGrid`."""
470        return list(map(KBox, layout.makeGrid(self.coords, rows, cols, gutter, debug)))
471
472    def probeGridItem(
473        self, rows: int = 1, cols: int = 1, gutter: layout.UnitSource = "5mm"
474    ) -> "KBox":
475        """Calculate the dimensions of a grid item without positioning. Useful for layout calculations."""
476        return KBox(layout.inferGridItemDimensions(self.dimensions, rows, cols, gutter))
477
478    def alignInside(
479        self,
480        container: Union["KBox", tuple],
481        position: tuple[layout.AlignX, layout.AlignY] = ("center", "center"),
482        clip: bool = True,
483        nudgeY: float = 1.0,
484    ) -> "KBox":
485        """
486        Align this box inside a container box.
487
488        Args:
489            container: The container `KBox` or `tuple` of coordinates.
490            position: The alignment position (x, y). Defaults to ("center", "center").
491            clip: If True, shrink this box to fit inside container bounds.
492                If False, keep dimensions and allow overflow.
493            nudgeY: Optical vertical nudge strength. `0` disables nudge,
494                `1` applies default compensation, and larger values increase it.
495        """
496        self.coords = layout.align(
497            container.coords if isinstance(container, KBox) else container,
498            self.coords,
499            position=position,
500            clip=clip,
501            nudgeY=nudgeY,
502        )
503        return self
504
505    def justifyInside(
506        self,
507        container: Union["KBox", tuple],
508        count: int,
509        create: layout.LayoutFlow,
510        crossAlign: layout.AlignX | layout.AlignY | None = None,
511    ) -> list["KBox"]:
512        """
513        Distribute multiple boxes evenly inside a container box.
514
515        Args:
516            container: The container `KBox` or `tuple` of coordinates.
517            count: The number of boxes to distribute.
518            create: Whether to distribute in "rows" or "columns".
519            crossAlign: Optional alignment for the non-justified axis ('left', 'center', 'right', 'stretch' for columns; 'top', 'center', 'bottom', 'stretch' for rows). 'stretch' expands each child to fill the full cross-axis extent of the parent.
520        Returns:
521            A list of new `KBox` instances that are distributed inside the container.
522        """
523        return list(
524            map(
525                KBox,
526                layout.justify(
527                    container.coords if isinstance(container, KBox) else container,
528                    self.coords,
529                    count,
530                    create,
531                    crossAlign,
532                ),
533            )
534        )
535
536    def snapHorizontally(self, x: int, snapTo: layout.AlignX = "center") -> "KBox":
537        if snapTo == "left":
538            self.x = x
539        elif snapTo == "center":
540            self.x = x - self.width / 2
541        elif snapTo == "right":
542            self.x = x - self.width
543        else:
544            logger.warning("Invalid horizontal snap position: {}", snapTo)
545        return self
546
547    def snapVertically(self, y: int, snapTo: layout.AlignY = "center") -> "KBox":
548        if snapTo == "bottom":
549            self.y = y - self.height
550        elif snapTo == "center":
551            self.y = y - self.height / 2
552        elif snapTo == "top":
553            self.y = y
554        else:
555            logger.warning("Invalid vertical snap position: {}", snapTo)
556        return self
557
558    def addCropMarks(
559        self,
560        edges: list[layout.BoxEdge] = ["top", "right", "bottom", "left"],
561        length: float = 1.5,
562        offset: float = 0.5,
563    ) -> "KBox":
564        """
565        Add crop marks to the box.
566
567        Args:
568            edges: The edges to add crop marks to. Defaults to all four edges.
569            length: The length of crop marks in mm. Defaults to 1.5.
570            offset: The offset of crop marks in mm. Defaults to 0.5.
571        """
572        length, offset = layout.mm(length), layout.mm(offset)
573
574        def _setLineAttrs():
575            drawBot.fill(None)
576            drawBot.cmykStroke(*color.CMYK(k=100).asCMYKA)
577            drawBot.strokeWidth(0.5)
578
579        def _drawVertical(x: int):
580            drawBot.line((x, self.bottom - offset - length), (x, self.bottom - offset))
581            drawBot.line((x, self.top + offset), (x, self.top + offset + length))
582
583        def _drawHorizontal(y: int):
584            drawBot.line((self.left - offset - length, y), (self.left - offset, y))
585            drawBot.line((self.right + offset, y), (self.right + offset + length, y))
586
587        with drawBot.savedState():
588            _setLineAttrs()
589
590            for edge in helpers.coerceList(edges):
591                func = _drawHorizontal if edge in ["top", "bottom"] else _drawVertical
592                coordinate: int = self.__getattribute__(edge)  # self.top => 123
593                func(coordinate)
594
595        return self