PlaceholderPicture

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 :ref:MsoAutoShapeType.

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.

True if this shape is a graphic frame containing a chart object.

False otherwise. When True, the chart object can be accessed using the .chart property.

True if this shape is a graphic frame containing a table object.

False otherwise. When True, the table object can be accessed using the .table property.

True if this shape can contain text.

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

The Image object for this picture.

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

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

The a:ln element for this p:pic.

Contains 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'.

The package part containing this shape.

A BaseSlidePart subclass in this case. Access to a slide part should only be required if you are extending the behavior of pp API objects.

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

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

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.

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 :ref:MsoShapeType 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.

Return the a:ln element for this p:pic-based image.

The a:ln element contains the line format properties XML.

Replace the image behind this picture, preserving its geometry exactly.

paper-pptx addition. Position, size, rotation, masking geometry, and crop (a:srcRect) are not touched — only the a:blip/@r:embed target changes. By default the new image's canonical format must match the existing image part's extension (jpg == jpeg); a mismatch refuses with UnsupportedStructureError. Passing allow_format_change=True permits a cross-format swap: the new image gets its own correctly-typed part and [Content_Types].xml follows automatically at save (it is regenerated from live parts).

A picture with no embedded image relationship (e.g. linked-only) refuses. The new image part is deduplicated package-wide by content hash; the old image part simply becomes unreferenced when this picture held its last reference (an unreachable part is never serialized).