python-pptx2 2.13.0__py3-none-any.whl

pptx2/skill/references/three-d.md

@@ -0,0 +1,109 @@
+# 3D primitives (Phase 8)
+
+`shape.three_d` exposes bevels (`<a:bevelT>` / `<a:bevelB>`) and
+extrusion (`<a:sp3d>`), backed by `CT_Shape3D` and `CT_Scene3D` element
+classes in `pptx2.oxml.dml.three_d`.
+
+## Bevels
+
+```python
+from pptx2.util import Pt
+from pptx2.enum.dml import BevelPreset
+
+three_d = card.three_d
+
+# Top bevel
+three_d.bevel_top.preset = BevelPreset.SOFT_ROUND
+three_d.bevel_top.width  = Pt(6)
+three_d.bevel_top.height = Pt(3)
+
+# Bottom bevel (less common)
+three_d.bevel_bottom.preset = BevelPreset.ANGLE
+three_d.bevel_bottom.width  = Pt(2)
+three_d.bevel_bottom.height = Pt(1)
+```
+
+`BevelPreset` covers the standard PowerPoint set: `RELAXED_INSET`,
+`CIRCLE`, `SLOPE`, `CROSS`, `ANGLE`, `SOFT_ROUND`, `CONVEX`, `COOL_SLANT`,
+`DIVOT`, `RIBLET`, `HARD_EDGE`, `ART_DECO`.
+
+To turn a bevel back off, assign `BevelPreset.NONE` — it removes the
+bevel entirely (`three_d.bevel_top.preset = BevelPreset.NONE`). Don't
+worry about it emitting an invalid `"none"` token; the setter maps it to
+element removal, so the deck stays schema-clean.
+
+## Extrusion
+
+```python
+from pptx2.dml.color import RGBColor
+
+three_d.extrusion_height = Pt(20)
+three_d.extrusion_color  = RGBColor(0x12, 0x1E, 0x4D)
+```
+
+## Contour
+
+```python
+three_d.contour_width = Pt(1)
+three_d.contour_color = RGBColor(0xFF, 0xFF, 0xFF)
+```
+
+## Material preset
+
+Material affects how the surface reacts to scene lighting:
+
+```python
+from pptx2.enum.dml import PresetMaterial
+
+three_d.preset_material = PresetMaterial.METAL
+# Other options: MATTE, PLASTIC, METAL, WARM_MATTE, TRANSLUCENT_POWDER,
+# POWDER, DK_EDGE, SOFT_EDGE, CLEAR, FLAT, SOFT_METAL
+# (also LEGACY_MATTE / LEGACY_METAL / LEGACY_PLASTIC / LEGACY_WIREFRAME)
+# Note it is DK_EDGE, not DARK_EDGE.
+```
+
+`PresetMaterial.NONE` clears the material (leaves it unset, reads back as
+`None`); use `PresetMaterial.FLAT` for an explicit non-reflective flat
+surface.
+
+## End-to-end: a beveled badge
+
+```python
+from pptx2 import Presentation
+from pptx2.util import Inches, Pt
+from pptx2.enum.shapes import MSO_SHAPE
+from pptx2.enum.dml import BevelPreset, PresetMaterial
+from pptx2.dml.color import RGBColor
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+badge = slide.shapes.add_shape(
+    MSO_SHAPE.OVAL,
+    Inches(5.5), Inches(3.0), Inches(2.0), Inches(2.0),
+)
+badge.fill.solid()
+badge.fill.fore_color.rgb = RGBColor(0xFF, 0xC1, 0x07)
+badge.line.fill.background()
+
+td = badge.three_d
+td.bevel_top.preset = BevelPreset.SOFT_ROUND
+td.bevel_top.width  = Pt(8)
+td.bevel_top.height = Pt(4)
+td.preset_material  = PresetMaterial.METAL
+
+# Combine with a soft shadow for depth
+badge.shadow.blur_radius = Pt(12)
+badge.shadow.distance    = Pt(4)
+badge.shadow.direction   = 90.0
+badge.shadow.color.alpha = 0.3
+
+prs.save("badge.pptx")
+```
+
+## Round-trip
+
+The `<a:scene3d>` and `<a:sp3d>` slots were already reserved in the
+upstream `oxml/shapes/shared.py`; this proxy just gives them a public
+read/write face. PowerPoint-authored 3D round-trips cleanly even if
+you don't touch the proxy.

pptx2/skill/references/transitions.md

@@ -0,0 +1,100 @@
+# Slide transitions (Phase 4)
+
+Each slide exposes a `transition` proxy backed by `<p:transition>`.
+Reads on an unset transition return `None` and never mutate XML,
+keeping theme inheritance intact.
+
+## Per-slide
+
+```python
+from pptx2.enum.presentation import MSO_TRANSITION_TYPE
+
+slide.transition.kind             = MSO_TRANSITION_TYPE.MORPH
+slide.transition.duration         = 1500          # milliseconds
+slide.transition.advance_on_click = True
+slide.transition.advance_after    = 5000          # 5-second auto-advance
+```
+
+To remove a transition entirely:
+
+```python
+slide.transition.clear()
+```
+
+Reads without explicit settings:
+
+```python
+if slide.transition.kind is None:
+    print("inherits from theme")
+```
+
+## Supported kinds
+
+`MSO_TRANSITION_TYPE` covers 25+ kinds including Office 2010+
+extension transitions on the `p14:` namespace:
+
+- Classics: `FADE`, `PUSH`, `WIPE`, `SPLIT`, `REVEAL`, `RANDOM_BARS`,
+  `SHAPE`, `UNCOVER`, `COVER`, `CUT`, `DISSOLVE`, `ZOOM`
+- Office 2010+ (p14): `MORPH`, `VORTEX`, `CONVEYOR`, `SWITCH`,
+  `GALLERY`, `FLY_THROUGH`, `RIPPLE`, `HONEYCOMB`, `GLITTER`, `ORBIT`,
+  `PAN`, `WARP`, `WIND`
+
+Direction modifiers (`fromLeft`, `fromTop`, etc.) are not yet
+exposed by the high-level API — they round-trip but you have to set
+them through the underlying element.
+
+## Deck-wide helper
+
+`Presentation.set_transition(...)` applies the same transition (or a
+partial update) to every slide in one call. Unspecified kwargs leave
+each slide's existing setting untouched:
+
+```python
+prs.set_transition(kind=MSO_TRANSITION_TYPE.FADE, duration=750)
+
+# Bump the duration on every slide without changing the kind
+prs.set_transition(duration=1200)
+
+# Turn on auto-advance everywhere without disturbing kind or duration
+prs.set_transition(advance_on_click=True, advance_after=8000)
+
+# Remove the transition element on every slide
+prs.set_transition(kind=None)
+```
+
+## End-to-end example
+
+```python
+from pptx2 import Presentation
+from pptx2.enum.presentation import MSO_TRANSITION_TYPE
+from pptx2.util import Inches
+
+prs = Presentation()
+
+# Slide 1 — title
+slide1 = prs.slides.add_slide(prs.slide_layouts[0])
+slide1.shapes.title.text = "Q4 Review"
+slide1.placeholders[1].text = "April 2026"
+
+# Slide 2 — content
+slide2 = prs.slides.add_slide(prs.slide_layouts[5])
+slide2.shapes.title.text = "Run-rate metrics"
+
+# Use Morph between the two title slides
+slide1.transition.kind     = MSO_TRANSITION_TYPE.MORPH
+slide1.transition.duration = 1500
+
+# Default everything else to a quick fade
+prs.set_transition(kind=MSO_TRANSITION_TYPE.FADE, duration=400)
+# (set_transition won't overwrite slide1's already-set kind unless the
+#  kind kwarg is provided — but we passed kind here, so for slide1 it
+#  WILL be overwritten. To preserve slide1, set it AFTER the deck-wide
+#  call instead.)
+
+# Correct order:
+prs.set_transition(kind=MSO_TRANSITION_TYPE.FADE, duration=400)
+slide1.transition.kind     = MSO_TRANSITION_TYPE.MORPH
+slide1.transition.duration = 1500
+
+prs.save("with-transitions.pptx")
+```