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.

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.

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.

Provides access to fill properties such as fill color.

has_text_frame

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

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

Integer distance of the left edge of this shape from the left edge of the slide.

Read/write. Expressed in English Metric Units (EMU)

line

LineFormat instance for this shape.

Provides access to line properties such as line color.

name

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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.

text

Read/write. Text in shape as a single string.

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 any 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 str encoding of line-breaks.)

text_frame

TextFrame instance for this shape.

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

top

Distance from the top edge of the slide to the top edge of this shape.

Read/write. Expressed in English Metric Units (EMU)

width

Distance between left and right extents of this shape.

Read/write. Expressed in English Metric Units (EMU).

LayoutPlaceholder objects

class pptx.shapes.placeholder.LayoutPlaceholder

Placeholder shape on a slide layout.

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

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.

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.

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

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.

is_placeholder

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

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.

Provides access to line properties such as line color.

ln

The a:ln element containing the line format properties such as line color and width.

None if no a:ln element is present.

name

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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

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

text

Read/write. Text in shape as a single string.

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 any 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 str encoding of line-breaks.)

text_frame

TextFrame instance for this shape.

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

top

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

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.

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.

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.

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

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.

is_placeholder

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

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.

Provides access to line properties such as line color.

ln

The a:ln element containing the line format properties such as line color and width.

None if no a:ln element is present.

name

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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

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

text

Read/write. Text in shape as a single string.

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 any 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 str encoding of line-breaks.)

text_frame

TextFrame instance for this shape.

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

top

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

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.

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.

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.

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

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.

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.

Provides access to line properties such as line color.

ln

The a:ln element containing the line format properties such as line color and width.

None if no a:ln element is present.

name

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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

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

text

Read/write. Text in shape as a single string.

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 any 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 str encoding of line-breaks.)

text_frame

TextFrame instance for this shape.

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

top

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

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.

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

Integer distance of the left edge of this shape from the left edge of the slide.

Read/write. Expressed in English Metric Units (EMU)

name

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

ole_format

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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.

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.

table

The Table object contained in this graphic frame.

Raises ValueError if this graphic frame does not contain a table.

top

Distance from the top edge of the slide to the top edge of this shape.

Read/write. Expressed in English Metric Units (EMU)

width

Distance between left and right extents of this shape.

Read/write. Expressed in English Metric Units (EMU).

PlaceholderPicture objects

class pptx.shapes.placeholder.PlaceholderPicture

Placeholder shape populated with a picture.

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.

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.

height

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

image

The Image object for this picture.

Provides access to the properties and bytes of the image in this picture shape.

is_placeholder

True if this shape is a placeholder.

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

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

Provides access to properties of the picture outline, such as its color and width.

name

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

placeholder_format

Provides access to placeholder-specific properties such as placeholder type.

Raises ValueError on access if the shape is not a placeholder.

rotation

Degrees of clockwise rotation.

Read/write float. 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

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

top

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

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

Provides properties specific to placeholders, such as the placeholder type.

Accessed via the placeholder_format property of a placeholder shape,

element

The p:ph element proxied by this object.

idx

Integer placeholder ‘idx’ attribute.

type

Placeholder type.

A member of the PP_PLACEHOLDER_TYPE enumeration, e.g. PP_PLACEHOLDER.CHART