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)[source]

Add a new chart of chart_type to the slide, positioned at (x, y), having size (cx, cy), and depicting 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)[source]

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_picture(image_file, left, top, width=None, height=None)[source]

Add picture shape displaying image in image_file, where image_file can be either a path to a file (a string) or a file-like object.

add_shape(autoshape_type_id, left, top, width, height)[source]

Add auto shape 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)[source]

Add text box shape of specified size at specified position on slide.

index(shape)[source]

Return the index of shape in this sequence, raising ValueError if shape is not in the collection.

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.

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, including Shape, Picture, and GraphicFrame.

click_action

An ActionSetting instance providing access to the mouse click behaviors defined on this shape. An ActionSetting object is always returned, even when no click behavior is defined on the shape.

element

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

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

id

DEPRECATED. Use .shape_id instead.

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.

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

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. Corresponds to the <p:pic> element.

crop_bottom

A float representing the relative portion cropped from the bottom of this picture where 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

A float representing the relative portion cropped from the left side of this picture where 1.0 represents 100%.

crop_right

A float representing the relative portion cropped from the right side of this picture where 1.0 represents 100%.

crop_top

A float representing the relative portion cropped from the top of this picture where 1.0 represents 100%.

image

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

line

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

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

An ActionSetting instance providing access to the mouse click behaviors defined on this shape. An ActionSetting object is always returned, even when no click behavior is defined on the shape.

element

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

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

id

DEPRECATED. Use .shape_id instead.

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.

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