Text Formatting¶

Actions¶

Paragraph Alignment Names¶

alignment for set-alignment must match a real PpParagraphAlignment enum member name exactly: ppAlignLeft, ppAlignCenter, ppAlignRight, ppAlignJustify, ppAlignDistribute, ppAlignThaiDistribute, ppAlignJustifyLow. Passing an unrecognized string returns success: false.

Auto-Fit / Auto-Size¶

auto_size for set-autosize must match a real PpAutoSize enum member name exactly:

Passing an unrecognized string returns success: false. Set this after set-text and any font-size changes — ppAutoSizeTextToFitShape computes the shrink factor from whatever text is in the frame at the moment PowerPoint next reflows it.

textframe(action: "set-text", session_id: ..., slide_index: ..., shape_index: ..., text: "A long paragraph that might overflow the box...")
textframe(action: "set-autosize", session_id: ..., slide_index: ..., shape_index: ..., auto_size: "ppAutoSizeTextToFitShape")

Whole-Range Formatting Only¶

These formatting actions apply to a shape's entire text frame — there is no API here for formatting a substring or a specific run of characters within one text box. If a slide needs mixed formatting (e.g., a bold label next to plain description text), use separate text boxes positioned next to each other rather than trying to mix runs inside one shape:

CORRECT — two text boxes for mixed emphasis
shape(action: "add-text-box", session_id: ..., slide_index: ..., left: 50, top: 100, width: 150, height: 30, text: "Revenue:")
textframe(action: "set-bold", session_id: ..., slide_index: ..., shape_index: <label shapeIndex>, bold: true)
shape(action: "add-text-box", session_id: ..., slide_index: ..., left: 210, top: 100, width: 300, height: 30, text: "$2.4M, up 12%")

Bullet Lists¶

Use textframe(action: "set-bullet", ...) for native PowerPoint bullets — it applies PowerPoint's own bullet glyph and per-paragraph indent, unlike a plain leading -/• character embedded in text. Put each bullet item on its own line (\n-separated) in the text parameter first, then turn bullets on for the whole text range:

textframe(action: "set-text", session_id: ..., slide_index: ..., shape_index: ...,
  text: "Revenue grew 24% year over year\nAPAC now the fastest-growing region\nRetention held steady at 91%")
textframe(action: "set-bullet", session_id: ..., slide_index: ..., shape_index: ..., enabled: true)

If a specific bullet glyph is required (e.g. a dash instead of the theme's default), pass character: textframe(action: "set-bullet", ..., enabled: true, character: "-").

Font Size Guidance¶

Keep to 2-3 distinct font sizes per slide; titles are typically bold, body text typically is not.

Color Values¶

set-font-color takes three separate byte parameters (red, green, blue), each 0-255 — not a hex string. Convert a hex color to decimal triplets before calling:

Hex "4472C4" → red=68, green=114, blue=196
textframe(action: "set-font-color", session_id: ..., slide_index: ..., shape_index: ..., red: 68, green: 114, blue: 196)

Read Before You Overwrite¶

set-text replaces the whole text frame content. If you only need to append or tweak part of an existing shape's text, call get-text first, compose the full new string yourself, and pass the complete result to set-text — there is no append/insert operation.

textframe(action: "get-text", session_id: ..., slide_index: ..., shape_index: ...) → "Q3 Results"
textframe(action: "set-text", session_id: ..., slide_index: ..., shape_index: ..., text: "Q3 Results (Final)")

Verify Text Fit¶

After setting text and font size, export the slide (see export-and-verify.md) to confirm the text fits inside the shape's width/height without visually overflowing. Use set-autosize (see "Auto-Fit / Auto-Size" above) to have PowerPoint handle overflow automatically instead of manually tuning size — ppAutoSizeTextToFitShape shrinks the font to fit a fixed box, ppAutoSizeShapeToFitText grows the box to fit the text. Without auto-size set (ppAutoSizeNone, the default), text can overflow: shorten the text, reduce font_size, or grow the shape with shape(action: "set-size", ...).