iofficeai--officecli/examples/ppt/animations.md

Animation Showcase

Demonstrates the first-class pptx animation element and its full property surface. Three files work together:

• animations.sh — Shell script driving officecli create/open/add/set/close.
• animations.py — SDK twin (officecli-sdk), same deck via doc.batch(...).
• animations.pptx — The generated 7-slide deck.

The animation element

An animation is a child element of a shape (or chart):

officecli add animations.pptx /slide[N]/shape[M] --type animation \
  --prop effect=fade --prop class=entrance --prop duration=800

add ... --type animation gives you the full timing model. (The legacy set --prop animation=fade-entrance-800 compound-token shortcut still works for quick one-liners, but the element form is what exposes trigger/delay/repeat/ autoReverse/restart/motion-paths.)

On get, each facet is its own key — there is no composite animation key in readback:

officecli get animations.pptx /slide[2]/shape[3]/animation[1]
# → effect=fade class=entrance presetId=10 trigger=onClick duration=800

Regenerate

cd examples/ppt
bash animations.sh          # → animations.pptx (7 slides, 44 animations)
# or the SDK twin:
python3 animations.py

Property reference

Prop	Values / format	Notes
effect	preset name (see catalog below)	The animation preset. Some effects require a specific class.
class	entrance | exit | emphasis | motion	Category. spin/grow/wave need emphasis; motion needs path=.
trigger	onClick | withPrevious | afterPrevious	When it starts. Default onClick.
duration	ms integer (alias dur)	e.g. 500 = 0.5s.
delay	ms integer	Delay before starting.
repeat	positive int | indefinite	Loop count, or loop forever.
autoReverse	true / false	Play forward then reverse (doubles the visible run).
restart	always | whenNotActive | never	Behavior when re-triggered.
direction	in/out/left/right/up/down (+ aliases top/bottom, l/r/u/d)	For directional effects.
path	line | arc | circle | diamond | triangle | square | custom	Motion preset (only with class=motion).
d	SVG-like path, coords 0..1 of slide	Custom motion path (only with path=custom; auto-appends E).

Get-only facets: presetId, easein, easeout, motionPath.

Timing model

Animations on a slide play as an ordered list. Each animation's trigger decides how it relates to the one before it:

• onClick — waits for a mouse click to start (the default).
• afterPrevious — starts automatically when the previous animation ends (add delay= for a gap).
• withPrevious — starts at the same instant as the previous animation.

Chaining onClick → afterPrevious → withPrevious … builds a self-playing sequence off a single click (see Slide 6).

Effect catalog

Entrance / Exit (same names, pick via class=): appear, fade, fly, zoom, wipe, bounce, float, swivel, split, wheel, checkerboard, blinds, dissolve, flash, box, circle, diamond, plus, strips, wedge, random.

Emphasis (class=emphasis): motion — spin, grow, wave, bold, growShrink, teeter, pulse; color — fillColor, lineColor, transparency, complementaryColor, complementaryColor2, contrastingColor, darken, desaturate, lighten, objectColor, colorPulse.

Motion (class=motion + path=): line, arc, circle, diamond, triangle, square, custom.

Template exit effects (class=exit, verbatim PowerPoint OOXML): contract, centerRevolve, collapse, floatOut, shrinkTurn, sinkDown, spinner, basicZoom, stretchy, boomerang, credits, curveDown, pinwheel, spiralOut, basicSwivel.

Known limitation — template exit effects are lossy on readback. These 15 effects are backed by byte-for-byte PowerPoint-authored OOXML, so they render correctly in PowerPoint but ignore the duration prop (they keep the authored timing) and do not round-trip their effect name — get reports them as a generic effect=fade/split/unknown plus a presetId. Because the effect name doesn't survive a round-trip, this demo builds its slides from the effects that round-trip cleanly. Use the template effects directly in a deck when you want their exact PowerPoint look; just don't rely on get echoing the name back.

Slides

Slide 1 — Title

Radial-gradient title slide (layout=title, background=radial:, title + subtitle placeholders, transition=fade).

Slide 2 — Entrance Effects

Twelve entrance effects on a 4-column grid, each with its own duration.

officecli add animations.pptx /slide[2]/shape[2] --type animation \
  --prop effect=appear --prop class=entrance --prop duration=400
officecli add animations.pptx /slide[2]/shape[3] --type animation \
  --prop effect=fade --prop class=entrance --prop duration=800
# … fly, zoom, wipe, bounce, float, swivel, split, wheel, box, circle

Features: effect= (entrance family), class=entrance, duration=.

Slide 3 — Exit Effects

Ten exit effects; directional ones (fly, wipe) add direction=.

officecli add animations.pptx /slide[3]/shape[3] --type animation \
  --prop effect=fly --prop class=exit --prop direction=down --prop duration=600
officecli add animations.pptx /slide[3]/shape[6] --type animation \
  --prop effect=wipe --prop class=exit --prop direction=left --prop duration=600

Features: class=exit, direction= on directional effects.

Slide 4 — Emphasis & Color Effects

Six emphasis effects on ellipses — motion (spin, grow, wave, growShrink, teeter) and pulse.

officecli add animations.pptx /slide[4]/shape[2] --type animation \
  --prop effect=spin --prop class=emphasis --prop duration=1000
officecli add animations.pptx /slide[4]/shape[5] --type animation \
  --prop effect=growShrink --prop class=emphasis --prop duration=800

Features: class=emphasis; color-change and motion emphasis effects.

Slide 5 — Motion Paths

Preset paths (line, arc, circle, diamond, square) plus a custom d=.

officecli add animations.pptx /slide[5]/shape[2] --type animation \
  --prop class=motion --prop path=line --prop direction=right --prop duration=1000
# Custom path — coords are 0..1 of the slide; a trailing 'E' is auto-appended
officecli add animations.pptx /slide[5]/shape[8] --type animation \
  --prop class=motion --prop path=custom \
  --prop d='M 0 0 L 0.3 -0.1 L 0.6 0.1 E' --prop duration=1500

Features: class=motion, path=<preset|custom>, direction=, d=. get echoes the resolved path back as motionPath=.

Slide 6 — Timing & Trigger Chaining

Five shapes chained into a self-playing sequence off one click, plus a delay= and a slow (2000ms) run.

officecli add animations.pptx /slide[6]/shape[2] --type animation \
  --prop effect=fade --prop class=entrance --prop trigger=onClick --prop duration=500
officecli add animations.pptx /slide[6]/shape[3] --type animation \
  --prop effect=fly --prop class=entrance --prop trigger=afterPrevious --prop duration=600
officecli add animations.pptx /slide[6]/shape[4] --type animation \
  --prop effect=zoom --prop class=entrance --prop trigger=withPrevious --prop duration=600
officecli add animations.pptx /slide[6]/shape[5] --type animation \
  --prop effect=wipe --prop class=entrance --prop trigger=afterPrevious \
  --prop delay=800 --prop duration=700

Features: trigger=onClick|afterPrevious|withPrevious, delay=, duration range (500–2000ms).

Slide 7 — Repeat, autoReverse & Restart

officecli add animations.pptx /slide[7]/shape[2] --type animation \
  --prop effect=spin --prop class=emphasis --prop repeat=3 --prop duration=800
officecli add animations.pptx /slide[7]/shape[3] --type animation \
  --prop effect=pulse --prop class=emphasis --prop repeat=indefinite \
  --prop trigger=withPrevious --prop duration=600
officecli add animations.pptx /slide[7]/shape[4] --type animation \
  --prop effect=grow --prop class=emphasis --prop autoReverse=true \
  --prop repeat=2 --prop duration=700
officecli add animations.pptx /slide[7]/shape[5] --type animation \
  --prop effect=teeter --prop class=emphasis --prop restart=whenNotActive \
  --prop repeat=indefinite --prop duration=500

Features: repeat=<int>, repeat=indefinite, autoReverse=true, restart=whenNotActive.

Complete feature coverage

Feature	Slide
add --type animation element	2–7
effect= entrance family	2
effect= exit family	3
effect= emphasis (motion + color)	4
class=entrance / exit / emphasis / motion	2 / 3 / 4 / 5
duration= (400–2000ms)	2–7
delay=	6
direction= on directional effects	3, 5
trigger=onClick / afterPrevious / withPrevious	6
repeat=<int> / repeat=indefinite	7
autoReverse=true	7
restart=whenNotActive	7
path= preset motion + d= custom	5
transition= (fade, wipe, push, zoom, split, reveal)	1–7

Inspect the generated file

officecli query animations.pptx animation
officecli get animations.pptx /slide[2]/shape[3]/animation[1]
officecli get animations.pptx /slide[6]/shape[5]/animation[1]
officecli get animations.pptx /slide[7]/shape[4]/animation[1]