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¶Placeholder shape on a slide master.
Enumeration value identifying the type of this auto shape, like
MSO_SHAPE.ROUNDED_RECTANGLE. Raises ValueError if this shape is
not an auto shape.
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.
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.
FillFormat instance for this shape, providing access to fill
properties such as fill color.
True if this shape can contain text. Always True for an
AutoShape.
Read/write. Integer distance between top and bottom extents of shape in EMUs
True if this shape is a placeholder. A shape is a placeholder if it has a <p:ph> element.
Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)
LineFormat instance for this shape, providing access to line
properties such as line color.
Name of this shape, e.g. ‘Picture 7’
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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).
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
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).
TextFrame instance for this shape.
Contains the text of the shape and provides access to text formatting properties.
Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)
Read/write. Integer distance between left and right extents of shape in EMUs
LayoutPlaceholder objects¶Placeholder shape that can only accept a chart.
Read-only reference to AdjustmentCollection instance for this
shape
Enumeration value identifying the type of this auto shape, like
MSO_SHAPE.ROUNDED_RECTANGLE. Raises ValueError if this shape is
not an auto shape.
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.
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.
FillFormat instance for this shape, providing access to fill
properties such as fill color.
Return the <a:ln> element containing the line format properties
XML for this shape.
The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.
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.
Boolean indicating whether this shape is a placeholder.
Unconditionally True in this case.
The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.
LineFormat instance for this shape, providing access to line
properties such as line color.
The <a:ln> element containing the line format properties such as
line color and width. None if no <a:ln> element is present.
Name of this shape, e.g. ‘Picture 7’
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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).
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
Member of MSO_SHAPE_TYPE specifying the type of this shape.
Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case.
Read-only.
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).
TextFrame instance for this shape.
Contains the text of the shape and provides access to text formatting properties.
The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.
The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.
Placeholder shape that can only accept a picture.
Read-only reference to AdjustmentCollection instance for this
shape
Enumeration value identifying the type of this auto shape, like
MSO_SHAPE.ROUNDED_RECTANGLE. Raises ValueError if this shape is
not an auto shape.
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.
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.
FillFormat instance for this shape, providing access to fill
properties such as fill color.
Return the <a:ln> element containing the line format properties
XML for this shape.
The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.
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.
Boolean indicating whether this shape is a placeholder.
Unconditionally True in this case.
The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.
LineFormat instance for this shape, providing access to line
properties such as line color.
The <a:ln> element containing the line format properties such as
line color and width. None if no <a:ln> element is present.
Name of this shape, e.g. ‘Picture 7’
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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).
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
Member of MSO_SHAPE_TYPE specifying the type of this shape.
Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case.
Read-only.
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).
TextFrame instance for this shape.
Contains the text of the shape and provides access to text formatting properties.
The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.
The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.
Placeholder shape that can only accept a table.
Read-only reference to AdjustmentCollection instance for this
shape
Enumeration value identifying the type of this auto shape, like
MSO_SHAPE.ROUNDED_RECTANGLE. Raises ValueError if this shape is
not an auto shape.
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.
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.
FillFormat instance for this shape, providing access to fill
properties such as fill color.
Return the <a:ln> element containing the line format properties
XML for this shape.
The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.
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.
The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.
LineFormat instance for this shape, providing access to line
properties such as line color.
The <a:ln> element containing the line format properties such as
line color and width. None if no <a:ln> element is present.
Name of this shape, e.g. ‘Picture 7’
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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).
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
Member of MSO_SHAPE_TYPE specifying the type of this shape.
Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case.
Read-only.
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).
TextFrame instance for this shape.
Contains the text of the shape and provides access to text formatting properties.
The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.
The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.
Placeholder shape populated with a table, chart, or smart art.
The Chart object containing the chart in this graphic frame.
Raises ValueError if this graphic frame does not contain a chart.
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.
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.
True if this graphic frame contains a chart object. False otherwise.
When True, the chart object can be accessed using the .chart property.
True if this graphic frame contains a table object, False otherwise.
When True, the table object can be accessed using the .table property.
Read/write. Integer distance between top and bottom extents of shape in EMUs
Read/write. Integer distance of the left edge of this shape from the left edge of the slide, in English Metric Units (EMU)
Name of this shape, e.g. ‘Picture 7’
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.
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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.
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
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.
The Table object contained in this graphic frame. Raises
ValueError if this graphic frame does not contain a table.
Read/write. Integer distance of the top edge of this shape from the top edge of the slide, in English Metric Units (EMU)
Read/write. Integer distance between left and right extents of shape in EMUs
Placeholder shape populated with a picture.
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.
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.
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.
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.
float representing relative portion cropped from right of shape.
Read/write. 1.0 represents 100%.
float representing relative portion cropped from shape top.
Read/write. 1.0 represents 100%.
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.
The effective height of this placeholder shape; its directly-applied height if it has one, otherwise the height of its parent layout placeholder.
An Image object providing access to the properties and bytes of the
image in this picture shape.
True if this shape is a placeholder. A shape is a placeholder if it has a <p:ph> element.
The effective left of this placeholder shape; its directly-applied left if it has one, otherwise the left of its parent layout placeholder.
An instance of LineFormat, providing access to the properties of
the outline bordering this shape, such as its color and width.
Name of this shape, e.g. ‘Picture 7’
A _PlaceholderFormat object providing access to
placeholder-specific properties such as placeholder type. Raises
ValueError on access if the shape is not a placeholder.
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.
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).
Read-only positive integer identifying this shape.
The id of a shape is unique among all shapes on a slide.
Member of MSO_SHAPE_TYPE specifying the type of this shape.
Unconditionally MSO_SHAPE_TYPE.PLACEHOLDER in this case.
Read-only.
The effective top of this placeholder shape; its directly-applied top if it has one, otherwise the top of its parent layout placeholder.
The effective width of this placeholder shape; its directly-applied width if it has one, otherwise the width of its parent layout placeholder.
Accessed via the placeholder_format property of
a placeholder shape, provides properties specific to placeholders, such
as the placeholder type.
The p:ph element proxied by this object.
Integer placeholder ‘idx’ attribute.
Placeholder type, a member of the PP_PLACEHOLDER_TYPE enumeration, e.g. PP_PLACEHOLDER.CHART