classes.c21_page

  1import drawBot
  2
  3from lib import layout, color, DEFAULT_FONT
  4from classes import KBox
  5
  6
  7class KPage(KBox):
  8    bgColor: color.RawRGB = None
  9
 10    def __init__(
 11        self,
 12        size: layout.PageSize = "A5",
 13        margin: tuple = 5,
 14        aside: int = 0,
 15        spread: bool = False,
 16        render: bool = True,
 17    ):
 18        """
 19        Extends `classes.c20_box.KBox` to form a page object.
 20
 21        Args:
 22            size: Page size. See `lib.layout.PageSize`.
 23            margin: Margin (implicitly in millimeters).
 24            aside: Width of pagination column (implicitly in millimeters).
 25            spread: Divide at spine for 2-page PDF view.
 26            render: Draw immediately. Otherwise, call `render()` manually.
 27        """
 28        super().__init__(size)
 29
 30        if render:
 31            self.render()
 32
 33        self.aside: int = aside
 34        """Width of aside/pagination column."""
 35        self.margin: tuple[int] = layout.mirror(margin) if spread else margin
 36        """Margin for the page (mirrored for left side)."""
 37        self._isSpread: bool = spread
 38        """Used to draw a spine for 2-page PDF view."""
 39
 40        self._divide()
 41        self._draftBoxes()
 42
 43    @staticmethod
 44    def fromMillimeters(dimensions: tuple[int, int], **kwargs) -> "KPage":
 45        """
 46        Alternate constructor to create a KPage from dimensions in millimeters.
 47
 48        Args:
 49            dimensions: Tuple of (width, height) in mm.
 50            **kwargs: Additional arguments for the main constructor.
 51        """
 52        return KPage(tuple(layout.mm(d) for d in dimensions), **kwargs)
 53
 54    def _draftBoxes(self) -> None:
 55        """Set up the frame and body `classes.c20_box.KBox` objects."""
 56        self.frame = KBox(layout.shrink(frame=self.coords, margin=self.margin))
 57        self.body = KBox(
 58            layout.shrinkWidth(
 59                frame=self.frame.coords,
 60                amount=self.aside,
 61                origin="right" if self.isRightSide else "left",
 62                implicitUnit="mm",
 63            )
 64        )
 65
 66    @property
 67    def isLeftSide(self) -> bool:
 68        """True if the page is on the left side."""
 69        return layout.pageIsEven()
 70
 71    @property
 72    def isRightSide(self) -> bool:
 73        """True if the page is on the right side."""
 74        return not self.isLeftSide
 75
 76    @property
 77    def size(self) -> tuple[int, int]:
 78        """Page size in millimeters."""
 79        return tuple(layout.pt(d) for d in self.dimensions)
 80
 81    @property
 82    def pageNumber(self) -> int:
 83        """The current page number."""
 84        return drawBot.pageCount()
 85
 86    def fillBackground(self, color: color.RawRGB) -> None:
 87        """
 88        Fill the background of the page with a color.
 89
 90        Args:
 91            color: RGB color to fill with.
 92
 93        Example:
 94        ```
 95        page.fillBackground((0.5, 0.5, 0.5))
 96        ```
 97        """
 98        self.bgColor = color
 99
100        with drawBot.savedState():
101            drawBot.fill(*color)
102            drawBot.rect(*self.coords)
103
104        self._divide()
105
106    def paginate(self) -> None:
107        """Draw the page number with contextual alignment. Padded to 2 digits."""
108        folio = str(self.pageNumber).rjust(2, "0")
109        folioBox = KBox.fromText(folio).alignInside(
110            self.frame.coords, ("left", "top") if self.isRightSide else ("right", "top")
111        )
112
113        if self.bgColor:
114            with drawBot.savedState():
115                drawBot.fill(*self.bgColor)
116                drawBot.rect(
117                    *layout.grow(folioBox.coords, "1mm")
118                )  # Do not mutate folioBox coords directly
119        drawBot.textBox(
120            folio,
121            folioBox.coords,
122            align="left" if self.isRightSide else "right",
123        )
124
125    def addBodyHeader(
126        self,
127        title: str = None,
128        gap: layout.UnitSource = "5mm",
129        lines: int = 1,
130        mutate: bool = True,
131    ) -> "KBox":
132        """
133        Add a header box to page body.
134
135        Args:
136            title (optional): Text to write in the header.
137            gap: Space between header and body.
138            lines: Number of lines in the header. Font properties must be set beforehand.
139            mutate: If True, modify the header in place. If False, keep the header unchanged.
140
141        Returns the header box.
142        """
143        self.header = self.body.addHeader(gap=gap, lines=lines, mutate=mutate)
144
145        if title and self.bgColor:
146            with drawBot.savedState():
147                drawBot.fill(*self.bgColor)
148                bgBox = (
149                    KBox.fromText(title)
150                    .alignInside(self.header.coords, ("left", "top"))
151                    .grow(1)
152                )
153                drawBot.rect(*bgBox.coords)
154        if title:
155            drawBot.textBox(title, self.header.coords)
156
157        return self.header
158
159    def addBodyFooter(
160        self,
161        title: str = None,
162        gap: layout.UnitSource = "5mm",
163        lines: int = 1,
164        mutate: bool = True,
165    ) -> "KBox":
166        """
167        Add a footer box to page body.
168
169        Args:
170            title (optional): Text to write in the footer. Font props must be set beforehand.
171            gap: Space between footer and body.
172            lines: Number of lines in the footer. Font properties must be set beforehand.
173            mutate: If True, modify the footer in place. If False, keep the footer unchanged.
174
175        Returns the footer box.
176        """
177        self.footer = self.body.addFooter(gap=gap, lines=lines, mutate=mutate)
178        if title:
179            drawBot.textBox(title, self.footer.coords)
180
181        return self.footer
182
183    def addBleed(self, bleed: int = 7, preview: bool = True) -> None:
184        """
185        Add crop marks and optional bleed preview.
186
187        Args:
188            bleed: Bleed size.
189            preview: Fill bleed area with black for preview.
190        """
191        if preview:
192            self.fillBackground((0,))
193        self.shrink(bleed)
194        self.addCropMarks()
195        if preview:
196            self.fillBackground((1,))
197
198        self._draftBoxes()
199
200    def xray(self, enabled: bool = True) -> "KPage":
201        """
202        Xaray all child `classes.c20_box.KBox` instances.
203
204        Args:
205            enabled: Toggle debug mode.
206
207        Returns self for chaining.
208        """
209        if enabled:
210            coordsList = [self.frame.coords, self.body.coords]
211            if hasattr(self, "header"):
212                coordsList.append(self.header.coords)
213            if hasattr(self, "footer"):
214                coordsList.append(self.footer.coords)
215            layout.xray(coordsList)
216
217            # ? Add page number and side for debugging
218            with drawBot.savedState():
219                drawBot.font(DEFAULT_FONT, 4)
220                xrayText = f"Page {self.pageNumber}"
221                if self._isSpread:
222                    xrayText += f", {'left' if self.isLeftSide else 'right'}"
223                drawBot.text(xrayText, (10, 10))
224
225        return self
226
227    def _divide(self) -> None:
228        """Draw a spine divider for 2-page PDF view."""
229        if not self._isSpread or not self.isLeftSide:
230            return
231
232        with drawBot.savedState():
233            drawBot.fill(None)
234            drawBot.stroke(0, 0.25)
235            drawBot.strokeWidth(3)
236            drawBot.line((self.right, self.bottom), (self.right, self.top))
237
238    def render(self) -> None:
239        """Render the page to the canvas via `drawBot`."""
240        drawBot.newPage(*self.dimensions)