Shapes

The following classes provide access to the shapes that appear on a slide and the collections that contain them.

SlideShapes objects

The SlideShapes object is encountered as the shapes property of Slide.

class pptx.shapes.shapetree.SlideShapes[source]

Sequence of shapes appearing on a slide.

The first shape in the sequence is the backmost in z-order and the last shape is topmost. Supports indexed access, len(), index(), and iteration.

add_chart(chart_type, x, y, cx, cy, chart_data)

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 XL_CHART_TYPE 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 chart property of the returned GraphicFrame object.

add_connector(connector_type, begin_x, begin_y, end_x, end_y)

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

connector_type is a member of the MSO_CONNECTOR_TYPE 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.

add_group_shape(shapes=[])

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.

add_movie(movie_file, left, top, width, height, poster_frame_image=None, mime_type='video/unknown')[source]

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

add_picture(image_file, left, top, width=None, height=None)

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.

add_shape(autoshape_type_id, left, top, width, height)

Return new Shape object appended to this shape tree.

Auto shape is of type specified by autoshape_type_id (like MSO_SHAPE.RECTANGLE) and of specified size at specified position.

add_table(rows, cols, left, top, width, height)[source]

Add a GraphicFrame object containing a table with 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.

add_textbox(left, top, width, height)

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.

build_freeform(start_x=0, start_y=0, scale=1.0)

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.

element

The lxml element proxied by this object.

index(shape)

Return the index of shape in this sequence.

Raises ValueError if shape is not in the collection.

parent

The ancestor proxy object to this one. For example, the parent of a shape is generally the SlideShapes object that contains it.

part

The package part containing this object

placeholders

Instance of SlidePlaceholders containing sequence of placeholder shapes in this slide.

title

The title placeholder shape on the slide or None if the slide has no title placeholder.

GroupShapes objects

The GroupShapes object is encountered as the shapes property of GroupShape.

class pptx.shapes.shapetree.GroupShapes[source]

The sequence of child shapes belonging to a group shape.

Note that this collection can itself contain a group shape, making this part of a recursive, tree data structure (acyclic graph).

add_chart(chart_type, x, y, cx, cy, chart_data)

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 XL_CHART_TYPE 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 chart property of the returned GraphicFrame object.

add_connector(connector_type, begin_x, begin_y, end_x, end_y)

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

connector_type is a member of the MSO_CONNECTOR_TYPE 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.

add_group_shape(shapes=[])

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.

add_picture(image_file, left, top, width=None, height=None)

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.

add_shape(autoshape_type_id, left, top, width, height)

Return new Shape object appended to this shape tree.

Auto shape is of type specified by autoshape_type_id (like MSO_SHAPE.RECTANGLE) and of specified size at specified position.

add_textbox(left, top, width, height)

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.

build_freeform(start_x=0, start_y=0, scale=1.0)

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.

element

The lxml element proxied by this object.

index(shape)

Return the index of shape in this sequence.

Raises ValueError if shape is not in the collection.

parent

The ancestor proxy object to this one. For example, the parent of a shape is generally the SlideShapes object that contains it.

part

The package part containing this object

Shape objects in general

The following properties and methods are common to all shapes.

class pptx.shapes.base.BaseShape[source]

Base class for shape objects.

Subclasses include Shape, Picture, and GraphicFrame.

click_action

ActionSetting instance providing access to click behaviors.

Click behaviors are hyperlink-like behaviors including jumping to a hyperlink (web page) or to another slide in the presentation. The click action is that defined on the overall shape, not a run of text within the shape. An ActionSetting object is always returned, even when no click behavior is defined on the shape.

element

lxml element for this shape, e.g. a CT_Shape instance.

Note that manipulating this element improperly can produce an invalid presentation file. Make sure you know what you’re doing if you use this to change the underlying XML.

has_chart

True if this shape is a graphic frame containing a chart object. False otherwise. When True, the chart object can be accessed using the .chart property.

has_table

True if this shape is a graphic frame containing a table object. False otherwise. When True, the table object can be accessed using the .table property.

has_text_frame

True if this shape can contain text.

height

Read/write. Integer distance between top and bottom extents of shape in EMUs

is_placeholder

True if this shape is a placeholder. A shape is a placeholder if it has a <p:ph> element.

left

Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)

name

Name of this shape, e.g. ‘Picture 7’

placeholder_format

A _PlaceholderFormat object providing access to placeholder-specific properties such as placeholder type. Raises ValueError on access if the shape is not a placeholder.

rotation

Read/write float. Degrees of clockwise rotation. Negative values can be assigned to indicate counter-clockwise rotation, e.g. assigning -45.0 will change setting to 315.0.

shadow

ShadowFormat object providing access to shadow for this shape.

A ShadowFormat object is always returned, even when no shadow is explicitly defined on this shape (i.e. it inherits its shadow behavior).

shape_id

Read-only positive integer identifying this shape.

The id of a shape is unique among all shapes on a slide.

shape_type

Unique integer identifying the type of this shape, like MSO_SHAPE_TYPE.CHART. Must be implemented by subclasses.

top

Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)

width

Read/write. Integer distance between left and right extents of shape in EMUs

Shape objects (AutoShapes)

The following properties and methods are defined for AutoShapes, which include text boxes and placeholders.

class pptx.shapes.autoshape.Shape[source]

A shape that can appear on a slide. Corresponds to the <p:sp> element that can appear in any of the slide-type parts (slide, slideLayout, slideMaster, notesPage, notesMaster, handoutMaster).

adjustments

Read-only reference to AdjustmentCollection instance for this shape

auto_shape_type

Enumeration value identifying the type of this auto shape, like MSO_SHAPE.ROUNDED_RECTANGLE. Raises ValueError if this shape is not an auto shape.

fill

FillFormat instance for this shape, providing access to fill properties such as fill color.

has_text_frame

True if this shape can contain text. Always True for an AutoShape.

line

LineFormat instance for this shape, providing access to line properties such as line color.

shape_type

Unique integer identifying the type of this shape, like MSO_SHAPE_TYPE.TEXT_BOX.

text

Read/write. All the text in this shape as a single string. A line feed character (‘\n’) appears in the string for each paragraph and line break in the shape, except the last paragraph. A shape containing a single paragraph with no line breaks will produce a string having no line feed characters. Assigning a string to this property replaces all text in the shape with a single paragraph containing the assigned text. The assigned value can be a 7-bit ASCII string, a UTF-8 encoded 8-bit string, or unicode. String values are converted to unicode assuming UTF-8 encoding. Each line feed character in an assigned string is translated into a line break within the single resulting paragraph.

text_frame

TextFrame instance for this shape, containing the text of the shape and providing access to text formatting properties.

AdjustmentCollection objects

An AutoShape is distinctive in that it can have adjustments, represented in the PowerPoint user interface as small yellow diamonds that each allow a parameter of the shape, such as the angle of an arrowhead, to be adjusted. The AdjustmentCollection object holds these adjustment values for an AutoShape, each of which is an Adjustment instance.

The AdjustmentCollection instance for an AutoShape is accessed using the Shape.adjustments property (read-only).

class pptx.shapes.autoshape.AdjustmentCollection(prstGeom)[source]

Sequence of Adjustment instances for an auto shape, each representing an available adjustment for a shape of its type. Supports len() and indexed access, e.g. shape.adjustments[1] = 0.15.

Adjustment objects

class pptx.shapes.autoshape.Adjustment(name, def_val, actual=None)[source]

An adjustment value for an autoshape.

An adjustment value corresponds to the position of an adjustment handle on an auto shape. Adjustment handles are the small yellow diamond-shaped handles that appear on certain auto shapes and allow the outline of the shape to be adjusted. For example, a rounded rectangle has an adjustment handle that allows the radius of its corner rounding to be adjusted.

Values are float and generally range from 0.0 to 1.0, although the value can be negative or greater than 1.0 in certain circumstances.

effective_value

Read/write float representing normalized adjustment value for this adjustment. Actual values are a large-ish integer expressed in shape coordinates, nominally between 0 and 100,000. The effective value is normalized to a corresponding value nominally between 0.0 and 1.0. Intuitively this represents the proportion of the width or height of the shape at which the adjustment value is located from its starting point. For simple shapes such as a rounded rectangle, this intuitive correspondence holds. For more complicated shapes and at more extreme shape proportions (e.g. width is much greater than height), the value can become negative or greater than 1.0.

val

Denormalized effective value (expressed in shape coordinates), suitable for using in the XML.

Connector objects

The following properties and methods are defined for Connector shapes:

class pptx.shapes.connector.Connector[source]

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 line can be straight, have elbows, or can be curved.

begin_connect(shape, cxn_pt_idx)[source]

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.

begin_x

Return the X-position of the begin point of this connector, in English Metric Units (as a Length object).

begin_y

Return the Y-position of the begin point of this connector, in English Metric Units (as a Length object).

end_connect(shape, cxn_pt_idx)[source]

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.

end_x

Return the X-position of the end point of this connector, in English Metric Units (as a Length object).

end_y

Return the Y-position of the end point of this connector, in English Metric Units (as a Length object).

FreeformBuilder objects

The following properties and methods are defined for FreeformBuilder objects. A freeform builder is used to create a shape with custom geometry:

class pptx.shapes.freeform.FreeformBuilder[source]

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

add_line_segments(vertices, close=True)[source]

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.

convert_to_shape(origin_x=0, origin_y=0)[source]

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.

move_to(x, y)[source]

Move pen to (x, y) (local coordinates) without drawing line.

Returns this FreeformBuilder object so it can be used in chained calls.

Picture objects

The following properties and methods are defined for picture shapes.

class pptx.shapes.picture.Picture[source]

A picture shape, one that places an image on a slide.

Based on the p:pic element.

click_action

ActionSetting instance providing access to click behaviors.

Click behaviors are hyperlink-like behaviors including jumping to a hyperlink (web page) or to another slide in the presentation. The click action is that defined on the overall shape, not a run of text within the shape. An ActionSetting object is always returned, even when no click behavior is defined on the shape.

crop_bottom

float representing relative portion cropped from shape bottom.

Read/write. 1.0 represents 100%. For example, 25% is represented by 0.25. Negative values are valid as are values greater than 1.0.

crop_left

float representing relative portion cropped from left of shape.

Read/write. 1.0 represents 100%. A negative value extends the side beyond the image boundary.

crop_right

float representing relative portion cropped from right of shape.

Read/write. 1.0 represents 100%.

crop_top

float representing relative portion cropped from shape top.

Read/write. 1.0 represents 100%.

element

lxml element for this shape, e.g. a CT_Shape instance.

Note that manipulating this element improperly can produce an invalid presentation file. Make sure you know what you’re doing if you use this to change the underlying XML.

has_chart

True if this shape is a graphic frame containing a chart object. False otherwise. When True, the chart object can be accessed using the .chart property.

has_table

True if this shape is a graphic frame containing a table object. False otherwise. When True, the table object can be accessed using the .table property.

has_text_frame

True if this shape can contain text.

height

Read/write. Integer distance between top and bottom extents of shape in EMUs

is_placeholder

True if this shape is a placeholder. A shape is a placeholder if it has a <p:ph> element.

left

Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)

line

An instance of LineFormat, providing access to the properties of the outline bordering this shape, such as its color and width.

name

Name of this shape, e.g. ‘Picture 7’

part

The package part containing this shape.

A BaseSlidePart subclass in this case. Access to a slide part should only be required if you are extending the behavior of python-pptx API objects.

placeholder_format

A _PlaceholderFormat object providing access to placeholder-specific properties such as placeholder type. Raises ValueError on access if the shape is not a placeholder.

rotation

Read/write float. Degrees of clockwise rotation. Negative values can be assigned to indicate counter-clockwise rotation, e.g. assigning -45.0 will change setting to 315.0.

shadow

ShadowFormat object providing access to shadow for this shape.

A ShadowFormat object is always returned, even when no shadow is explicitly defined on this shape (i.e. it inherits its shadow behavior).

shape_id

Read-only positive integer identifying this shape.

The id of a shape is unique among all shapes on a slide.

top

Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)

width

Read/write. Integer distance between left and right extents of shape in EMUs

image

An Image object providing access to the properties and bytes of the image in this picture shape.

shape_type

Unique integer identifying the type of this shape, unconditionally MSO_SHAPE_TYPE.PICTURE in this case.

GraphicFrame objects

The following properties and methods are defined for graphic frame shapes. A graphic frame is the shape containing a table, chart, or smart art.

class pptx.shapes.graphfrm.GraphicFrame[source]

Bases: pptx.shapes.base.BaseShape

Container shape for table, chart, smart art, and media objects.

Corresponds to a <p:graphicFrame> element in the shape tree.

chart

The Chart object containing the chart in this graphic frame. Raises ValueError if this graphic frame does not contain a chart.

click_action

ActionSetting instance providing access to click behaviors.

Click behaviors are hyperlink-like behaviors including jumping to a hyperlink (web page) or to another slide in the presentation. The click action is that defined on the overall shape, not a run of text within the shape. An ActionSetting object is always returned, even when no click behavior is defined on the shape.

element

lxml element for this shape, e.g. a CT_Shape instance.

Note that manipulating this element improperly can produce an invalid presentation file. Make sure you know what you’re doing if you use this to change the underlying XML.

has_chart

True if this graphic frame contains a chart object. False otherwise. When True, the chart object can be accessed using the .chart property.

has_table

True if this graphic frame contains a table object. False otherwise. When True, the table object can be accessed using the .table property.

height

Read/write. Integer distance between top and bottom extents of shape in EMUs

left

Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)

name

Name of this shape, e.g. ‘Picture 7’

rotation

Read/write float. Degrees of clockwise rotation. Negative values can be assigned to indicate counter-clockwise rotation, e.g. assigning -45.0 will change setting to 315.0.

shadow

Unconditionally raises NotImplementedError.

Access to the shadow effect for graphic-frame objects is content-specific (i.e. different for charts, tables, etc.) and has not yet been implemented.

shape_id

Read-only positive integer identifying this shape.

The id of a shape is unique among all shapes on a slide.

table

The Table object contained in this graphic frame. Raises ValueError if this graphic frame does not contain a table.

top

Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)

width

Read/write. Integer distance between left and right extents of shape in EMUs

GroupShape objects

The following properties and methods are defined for group shapes. A group shape acts as a container for other shapes.

Note that:

  • A group shape has no text frame and cannot have one.
  • A group shape cannot have a click action, such as a hyperlink.
class pptx.shapes.group.GroupShape[source]

Bases: pptx.shapes.base.BaseShape

A shape that acts as a container for other shapes.

click_action

Unconditionally raises TypeError.

A group shape cannot have a click action or hover action.

element

lxml element for this shape, e.g. a CT_Shape instance.

Note that manipulating this element improperly can produce an invalid presentation file. Make sure you know what you’re doing if you use this to change the underlying XML.

has_text_frame

Unconditionally False.

A group shape does not have a textframe and cannot itself contain text. This does not impact the ability of shapes contained by the group to each have their own text.

height

Read/write. Integer distance between top and bottom extents of shape in EMUs

left

Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)

name

Name of this shape, e.g. ‘Picture 7’

part

The package part containing this shape.

A BaseSlidePart subclass in this case. Access to a slide part should only be required if you are extending the behavior of python-pptx API objects.

rotation

Read/write float. Degrees of clockwise rotation. Negative values can be assigned to indicate counter-clockwise rotation, e.g. assigning -45.0 will change setting to 315.0.

shadow

ShadowFormat object representing shadow effect for this group.

A ShadowFormat object is always returned, even when no shadow is explicitly defined on this group shape (i.e. when the group inherits its shadow behavior).

shape_id

Read-only positive integer identifying this shape.

The id of a shape is unique among all shapes on a slide.

shape_type

Member of MSO_SHAPE_TYPE identifying the type of this shape.

Unconditionally MSO_SHAPE_TYPE.GROUP in this case

shapes

GroupShapes object for this group.

The GroupShapes object provides access to the group’s member shapes and provides methods for adding new ones.

top

Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)

width

Read/write. Integer distance between left and right extents of shape in EMUs