> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shapes

## `Shape`

`PowerPoint.Shape`. Handles are live element references; edits apply at once.

Import from `@reductoai/pptx/officejs`.

### Shape properties

| Name | Type | Description |
| - | - | - |
| `fill` | `ShapeFill` | read-only |
| `lineFormat` | `ShapeLineFormat` | read-only |
| `textFrame` | `TextFrame` | read-only |
| `adjustments` | `Adjustments` | read-only |
| `altTextDescription` | `string` | |
| `altTextTitle` | `string` | |
| `customXmlParts` | `CustomXmlPartCollection` | read-only |
| `geometricShapeType` | `GeometricShapeType \| null` | Extension (VBA `Shape.AutoShapeType`; Change Shape, and Crop to Shape on a picture): the preset outline, `null` for a drawn one. Setting it drops the old adjustments. |
| `glow` | `GlowFormat` | read-only Extension (VBA `Shape.Glow`). |
| `group` | `ShapeGroup` | read-only |
| `height` | `number` | |
| `horizontalFlip` | `boolean` | read-only Extension (VBA `Shape.HorizontalFlip`): mirrored left to right, `a:xfrm@flipH`. |
| `id` | `string` | read-only |
| `isDecorative` | `boolean` | Marked decorative: screen readers skip it (the Office 2019 `adec:decorative` extension). |
| `left` | `number` | |
| `level` | `number` | read-only |
| `name` | `string` | |
| `parentGroup` | `Shape` | read-only |
| `pictureFormat` | `PictureFormat` | read-only Headless extension (VBA `Shape.PictureFormat`): crop of a picture. |
| `placeholderFormat` | `PlaceholderFormat` | read-only |
| `reflection` | `ReflectionFormat` | read-only Extension (VBA `Shape.Reflection`). |
| `rotation` | `number` | Clockwise rotation in degrees. |
| `shadow` | `ShadowFormat` | read-only Extension (VBA `Shape.Shadow`): the shape's outer shadow. |
| `softEdge` | `SoftEdgeFormat` | read-only Extension (VBA `Shape.SoftEdge`). |
| `tags` | `TagCollection` | read-only |
| `top` | `number` | |
| `type` | `ShapeType` | read-only |
| `verticalFlip` | `boolean` | read-only Extension (VBA `Shape.VerticalFlip`): mirrored top to bottom, `a:xfrm@flipV`. |
| `visible` | `boolean` | |
| `width` | `number` | |
| `zOrderPosition` | `number` | read-only |

### `Shape.delete()`

```ts theme={null}
delete(): void
```

### `Shape.flip()`

```ts theme={null}
flip(flipCmd: ShapeFlip): void
```

Extension (VBA `Shape.Flip`): mirrors the shape in its box; a second flip undoes the first.

### `Shape.getChart()`

```ts theme={null}
getChart(): Chart
```

Headless extension: the chart in this graphic frame.

### `Shape.getImageAsBase64()`

```ts theme={null}
getImageAsBase64(options?: ImageSizeOptions): Promise<string>
```

Office.js queues a ClientResult; the facade resolves a Base64 PNG of this shape alone.

### `Shape.getParentSlide()`

```ts theme={null}
getParentSlide(): Slide
```

### `Shape.getParentSlideLayout()`

```ts theme={null}
getParentSlideLayout(): SlideLayout
```

### `Shape.getParentSlideLayoutOrNullObject()`

```ts theme={null}
getParentSlideLayoutOrNullObject(): SlideLayout & { isNullObject: boolean }
```

### `Shape.getParentSlideMaster()`

```ts theme={null}
getParentSlideMaster(): SlideMaster
```

### `Shape.getParentSlideMasterOrNullObject()`

```ts theme={null}
getParentSlideMasterOrNullObject(): SlideMaster & { isNullObject: boolean }
```

### `Shape.getParentSlideOrNullObject()`

```ts theme={null}
getParentSlideOrNullObject(): Slide & { isNullObject: boolean }
```

### `Shape.getTable()`

```ts theme={null}
getTable(): Table
```

### `Shape.getTextFrameOrNullObject()`

```ts theme={null}
getTextFrameOrNullObject(): TextFrame & { isNullObject: boolean }
```

### `Shape.setHyperlink()`

```ts theme={null}
setHyperlink(options?: HyperlinkAddOptions): Hyperlink
```

Links the whole shape; a click on it follows the link.

### `Shape.setZOrder()`

```ts theme={null}
setZOrder(position: ShapeZOrder): void
```

## `ShapeCollection`

`PowerPoint.ShapeCollection` of one slide, layout or master.

Import from `@reductoai/pptx/officejs`.

### ShapeCollection properties

| Name | Type | Description |
| - | - | - |
| `items` | `T[]` | read-only |

### `ShapeCollection.addChart()`

```ts theme={null}
addChart(options: ChartAddOptions): Shape
```

Headless extension (VBA `Shapes.AddChart2`): a column, bar, line, pie or area chart
from literal data. Without a size it is 432 x 252 pt.

### `ShapeCollection.addCopy()`

```ts theme={null}
addCopy(shape: Shape, options?: ShapeAddOptions): Shape
```

Extension (VBA `Shape.Copy` then `Shapes.Paste`): a copy of a shape of this presentation,
where the original sits or at `options`. A copied chart gets its own chart part and data.

### `ShapeCollection.addGeometricShape()`

```ts theme={null}
addGeometricShape(
  geometricShapeType: GeometricShapeType,
  options?: ShapeAddOptions,
): Shape
```

### `ShapeCollection.addGroup()`

```ts theme={null}
addGroup(values: (string | Shape)[]): Shape
```

Groups shapes of this collection, given as handles or ids.

### `ShapeCollection.addLine()`

```ts theme={null}
addLine(connectorType?: ConnectorType, options?: ShapeAddOptions): Shape
```

### `ShapeCollection.addMedia()`

```ts theme={null}
addMedia(media: Uint8Array, poster: ImageSource, options?: ShapeAddOptions): Shape
```

Headless extension (VBA `Shapes.AddMediaObject2`, embedded): an MP4, M4V, MOV, M4A, MP3 or WAV
file shown as `poster` (PNG, JPEG or GIF). Sized and placed as `addPicture` places the poster.

### `ShapeCollection.addPicture()`

```ts theme={null}
addPicture(image: ImageSource, options?: PictureAddOptions): Shape
```

Headless extension (VBA `Shapes.AddPicture`): a PNG, JPEG, GIF, EMF, WMF or SVG picture, as
base64, a data URL or bytes. Without a size it takes its natural size, shrunk to fit the slide;
one given side keeps the aspect ratio. Without a position it is centred on the slide.

### `ShapeCollection.addPlaceholder()`

```ts theme={null}
addPlaceholder(type: PlaceholderType, options?: ShapeAddOptions): Shape
```

Extension, a superset of VBA `Shapes.AddPlaceholder`. On a slide it restores the layout's first
missing placeholder of `type`, as VBA does, and otherwise adds a new one; on a layout or master
it adds a new placeholder. Without a box it takes the geometry it inherits.

### `ShapeCollection.addTable()`

```ts theme={null}
addTable(rowCount: number, columnCount: number, options?: TableAddOptions): Shape
```

A table of `rowCount` x `columnCount` cells. Without cell properties it takes PowerPoint's
default look (Medium Style 2 - Accent 1, header row, banded rows); with them it is plain.

### `ShapeCollection.addTextBox()`

```ts theme={null}
addTextBox(text: string, options?: ShapeAddOptions): Shape
```

### `ShapeCollection.buildFreeform()`

```ts theme={null}
buildFreeform(editingType: EditingType, x1: number, y1: number): FreeformBuilder<Shape>
```

Extension (VBA `Shapes.BuildFreeform`): a freeform that starts at (x1, y1), in slide points.

### `ShapeCollection.getCount()`

```ts theme={null}
getCount(): ClientResult<number>
```

### `ShapeCollection.getItem()`

```ts theme={null}
getItem(key: string): Shape
```

### `ShapeCollection.getItemAt()`

```ts theme={null}
getItemAt(index: number): Shape
```

### `ShapeCollection.getItemOrNullObject()`

```ts theme={null}
getItemOrNullObject(key: string): Shape & { isNullObject: boolean }
```

Office.js null-object variant; inspect `isNullObject` before other members.

## `ShapeAddOptions`

Import from `@reductoai/pptx/officejs`.

| Name | Type | Description |
| - | - | - |
| `height?` | `number` | |
| `left?` | `number` | |
| `top?` | `number` | |
| `width?` | `number` | |

## `PictureAddOptions`

Extension: `fallbackImage` is the bitmap an SVG picture shows where SVG is not read.

Import from `@reductoai/pptx/officejs`.

```ts theme={null}
type PictureAddOptions = ShapeAddOptions & { fallbackImage?: ImageSource }
```

## `ShapeGroup`

`PowerPoint.ShapeGroup`: the members of a `p:grpSp`.

Import from `@reductoai/pptx/officejs`.

### ShapeGroup properties

| Name | Type | Description |
| - | - | - |
| `shape` | `Shape` | read-only |
| `id` | `string` | read-only |
| `shapes` | `ShapeScopedCollection` | read-only |

### `ShapeGroup.ungroup()`

```ts theme={null}
ungroup(): void
```

Moves the members into the group's parent at the group's z-position and removes the group.

## `FreeformBuilder`

Extension (VBA `FreeformBuilder`): the nodes of a freeform, in slide points, made into a shape by
`convertToShape`. A figure whose last node lands on its first is closed, as in PowerPoint.

Import from `@reductoai/pptx/officejs`.

### `FreeformBuilder.addNodes()`

```ts theme={null}
addNodes(
  segmentType: SegmentType,
  editingType: EditingType,
  x1: number,
  y1: number,
  x2?: number,
  y2?: number,
  x3?: number,
  y3?: number,
): void
```

VBA `FreeformBuilder.AddNodes`: a corner curve takes two control points and its end, x1..y3.

### `FreeformBuilder.closeFigure()`

```ts theme={null}
closeFigure(): void
```

Extension (GDI+ `GraphicsPath.CloseFigure`): joins the figure's last node to its first.

### `FreeformBuilder.convertToShape()`

```ts theme={null}
convertToShape(): S
```

VBA `FreeformBuilder.ConvertToShape`.

### `FreeformBuilder.startFigure()`

```ts theme={null}
startFigure(x: number, y: number): void
```

Extension (GDI+ `GraphicsPath.StartFigure`): a new figure of the same shape from (x, y).

## `PlaceholderFormat`

`PowerPoint.PlaceholderFormat`.

Import from `@reductoai/pptx/officejs`.

### PlaceholderFormat properties

| Name | Type | Description |
| - | - | - |
| `containedType` | `string \| null` | read-only The kind of content the placeholder holds; null while it is empty. |
| `index` | `number` | read-only Headless extension: `p:ph@idx`, the key that ties a slide placeholder to its layout. |
| `type` | `PlaceholderType` | read-only |
