iofficeai--officecli/examples/ppt/shapes/shapes-effects.md

Shape Effects and Meta

This demo consists of three files that work together:

• shapes-effects.sh — Shell script that calls officecli commands to generate the deck. It generates a sample PNG inline via a Python heredoc — no external image file is needed.
• shapes-effects.pptx — The generated 5-slide deck (autoFit, flipH/V, image fill, 3D bevel/depth/lighting/material, softEdge/link/name/zorder).
• shapes-effects.md — This file. Covers shape properties not found in shapes-basic or shapes-connectors.

Regenerate

cd examples/ppt
bash shapes/shapes-effects.sh
# → shapes/shapes-effects.pptx

Slides

Slide 1 — autoFit: Text Overflow Behavior

Three textboxes with the same long text and a fixed height, each using a different autoFit= mode.

officecli create shapes-effects.pptx
officecli open shapes-effects.pptx
officecli add shapes-effects.pptx / --type slide

LONGTEXT='Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.'

# autoFit=none — text runs off the box boundary (no shrink, no clip)
officecli add shapes-effects.pptx '/slide[1]' --type textbox \
  --prop x=0.5in --prop y=1.5in --prop width=4in --prop height=1.5in \
  --prop fill=F1FAEE --prop size=18 --prop text="$LONGTEXT" \
  --prop autoFit=none

# autoFit=normal — font size shrinks until all text fits inside the fixed box
officecli add shapes-effects.pptx '/slide[1]' --type textbox \
  --prop x=5in --prop y=1.5in --prop width=4in --prop height=1.5in \
  --prop fill=A8DADC --prop size=18 --prop text="$LONGTEXT" \
  --prop autoFit=normal

# autoFit=shape — box grows taller to accommodate the text at the declared font size
officecli add shapes-effects.pptx '/slide[1]' --type textbox \
  --prop x=9.5in --prop y=1.5in --prop width=4in --prop height=1.5in \
  --prop fill=F4A261 --prop size=18 --prop text="$LONGTEXT" \
  --prop autoFit=shape

Features: autoFit (none — overflows, normal — text shrinks, shape — box grows)

---

Slide 2 — flipH / flipV: Mirror

Four rightArrow shapes showing all combinations of horizontal and vertical flipping.

officecli add shapes-effects.pptx / --type slide

# Original — no flip flags
officecli add shapes-effects.pptx '/slide[2]' --type shape --prop geometry=rightArrow \
  --prop x=0.5in --prop y=2in --prop width=2.8in --prop height=1.5in \
  --prop fill=4472C4 --prop color=FFFFFF --prop bold=true --prop text="original"

# flipH=true — mirror horizontally (arrow points left)
officecli add shapes-effects.pptx '/slide[2]' --type shape --prop geometry=rightArrow \
  --prop x=4in --prop y=2in --prop width=2.8in --prop height=1.5in \
  --prop fill=E63946 --prop color=FFFFFF --prop bold=true --prop text="flipH=true" \
  --prop flipH=true

# flipV=true — mirror vertically (arrow points down-right)
officecli add shapes-effects.pptx '/slide[2]' --type shape --prop geometry=rightArrow \
  --prop x=7.5in --prop y=2in --prop width=2.8in --prop height=1.5in \
  --prop fill=2A9D8F --prop color=FFFFFF --prop bold=true --prop text="flipV=true" \
  --prop flipV=true

# flipH + flipV together — visually 180° rotation, stored as flip flags not rotation
officecli add shapes-effects.pptx '/slide[2]' --type shape --prop geometry=rightArrow \
  --prop x=11in --prop y=2in --prop width=2.8in --prop height=1.5in \
  --prop fill=F4A261 --prop color=000000 --prop bold=true --prop text="flipH + flipV" \
  --prop flipH=true --prop flipV=true

Features: flipH (alias: flipHorizontal), flipV (alias: flipVertical). Flip flags are stored independently of rotation=, so flipH=true + rotation=90 chains predictably.

---

Slide 3 — image=: Picture as Shape Fill (blipFill)

Three shapes with different geometries all filled with an image. The geometry preset clips the bitmap to its outline.

officecli add shapes-effects.pptx / --type slide

# Ellipse with image fill + outline border — image clipped to ellipse shape
officecli add shapes-effects.pptx '/slide[3]' --type shape --prop geometry=ellipse \
  --prop x=0.5in --prop y=1.5in --prop width=3.5in --prop height=3.5in \
  --prop image="$SAMPLE_PNG" \
  --prop lineColor=1D3557 --prop lineWidth=3pt

# Star5 — image clipped to a 5-pointed star
officecli add shapes-effects.pptx '/slide[3]' --type shape --prop geometry=star5 \
  --prop x=4.5in --prop y=1.5in --prop width=3.5in --prop height=3.5in \
  --prop image="$SAMPLE_PNG"

# Diamond with image fill + outline
officecli add shapes-effects.pptx '/slide[3]' --type shape --prop geometry=diamond \
  --prop x=8.5in --prop y=1.5in --prop width=3.5in --prop height=3.5in \
  --prop image="$SAMPLE_PNG" \
  --prop lineColor=1D3557 --prop lineWidth=3pt

Features: image (file path to PNG/JPG — embeds the image as a blipFill inside the shape geometry; the geometry clips the image). This is distinct from --type picture, which embeds the bitmap with its native bounding box.

---

Slide 4 — 3D Effects: Bevel / Depth / Lighting / Material

Six shapes demonstrating bevel types, extrusion depth, and lighting/material combinations.

officecli add shapes-effects.pptx / --type slide

# bevel=circle — top bevel only, default size
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=roundRect \
  --prop x=0.5in --prop y=1.4in --prop width=3in --prop height=1.8in \
  --prop fill=4472C4 --prop color=FFFFFF --prop bold=true --prop size=14 \
  --prop text='bevel=circle' \
  --prop bevel=circle

# bevel with explicit dimensions + separate bottom bevel
# bevel=TYPE-W-H: bevel type, width in pt, height in pt
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=roundRect \
  --prop x=4in --prop y=1.4in --prop width=3in --prop height=1.8in \
  --prop fill=E63946 --prop color=FFFFFF --prop bold=true --prop size=14 \
  --prop text='bevel=angle-8-4 + bevelBottom=circle-4-4' \
  --prop bevel=angle-8-4 --prop bevelBottom=circle-4-4

# depth= — extrusion thickness (pt-suffixed)
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=roundRect \
  --prop x=7.5in --prop y=1.4in --prop width=3in --prop height=1.8in \
  --prop fill=2A9D8F --prop color=FFFFFF --prop bold=true --prop size=14 \
  --prop text='depth=14pt + bevel=softRound' \
  --prop depth=14pt --prop bevel=softRound

# lighting=threePt material=metal
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=ellipse \
  --prop x=0.5in --prop y=3.7in --prop width=3in --prop height=1.8in \
  --prop fill=F4A261 --prop color=000000 --prop bold=true --prop size=12 \
  --prop text='lighting=threePt material=metal' \
  --prop bevel=circle-8 --prop depth=10 --prop lighting=threePt --prop material=metal

# lighting=balanced material=plastic
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=ellipse \
  --prop x=4in --prop y=3.7in --prop width=3in --prop height=1.8in \
  --prop fill=A8DADC --prop color=000000 --prop bold=true --prop size=12 \
  --prop text='lighting=balanced material=plastic' \
  --prop bevel=circle-6 --prop depth=8 --prop lighting=balanced --prop material=plastic

# lighting=harsh material=warmMatte
officecli add shapes-effects.pptx '/slide[4]' --type shape --prop geometry=ellipse \
  --prop x=7.5in --prop y=3.7in --prop width=3in --prop height=1.8in \
  --prop fill=FFD700 --prop color=000000 --prop bold=true --prop size=12 \
  --prop text='lighting=harsh material=warmMatte' \
  --prop bevel=circle-6 --prop depth=8 --prop lighting=harsh --prop material=warmMatte

Features: bevel (TYPE or TYPE-W or TYPE-W-H; preset types: circle, angle, softRound, convex, coolSlant, cross, divot, hardEdge, relaxedInset, riblet, slope), bevelBottom (same syntax, sets the bottom face bevel), depth (extrusion in pt), lighting (threePt, balanced, harsh, flat, softAmbient, …), material (metal, plastic, warmMatte, matte, powder, translucentPowder, …)

---

Slide 5 — softEdge / link / name / zorder

Feathered edges, clickable hyperlinks with tooltip, named addressable shapes, and explicit z-order stacking.

officecli add shapes-effects.pptx / --type slide

# softEdge — feathered/blurred edge in points; 0 = sharp
officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=ellipse \
  --prop x=0.5in --prop y=1.5in --prop width=3in --prop height=2in \
  --prop fill=E63946 --prop color=FFFFFF --prop bold=true \
  --prop text='softEdge=0  (sharp)' --prop softEdge=0

officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=ellipse \
  --prop x=4in --prop y=1.5in --prop width=3in --prop height=2in \
  --prop fill=E63946 --prop color=FFFFFF --prop bold=true \
  --prop text='softEdge=8pt' --prop softEdge=8pt

officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=ellipse \
  --prop x=7.5in --prop y=1.5in --prop width=3in --prop height=2in \
  --prop fill=E63946 --prop color=FFFFFF --prop bold=true \
  --prop text='softEdge=20pt  (heavy feather)' --prop softEdge=20pt

# link + tooltip — makes the entire shape a clickable hyperlink
officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=roundRect \
  --prop x=0.5in --prop y=4in --prop width=4in --prop height=1in \
  --prop fill=2A9D8F --prop color=FFFFFF --prop bold=true --prop size=16 \
  --prop text="Click me → example.com" \
  --prop link=https://example.com --prop tooltip="Open example.com" \
  --prop name="cta-button"

# zorder — three overlapping rects with explicit stack depth
officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=rect \
  --prop x=8in --prop y=4in --prop width=2.5in --prop height=2.5in \
  --prop fill=4472C4 --prop name="back" --prop zorder=1 \
  --prop color=FFFFFF --prop bold=true --prop text="back (zorder=1)"

officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=rect \
  --prop x=9in --prop y=4.5in --prop width=2.5in --prop height=2.5in \
  --prop fill=E63946 --prop name="middle" --prop zorder=2 \
  --prop color=FFFFFF --prop bold=true --prop text="middle (zorder=2)"

officecli add shapes-effects.pptx '/slide[5]' --type shape --prop geometry=rect \
  --prop x=10in --prop y=5in --prop width=2.5in --prop height=2.5in \
  --prop fill=F4A261 --prop name="front" --prop zorder=3 \
  --prop color=000000 --prop bold=true --prop text="front (zorder=3)"

officecli close shapes-effects.pptx
officecli validate shapes-effects.pptx

Features: softEdge (pt-suffixed radius; 0 = sharp), link (URL, slide[N] in-deck jump, or named action like nextslide), tooltip (hover text on hyperlinked shapes), name (stable identifier; addressable as /slide[N]/shape[@name=...]), zorder (integer stack depth; aliases: z-order, order)

---

Complete Feature Coverage

Feature	Slide
autoFit: none (overflow), normal (shrink text), shape (grow box)	1
flipH / flipV: mirror horizontal/vertical, independent of rotation	2
image=: blipFill — image clipped to any geometry preset	3
bevel: circle, angle, softRound, convex, and more (TYPE-W-H form)	4
bevelBottom: separate bottom-face bevel	4
depth=: 3D extrusion thickness in pt	4
lighting: threePt, balanced, harsh, flat, softAmbient	4
material: metal, plastic, warmMatte, matte, powder	4
softEdge=: feathered boundary radius in pt	5
link=: URL / slide[N] jump / named action	5
tooltip=: hover text for hyperlinked shapes	5
name=: stable @name addressing	5
zorder=: explicit stack depth (aliases: z-order, order)	5

Inspect the Generated File

# Check autoFit mode on each textbox (slide 1)
officecli get shapes-effects.pptx '/slide[1]/shape[1]'
officecli get shapes-effects.pptx '/slide[1]/shape[3]'

# Read back flip flags on slide 2
officecli get shapes-effects.pptx '/slide[2]/shape[2]'
officecli get shapes-effects.pptx '/slide[2]/shape[4]'

# Get bevel/depth/lighting details on slide 4
officecli get shapes-effects.pptx '/slide[4]/shape[1]'
officecli get shapes-effects.pptx '/slide[4]/shape[4]'

# Verify link, tooltip, name on the CTA button
officecli get shapes-effects.pptx '/slide[5]/shape[@name=cta-button]'

# Check zorder stack on slide 5
officecli get shapes-effects.pptx '/slide[5]/shape[@name=back]'
officecli get shapes-effects.pptx '/slide[5]/shape[@name=front]'