pptx-ts

Class: Picture ​

A picture (p:pic).

Extends ​

Constructors ​

Constructor ​

new Picture(element, host): Picture

Parameters ​

ParameterTypeDescription
elementElement-
hostShapeHostThe part that owns this shape's tree: a Slide, a SlideLayout, or a SlideMaster. Narrow it with instanceof when you need the concrete class; ShapeHost.partName tells the tiers apart without one.

Returns ​

Picture

Inherited from ​

Shape.constructor

Properties ​

host ​

readonly host: ShapeHost

The part that owns this shape's tree: a Slide, a SlideLayout, or a SlideMaster. Narrow it with instanceof when you need the concrete class; ShapeHost.partName tells the tiers apart without one.

Inherited from ​

Shape.host

shapeType ​

readonly shapeType: "picture"

Which concrete shape kind this is.

Overrides ​

Shape.shapeType

Accessors ​

absoluteFrame ​

Get Signature ​

get absoluteFrame(): AbsoluteFrame | null

This shape's position, size, and effective orientation in slide-absolute EMU/degrees, composing every enclosing group transform.

left/top/width/height report a group child's geometry in its group's child coordinate space (a:chOff/a:chExt), which is not directly placeable on the slide. This getter walks the p:grpSp ancestor chain outward, mapping the box through each group's off + (p - chOff) * (ext / chExt) transform, then composing group flips and rotations about the group centre. For a shape already at slide level the box equals its own { left, top, width, height }, while rotation/flipH/flipV equal the shape's own transform values.

null when the shape (or any enclosing group) has no own transform, or a group's a:chExt is degenerate (zero). There is then no resolvable frame. absoluteFrameFailure says which of those it was.

A rotated shape's returned left/top remain PowerPoint's unrotated placement box (the same box PowerPoint writes after Ungroup), with the effective rotation exposed separately.

Returns ​

AbsoluteFrame | null

Inherited from ​

Shape.absoluteFrame

absoluteFrameFailure ​

Get Signature ​

get absoluteFrameFailure(): AbsoluteFrameFailure | null

Why absoluteFrame is null, or null when it resolved.

absoluteFrame reports one null for three different situations, and only a caller that wants to report the unresolvable shape needs them apart: an inherited placeholder box is ordinary, a group with no usable a:xfrm is not. The distinction is not recoverable from the null, and re-deriving it means walking the same ancestry a second time, so it is named here instead. See AbsoluteFrameFailure for what each value means.

Returns ​

AbsoluteFrameFailure | null

Inherited from ​

Shape.absoluteFrameFailure

adjustValues ​

Get Signature ​

get adjustValues(): Record<string, string>

Preset-geometry adjustment values (spPr/a:prstGeom/a:avLst/a:gd) as a name → formula map, e.g. { adj: 'val 16667' }. Empty when the shape has no adjust handles (or uses custom geometry). Pair with presetGeometry.

Returns ​

Record<string, string>

Inherited from ​

Shape.adjustValues

crop ​

Get Signature ​

get crop(): FillRect | null

The picture's crop as fractions of the source image, read from p:blipFill/a:srcRect as { left, top, right, bottom }, each the amount trimmed off that edge (so 0.1 = 10 % cropped away, an uncropped edge is 0). null when there is no a:srcRect at all; an explicit {0,0,0,0} crop still reports zeros, since its presence is meaningful. The raw attributes are thousandths of a percent; this divides by 100000 to match the fraction convention used elsewhere in the read API (see recolor).

Returns ​

FillRect | null

customGeometry ​

Get Signature ​

get customGeometry(): CustomGeometry | null

Custom freeform geometry (spPr/a:custGeom/a:pathLst), or null when the shape uses preset geometry / none. The faithful, multi-path counterpart of presetGeometry: each a:path keeps its own path-unit viewport (w/h) and ordered GeometryCommands. Coordinates are raw path-unit integers, not EMU. Pair the path w/h with the shape's box size to map them into slide space.

Not an auto-shape-only property either: a picture clipped to a freeform (what PowerPoint writes when Merge Shapes intersects a picture with a shape, and what addImage({ points }) writes) carries its clip here. A group reads null.

Returns ​

CustomGeometry | null

Inherited from ​

Shape.customGeometry

description ​

Get Signature ​

get description(): string | null

The shape's alt-text description (p:cNvPr/@descr), or null when unset. This is the accessibility primitive a screen reader announces; an audit or accessible-export tool reads it here. Distinct from name, which is the authoring-time shape name and is never surfaced to assistive tech.

Returns ​

string | null

Set Signature ​

set description(value): void

Set (or clear, with '') the alt-text description. Requires the shape's p:cNvPr to exist, which every well-formed shape carries.

Parameters ​
ParameterType
valuestring
Returns ​

void

Inherited from ​

Shape.description

element_ ​

Get Signature ​

get element_(): Element

Escape hatch: the underlying shape element. After mutating it call markDirty, or save() writes the original bytes.

Returns ​

Element

Inherited from ​

Shape.element_

fillColor ​

Get Signature ​

get fillColor(): string | null

Explicit RGB fill colour as a 6-hex string (spPr/a:solidFill/a:srgbClr/@val), or null.

Returns ​

string | null

Set Signature ​

set fillColor(value): void

Parameters ​
ParameterType
valuestring | null
Returns ​

void

Inherited from ​

Shape.fillColor

fillNoFill ​

Get Signature ​

get fillNoFill(): boolean

true when the shape sets an explicit no-fill (spPr/a:noFill): a deliberately transparent surface. The fill-side counterpart of lineNoFill, and the only accessor that separates it from a shape carrying no fill child at all (one inheriting through p:style/a:fillRef): every other fill accessor (fillColor, fillSchemeColor, resolvedFill, gradientFill, patternFill, pictureFill) reports null for both. The two paint completely differently, so a consumer that cannot tell them apart paints a transparent shape in the theme's accent colour.

Returns ​

boolean

Inherited from ​

Shape.fillNoFill

fillSchemeColor ​

Get Signature ​

get fillSchemeColor(): string | null

Theme colour token when the fill is a scheme colour (a:solidFill/a:schemeClr/@val, e.g. accent2), or null.

Returns ​

string | null

Set Signature ​

set fillSchemeColor(value): void

Parameters ​
ParameterType
valuestring | null
Returns ​

void

Inherited from ​

Shape.fillSchemeColor

flipH ​

Get Signature ​

get flipH(): boolean

Whether the shape is flipped horizontally (a:xfrm/@flipH); false when unset or when the shape has no own transform. This is the shape's own horizontal flip; use absoluteFrame for the effective value after enclosing group transforms are composed.

Returns ​

boolean

Inherited from ​

Shape.flipH

flipV ​

Get Signature ​

get flipV(): boolean

Whether the shape is flipped vertically (a:xfrm/@flipV); false when unset or when the shape has no own transform. This is the shape's own vertical flip; use absoluteFrame for the effective value after enclosing group transforms are composed.

Returns ​

boolean

Inherited from ​

Shape.flipV

glow ​

Get Signature ​

get glow(): Glow | null

The shape's glow halo (spPr/a:effectLst/a:glow), resolved against the host's theme, or null when the shape has no glow. The write-side glow option is a text glow in run properties, so it does not read back here.

Returns ​

Glow | null

Inherited from ​

Shape.glow

gradientFill ​

Get Signature ​

get gradientFill(): GradientFill | null

The shape's gradient fill with its geometry (spPr/a:gradFill), or null when the fill is not a gradient. Unlike gradientStops (stops only), this also carries the linear GradientFill.angleDeg or the GradientFill.path shape: the geometry a faithful replica needs and which the bare stop list omits.

Returns ​

GradientFill | null

Inherited from ​

Shape.gradientFill

gradientStops ​

Get Signature ​

get gradientStops(): GradientStop[] | null

Gradient fill stops (spPr/a:gradFill/a:gsLst/a:gs) in document order, or null when the shape's fill is not a gradient. Each stop carries its position (0–1, from @pos in thousandths of a percent) and either an explicit color (hex) or a schemeColor token, mirroring the fillColor / fillSchemeColor split for solid fills.

Returns ​

GradientStop[] | null

Inherited from ​

Shape.gradientStops

hasOwnLine ​

Get Signature ​

get hasOwnLine(): boolean

Whether the shape states an outline of its own (spPr/a:ln), however little it holds.

The line accessors all report null both for a shape with no a:ln and for one whose a:ln is empty, and the two are different statements to a writer: an empty <a:ln/> says "take the whole outline from p:style or the placeholder", which is what PowerPoint writes on its own placeholders, and addShape writes it for line: { type: 'inherit' }. A copy that has to reproduce the outline rather than describe it needs to know which one it has.

Returns ​

boolean

Inherited from ​

Shape.hasOwnLine

hasTextFrame ​

Get Signature ​

get hasTextFrame(): boolean

Whether this shape can hold text (only p:sp does in this read model).

Returns ​

boolean

Inherited from ​

Shape.hasTextFrame

height ​

Get Signature ​

get height(): number | null

Height in EMU (a:ext/@cy), or null when the shape has no own transform.

Returns ​

number | null

Set Signature ​

set height(value): void

Parameters ​
ParameterType
valuenumber
Returns ​

void

Inherited from ​

Shape.height

hidden ​

Get Signature ​

get hidden(): boolean

Whether the shape is explicitly hidden (p:cNvPr/@hidden="1"); false when the attribute is unset. A hidden shape stays in the slide XML but is not rendered. Decks use it as a fallback layer (e.g. a duotone-recolour source sitting behind the visible icon), so a faithful reader must distinguish it from the drawn shapes.

Returns ​

boolean

Inherited from ​

Shape.hidden

Get Signature ​

get hyperlink(): Hyperlink | null

The shape's own click hyperlink (p:cNvPr/a:hlinkClick), or null when it carries none.

This is the link PowerPoint's Insert > Link puts on a whole shape, as opposed to the one a Run carries on a span of text. It is the same element, read the same way, and it had no reader at all -- so a linked shape read back as an ordinary one and a replica lost the link with nothing to say so. addShape, addText and addImage all take hyperlink.

A URL link resolves its @r:id to the external target; a slide jump resolves it to the linked slide's partname and reports ppaction://hlinksldjump as its action. An action-only link (a slide-show navigation button) has no @r:id and resolves to neither.

Returns ​

Hyperlink | null

Inherited from ​

Shape.hyperlink

id ​

Get Signature ​

get id(): number | null

Drawing id (p:cNvPr/@id), or null if absent.

Returns ​

number | null

Inherited from ​

Shape.id

imagePartName ​

Get Signature ​

get imagePartName(): string | null

Absolute partname of the embedded image, resolved via the owning part's relationships.

null covers every way there is nothing to name: no r:embed, an id the part does not declare, or a relationship whose target is external (a LINKED image). It used to throw on the last two while the same blip reached through a picture fill returned null.

Returns ​

string | null

imageRelId ​

Get Signature ​

get imageRelId(): string | null

Relationship id of the embedded image (p:blipFill/a:blip/@r:embed), or null.

Returns ​

string | null

Set Signature ​

set imageRelId(value): void

Repoint the blip at a relationship id already present in the owning part's relationships, without minting a new media part. The caller owns ensuring the id exists and targets an image; use setImage to add fresh bytes.

Parameters ​
ParameterType
valuestring
Returns ​

void

innerShadow ​

Get Signature ​

get innerShadow(): InnerShadow | null

The shape's inner shadow (spPr/a:effectLst/a:innerShdw), resolved against the host's theme, or null when the shape has no inner shadow. The inset counterpart of shadow: the write-side shadow: { type: 'inner' } emits it, and it is invisible in geometry/fill alone.

Returns ​

InnerShadow | null

Inherited from ​

Shape.innerShadow

isDecorative ​

Get Signature ​

get isDecorative(): boolean

Whether the shape is flagged decorative (p:cNvPr/a:extLst/a:ext uri {C183D7F6-…} / adec:decorative@val), PowerPoint's "Mark as decorative": a purely visual element assistive tech should skip. false when the extension is absent. A decorative shape typically has no description; the two are alternatives, not companions.

Returns ​

boolean

Inherited from ​

Shape.isDecorative

left ​

Get Signature ​

get left(): number | null

Left edge in EMU (a:off/@x), or null when the shape has no own transform.

Returns ​

number | null

Set Signature ​

set left(value): void

Parameters ​
ParameterType
valuenumber
Returns ​

void

Inherited from ​

Shape.left

lineAlign ​

Get Signature ​

get lineAlign(): string | null

The line alignment (spPr/a:ln/@algn) as the raw OOXML token, 'ctr' (centred on the shape's outline) or 'in' (inset, drawn wholly inside it), or null when unset. It shifts a thick outline by half its width, so it changes where the border sits relative to the fill.

Returns ​

string | null

Inherited from ​

Shape.lineAlign

lineCap ​

Get Signature ​

get lineCap(): string | null

The line end cap (spPr/a:ln/@cap) as the raw OOXML token, 'flat', 'rnd' (round) or 'sq' (square), or null when unset (PowerPoint's default is flat). The write API authors this attribute through ShapeLineProps.cap, so without the accessor a deck this library produced could not be read back without losing it.

Not cosmetic on a thick dashed rule: the cap decides whether each dash reads as a rectangle or a lozenge, and it extends every dash by the stroke width. SVG's stroke-linecap is the exact equivalent (flat→butt, rnd→round, sq→square).

Returns ​

string | null

Inherited from ​

Shape.lineCap

lineColor ​

Get Signature ​

get lineColor(): string | null

Explicit RGB line/border colour (spPr/a:ln/a:solidFill/a:srgbClr/@val), or null.

Returns ​

string | null

Set Signature ​

set lineColor(value): void

Parameters ​
ParameterType
valuestring | null
Returns ​

void

Inherited from ​

Shape.lineColor

lineDash ​

Get Signature ​

get lineDash(): string | null

The line/border dash style (spPr/a:ln/a:prstDash/@val), e.g. 'dash', 'lgDashDot', 'sysDot', or null when the line is solid/unset. A faithful replica of dashed dividers and dashed card borders needs this: it is otherwise invisible in lineColor/lineWidthPt alone.

Returns ​

string | null

Inherited from ​

Shape.lineDash

lineEnds ​

Get Signature ​

get lineEnds(): LineEnds | null

The shape's line/connector arrowheads (a:ln/a:headEnd + a:tailEnd), or null when neither end carries one. Essential for replicating connectors, whose dot/arrow ends are otherwise invisible in the geometry.

Returns ​

LineEnds | null

Inherited from ​

Shape.lineEnds

lineGradient ​

Get Signature ​

get lineGradient(): GradientFill | null

The shape's line/border gradient stroke (spPr/a:ln/a:gradFill), or null when the line is a solid, absent, or inherited border (see resolvedLine). The line counterpart of gradientFill: a gradient-stroked connector (common for faded process arrows in styled decks) otherwise surfaces only its lineWidthPt, dropping the colour entirely, so a replica cannot reproduce the stroke.

Returns ​

GradientFill | null

Inherited from ​

Shape.lineGradient

lineNoFill ​

Get Signature ​

get lineNoFill(): boolean

true when the shape sets an explicit no-line (spPr/a:ln/a:noFill): a deliberately border-less shape. Distinct from simply having no a:ln (an inherited line), which resolvedLine cannot tell apart: both report null. A replica that relies on a shadow instead of a border needs to know the border was explicitly suppressed.

Returns ​

boolean

Inherited from ​

Shape.lineNoFill

linePatternFill ​

Get Signature ​

get linePatternFill(): PatternFill | null

The shape's line/border pattern stroke (spPr/a:ln/a:pattFill), or null when the line is not a pattern. The line counterpart of patternFill, and what the write side's line.pattern writes.

Returns ​

PatternFill | null

Inherited from ​

Shape.linePatternFill

lineSchemeColor ​

Get Signature ​

get lineSchemeColor(): string | null

Theme colour token when the line is a scheme colour (a:ln/a:solidFill/a:schemeClr/@val), or null.

Returns ​

string | null

Set Signature ​

set lineSchemeColor(value): void

Parameters ​
ParameterType
valuestring | null
Returns ​

void

Inherited from ​

Shape.lineSchemeColor

lineWidthPt ​

Get Signature ​

get lineWidthPt(): number | null

Line/border width in points (spPr/a:ln/@w is EMU; 12700 EMU = 1pt), or null when unset.

Returns ​

number | null

Inherited from ​

Shape.lineWidthPt

locks ​

Get Signature ​

get locks(): Record<string, boolean> | null

The shape's lock flags: the attributes of the locking element under its non-visual drawing properties (a:spLocks, a:picLocks, a:cxnSpLocks, a:graphicFrameLocks or a:grpSpLocks), each as the boolean it states, keyed by attribute name (noMove, noGrp, …). null when the shape has no locking element. The read counterpart of objectLock.

Returns ​

Record<string, boolean> | null

Inherited from ​

Shape.locks

media ​

Get Signature ​

get media(): PictureMedia | null

The audio or video this picture plays (p:nvPr/a:audioFile or a:videoFile), or null for a still picture. Its blip (imagePartName) is then the poster frame. See PictureMedia.

Returns ​

PictureMedia | null

mediaKind ​

Get Signature ​

get mediaKind(): "none" | "both" | "svg" | "raster"

Which drawable media this picture carries:

  • 'raster': only a raster blip (a:blip/@r:embed);
  • 'svg': only a vector blip (asvg:svgBlip/@r:embed, no raster). This is what PowerPoint's Insert → Icons and a plain SVG insert produce;
  • 'both': a raster fallback and an SVG (PowerPoint's usual pairing);
  • 'none': a p:pic with no embedded blip at all (e.g. a linked image).

Lets a caller distinguish an SVG-only picture (where imagePartName is legitimately null) from a genuinely empty one, without two null checks.

Returns ​

"none" | "both" | "svg" | "raster"

mediaPartName ​

Get Signature ​

get mediaPartName(): string | null

Absolute partname of whichever part actually carries this picture's drawn data (the raster part when present, otherwise the SVG part), or null when the picture embeds neither. Use this when you just want "the bytes this picture shows"; prefer imagePartName / svgPartName (and mediaKind) when you need to know which kind it is. An SVG-only picture returns its SVG part here even though imagePartName is null.

Returns ​

string | null

name ​

Get Signature ​

get name(): string

Shape name (p:cNvPr/@name), or '' if unnamed.

Returns ​

string

Inherited from ​

Shape.name

patternFill ​

Get Signature ​

get patternFill(): PatternFill | null

The shape's pattern (hatch) fill (spPr/a:pattFill), or null when the fill is not a pattern. Surfaces the PatternFill.preset name and both colours resolved against the host's theme: the pattern counterpart of resolvedFill, which reports null for a non-solid fill and so drops a hatched surface entirely.

Returns ​

PatternFill | null

Inherited from ​

Shape.patternFill

pictureFill ​

Get Signature ​

get pictureFill(): PictureFill | null

The shape's picture (image) fill (spPr/a:blipFill), or null when the fill is not a picture. The image-fill counterpart of patternFill: a shape whose surface is an image is not a Picture (it is an autoShape with a blip fill), and resolvedFill reports null for one, so without this an image-filled shape reads as unfilled. Carries the embedded image (PictureFill.relId/PictureFill.partName) plus the stretch/tile geometry.

Returns ​

PictureFill | null

Inherited from ​

Shape.pictureFill

placeholder ​

Get Signature ​

get placeholder(): PlaceholderRef | null

This shape's placeholder identity (p:ph type/idx), or null when it is not a placeholder. idx defaults to '0' when the attribute is absent, as PowerPoint does. A text placeholder is a p:sp; a filled picture, table or chart placeholder is a p:pic or p:graphicFrame carrying the same p:ph, which is what inserting a picture into a picture placeholder produces. This used to be null for every shape but a p:sp (#111). Use Slide.placeholder to find a text placeholder by type.

Returns ​

PlaceholderRef | null

Inherited from ​

Shape.placeholder

presetGeometry ​

Get Signature ​

get presetGeometry(): string | null

Preset geometry name (spPr/a:prstGeom/@prst, e.g. rect), or null for custom geometry or none. Not an auto-shape-only property: PowerPoint gives a picture and a connector a preset geometry too (a p:pic is rect unless it has been cropped to a shape), so it reads off whichever properties element this kind carries. A group has no geometry of its own and reads null.

Returns ​

string | null

Inherited from ​

Shape.presetGeometry

recolor ​

Get Signature ​

get recolor(): Recolor | null

The picture's blip recolour effect (p:blipFill/a:blip recolour child), or null when the blip carries none. Recognises the effects a faithful reader needs to reproduce a recoloured image: a:duotone (the two-stop icon-tint trick), a:clrChange, a:grayscl, a:biLevel, and a:alphaModFix; the first such effect in document order wins, and recolors lists them all. Colours mirror the GradientStop split (color/schemeColor/presetColor) so theme tokens resolve through Slide.themeContext. threshold/amount are 0–1 fractions. hidden (the duotone fallback-layer trick) reports the visibility of a recolour source; this reports the tint itself.

Returns ​

Recolor | null

recolors ​

Get Signature ​

get recolors(): Recolor[]

Every blip effect recolor recognises, in document order: the first is recolor. They combine (a picture can be faded with a:alphaModFix and recoloured too, which is how the write API emits transparency beside a recolour), and recolor alone reported only the first of them.

Returns ​

Recolor[]

reflection ​

Get Signature ​

get reflection(): Reflection | null

The shape's reflection (spPr/a:effectLst/a:reflection), or null when it has none. Read-only: this library authors no reflection, so a replica should carry the part rather than regenerate it (see Reflection).

Returns ​

Reflection | null

Inherited from ​

Shape.reflection

resolvedFill ​

Get Signature ​

get resolvedFill(): ResolvedColor | null

The shape's solid fill resolved against the host's theme (Slide.themeContext) to a literal hex: the resolved counterpart of fillColor/fillSchemeColor, which report the raw reference. null when the shape has no a:solidFill (a gradient/none/inherited fill) or the colour cannot be made literal. The returned ResolvedColor carries the base hex and raw transforms, and effectiveHex, the base with its colour transforms (lumMod/shade/…) applied (read that for the final rendered colour).

When the shape carries no explicit spPr fill choice, this falls back to the fill the shape inherits from its p:style a:fillRef (the theme style matrix), resolved the same way the theme: 'preserve' flatten path bakes it.

Returns ​

ResolvedColor | null

Inherited from ​

Shape.resolvedFill

resolvedFrame ​

Get Signature ​

get resolvedFrame(): ResolvedFrame | null

This shape's effective position and size in EMU: its own a:xfrm when it has one (left/top/width/height, tagged source: 'own'); otherwise, for a placeholder, the geometry it inherits from the matching layout placeholder, else the master's (tagged accordingly). A non-placeholder shape with no own transform has nothing to inherit from and reads null, as does a placeholder whose layout/master chain defines no matching geometry either.

The writer always emits an explicit a:xfrm on every placeholder it authors, so source reads 'own' for every authored deck; 'layout'/'master' is the case an imported deck exercises, when PowerPoint itself leaves a placeholder's geometry to inherit.

Returns ​

ResolvedFrame | null

Inherited from ​

Shape.resolvedFrame

resolvedLine ​

Get Signature ​

get resolvedLine(): ResolvedColor | null

The shape's line/border solid fill resolved against the host's theme to a literal hex: the resolved counterpart of lineColor/lineSchemeColor. null when the shape has no a:ln/a:solidFill or it cannot be made literal. Like resolvedFill, the result carries effectiveHex (the base colour with its transforms applied) for the final rendered colour.

When the shape's spPr/a:ln states no fill of its own, this falls back to the line colour the shape inherits from its p:style a:lnRef (the theme style matrix). An a:ln without a fill is not a replacement: PowerPoint layers it over the style line one property at a time, and changing only an outline's weight writes <a:ln w="76200"/> and paints the style colour (test/read/fixtures/shape-line-style-override.pptx).

Returns ​

ResolvedColor | null

Inherited from ​

Shape.resolvedLine

rotation ​

Get Signature ​

get rotation(): number | null

Clockwise rotation in degrees (a:xfrm/@rot ÷ 60000), or null when the shape has no own transform. A present xfrm with no @rot reads as 0, so, mirroring left/top/width/height, null ("inherits layout geometry") stays distinct from 0 ("has a transform, not rotated"). The value is faithful to the XML and not normalised to a signed range, so a @rot past 360° (e.g. a negative angle stored as 19216344) reads back greater than 360. This is the shape's own orientation; use absoluteFrame when you need the effective orientation after enclosing group transforms are composed.

Returns ​

number | null

Inherited from ​

Shape.rotation

shadow ​

Get Signature ​

get shadow(): OuterShadow | null

The shape's outer drop shadow (spPr/a:effectLst/a:outerShdw), resolved against the host's theme, or null when the shape has no outer shadow. The soft brand shadows the eye reads as "floating" panels live here and are invisible in geometry/fill alone.

Returns ​

OuterShadow | null

Inherited from ​

Shape.shadow

softEdge ​

Get Signature ​

get softEdge(): SoftEdge | null

The shape's soft (feathered) edge (spPr/a:effectLst/a:softEdge), or null when it has none. Read-only like reflection: carry, don't regenerate.

Returns ​

SoftEdge | null

Inherited from ​

Shape.softEdge

svgPartName ​

Get Signature ​

get svgPartName(): string | null

Absolute partname of the embedded SVG image, or null. Same rule as imagePartName.

Returns ​

string | null

svgRelId ​

Get Signature ​

get svgRelId(): string | null

Relationship id of the embedded vector (SVG) image, read from the Microsoft SVG blip extension (a:blip/a:extLst/a:ext/asvg:svgBlip/@r:embed), or null when the picture has no SVG. PowerPoint usually pairs this with a raster fallback in a:blip/@r:embed (imageRelId), but some exporters emit an SVG-only blip where imageRelId is absent and only this resolves, so a reader that wants the real drawn art must consult both.

Returns ​

string | null

text ​

Get Signature ​

get text(): string

Convenience: the shape's full text, or '' if it has none.

Returns ​

string

Set Signature ​

set text(value): void

Convenience: replace the shape's text with a single run, preserving the first existing run's formatting (see TextFrame.text). Throws when the shape has no text frame. For multiple runs or per-run formatting, edit textFrame.paragraphs[].runs[] directly.

Parameters ​
ParameterType
valuestring
Returns ​

void

Inherited from ​

Shape.text

textFrame ​

Get Signature ​

get textFrame(): TextFrame | null

The shape's text frame, or null when it cannot hold text.

Returns ​

TextFrame | null

Inherited from ​

Shape.textFrame

title ​

Get Signature ​

get title(): string | null

The shape's alt-text title (p:cNvPr/@title), or null when unset. Modern PowerPoint no longer exposes a separate title field (only description + "mark as decorative"), so this is usually null; it survives on decks authored by older PowerPoint or other producers that still write it.

Returns ​

string | null

Inherited from ​

Shape.title

top ​

Get Signature ​

get top(): number | null

Top edge in EMU (a:off/@y), or null when the shape has no own transform.

Returns ​

number | null

Set Signature ​

set top(value): void

Parameters ​
ParameterType
valuenumber
Returns ​

void

Inherited from ​

Shape.top

width ​

Get Signature ​

get width(): number | null

Width in EMU (a:ext/@cx), or null when the shape has no own transform.

Returns ​

number | null

Set Signature ​

set width(value): void

Parameters ​
ParameterType
valuenumber
Returns ​

void

Inherited from ​

Shape.width

Methods ​

delete() ​

delete(): void

Remove this shape from its parent (the host's shape tree, or an enclosing group) and mark the owning host's part dirty. The proxy is dead afterwards.

The build animations targeting the shape, or any shape inside a deleted group, go with it, and a connector attached to one of them keeps its geometry with that end unbound. PowerPoint refuses a deck whose animation names a shape that is not on the slide.

Returns ​

void

Inherited from ​

Shape.delete

markDirty() ​

markDirty(): void

Mark the owning host's part dirty so save() reserializes it. Public because element_ hands out the live DOM node: the hatch and the obligation that comes with it belong on the same object.

Returns ​

void

Inherited from ​

Shape.markDirty

noFill() ​

noFill(): void

Set an explicit <a:noFill/> on the shape: a transparent surface. This is distinct from clearing the fill (fillColor = null), which removes the a:solidFill and lets the fill inherit from the shape's style/placeholder. Read it back with fillNoFill.

Returns ​

void

Inherited from ​

Shape.noFill

setImage() ​

setImage(bytes, options): void

Replace this picture's image with new bytes. Mints a fresh media part under /ppt/media/, registers its content type, wires an image relationship from the owning part, and repoints the blip's @r:embed at it.

Copy-on-write: the previous media part is never mutated or removed, so any other picture sharing it (common after importSlide/dedup) is unaffected; an orphaned old part is left in place for a later GC pass to prune.

contentType is required (e.g. image/png); the bytes are not sniffed. extension defaults from the content type.

fit controls the picture's a:srcRect crop against its current frame extent (a:xfrm/a:ext):

  • omitted (default): geometry and crop are left untouched; the caller owns sizing. Note an inherited a:srcRect was tuned to the previous image's aspect ratio, so swapping in an image of a different ratio reuses a crop that no longer fits and the result looks stretched; pass fit to refit.
  • 'cover': fill the frame, cropping the overflowing axis (no distortion).
  • 'contain': fit the whole image inside the frame, letterboxing the short axis (no distortion).
  • 'stretch': drop any crop so the full image is stretched to the frame.

'cover'/'contain' measure the new bytes' natural size; if unmeasurable (e.g. an unknown format) the crop is left as-is and a warning is emitted.

Parameters ​

ParameterType
bytesUint8Array
options{ contentType: string; extension?: string; fit?: "contain" | "cover" | "stretch"; }
options.contentTypestring
options.extension?string
options.fit?"contain" | "cover" | "stretch"

Returns ​

void