mcp-server-ppt ppt-com-patterns-guide.instructions.md

PowerPoint COM Patterns - Quick Reference

Essential patterns for PowerPoint COM automation via late binding

Core Principles

1. Use Late Binding - dynamic types with Type.GetTypeFromProgID("PowerPoint.Application")
2. 1-Based Indexing - All PowerPoint collections (Slides, Shapes, Paragraphs) start at 1
3. Exception Propagation - Never wrap in try-catch; let batch.Execute() handle exceptions
4. msoTrue / msoFalse - PowerPoint uses MsoTriState: msoTrue = -1, msoFalse = 0, msoCTrue = 1
5. Points as Units - Positions and sizes are in points (1 inch = 72 points)

---

Decision Tree: Which Tool to Use

Working with presentations?
├─ Slide lifecycle (add, delete, duplicate, move, reorder)?
│  └─ Use slide tool
│
├─ Shapes on a slide (create, modify, delete, position)?
│  └─ Use shape tool
│
├─ Text inside a shape (read, write, format)?
│  └─ Use text / shape tool (TextFrame access)
│
├─ Charts embedded in a slide?
│  └─ Use chart tool
│
├─ Placeholders (title, body, footer)?
│  └─ Use placeholder tool
│
└─ Presentation-level properties (slide size, metadata)?
   └─ Use file / presentation tool

---

Slide Operations

Adding Slides

// Get a slide layout from the first slide master
dynamic slideMaster = presentation.SlideMasters.Item(1);
dynamic customLayout = slideMaster.CustomLayouts.Item(layoutIndex); // 1-based

// Add slide at a specific position
dynamic newSlide = presentation.Slides.AddSlide(position, customLayout);

Navigating Slides

// By index (1-based)
dynamic slide = presentation.Slides.Item(slideIndex);

// By SlideID (stable across reorders)
dynamic slide = presentation.Slides.FindBySlideID(slideId);

// Iterate all slides
for (int i = 1; i <= presentation.Slides.Count; i++)
{
    dynamic slide = presentation.Slides.Item(i);
    // ... process slide ...
    ComUtilities.Release(ref slide!);
}

Deleting and Reordering

// Delete
slide.Delete();

// Move to new position
slide.MoveTo(newPosition); // 1-based target index

// Duplicate (returns SlideRange, not single slide)
dynamic slideRange = slide.Duplicate();
dynamic duplicated = slideRange.Item(1);