python-pptx2 2.13.0__py3-none-any.whl

pptx2/shapes/connector.py

@@ -0,0 +1,297 @@
+"""Connector (line) shape and related objects.
+
+A connector is a line shape having end-points that can be connected to other
+objects (but not to other connectors). A connector can be straight, have
+elbows, or can be curved.
+"""
+
+from __future__ import annotations
+
+from pptx2.dml.line import LineFormat
+from pptx2.enum.shapes import MSO_SHAPE_TYPE
+from pptx2.shapes.base import BaseShape
+from pptx2.util import Emu, lazyproperty
+
+
+class Connector(BaseShape):
+    """Connector (line) shape.
+
+    A connector is a linear shape having end-points that can be connected to
+    other objects (but not to other connectors). A connector can be straight,
+    have elbows, or can be curved.
+    """
+
+    def begin_connect(self, shape, cxn_pt_idx):
+        """
+        **EXPERIMENTAL** - *The current implementation only works properly
+        with rectangular shapes, such as pictures and rectangles. Use with
+        other shape types may cause unexpected visual alignment of the
+        connected end-point and could lead to a load error if cxn_pt_idx
+        exceeds the connection point count available on the connected shape.
+        That said, a quick test should reveal what to expect when using this
+        method with other shape types.*
+
+        Connect the beginning of this connector to *shape* at the connection
+        point specified by *cxn_pt_idx*. Each shape has zero or more
+        connection points and they are identified by index, starting with 0.
+        Generally, the first connection point of a shape is at the top center
+        of its bounding box and numbering proceeds counter-clockwise from
+        there. However this is only a convention and may vary, especially
+        with non built-in shapes.
+        """
+        self._connect_begin_to(shape, cxn_pt_idx)
+        self._move_begin_to_cxn(shape, cxn_pt_idx)
+
+    @property
+    def begin_x(self):
+        """
+        Return the X-position of the begin point of this connector, in
+        English Metric Units (as a |Length| object).
+        """
+        cxnSp = self._element
+        x, cx, flipH = cxnSp.x, cxnSp.cx, cxnSp.flipH
+        begin_x = x + cx if flipH else x
+        return Emu(begin_x)
+
+    @begin_x.setter
+    def begin_x(self, value):
+        cxnSp = self._element
+        x, cx, flipH, new_x = cxnSp.x, cxnSp.cx, cxnSp.flipH, int(value)
+
+        if flipH:
+            old_x = x + cx
+            dx = abs(new_x - old_x)
+            if new_x >= old_x:
+                cxnSp.cx = cx + dx
+            elif dx <= cx:
+                cxnSp.cx = cx - dx
+            else:
+                cxnSp.flipH = False
+                cxnSp.x = new_x
+                cxnSp.cx = dx - cx
+        else:
+            dx = abs(new_x - x)
+            if new_x <= x:
+                cxnSp.x = new_x
+                cxnSp.cx = cx + dx
+            elif dx <= cx:
+                cxnSp.x = new_x
+                cxnSp.cx = cx - dx
+            else:
+                cxnSp.flipH = True
+                cxnSp.x = x + cx
+                cxnSp.cx = dx - cx
+
+    @property
+    def begin_y(self):
+        """
+        Return the Y-position of the begin point of this connector, in
+        English Metric Units (as a |Length| object).
+        """
+        cxnSp = self._element
+        y, cy, flipV = cxnSp.y, cxnSp.cy, cxnSp.flipV
+        begin_y = y + cy if flipV else y
+        return Emu(begin_y)
+
+    @begin_y.setter
+    def begin_y(self, value):
+        cxnSp = self._element
+        y, cy, flipV, new_y = cxnSp.y, cxnSp.cy, cxnSp.flipV, int(value)
+
+        if flipV:
+            old_y = y + cy
+            dy = abs(new_y - old_y)
+            if new_y >= old_y:
+                cxnSp.cy = cy + dy
+            elif dy <= cy:
+                cxnSp.cy = cy - dy
+            else:
+                cxnSp.flipV = False
+                cxnSp.y = new_y
+                cxnSp.cy = dy - cy
+        else:
+            dy = abs(new_y - y)
+            if new_y <= y:
+                cxnSp.y = new_y
+                cxnSp.cy = cy + dy
+            elif dy <= cy:
+                cxnSp.y = new_y
+                cxnSp.cy = cy - dy
+            else:
+                cxnSp.flipV = True
+                cxnSp.y = y + cy
+                cxnSp.cy = dy - cy
+
+    def end_connect(self, shape, cxn_pt_idx):
+        """
+        **EXPERIMENTAL** - *The current implementation only works properly
+        with rectangular shapes, such as pictures and rectangles. Use with
+        other shape types may cause unexpected visual alignment of the
+        connected end-point and could lead to a load error if cxn_pt_idx
+        exceeds the connection point count available on the connected shape.
+        That said, a quick test should reveal what to expect when using this
+        method with other shape types.*
+
+        Connect the ending of this connector to *shape* at the connection
+        point specified by *cxn_pt_idx*.
+        """
+        self._connect_end_to(shape, cxn_pt_idx)
+        self._move_end_to_cxn(shape, cxn_pt_idx)
+
+    @property
+    def end_x(self):
+        """
+        Return the X-position of the end point of this connector, in English
+        Metric Units (as a |Length| object).
+        """
+        cxnSp = self._element
+        x, cx, flipH = cxnSp.x, cxnSp.cx, cxnSp.flipH
+        end_x = x if flipH else x + cx
+        return Emu(end_x)
+
+    @end_x.setter
+    def end_x(self, value):
+        cxnSp = self._element
+        x, cx, flipH, new_x = cxnSp.x, cxnSp.cx, cxnSp.flipH, int(value)
+
+        if flipH:
+            dx = abs(new_x - x)
+            if new_x <= x:
+                cxnSp.x = new_x
+                cxnSp.cx = cx + dx
+            elif dx <= cx:
+                cxnSp.x = new_x
+                cxnSp.cx = cx - dx
+            else:
+                cxnSp.flipH = False
+                cxnSp.x = x + cx
+                cxnSp.cx = dx - cx
+        else:
+            old_x = x + cx
+            dx = abs(new_x - old_x)
+            if new_x >= old_x:
+                cxnSp.cx = cx + dx
+            elif dx <= cx:
+                cxnSp.cx = cx - dx
+            else:
+                cxnSp.flipH = True
+                cxnSp.x = new_x
+                cxnSp.cx = dx - cx
+
+    @property
+    def end_y(self):
+        """
+        Return the Y-position of the end point of this connector, in English
+        Metric Units (as a |Length| object).
+        """
+        cxnSp = self._element
+        y, cy, flipV = cxnSp.y, cxnSp.cy, cxnSp.flipV
+        end_y = y if flipV else y + cy
+        return Emu(end_y)
+
+    @end_y.setter
+    def end_y(self, value):
+        cxnSp = self._element
+        y, cy, flipV, new_y = cxnSp.y, cxnSp.cy, cxnSp.flipV, int(value)
+
+        if flipV:
+            dy = abs(new_y - y)
+            if new_y <= y:
+                cxnSp.y = new_y
+                cxnSp.cy = cy + dy
+            elif dy <= cy:
+                cxnSp.y = new_y
+                cxnSp.cy = cy - dy
+            else:
+                cxnSp.flipV = False
+                cxnSp.y = y + cy
+                cxnSp.cy = dy - cy
+        else:
+            old_y = y + cy
+            dy = abs(new_y - old_y)
+            if new_y >= old_y:
+                cxnSp.cy = cy + dy
+            elif dy <= cy:
+                cxnSp.cy = cy - dy
+            else:
+                cxnSp.flipV = True
+                cxnSp.y = new_y
+                cxnSp.cy = dy - cy
+
+    def get_or_add_ln(self):
+        """Helper method required by |LineFormat|."""
+        return self._element.spPr.get_or_add_ln()
+
+    @lazyproperty
+    def line(self):
+        """|LineFormat| instance for this connector.
+
+        Provides access to line properties such as line color, width, and
+        line style.
+        """
+        return LineFormat(self)
+
+    @property
+    def ln(self):
+        """Helper method required by |LineFormat|.
+
+        The ``<a:ln>`` element containing the line format properties such as
+        line color and width. |None| if no `<a:ln>` element is present.
+        """
+        return self._element.spPr.ln
+
+    @property
+    def shape_type(self):
+        """Member of `MSO_SHAPE_TYPE` identifying the type of this shape.
+
+        Unconditionally `MSO_SHAPE_TYPE.LINE` for a `Connector` object.
+        """
+        return MSO_SHAPE_TYPE.LINE
+
+    def _connect_begin_to(self, shape, cxn_pt_idx):
+        """
+        Add or update a stCxn element for this connector that connects its
+        begin point to the connection point of *shape* specified by
+        *cxn_pt_idx*.
+        """
+        cNvCxnSpPr = self._element.nvCxnSpPr.cNvCxnSpPr
+        stCxn = cNvCxnSpPr.get_or_add_stCxn()
+        stCxn.id = shape.shape_id
+        stCxn.idx = cxn_pt_idx
+
+    def _connect_end_to(self, shape, cxn_pt_idx):
+        """
+        Add or update an endCxn element for this connector that connects its
+        end point to the connection point of *shape* specified by
+        *cxn_pt_idx*.
+        """
+        cNvCxnSpPr = self._element.nvCxnSpPr.cNvCxnSpPr
+        endCxn = cNvCxnSpPr.get_or_add_endCxn()
+        endCxn.id = shape.shape_id
+        endCxn.idx = cxn_pt_idx
+
+    def _move_begin_to_cxn(self, shape, cxn_pt_idx):
+        """
+        Move the begin point of this connector to coordinates of the
+        connection point of *shape* specified by *cxn_pt_idx*.
+        """
+        x, y, cx, cy = shape.left, shape.top, shape.width, shape.height
+        self.begin_x, self.begin_y = {
+            0: (int(x + cx / 2), y),
+            1: (x, int(y + cy / 2)),
+            2: (int(x + cx / 2), y + cy),
+            3: (x + cx, int(y + cy / 2)),
+        }[cxn_pt_idx]
+
+    def _move_end_to_cxn(self, shape, cxn_pt_idx):
+        """
+        Move the end point of this connector to the coordinates of the
+        connection point of *shape* specified by *cxn_pt_idx*.
+        """
+        x, y, cx, cy = shape.left, shape.top, shape.width, shape.height
+        self.end_x, self.end_y = {
+            0: (int(x + cx / 2), y),
+            1: (x, int(y + cy / 2)),
+            2: (int(x + cx / 2), y + cy),
+            3: (x + cx, int(y + cy / 2)),
+        }[cxn_pt_idx]

pptx2/shapes/freeform.py

@@ -0,0 +1,337 @@
+"""Objects related to construction of freeform shapes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable, Iterator, Sequence
+
+from pptx2.util import Emu, lazyproperty
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
+    from pptx2.oxml.shapes.autoshape import (
+        CT_Path2D,
+        CT_Path2DClose,
+        CT_Path2DLineTo,
+        CT_Path2DMoveTo,
+        CT_Shape,
+    )
+    from pptx2.shapes.shapetree import _BaseGroupShapes  # pyright: ignore[reportPrivateUsage]
+    from pptx2.util import Length
+
+CT_DrawingOperation: TypeAlias = "CT_Path2DClose | CT_Path2DLineTo | CT_Path2DMoveTo"
+DrawingOperation: TypeAlias = "_LineSegment | _MoveTo | _Close"
+
+
+class FreeformBuilder(Sequence[DrawingOperation]):
+    """Allows a freeform shape to be specified and created.
+
+    The initial pen position is provided on construction. From there, drawing proceeds using
+    successive calls to draw line segments. The freeform shape may be closed by calling the
+    :meth:`close` method.
+
+    A shape may have more than one contour, in which case overlapping areas are "subtracted". A
+    contour is a sequence of line segments beginning with a "move-to" operation. A move-to
+    operation is automatically inserted in each new freeform; additional move-to ops can be
+    inserted with the `.move_to()` method.
+    """
+
+    def __init__(
+        self,
+        shapes: _BaseGroupShapes,
+        start_x: Length,
+        start_y: Length,
+        x_scale: float,
+        y_scale: float,
+    ):
+        super(FreeformBuilder, self).__init__()
+        self._shapes = shapes
+        self._start_x = start_x
+        self._start_y = start_y
+        self._x_scale = x_scale
+        self._y_scale = y_scale
+
+    def __getitem__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, idx: int
+    ) -> DrawingOperation:
+        return self._drawing_operations.__getitem__(idx)
+
+    def __iter__(self) -> Iterator[DrawingOperation]:
+        return self._drawing_operations.__iter__()
+
+    def __len__(self):
+        return self._drawing_operations.__len__()
+
+    @classmethod
+    def new(
+        cls,
+        shapes: _BaseGroupShapes,
+        start_x: float,
+        start_y: float,
+        x_scale: float,
+        y_scale: float,
+    ):
+        """Return a new |FreeformBuilder| object.
+
+        The initial pen location is specified (in local coordinates) by
+        (`start_x`, `start_y`).
+        """
+        return cls(shapes, Emu(int(round(start_x))), Emu(int(round(start_y))), x_scale, y_scale)
+
+    def add_line_segments(self, vertices: Iterable[tuple[float, float]], close: bool = True):
+        """Add a straight line segment to each point in `vertices`.
+
+        `vertices` must be an iterable of (x, y) pairs (2-tuples). Each x and y value is rounded
+        to the nearest integer before use. The optional `close` parameter determines whether the
+        resulting contour is `closed` or left `open`.
+
+        Returns this |FreeformBuilder| object so it can be used in chained calls.
+        """
+        for x, y in vertices:
+            self._add_line_segment(x, y)
+        if close:
+            self._add_close()
+        return self
+
+    def convert_to_shape(self, origin_x: Length = Emu(0), origin_y: Length = Emu(0)):
+        """Return new freeform shape positioned relative to specified offset.
+
+        `origin_x` and `origin_y` locate the origin of the local coordinate system in slide
+        coordinates (EMU), perhaps most conveniently by use of a |Length| object.
+
+        Note that this method may be called more than once to add multiple shapes of the same
+        geometry in different locations on the slide.
+        """
+        sp = self._add_freeform_sp(origin_x, origin_y)
+        path = self._start_path(sp)
+        for drawing_operation in self:
+            drawing_operation.apply_operation_to(path)
+        return self._shapes._shape_factory(sp)  # pyright: ignore[reportPrivateUsage]
+
+    def move_to(self, x: float, y: float):
+        """Move pen to (x, y) (local coordinates) without drawing line.
+
+        Returns this |FreeformBuilder| object so it can be used in chained calls.
+        """
+        self._drawing_operations.append(_MoveTo.new(self, x, y))
+        return self
+
+    @property
+    def shape_offset_x(self) -> Length:
+        """Return x distance of shape origin from local coordinate origin.
+
+        The returned integer represents the leftmost extent of the freeform shape, in local
+        coordinates. Note that the bounding box of the shape need not start at the local origin.
+        """
+        min_x = self._start_x
+        for drawing_operation in self:
+            if isinstance(drawing_operation, _Close):
+                continue
+            min_x = min(min_x, drawing_operation.x)
+        return Emu(min_x)
+
+    @property
+    def shape_offset_y(self) -> Length:
+        """Return y distance of shape origin from local coordinate origin.
+
+        The returned integer represents the topmost extent of the freeform shape, in local
+        coordinates. Note that the bounding box of the shape need not start at the local origin.
+        """
+        min_y = self._start_y
+        for drawing_operation in self:
+            if isinstance(drawing_operation, _Close):
+                continue
+            min_y = min(min_y, drawing_operation.y)
+        return Emu(min_y)
+
+    def _add_close(self):
+        """Add a close |_Close| operation to the drawing sequence."""
+        self._drawing_operations.append(_Close.new())
+
+    def _add_freeform_sp(self, origin_x: Length, origin_y: Length):
+        """Add a freeform `p:sp` element having no drawing elements.
+
+        `origin_x` and `origin_y` are specified in slide coordinates, and represent the location
+        of the local coordinates origin on the slide.
+        """
+        spTree = self._shapes._spTree  # pyright: ignore[reportPrivateUsage]
+        return spTree.add_freeform_sp(
+            origin_x + self._left, origin_y + self._top, self._width, self._height
+        )
+
+    def _add_line_segment(self, x: float, y: float) -> None:
+        """Add a |_LineSegment| operation to the drawing sequence."""
+        self._drawing_operations.append(_LineSegment.new(self, x, y))
+
+    @lazyproperty
+    def _drawing_operations(self) -> list[DrawingOperation]:
+        """Return the sequence of drawing operation objects for freeform."""
+        return []
+
+    @property
+    def _dx(self) -> Length:
+        """Return width of this shape's path in local units."""
+        min_x = max_x = self._start_x
+        for drawing_operation in self:
+            if isinstance(drawing_operation, _Close):
+                continue
+            min_x = min(min_x, drawing_operation.x)
+            max_x = max(max_x, drawing_operation.x)
+        return Emu(max_x - min_x)
+
+    @property
+    def _dy(self) -> Length:
+        """Return integer height of this shape's path in local units."""
+        min_y = max_y = self._start_y
+        for drawing_operation in self:
+            if isinstance(drawing_operation, _Close):
+                continue
+            min_y = min(min_y, drawing_operation.y)
+            max_y = max(max_y, drawing_operation.y)
+        return Emu(max_y - min_y)
+
+    @property
+    def _height(self):
+        """Return vertical size of this shape's path in slide coordinates.
+
+        This value is based on the actual extents of the shape and does not include any
+        positioning offset.
+        """
+        return int(round(self._dy * self._y_scale))
+
+    @property
+    def _left(self):
+        """Return leftmost extent of this shape's path in slide coordinates.
+
+        Note that this value does not include any positioning offset; it assumes the drawing
+        (local) coordinate origin is at (0, 0) on the slide.
+        """
+        return int(round(self.shape_offset_x * self._x_scale))
+
+    def _local_to_shape(self, local_x: Length, local_y: Length) -> tuple[Length, Length]:
+        """Translate local coordinates point to shape coordinates.
+
+        Shape coordinates have the same unit as local coordinates, but are offset such that the
+        origin of the shape coordinate system (0, 0) is located at the top-left corner of the
+        shape bounding box.
+        """
+        return Emu(local_x - self.shape_offset_x), Emu(local_y - self.shape_offset_y)
+
+    def _start_path(self, sp: CT_Shape) -> CT_Path2D:
+        """Return a newly created `a:path` element added to `sp`.
+
+        The returned `a:path` element has an `a:moveTo` element representing the shape starting
+        point as its only child.
+        """
+        path = sp.add_path(w=self._dx, h=self._dy)
+        path.add_moveTo(*self._local_to_shape(self._start_x, self._start_y))
+        return path
+
+    @property
+    def _top(self):
+        """Return topmost extent of this shape's path in slide coordinates.
+
+        Note that this value does not include any positioning offset; it assumes the drawing
+        (local) coordinate origin is located at slide coordinates (0, 0) (top-left corner of
+        slide).
+        """
+        return int(round(self.shape_offset_y * self._y_scale))
+
+    @property
+    def _width(self):
+        """Return width of this shape's path in slide coordinates.
+
+        This value is based on the actual extents of the shape path and does not include any
+        positioning offset.
+        """
+        return int(round(self._dx * self._x_scale))
+
+
+class _BaseDrawingOperation(object):
+    """Base class for freeform drawing operations.
+
+    A drawing operation has at least one location (x, y) in local coordinates.
+    """
+
+    def __init__(self, freeform_builder: FreeformBuilder, x: Length, y: Length):
+        super(_BaseDrawingOperation, self).__init__()
+        self._freeform_builder = freeform_builder
+        self._x = x
+        self._y = y
+
+    def apply_operation_to(self, path: CT_Path2D) -> CT_DrawingOperation:
+        """Add the XML element(s) implementing this operation to `path`.
+
+        Must be implemented by each subclass.
+        """
+        raise NotImplementedError("must be implemented by each subclass")
+
+    @property
+    def x(self) -> Length:
+        """Return the horizontal (x) target location of this operation.
+
+        The returned value is an integer in local coordinates.
+        """
+        return self._x
+
+    @property
+    def y(self) -> Length:
+        """Return the vertical (y) target location of this operation.
+
+        The returned value is an integer in local coordinates.
+        """
+        return self._y
+
+
+class _Close(object):
+    """Specifies adding a `<a:close/>` element to the current contour."""
+
+    @classmethod
+    def new(cls) -> _Close:
+        """Return a new _Close object."""
+        return cls()
+
+    def apply_operation_to(self, path: CT_Path2D) -> CT_Path2DClose:
+        """Add `a:close` element to `path`."""
+        return path.add_close()
+
+
+class _LineSegment(_BaseDrawingOperation):
+    """Specifies a straight line segment ending at the specified point."""
+
+    @classmethod
+    def new(cls, freeform_builder: FreeformBuilder, x: float, y: float) -> _LineSegment:
+        """Return a new _LineSegment object ending at point *(x, y)*.
+
+        Both `x` and `y` are rounded to the nearest integer before use.
+        """
+        return cls(freeform_builder, Emu(int(round(x))), Emu(int(round(y))))
+
+    def apply_operation_to(self, path: CT_Path2D) -> CT_Path2DLineTo:
+        """Add `a:lnTo` element to `path` for this line segment.
+
+        Returns the `a:lnTo` element newly added to the path.
+        """
+        return path.add_lnTo(
+            Emu(self._x - self._freeform_builder.shape_offset_x),
+            Emu(self._y - self._freeform_builder.shape_offset_y),
+        )
+
+
+class _MoveTo(_BaseDrawingOperation):
+    """Specifies a new pen position."""
+
+    @classmethod
+    def new(cls, freeform_builder: FreeformBuilder, x: float, y: float) -> _MoveTo:
+        """Return a new _MoveTo object for move to point `(x, y)`.
+
+        Both `x` and `y` are rounded to the nearest integer before use.
+        """
+        return cls(freeform_builder, Emu(int(round(x))), Emu(int(round(y))))
+
+    def apply_operation_to(self, path: CT_Path2D) -> CT_Path2DMoveTo:
+        """Add `a:moveTo` element to `path` for this line segment."""
+        return path.add_moveTo(
+            Emu(self._x - self._freeform_builder.shape_offset_x),
+            Emu(self._y - self._freeform_builder.shape_offset_y),
+        )