Placeholders

The following classes represent placeholder shapes. A placeholder most commonly appears on a slide, but also appears on a slide layout and a slide master. The role of a master placeholder and layout placeholder differs from that of a slide placeholder and these roles are reflected in the distinct classes for each.

There are a larger variety of slide placeholders to accomodate their more complex and varied behaviors.

MasterPlaceholder objects

class pptx.shapes.placeholder.MasterPlaceholder

Placeholder shape on a slide master.

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

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.

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

fill

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

property has_text_frame

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

property height

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

property is_placeholder

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

property 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

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

property name

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property text

Read/write. Unicode (str in Python 3) representation of shape text.

The returned string will contain a newline character ("\n") separating each paragraph and a vertical-tab ("\v") character for each line break (soft carriage return) in the shape’s text.

Assignment to text replaces all text previously contained in the shape, along with any paragraph or font formatting applied to it. A newline character ("\n") in the assigned text causes a new paragraph to be started. A vertical-tab ("\v") character in the assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab character appears in clipboard text copied from PowerPoint as its encoding of line-breaks.)

Either bytes (Python 2 str) or unicode (Python 3 str) can be assigned. Bytes can be 7-bit ASCII or UTF-8 encoded 8-bit bytes. Bytes values are converted to unicode assuming UTF-8 encoding (which also works for ASCII).

property text_frame

TextFrame instance for this shape.

Contains the text of the shape and provides access to text formatting properties.

property top

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

property width

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

LayoutPlaceholder objects

class pptx.shapes.placeholder.LayoutPlaceholder

Placeholder shape on a slide layout, providing differentiated behavior for slide layout placeholders, in particular, inheriting shape properties from the master placeholder having the same type, when a matching one exists.

ChartPlaceholder objects

class pptx.shapes.placeholder.ChartPlaceholder

Placeholder shape that can only accept a chart.

adjustments

Read-only reference to AdjustmentCollection instance for this shape

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

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.

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

fill

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

get_or_add_ln()

Return the <a:ln> element containing the line format properties XML for this shape.

property height

The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.

insert_chart(chart_type, chart_data)

Return a PlaceholderGraphicFrame object containing a new chart of chart_type depicting chart_data and having the same position and size as this placeholder. 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 the new Chart object is not returned directly. The chart object may be accessed using the chart property of the returned PlaceholderGraphicFrame object.

property is_placeholder

Boolean indicating whether this shape is a placeholder. Unconditionally True in this case.

property left

The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.

line

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

property ln

The <a:ln> element containing the line format properties such as line color and width. None if no <a:ln> element is present.

property name

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property shape_type

Member of MSO_SHAPE_TYPE specifying the type of this shape. Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case. Read-only.

property text

Read/write. Unicode (str in Python 3) representation of shape text.

The returned string will contain a newline character ("\n") separating each paragraph and a vertical-tab ("\v") character for each line break (soft carriage return) in the shape’s text.

Assignment to text replaces all text previously contained in the shape, along with any paragraph or font formatting applied to it. A newline character ("\n") in the assigned text causes a new paragraph to be started. A vertical-tab ("\v") character in the assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab character appears in clipboard text copied from PowerPoint as its encoding of line-breaks.)

Either bytes (Python 2 str) or unicode (Python 3 str) can be assigned. Bytes can be 7-bit ASCII or UTF-8 encoded 8-bit bytes. Bytes values are converted to unicode assuming UTF-8 encoding (which also works for ASCII).

property text_frame

TextFrame instance for this shape.

Contains the text of the shape and provides access to text formatting properties.

property top

The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.

property width

The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.

PicturePlaceholder objects

class pptx.shapes.placeholder.PicturePlaceholder

Placeholder shape that can only accept a picture.

adjustments

Read-only reference to AdjustmentCollection instance for this shape

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

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.

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

fill

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

get_or_add_ln()

Return the <a:ln> element containing the line format properties XML for this shape.

property height

The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.

insert_picture(image_file)

Return a PlaceholderPicture object depicting the image in image_file.

image_file may be either a path (string) or a file-like object. The image is cropped to fill the entire space of the placeholder. A PlaceholderPicture object has all the properties and methods of a Picture shape except that the value of its shape_type property is MSO_SHAPE_TYPE.PLACEHOLDER instead of MSO_SHAPE_TYPE.PICTURE.

property is_placeholder

Boolean indicating whether this shape is a placeholder. Unconditionally True in this case.

property left

The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.

line

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

property ln

The <a:ln> element containing the line format properties such as line color and width. None if no <a:ln> element is present.

property name

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property shape_type

Member of MSO_SHAPE_TYPE specifying the type of this shape. Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case. Read-only.

property text

Read/write. Unicode (str in Python 3) representation of shape text.

The returned string will contain a newline character ("\n") separating each paragraph and a vertical-tab ("\v") character for each line break (soft carriage return) in the shape’s text.

Assignment to text replaces all text previously contained in the shape, along with any paragraph or font formatting applied to it. A newline character ("\n") in the assigned text causes a new paragraph to be started. A vertical-tab ("\v") character in the assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab character appears in clipboard text copied from PowerPoint as its encoding of line-breaks.)

Either bytes (Python 2 str) or unicode (Python 3 str) can be assigned. Bytes can be 7-bit ASCII or UTF-8 encoded 8-bit bytes. Bytes values are converted to unicode assuming UTF-8 encoding (which also works for ASCII).

property text_frame

TextFrame instance for this shape.

Contains the text of the shape and provides access to text formatting properties.

property top

The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.

property width

The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.

TablePlaceholder objects

class pptx.shapes.placeholder.TablePlaceholder

Placeholder shape that can only accept a table.

adjustments

Read-only reference to AdjustmentCollection instance for this shape

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

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.

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

fill

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

get_or_add_ln()

Return the <a:ln> element containing the line format properties XML for this shape.

property height

The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.

insert_table(rows, cols)

Return PlaceholderGraphicFrame object containing a rows by cols table.

The position and width of the table are those of the placeholder and its height is proportional to the number of rows. A PlaceholderGraphicFrame object has all the properties and methods of a GraphicFrame shape except that the value of its shape_type property is unconditionally MSO_SHAPE_TYPE.PLACEHOLDER. Note that the return value is not the new table but rather contains the new table. The table can be accessed using the table property of the returned PlaceholderGraphicFrame object.

property left

The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.

line

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

property ln

The <a:ln> element containing the line format properties such as line color and width. None if no <a:ln> element is present.

property name

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property shape_type

Member of MSO_SHAPE_TYPE specifying the type of this shape. Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case. Read-only.

property text

Read/write. Unicode (str in Python 3) representation of shape text.

The returned string will contain a newline character ("\n") separating each paragraph and a vertical-tab ("\v") character for each line break (soft carriage return) in the shape’s text.

Assignment to text replaces all text previously contained in the shape, along with any paragraph or font formatting applied to it. A newline character ("\n") in the assigned text causes a new paragraph to be started. A vertical-tab ("\v") character in the assigned text causes a line-break (soft carriage-return) to be inserted. (The vertical-tab character appears in clipboard text copied from PowerPoint as its encoding of line-breaks.)

Either bytes (Python 2 str) or unicode (Python 3 str) can be assigned. Bytes can be 7-bit ASCII or UTF-8 encoded 8-bit bytes. Bytes values are converted to unicode assuming UTF-8 encoding (which also works for ASCII).

property text_frame

TextFrame instance for this shape.

Contains the text of the shape and provides access to text formatting properties.

property top

The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.

property width

The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.

PlaceholderGraphicFrame objects

class pptx.shapes.placeholder.PlaceholderGraphicFrame

Placeholder shape populated with a table, chart, or smart art.

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

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

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

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.

property height

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

property left

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

property name

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

property ole_format

Optional _OleFormat object for this graphic-frame shape.

Raises ValueError on a GraphicFrame instance that does not contain an OLE object.

An shape that contains an OLE object will have .shape_type of either EMBEDDED_OLE_OBJECT or LINKED_OLE_OBJECT.

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property shape_type

Optional member of MSO_SHAPE_TYPE identifying the type of this shape.

Possible values are MSO_SHAPE_TYPE.CHART, MSO_SHAPE_TYPE.TABLE, MSO_SHAPE_TYPE.EMBEDDED_OLE_OBJECT, MSO_SHAPE_TYPE.LINKED_OLE_OBJECT.

This value is None when none of these four types apply, for example when the shape contains SmartArt.

property table

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

property top

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

property width

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

PlaceholderPicture objects

class pptx.shapes.placeholder.PlaceholderPicture

Placeholder shape populated with a picture.

property auto_shape_type

Member of MSO_SHAPE indicating masking shape.

A picture can be masked by any of the so-called “auto-shapes” available in PowerPoint, such as an ellipse or triangle. When a picture is masked by a shape, the shape assumes the same dimensions as the picture and the portion of the picture outside the shape boundaries does not appear. Note the default value for a newly-inserted picture is MSO_AUTO_SHAPE_TYPE.RECTANGLE, which performs no cropping because the extents of the rectangle exactly correspond to the extents of the picture.

The available shapes correspond to the members of MSO_AUTO_SHAPE_TYPE.

The return value can also be None, indicating the picture either has no geometry (not expected) or has custom geometry, like a freeform shape. A picture with no geometry will have no visible representation on the slide, although it can be selected. This is because without geometry, there is no “inside-the-shape” for it to appear in.

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.

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

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

property crop_right

float representing relative portion cropped from right of shape.

Read/write. 1.0 represents 100%.

property crop_top

float representing relative portion cropped from shape top.

Read/write. 1.0 represents 100%.

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

property height

The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.

property image

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

property is_placeholder

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

property left

The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.

line

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

property name

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

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

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

property shape_id

Read-only positive integer identifying this shape.

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

property shape_type

Member of MSO_SHAPE_TYPE specifying the type of this shape. Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case. Read-only.

property top

The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.

property width

The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.

_PlaceholderFormat objects

class pptx.shapes.base._PlaceholderFormat

Accessed via the placeholder_format property of a placeholder shape, provides properties specific to placeholders, such as the placeholder type.

property element

The p:ph element proxied by this object.

property idx

Integer placeholder ‘idx’ attribute.

property type

Placeholder type, a member of the PP_PLACEHOLDER_TYPE enumeration, e.g. PP_PLACEHOLDER.CHART