Class TextFitter

src/pptx/text/layout.py:13–116

Value object that knows how to fit text into given rectangular extents.

class TextFitter(tuple):
    """Value object that knows how to fit text into given rectangular extents."""

    def __new__(cls, line_source, extents, font_file):
        width, height = extents
        return tuple.__new__(cls, (line_source, width, height, font_file))

    @classmethod
    def best_fit_font_size(
        cls, text: str, extents: tuple[Length, Length], max_size: int, font_file: str
    ) -> int:
        """Return whole-number best fit point size less than or equal to `max_size`.

        The return value is the largest whole-number point size less than or equal to
        `max_size` that allows `text` to fit completely within `extents` when rendered
        using font defined in `font_file`.
        """
        line_source = _LineSource(text)
        text_fitter = cls(line_source, extents, font_file)
        return text_fitter._best_fit_font_size(max_size)

    def _best_fit_font_size(self, max_size):
        """
        Return the largest whole-number point size less than or equal to
        *max_size* that this fitter can fit.
        """
        predicate = self._fits_inside_predicate
        sizes = _BinarySearchTree.from_ordered_sequence(range(1, int(max_size) + 1))
        return sizes.find_max(predicate)

    def _break_line(self, line_source, point_size):
        """
        Return a (line, remainder) pair where *line* is the longest line in
        *line_source* that will fit in this fitter's width and *remainder* is
        a |_LineSource| object containing the text following the break point.
        """
        lines = _BinarySearchTree.from_ordered_sequence(line_source)
        predicate = self._fits_in_width_predicate(point_size)
        return lines.find_max(predicate)

    def _fits_in_width_predicate(self, point_size):
        """
        Return a function taking a text string value and returns |True| if
        that text fits in this fitter when rendered at *point_size*. Used as
        predicate for _break_line()
        """

        def predicate(line):
            """
            Return |True| if *line* fits in this fitter when rendered at
            *point_size*.
            """
            cx = _rendered_size(line.text, point_size, self._font_file)[0]
            return cx <= self._width

        return predicate

    @property