Module drawing 

Everything from the drawing crate — shape/text formatting shared by every format (fill, line, geometry, text body…). Always available: unlike word/excel/powerpoint, not gated by a feature, since it has no meaningful “opt out” — any format that has images or shapes at all needs it.

Structs

BlipFill

An image fill (<a:blipFill>, CT_BlipFillProperties). Confirmed against dml-picture.xsd’s CT_Picture (nvPicPr/ blipFill/spPr) that this is the same type PowerPoint/Word/Excel all use both for a real picture shape’s own always-present fill and for texturing an ordinary shape with an image (EG_FillProperties’s blipFill choice, alongside noFill/solidFill/..) — one model, Fill::Image, covers both uses.

CropRect

<a:srcRect l=".." t=".." r=".." b=".."/> (CT_RelativeRect) — how much of a BlipFill’s source image to crop from each edge, before stretching/tiling the remainder into the shape. Each side is independently optional (ST_Percentage, thousandths of a percent of the image’s own width/height; can be negative, which zooms out rather than cropping — real PowerPoint uses this for “fill the shape, source image too small” cases). Grounded against a real fixture (e.g. <a:srcRect l="2878" t="2522" r="21582" b="46217"/>, and <a:srcRect t="52941" b="-17647"/> for the negative case).

CustomGeometry

<a:custGeom><a:pathLst><a:path w=".." h="..">’s own draw commands (CT_Path2D) — see Geometry::Custom’s doc comment for scope.

EffectList

<a:effectLst> (CT_EffectList). Only the four effects real-world decks overwhelmingly use are modeled (outer shadow, glow, reflection, soft edge); CT_EffectList’s other choices (innerShdw/prstShdw, blur, fillOverlay, alpha/color/duotone/ luminance-modulation effect filters rather than genuine visual effects) are not, matching the “common case first” posture already used for e.g. Geometry::Custom’s draw-command subset. Grounded against real fixtures covering outerShdw, glow/softEdge, and reflection.

GeometryAdjustment

One <a:gd name=".." fmla=".."/> (CT_GeomGuide) inside a preset shape’s <a:avLst> — an adjustment handle’s current value. name is the handle’s identifier ("adj" for a shape with a single handle, "adj1"/"adj2"/. for shapes with several); formula is the raw guide formula string PowerPoint itself writes (almost always "val N" for a literal value — the small expression language CT_GeomGuide otherwise allows, e.g. referencing other guides, is not interpreted here, only stored/round-tripped verbatim).

Glow

<a:glow rad="..">{color}</a:glow> (CT_GlowEffect) — a soft colored halo around the shape’s outline. Unlike OuterShadow, rad is required (CT_GlowEffect’s only attribute).

GradientFill

A gradient fill (<a:gradFill>, CT_GradientFillProperties).

GradientStop

One color stop in a gradient (<a:gs pos="..">, CT_GradientStop).

Hyperlink

A clickable hyperlink (<a:hlinkClick>, CT_Hyperlink).

Line

A shape’s outline stroke (<a:ln>, CT_LineProperties).

LineEnd

One end of a line/connector (<a:headEnd>/<a:tailEnd>, CT_LineEndProperties) — e.g. an arrowhead.

OuterShadow

<a:outerShdw> (CT_OuterShadowEffect) — a drop shadow cast outward from the shape. algn/rotWithShape/kx/ky/sx/sy (fine-grained skew/scale/anchor controls) are not modeled — a scope reduction, not a fixture gap (all CT_OuterShadowEffect’s own attributes beyond the ones here are optional). color’s own alpha modifier (<a:alpha val="..">, seen alongside <a:srgbClr>/<a:schemeClr> in real fixtures, e.g. 60810.pptx’s <a:srgbClr val="000000"><a:alpha val="41000"/></a:srgbClr>) is not preserved either — Color itself has never modeled color transforms (see its own doc comment), not a new limitation.

PatternFill

A two-color repeating pattern fill (<a:pattFill>, CT_PatternFillProperties).

Reader

Reads a sequence of generic XML events from an in-memory UTF-8 string.

Reflection

<a:reflection> (CT_ReflectionEffect) — a faded mirror image below the shape. endPos/sx/sy/kx/ky/algn/fadeDir/rotWithShape (fine- grained scale/skew/anchor/fade-direction controls) are not modeled — the same scope-reduction posture as OuterShadow; only the four attributes that dominate real-world usage (blur, distance, direction, and the start/end fade transparency) are kept. Grounded against a real fixture (<a:reflection blurRad="12700" stA="48000" endA="300" endPos="55000" dir="5400000" sy="-90000" algn="bl" rotWithShape="0"/>).

ShapeProperties

A shape’s visual properties (<a:spPr>, CT_ShapeProperties): local position/size, geometry, fill, and line. Everything about how a shape looks, independent of where it is anchored in its host document (that part is never modeled here — see the crate-level doc comment).

SoftEdge

<a:softEdge rad=".."/> (CT_SoftEdgesEffect) — blurs the shape’s own outline edge. rad is required (its only attribute).

TabStop

One explicit tab stop (<a:tab pos="." algn=".">, CT_TextTabStop). Grounded against a real fixture, which confirmed the tabLst/tab element shape and attribute names exactly as modeled here.

TextBody

The text content of a shape (<a:txBody>, CT_TextBody). Structurally a sibling of ShapeProperties, not a field on it: confirmed against dml-spreadsheetDrawing.xsd’s CT_Shape (nvSpPr/spPr/style?/txBody?, txBody a sibling of spPr, both direct children of the host’s own <*:sp> wrapper) — a future host crate combines the two itself, drawing never nests one inside the other.

TextBodyProperties

<a:bodyPr>’s attributes (CT_TextBodyProperties) — text wrapping, vertical anchor, horizontal centering, inset margins, and autofit. See TextBody’s doc comment for what else CT_TextBodyProperties allows but isn’t modeled here (3D, preset text warp/WordArt).

TextParagraph

One paragraph of text (<a:p>, CT_TextParagraph).

TextParagraphProperties

<a:pPr>’s attributes (CT_TextParagraphProperties) — alignment, margins/indent, tab stops (tabLst), paragraph spacing, indent/outline level, default run formatting, and bullets.

TextRunProperties

A run’s character formatting (<a:rPr>/<a:defRPr>/<a:endParaRPr>, CT_TextCharacterProperties) — this crate only ever writes/reads it as <a:rPr> (on <a:r>/<a:br>), not the other two contexts.

Transform2D

Position, size, rotation, and flipping (<a:xfrm>, CT_Transform2D). Both offset/extent are optional in the schema (a shape can rely entirely on its host anchor for placement, e.g. a picture inside a xdr:twoCellAnchor with no local xfrm at all) — None here means the element itself is either absent or written with only the attributes present, matching that flexibility rather than forcing a fixed size.

Enums

BlipFillMode

EG_FillModeProperties — how an image fill is fitted to its shape.

BulletColor

This paragraph’s bullet color (EG_TextBulletColor).

BulletFont

This paragraph’s bullet font (EG_TextBulletTypeface).

BulletKind

This paragraph’s bullet/numbering marker (EG_TextBullet).

BulletSize

This paragraph’s bullet size (EG_TextBulletSize).

Color

A color (EG_ColorChoice): the choice DrawingML offers wherever a color is needed (fills, lines, gradient stops..).

Error

Errors that can occur while reading or writing DrawingML content.

Fill

How a shape’s (or a line’s) interior is painted (EG_FillProperties).

Geometry

A shape’s outline (EG_Geometry, the choice between <a:custGeom> and <a:prstGeom>).

LineCap

ST_LineCap — a stroke’s end-cap style.

LineCompound

ST_CompoundLine — a stroke’s compound-line style.

LineEndSize

ST_LineEndWidth/ST_LineEndLength — both share the same three-value small/medium/large scale.

LineEndType

ST_LineEndType — the shape of a line end decoration.

LineJoin

EG_LineJoinProperties — how a stroke’s corners are drawn.

PathCommand

One draw command inside a custom path (EG_Path2DList’s children within a single <a:path> — moveTo/lnTo/cubicBezTo/close only, see Geometry::Custom’s doc comment for what else exists but isn’t modeled). Coordinates are in the enclosing <a:path>’s own coordinate space (0.=width_emu/0.=height_emu), not absolute EMUs.

PresetLineDash

ST_PresetLineDashVal’s full set of 11 named dash patterns.

PresetPattern

ST_PresetPatternVal’s full, finite set of 54 named patterns — unlike PresetShape/Color::Preset, small enough to enumerate exhaustively (no Other escape hatch needed).

PresetShape

A useful subset of ST_ShapeType’s ~185 preset shape names — the ones most commonly authored by real tools (basic shapes, arrows, a handful of callouts/symbols). PresetShape::Other preserves round-trip fidelity for any preset name not explicitly modeled here, the same “closed enum + escape hatch” posture this workspace already uses for open-ended, large-but-finite value sets (e.g. font family names) rather than exhaustively enumerating every value up front for a feature not yet needed.

TabAlignment

ST_TextTabAlignType.

TextAlign

ST_TextAlignType.

TextAnchor

ST_TextAnchoringType — vertical anchor of a text body within its shape. Justified/Distributed (just/dist) stretch line spacing to fill the shape’s height rather than anchoring to one edge.

TextAutofit

EG_TextAutofit — how a text body reacts to content that doesn’t fit its shape. Grounded against real fixtures exercising all three variants.

TextCaps

ST_TextCapsType.

TextRun

One run of text within a paragraph (EG_TextRun’s r/br/fld choices — see TextRun::Field).

TextSpacing

Paragraph-level spacing (CT_TextSpacing, the choice behind <a:lnSpc>/ <a:spcBef>/<a:spcAft>). Grounded against a real fixture exercising both variants side by side (<a:lnSpc><a:spcPct val="100000"/></a:lnSpc>, <a:spcBef><a:spcPts val="0"/></a:spcBef>).

TextStrike

ST_TextStrikeType.

TextUnderline

ST_TextUnderlineType’s full set of 18 named underline styles.

TextVerticalType

ST_TextVerticalType.

TextWrap

ST_TextWrappingType.

Functions

is_fill_choice_element

Parses one already-matched EG_FillProperties choice element (<a:noFill/>, <a:solidFill>, <a:gradFill>, <a:pattFill>, or <a:blipFill>) into a Fill, given the caller has already read its own Start/Empty event and knows (e.g. via is_fill_choice_element) that it is one — for a host that mixes a bare fill choice among other, individually-matched sibling elements at the same nesting level, so can’t hand the whole scan over to read_fill (which skips anything that isn’t a fill choice, silently discarding those other siblings). PresentationML table cell properties (<a:tcPr>’s own trailing fill choice, sitting alongside <a:lnL>/<a:lnR>/<a:lnT>/<a:lnB> — powerpoint-ooxml’s own TableCellProperties, point 8) is exactly this case.

read_color

Parses a single bare EG_ColorChoice element (<a:srgbClr>/ <a:scrgbClr>/<a:hslClr>/<a:sysClr>/<a:prstClr>) from a reader positioned wherever the caller expects to find it, skipping over any other, unrelated children along the way — the same “bare choice, not wrapped in <*:spPr>” posture as read_fill, for a host embedding a bare color choice outside DrawingML’s own fill/line vocabulary (e.g. powerpoint-ooxml’s custom table styles, point 8). Returns None if no recognized color child is found before the first End/Eof at this nesting level. A theme-relative <a:schemeClr> reference isn’t modeled — see Color’s own doc comment.

read_fill

Parses a single bare EG_FillProperties choice (<a:noFill/>, <a:solidFill>, <a:gradFill>, <a:pattFill>, or <a:blipFill>) from a reader positioned wherever the caller expects to find it, skipping over any other, unrelated children along the way — unlike read_shape_properties (which parses a whole <*:spPr>’s worth of xfrm/geometry/fill/line), this is for a host embedding a bare fill choice on its own, outside any <*:spPr> wrapper (e.g. powerpoint-ooxml’s own <p:bgPr> slide background, point 4). Returns None if no recognized fill child is found before the first End/Eof at this nesting level.

read_fill_choice

See is_fill_choice_element’s own doc comment for when to reach for this instead of read_fill.

read_line

Parses a CT_LineProperties-typed element (<a:ln>, or the same type under a different name, e.g. PresentationML’s table cell borders <a:lnL>/<a:lnR>/<a:lnT>/<a:lnB> — see crate::write_line_named for the writer-side symmetric case), from a reader positioned right at its own Start/Empty event — unlike read_fill/read_color, which scan forward looking for a bare choice, the caller here has already matched the element by name (its own name isn’t fixed, unlike <a:solidFill>/<a:srgbClr>) and hands over its start/is_start directly, the same contract read_shape_properties’s own internal <a:xfrm>/<a:ln> handling uses.

read_shape_properties

Parses CT_ShapeProperties’s content (<a:xfrm>/EG_Geometry/ EG_FillProperties/<a:ln>, in any order, each optional) from a reader positioned right after the wrapper element’s own opening tag was consumed by the caller. See the module doc comment for the exact contract.

read_text_body

Parses <a:bodyPr>../<a:p>..</a:p>* — the content of <a:txBody> (CT_TextBody) — from a reader positioned right after the caller already consumed the wrapper’s own opening tag, mirroring read_shape_properties’s exact contract (see the module doc comment).

write_blip_fill

Writes <a:blipFill> — (<a:blip>/stretch-or-tile), (<a:srcRect>). See BlipFill’s doc comment for what else isn’t modeled (no per-mode tiling/stretching sub-rects).

write_color

Writes EG_ColorChoice — a single <a:srgbClr../>, <a:scrgbClr../>, <a:hslClr../>, <a:sysClr../>, or <a:prstClr../> element, with no wrapping element of its own (the caller — <a:solidFill>, <a:fgClr>, <a:gs>. — provides that).

write_effect_list

Writes <a:effectLst>. Self-closing when every effect is unset (schema-valid: CT_EffectList’s own effect choices are all minOccurs="0"), otherwise wraps whichever of <a:outerShdw>/<a:glow>/<a:reflection>/<a:softEdge> are set, in that schema order (EG_EffectProperties’s own group definition).

write_fill

Writes EG_FillProperties — <a:noFill/>, <a:solidFill>.., <a:gradFill>.., <a:pattFill>.., or <a:blipFill>...

write_geometry

Writes EG_Geometry — <a:prstGeom prst=".."> or <a:custGeom>.. (see Geometry’s doc comment for what custGeom scope is modeled).

write_geometry_fill_line_effects

Writes EG_Geometry/EG_FillProperties/<a:ln>/<a:effectLst>, in that schema order — like write_shape_properties, minus <a:xfrm>, and with one difference that matters in practice: when properties.geometry is unset, this writes a fixed <a:prstGeom prst="{default_preset}"><a:avLst/></a:prstGeom> fallback instead of omitting the geometry element entirely.

write_line

Writes <a:ln w="..">EG_LineFillProperties, EG_LineDashProperties, EG_LineJoinProperties, headEnd?, tailEnd?</a:ln>.

write_line_named

Writes a CT_LineProperties-typed element under a caller-chosen name — same content model as write_line (which is just this called with "a:ln"), for the handful of other elements in the wider OOXML vocabulary that reuse CT_LineProperties under a different name, e.g. PresentationML table cell borders (<a:lnL>/<a:lnR>/<a:lnT>/ <a:lnB>, powerpoint-ooxml’s own crate-external TableCellProperties, point 8).

write_shape_properties

Writes <a:xfrm>/EG_Geometry/EG_FillProperties/<a:ln>, in that schema order — the content of CT_ShapeProperties, i.e. what a host crate’s own <*:spPr> wrapper should contain.

write_text_body

Writes <a:bodyPr>../<a:p>..</a:p>* — the content of <a:txBody> (CT_TextBody). Like write_shape_properties, never writes the <a:txBody> wrapper itself (a sibling of <a:spPr> inside a host’s own <*:sp>, not this crate’s concern — see crate::TextBody’s doc comment).

write_text_body_properties

Writes <a:bodyPr> (self-closing unless autofit is set — no 3D/preset warp modeled, see TextBody’s doc comment), matching the schema’s own minOccurs="1" on this element even when everything is unset (<a:bodyPr/>).

write_text_paragraph

Writes <a:p><a:pPr../>EG_TextRun*</a:p> (CT_TextParagraph).

write_text_paragraph_properties

Writes <a:pPr> — self-closing when nothing beyond its own attributes is set, otherwise wraps <a:lnSpc>/<a:spcBef>/<a:spcAft>/bullet elements/<a:tabLst>/<a:defRPr> children, in that order — the same child sequence confirmed on a real fixture (<a:lnSpc>..<a:spcBef>..<a:spcAft>..<a:buClrTx/><a:buSzTx/> <a:buFontTx/><a:buNone/><a:tabLst/><a:defRPr/>).

write_text_run

Writes one EG_TextRun choice — <a:r>..</a:r> for TextRun::Regular, <a:br../>/<a:br>..</a:br> for TextRun::LineBreak.

write_transform

Writes <a:xfrm rot=".." flipH=".." flipV=".."><a:off../><a:ext../></a:xfrm>.

Type Aliases

Result

A Result alias using [Error] as the error type.