Aspose.Slides FOSS
Python
ShapeCollection

ShapeCollection, AutoShape, PictureFrame, Connector, GroupShape — Aspose.Slides FOSS for Python API Reference

ShapeCollection is the container for all shapes on a slide. Access it via slide.shapes. It provides factory methods to add every supported shape type and collection methods to iterate, index, remove, or reorder shapes.

Package: aspose.slides_foss

ShapeCollection

Access via slide.shapes.

Add Methods

MethodSignatureReturnsDescription
add_auto_shapeadd_auto_shape(shape_type, x, y, width, height[, create_from_template=True]) -> AutoShapeAutoShapeAdd a standard geometric shape at the given position and size (all in points).
insert_auto_shapeinsert_auto_shape(index, shape_type, x, y, width, height[, create_from_template=True]) -> AutoShapeAutoShapeInsert an AutoShape at a specific zero-based position in the collection.
add_connectoradd_connector(shape_type, x, y, width, height[, create_from_template=True]) -> ConnectorConnectorAdd a line connector. Use ShapeType.STRAIGHT_CONNECTOR1, BENT_CONNECTOR3, etc.
insert_connectorinsert_connector(index, shape_type, x, y, width, height[, create_from_template=True]) -> ConnectorConnectorInsert a connector at a specific position.
add_picture_frameadd_picture_frame(shape_type, x, y, width, height, image) -> PictureFramePictureFrameAdd a picture frame. image must be a PPImage obtained from prs.images.add_image(...).
insert_picture_frameinsert_picture_frame(index, shape_type, x, y, width, height, image) -> PictureFramePictureFrameInsert a picture frame at a specific position.
add_tableadd_table(x, y, column_widths, row_heights) -> TableTableAdd a table. column_widths and row_heights are lists of floats in points.
insert_tableinsert_table(index, x, y, column_widths, row_heights) -> TableTableInsert a table at a specific position.

Remove and Reorder Methods

MethodSignatureDescription
removeremove(shape)Remove the given shape object from the collection.
remove_atremove_at(index)Remove the shape at the given zero-based index.
clearclear()Remove all shapes from the slide.
reorderreorder(new_index, shape_or_shapes)Move one shape or a list of shapes to a new zero-based index (affects z-order).

Query Methods

MethodSignatureDescription
index_ofindex_of(shape) -> intReturn the zero-based index of a shape, or -1 if not found.
to_arrayto_array() -> list[Shape]Return all shapes as a Python list.
to_arrayto_array(start, count) -> list[Shape]Return a slice of count shapes starting at start.

Collection Protocol

MemberDescription
__getitem__(i)Return the shape at index i. Negative indices supported.
__len__Number of shapes on the slide.
__iter__Iterate shapes in z-order (bottom to top).

Properties

PropertyTypeDescription
parent_groupGroupShape or NoneParent group shape, or None for slide-level collections.

AutoShape

The most common shape type. Created by add_auto_shape().

Properties

PropertyTypeDescription
shape_typeShapeTypeThe geometry preset (e.g. RECTANGLE, ELLIPSE, TRIANGLE).
text_frameTextFrame or NoneThe attached text container. None until add_text_frame() is called.
fill_formatFillFormatShape fill settings.
line_formatLineFormatShape border settings.
effect_formatEffectFormatVisual effects (shadow, glow, blur).
three_d_formatThreeDFormat3D bevel and extrusion settings.
x, yfloatPosition in points.
width, heightfloatSize in points.
namestrShape name as shown in the Selection Pane.
hiddenboolWhether the shape is hidden.
rotationfloatClockwise rotation in degrees.
z_order_positionintIndex in the z-order stack.

Methods

MethodSignatureDescription
add_text_frameadd_text_frame(text) -> TextFrameCreate a text frame with the given initial text, or return the existing one.

PictureFrame

A shape containing an embedded raster image. Created by add_picture_frame().

Properties

PropertyTypeDescription
picture_formatIPictureFillFormatAccess the embedded image and crop settings.
fill_formatFillFormatFrame background fill (usually inherits the picture).
line_formatLineFormatFrame border.

Inherits all position, size, and effect properties from Shape.

Typical workflow 

with open("photo.jpg", "rb") as f:
    image = prs.images.add_image(f)

pic_frame = slide.shapes.add_picture_frame(
    ShapeType.RECTANGLE, 100, 100, 300, 200, image
)

Connector

A line shape that can link two anchor shapes. Created by add_connector().

Properties

PropertyTypeDescription
line_formatLineFormatStroke appearance (colour, width, arrowheads).
start_shape_connected_toIShape or NoneShape at the start end of the connector.
end_shape_connected_toIShape or NoneShape at the end of the connector.
start_shape_connection_site_indexintConnection site index on the start shape.
end_shape_connection_site_indexintConnection site index on the end shape.

Common connector ShapeType values

ConstantDescription
ShapeType.STRAIGHT_CONNECTOR1Straight line
ShapeType.BENT_CONNECTOR2One elbow
ShapeType.BENT_CONNECTOR3Two elbows (most common)
ShapeType.CURVED_CONNECTOR3Curved with midpoint handle

GroupShape

A shape that contains other shapes. Created when the source file has grouped objects.

Properties

PropertyTypeDescription
shapesShapeCollectionThe nested collection of grouped shapes.

Iterating a GroupShape.shapes follows the same API as the slide-level ShapeCollection.

Usage Example

Add shapes, a picture, and a connector 

import aspose.slides_foss as slides
from aspose.slides_foss import ShapeType, FillType, LineArrowheadStyle, NullableBool
from aspose.slides_foss.drawing import Color
from aspose.slides_foss.export import SaveFormat

with slides.Presentation() as prs:
    slide = prs.slides[0]

    # Rounded rectangle with text
    rect = slide.shapes.add_auto_shape(ShapeType.ROUND_CORNER_RECTANGLE, 50, 80, 240, 80)
    rect.fill_format.fill_type = FillType.SOLID
    rect.fill_format.solid_fill_color.color = Color.from_argb(255, 0, 112, 192)
    tf = rect.add_text_frame("Source")
    tf.paragraphs[0].portions[0].portion_format.fill_format.fill_type = FillType.SOLID
    tf.paragraphs[0].portions[0].portion_format.fill_format.solid_fill_color.color = Color.white

    # Target shape
    ellipse = slide.shapes.add_auto_shape(ShapeType.ELLIPSE, 400, 80, 160, 80)
    ellipse.fill_format.fill_type = FillType.SOLID
    ellipse.fill_format.solid_fill_color.color = Color.from_argb(255, 70, 175, 73)

    # Picture frame
    with open("logo.png", "rb") as f:
        img = prs.images.add_image(f)
    pf = slide.shapes.add_picture_frame(ShapeType.RECTANGLE, 50, 220, 120, 80, img)

    # Arrow connector
    arrow = slide.shapes.add_connector(ShapeType.BENT_CONNECTOR3, 295, 120, 100, 1)
    arrow.line_format.width = 1.5
    arrow.line_format.fill_format.fill_type = FillType.SOLID
    arrow.line_format.fill_format.solid_fill_color.color = Color.from_argb(255, 100, 100, 100)
    arrow.line_format.end_arrowhead_style = LineArrowheadStyle.TRIANGLE

    prs.save("shape-collection-demo.pptx", SaveFormat.PPTX)

See Also