Placeholder — Aspose.Slides FOSS Python API Reference

A placeholder is a reserved region on a layout or master slide that defines a default position, size, and formatting for a particular type of content (title, body text, footer, date, slide number, etc.). When a regular slide is based on a layout that has placeholders, the corresponding shapes on the slide inherit those positions and formats.

Package: aspose.slides_foss

How Placeholders Work in This Implementation

Placeholders are represented internally as ordinary shapes whose XML carries a <p:ph> element specifying the placeholder type and index. The Shape class reads <p:ph> to determine whether a shape is a placeholder and walks the layout → master inheritance chain to resolve the shape’s position when no local <a:xfrm> is defined.

There is no standalone Placeholder class file in this release; placeholder identity is carried by the underlying AutoShape, Table, or other shape.

Detecting Placeholder Shapes

A shape on a layout or slide XML is a placeholder when its nvSpPr/nvPr (or equivalent non-visual properties block) contains a <p:ph> element.

The Shape base class exposes the internal helper _get_placeholder_info() which returns a (ph_type, ph_idx) tuple or None for non-placeholder shapes.

Layout and Master Placeholder Inheritance

When a slide shape does not have its own <a:xfrm> element, the framework resolves position and size from the matching placeholder in the layout slide, and then from the master slide if the layout does not define one either. This inheritance is handled automatically; client code only accesses shape.x, shape.y, shape.width, and shape.height.

PlaceholderType (declared in __all__)

The following placeholder types are declared in the public API surface. They map to the type attribute of <p:ph> in OOXML:

Code Examples

Identify Placeholder Shapes on a Layout

import aspose.slides_foss as slides

with slides.Presentation("deck.pptx") as prs:
    layout = prs.layout_slides[0]
    print(f"Layout: {layout.name!r}")
    for shape in layout.shapes:
        # Access the internal placeholder info via the XML helper
        ph_info = shape._get_placeholder_info() if hasattr(shape, '_get_placeholder_info') else None
        if ph_info:
            ph_type, ph_idx = ph_info
            print(f"  Placeholder: type={ph_type!r}  idx={ph_idx}"
                  f"  at ({shape.x:.0f}, {shape.y:.0f})")
        else:
            print(f"  Regular shape: {shape.name!r}")

Add a Slide and Work with Its Title Placeholder

import aspose.slides_foss as slides
from aspose.slides_foss import SlideLayoutType
from aspose.slides_foss.export import SaveFormat

with slides.Presentation() as prs:
    # Use the Title layout which has a title placeholder
    title_layout = prs.layout_slides.get_by_type(SlideLayoutType.TITLE)
    if title_layout is None:
        title_layout = prs.layout_slides[0]

    slide = prs.slides.add_empty_slide(title_layout)

    # The first shape on a TITLE layout is typically the title placeholder
    for shape in slide.shapes:
        if hasattr(shape, 'add_text_frame'):
            shape.add_text_frame("Quarterly Review")
            break

    prs.save("titled-slide.pptx", SaveFormat.PPTX)

Add Text to All Shapes on a Slide (Including Placeholders)

import aspose.slides_foss as slides
from aspose.slides_foss.export import SaveFormat

with slides.Presentation("template.pptx") as prs:
    slide = prs.slides[0]
    for i, shape in enumerate(slide.shapes):
        if hasattr(shape, 'add_text_frame'):
            try:
                shape.add_text_frame(f"Content {i + 1}")
            except Exception:
                pass  # some shapes may not accept text
    prs.save("filled.pptx", SaveFormat.PPTX)

See Also

• Slide class reference
• LayoutSlide / MasterSlide reference
• Shape class reference
• ShapeCollection reference
• Slides Python API Reference home