GroupShapes

The lxml element proxied by this object.

The ancestor proxy object to this one.

For example, the parent of a shape is generally the SlideShapes object that contains it.

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 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-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.

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.

Add a new placeholder shape based on placeholder.

Return the index of shape in this sequence.

Raises ValueError if shape is not in the collection.

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.