Text Formatting: TextFrame Tools¶

Reference for the textframe tool's actions — set-text, get-text, find-text, replace-text, set-font-size/get-font-size, set-bold/get-bold, set-font-color/get-font-color, set-italic/get-italic, set-underline/get-underline, set-font-name/get-font-name, set-alignment/get-alignment, set-bullet/get-bullet, set-autosize/get-autosize — all operate on a shape's text frame.

Actions¶

Find and Replace Within One Shape¶

Select a text-bearing shape using its 1-based slide_index and shape_index. Both actions use literal PowerPoint matching, not regex or wildcard patterns. match_case and whole_words default to false; whole-word boundaries follow PowerPoint's native rules. Empty search text is invalid, but whitespace is literal. Missing replacement text is an error; an explicit replace_what: "" deletes matches.

find-text reports non-overlapping matches in ascending order. Each start is a 1-based PowerPoint character position in the original frame, with a length and the original matched text. No match is a successful result with zero matches.

replace-text collects original matches before editing, then replaces ranges from right to left. Inserted text is never searched again, including when it contains the search term. The count includes identical replacements. It does not assign a new string to the whole frame, preserving character formatting outside matched ranges. Replacement styling and paragraph merging when deleting paragraph breaks follow PowerPoint's native text editing behavior.

These actions do not traverse groups, tables, notes, other shapes, or other slides. A shape without a text frame returns an error. Unexpected COM failures can leave partial edits; no transactional rollback is promised. Save explicitly when done.

textframe(action: "find-text", presentation_session_id: ..., slide_index: 1, shape_index: 2, find_what: "Draft", whole_words: true)
textframe(action: "replace-text", presentation_session_id: ..., slide_index: 1, shape_index: 2, find_what: "Draft", replace_what: "Final", whole_words: true)

CLI equivalents use pptcli textframe find-text / replace-text, --session, --slide-index, --shape-index, --find-what, --replace-what, --match-case, and --whole-words. Use live --help for exact option syntax.

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", presentation_session_id: ..., slide_index: ..., shape_index: ..., text: "A long paragraph that might overflow the box...")
textframe(action: "set-autosize", presentation_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", presentation_session_id: ..., slide_index: ..., left: 50, top: 100, width: 150, height: 30, text: "Revenue:")
textframe(action: "set-bold", presentation_session_id: ..., slide_index: ..., shape_index: <label shapeIndex>, bold: true)
shape(action: "add-text-box", presentation_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", presentation_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", presentation_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", presentation_session_id: ..., slide_index: ..., shape_index: ..., red: 68, green: 114, blue: 196)

Read Before You Overwrite¶

set-text replaces the whole text frame content. For a literal substring edit, use find-text followed by replace-text to avoid rewriting unrelated character formatting. To append 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", presentation_session_id: ..., slide_index: ..., shape_index: ...) → "Q3 Results"
textframe(action: "set-text", presentation_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", ...).