SlideShapes

The lxml element proxied by this object.

Sequence of placeholder shapes in this slide.

The title placeholder shape on the slide.

None if the slide has no title placeholder.

True if "turbo-add" mode is enabled. Read/Write.

EXPERIMENTAL: This feature can radically improve performance when adding large numbers (hundreds of shapes) to a slide. It works by caching the last shape ID used and incrementing that value to assign the next shape id. This avoids repeatedly searching all shape ids in the slide each time a new ID is required.

Performance is not noticeably improved for a slide with a relatively small number of shapes, but because the search time rises with the square of the shape count, this option can be useful for optimizing generation of a slide composed of many shapes.

Shape-id collisions can occur (causing a repair error on load) if more than one Slide object is used to interact with the same slide in the presentation. Note that the Slides collection creates a new Slide object each time a slide is accessed (e.g. slide = prs.slides[0], so you must be careful to limit use to a single Slide object.

Return shape at idx in sequence, e.g. shapes[2].

Generate a reference to each shape in the collection, in sequence.

Return count of shapes in this shape tree.

A group shape contributes 1 to the total, without regard to the number of shapes contained in the group.

Add a new chart of chart_type to the slide.

The chart is positioned at (x, y), has size (cx, cy), and depicts chart_data. chart_type is one of the :ref:XlChartType enumeration values. chart_data is a ChartData object populated with the categories and series values for the chart.

Note that a GraphicFrame shape object is returned, not the Chart object contained in that graphic frame shape. The chart object may be accessed using the :attr:chart property of the returned GraphicFrame object.

Add a newly created connector shape to the end of this shape tree.

connector_type is a member of the :ref:MsoConnectorType enumeration and the end-point values are specified as EMU values. The returned connector is of type connector_type and has begin and end points as specified.

Return a copy of shape (from this or another slide) added to this slide.

paper-pptx addition. The copy gets fresh shape ids; its relationships follow the pinned policy: image/media parts shared, external (hyperlink) relationships copied, charts deep-copied WITH their embedded workbooks and style parts. Any other relationship type refuses with RelationshipPolicyError before anything changes. A shape from another presentation raises TargetNotFoundError.

Return a GroupShape object newly appended to this shape tree.

The group shape is empty and must be populated with shapes using methods on its shape tree, available on its .shapes property. The position and extents of the group shape are determined by the shapes it contains; its position and extents are recalculated each time a shape is added to it.

Return newly added movie shape displaying video in movie_file.

EXPERIMENTAL. This method has important limitations:

• The size must be specified; no auto-scaling such as that provided by :meth:add_picture is performed.
• The MIME type of the video file should be specified, e.g. 'video/mp4'. The provided video file is not interrogated for its type. The MIME type video/unknown is used by default (and works fine in tests as of this writing).
• A poster frame image must be provided, it cannot be automatically extracted from the video file. If no poster frame is provided, the default "media loudspeaker" image will be used.

Return a newly added movie shape to the slide, positioned at (left, top), having size (width, height), and containing movie_file. Before the video is started, poster_frame_image is displayed as a placeholder for the video.

Return newly-created GraphicFrame shape embedding object_file.

The returned graphic-frame shape contains object_file as an embedded OLE object. It is displayed as an icon at left, top with size width, height. width and height may be omitted when prog_id is a member of PROG_ID, in which case the default icon size is used. This is advised for best appearance where applicable because it avoids an icon with a "stretched" appearance.

object_file may either be a str path to a file or file-like object (such as io.BytesIO) containing the bytes of the object to be embedded (such as an Excel file).

prog_id can be either a member of pptx.enum.shapes.PROG_ID or a str value like "Adobe.Exchange.7" determined by inspecting the XML generated by PowerPoint for an object of the desired type.

icon_file may either be a str path to an image file or a file-like object containing the image. The image provided will be displayed in lieu of the OLE object; double-clicking on the image opens the object (subject to operating-system limitations). The image file can be any supported image file. Those produced by PowerPoint itself are generally EMF and can be harvested from a PPTX package that embeds such an object. PNG and JPG also work fine.

icon_width and icon_height are Length values (e.g. Emu() or Inches()) that describe the size of the icon image within the shape. These should be omitted unless a custom icon_file is provided. The dimensions must be discovered by inspecting the XML. Automatic resizing of the OLE-object shape can occur when the icon is double-clicked if these values are not as set by PowerPoint. This behavior may only manifest in the Windows version of PowerPoint.

Add picture shape displaying image in image_file.

image_file can be either a path to a file (a string) or a file-like object. The picture is positioned with its top-left corner at (top, left). If width and height are both None, the native size of the image is used. If only one of width or height is used, the unspecified dimension is calculated to preserve the aspect ratio of the image. If both are specified, the picture is stretched to fit, without regard to its native aspect ratio.

Return new Shape object appended to this shape tree.

autoshape_type_id is a member of :ref:MsoAutoShapeType e.g. MSO_SHAPE.RECTANGLE specifying the type of shape to be added. The remaining arguments specify the new shape's position and size.

Add a GraphicFrame object containing a table.

The table has the specified number of rows and cols and the specified position and size. width is evenly distributed between the columns of the new table. Likewise, height is evenly distributed between the rows. Note that the .table property on the returned GraphicFrame shape must be used to access the enclosed Table object.

Return newly added text box shape appended to this shape tree.

The text box is of the specified size, located at the specified position on the slide.

Return FreeformBuilder object to specify a freeform shape.

The optional start_x and start_y arguments specify the starting pen position in local coordinates. They will be rounded to the nearest integer before use and each default to zero.

The optional scale argument specifies the size of local coordinates proportional to slide coordinates (EMU). If the vertical scale is different than the horizontal scale (local coordinate units are "rectangular"), a pair of numeric values can be provided as the scale argument, e.g. scale=(1.0, 2.0). In this case the first number is interpreted as the horizontal (X) scale and the second as the vertical (Y) scale.

A convenient method for calculating scale is to divide a Length object by an equivalent count of local coordinate units, e.g. scale = Inches(1)/1000 for 1000 local units per inch.

Return the Chart held by the shape on this slide named name.

paper-pptx addition, the chart-addressing half of safe chart-data replacement. Group-aware: shapes inside groups are found too. Raises TargetNotFoundError when no shape has that name, or when shapes with the name exist but none holds a chart (the message says what was found instead). Raises AmbiguousTargetError when more than one chart-bearing shape has the name — this API never guesses between them.

Add placeholder shapes based on those in slide_layout.

Z-order of placeholders is preserved. Latent placeholders (date, slide number, and footer) are not cloned.

Add a new placeholder shape based on placeholder.

Remove shape from this slide, with relationship hygiene.

paper-pptx addition. Relationships referenced by the removed subtree are dropped unless something else in the part still references them (two pictures can share one image relationship). A shape that is not a direct member of this collection — including a shape inside a group — raises TargetNotFoundError (delete the group, or ungroup first).

Return the index of shape in this sequence.

Raises ValueError if shape is not in the collection.

Move shape to 0-based to_index in this collection's z-order.

paper-pptx addition. Index 0 is backmost, the last index topmost — the same order this collection iterates. to_index outside range raises ValueError; a shape not directly in this collection raises TargetNotFoundError.

Return the base name for a placeholder of ph_type in this shape collection.

There is some variance between slide types, for example a notes slide uses a different name for the body placeholder, so this method can be overriden by subclasses.

Return the Picture on this slide named name (group-aware).

paper-pptx addition, with the same contract as chart_by_name: TargetNotFoundError when nothing (or nothing picture-shaped) has the name, AmbiguousTargetError when several pictures do.

Return the single shape on this slide named name (group-aware).

paper-pptx addition: TargetNotFoundError / AmbiguousTargetError, never first-match.

Return the Table held by the graphic frame on this slide named name.

paper-pptx addition, same contract as chart_by_name.