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

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

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.

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.

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)

line

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

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.

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.

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

LayoutPlaceholder objects

class pptx.shapes.placeholder.LayoutPlaceholder[source]

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

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

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.

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.

height

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

id

DEPRECATED. Use .shape_id instead.

insert_chart(chart_type, chart_data)[source]

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, providing 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

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

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

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.

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

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

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.

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.

height

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

id

DEPRECATED. Use .shape_id instead.

insert_picture(image_file)[source]

Return a PlaceholderPicture object depicting the image in image_file, which 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, providing 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

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

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

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.

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

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

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.

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.

height

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

id

DEPRECATED. Use .shape_id instead.

insert_table(rows, cols)[source]

Return a PlaceholderGraphicFrame object containing a table of rows rows and cols columns. 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, providing 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

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

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

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.

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

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

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’

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, e.g. MSO_SHAPE_TYPE.TABLE.

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

PlaceholderPicture objects

class pptx.shapes.placeholder.PlaceholderPicture[source]

Placeholder shape populated with a picture.

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.

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

element

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

height

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

id

DEPRECATED. Use .shape_id instead.

image

An Image object providing 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

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

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

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

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

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