# PPTX API

PPTX APIs are called through the `app` returned by `widget.render()`:

    const { widget } = await OfficeSdk.openfile({ docId: "demo-pptx", fileName: "demo.pptx", file });
    const app = await widget.mount("#office-container").render();

## Components#

Component | Description
--- | ---
`Document` | Page number, zoom, layout, export, and read-only state
`Paragraph` | Text font, color, size, bold, italic, underline, strikethrough, and horizontal paragraph alignment
`TextBox` | Text box vertical alignment
`Player` | Slide playback and full-screen playback
`Selection` | Selection type, text style queries, and selection change events
`Viewer` | Current active target in the thumbnail area
`UndoRedo` | Undo, redo, and availability state

## Quick Example#

    app.Document.setZoom(120);
    app.Document.goToSlide(2);

    app.Paragraph.setFontName("Arial");
    app.Paragraph.setBold(true);
    app.Paragraph.setAlignment(2);

    app.TextBox.setVerticalAlignment(1);
    app.Player.play(1);

Event example:

    function onSelectionChange(info) {
      console.log(info.selectType);
    }

    app.Selection.addEventListener("SELECTION_CHANGE", onSelectionChange);

## Document#

Method | Signature | Returns | Description
--- | --- | --- | ---
`getSlideInfo` | `(): { total: number; current: number }` | `{ total; current }` | Gets total slide count and current slide. Page numbers start from `1`.
`getCurrentSlideIndex` | `(): number` | `number` | Gets current page number. Page numbers start from `1`.
`getSlideCount` | `(): number` | `number` | Gets total slide count.
`getZoom` | `(): number` | `number` | Gets zoom percentage.
`setZoom` | `(value: number): void` | `void` | Sets zoom percentage. Common values include `80`, `100`, and `120`.
`autoZoom` | `(): void` | `void` | Adjusts the zoom automatically.
`focusEditor` | `(): void` | `void` | Currently a no-op in the PPTX implementation.
`updateVisibleArea` | `(): void` | `void` | Recalculates the visible area.
`goToSlide` | `(slideNum: number): void` | `void` | Goes to a slide. `slideNum` starts from `1`.
`deleteSlides` | `(slides?: number[]): void` | `void` | Deletes specified slide indexes. If omitted, deletes the currently selected slide. `slides` uses zero-based indexes.
`addSlide` | `(layout?: SlideLayoutRef, position?: number): void` | `void` | Inserts a new slide. `layout` uses layout indexes, and `position` is the zero-based insert position. If `layout` is omitted, the layout near the current selection is reused.
`getSlideLayouts` | `(force?: boolean): SlideLayoutItem[][]` | `SlideLayoutItem[][]` | Gets layouts grouped by slide master. When `force = true`, refreshes the cache.
`exportDocument` | `(): Promise<void>` | `Promise<void>` | Exports the original PPTX file.
`exportPdf` | `(printOptions?: unknown): Promise<void>` | `Promise<void>` | Exports PDF with print options.
`copy` | `(): Promise<void>` | `Promise<void>` | Copies the current selection.
`cut` | `(): Promise<void>` | `Promise<void>` | Cuts the current selection.
`paste` | `(): Promise<void>` | `Promise<void>` | Pastes into the current selection.
`getColorPalette` | `(): { theme: unknown[]; standard: unknown[] }` | `{ theme; standard }` | Gets theme colors and standard colors.
`startReadOnly` | `(): void` | `void` | Enters read-only state.
`endReadOnly` | `(): void` | `void` | Exits read-only state.
`isReadOnly` | `(): boolean` | `boolean` | Whether the current state is read-only.
`isDisable` | `(): boolean` | `boolean` | Whether the current editor is disabled.

    type SlideLayoutRef = {
      masterIndex: number;
      layoutIndex: number;
    };

    type SlideLayoutItem = {
      img: unknown;
      name: string;
      xmlName: string;
      id: string | number;
      layoutIndex: number;
      slideMasterIndex: number;
    };

`goToSlide(slideNum)` uses display page numbers starting from `1`; `deleteSlides(slides)` and `addSlide(layout, position)` use zero-based underlying indexes.

Document example:

    const pages = app.Document.getSlideInfo();
    console.log(pages.current, pages.total);

    app.Document.goToSlide(1);
    const layoutGroups = app.Document.getSlideLayouts();
    const layout = layoutGroups[0][0];
    app.Document.addSlide(
      {
        masterIndex: layout.slideMasterIndex,
        layoutIndex: layout.layoutIndex
      },
      1
    );
    app.Document.deleteSlides([0]);

    await app.Document.exportDocument();
    await app.Document.exportPdf();

Document component events:

Event Name | Payload | Description
--- | --- | ---
`DOCUMENT_READY` | Raw event parameters | Document ready.
`DOCUMENT_EXPORT_READY` | Raw event parameters | Export completed.
`DOCUMENT_EDITING_ENABLED` | None | The document entered editable state.
`DOCUMENT_EDITING_DISABLED` | None | The document exited editable state.
`PPTX_SLIDES_CHANGED` | `(currentPage: number, totalPages: number)` | Current page or page count changed.
`PPTX_ZOOM_CHANGE` | `(zoom: number)` | Zoom changed.
`PPTX_FIRST_PAGE_LOADED` | None | First page loaded.
`PPTX_START_LOADING` | None | Loading started.

`exportPdf(...)` requires a secure context (normally HTTPS or localhost), `window.queryLocalFonts`, and permission to access local fonts. If these requirements are not met, the current implementation does not perform the PDF export.

## Paragraph#

Method | Signature | Returns | Description
--- | --- | --- | ---
`setFontName` | `(value: string): void` | `void` | Sets font family.
`setFontColor` | `(value: string \| { hex: string; [key: string]: unknown }): void` | `void` | Sets font color. Prefer an object containing `hex`; the current string parser has a known limitation when any color channel is `0`.
`setFontSize` | `(value: number \| string): void` | `void` | Sets font size.
`setBold` | `(value: boolean): void` | `void` | Sets bold.
`setItalic` | `(value: boolean): void` | `void` | Sets italic.
`setUnderline` | `(value: boolean): void` | `void` | Sets underline.
`setStrikeThrough` | `(value: boolean): void` | `void` | Sets strikethrough.
`setAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | Sets horizontal paragraph alignment.
`decreaseFontSize` | `(): void` | `void` | Decreases font size.
`increaseFontSize` | `(): void` | `void` | Increases font size.

`setAlignment(value)` enum:

Value | Description
--- | ---
`0` | Right
`1` | Left
`2` | Center
`3` | Justified
`4` | Distributed

Paragraph example:

    app.Paragraph.setFontName("Microsoft YaHei");
    app.Paragraph.setFontColor({ hex: "#4472C4" });
    app.Paragraph.setFontSize(18);
    app.Paragraph.setBold(true);
    app.Paragraph.setItalic(false);
    app.Paragraph.setUnderline(true);
    app.Paragraph.setStrikeThrough(false);
    app.Paragraph.setAlignment(2);
    app.Paragraph.increaseFontSize();

## TextBox#

Method | Signature | Returns | Description
--- | --- | --- | ---
`setVerticalAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | Sets text box vertical alignment.

`setVerticalAlignment(value)` enum:

Value | Description
--- | ---
`0` | Top
`1` | Center
`2` | Bottom
`3` | Justified distribution
`4` | Distributed

Example:

    app.TextBox.setVerticalAlignment(1);

## Player#

Method | Signature | Returns | Description
--- | --- | --- | ---
`playFirst` | `(): void` | `void` | Plays from the first slide.
`playLast` | `(): void` | `void` | Plays the last slide.
`play` | `(fromType: 1 \| 2): void` | `void` | Starts slide playback.
`playPrevious` | `(): void` | `void` | Plays the previous slide.
`playNext` | `(): void` | `void` | Plays the next slide.
`enterFullScreen` | `(fromType: 1 \| 2): void` | `void` | Enters full-screen playback.
`exitFullScreen` | `(): void` | `void` | Exits full screen.

`fromType`:

Value | Description
--- | ---
`1` | From beginning
`2` | From current slide

Example:

    app.Player.play(2);
    app.Player.enterFullScreen(1);
    app.Player.exitFullScreen();

## Selection#

Method | Signature | Returns | Description
--- | --- | --- | ---
`isTextSelected` | `(): boolean` | `boolean` | Whether text is currently selected.
`isTableSelected` | `(): boolean` | `boolean` | Whether a table is currently selected.
`isShapeSelected` | `(): boolean` | `boolean` | Whether a shape is currently selected.
`isSmartArtSelected` | `(): boolean` | `boolean` | Whether SmartArt is currently selected.
`isChartSelected` | `(): boolean` | `boolean` | Whether a chart is currently selected.
`isUnderline` | `(): boolean` | `boolean` | Whether the current text has single underline.
`isStrikeThrough` | `(): boolean` | `boolean` | Whether the current text has single strikethrough.
`getFontSize` | `(): string` | `string` | Gets current font size. For mixed font sizes, returns the minimum font size plus `+`.
`getFontName` | `(): string \| null` | `string \| null` | Gets current font family. For mixed fonts, returns an empty string.
`isBold` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | Gets bold state. Returns `0` for mixed states.
`isItalic` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | Gets italic state. Returns `0` for mixed states.
`getFontColor` | `(): string` | `string` | Gets font color as an `rgba(...)` string. The alpha value comes from underlying data and must not be assumed to be CSS-normalized to `0` through `1`.
`getAlignment` | `(): "default" \| "right" \| "left" \| "center" \| "justify" \| "distribute" \| "nil"` | `string` | Gets horizontal paragraph alignment.
`getVerticalAlignment` | `(): "top" \| "center" \| "bottom" \| "default" \| "NIL" \| undefined` | `string \| undefined` | Gets text box vertical alignment.

Selection example:

    if (app.Selection.isTextSelected()) {
      console.log(app.Selection.getFontName());
      console.log(app.Selection.getFontColor());
    }

`getAlignment()` return values:

Value | Description
--- | ---
`"default"` | Default alignment.
`"right"` | Right.
`"left"` | Left.
`"center"` | Center.
`"justify"` | Justified.
`"distribute"` | Distributed.
`"nil"` | Multiple selected contents do not share one horizontal alignment value.

`getVerticalAlignment()` return values:

Value | Description
--- | ---
`"top"` | Top.
`"center"` | Center.
`"bottom"` | Bottom.
`"default"` | Default vertical alignment.
`"NIL"` | Multiple selected contents do not share one vertical alignment value.
`undefined` | No recognizable vertical alignment value currently.

Selection component events:

Event Name | Payload
--- | ---
`SELECTION_CHANGE` | `PptxSelectionChange`

    type PptxSelectionChange = {
      selectType: number;
      bold?: boolean | 0 | null;
      italic?: boolean | 0 | null;
      fontName?: string | null;
      fontSize?: string;
      fontColor?: string;
      underline?: boolean;
      strikeout?: boolean;
      alignHorizontal?: string;
      alignVertical?: string;
      canCopy: boolean;
    };

`selectType` is a bit flag and can be combined with bitwise OR:

Value | Description
--- | ---
`0` | No stable selection
`1` | Table
`2` | Shape
`4` | Text
`6` | Shape + text
`8` | SmartArt
`16` | Chart
`32` | Image

Common combined values:

Value | Description
--- | ---
`6` | Shape + text

## Viewer#

Method | Signature | Returns | Description
--- | --- | --- | ---
`getActiveZoom` | `(): null \| "" \| "Thumbnail" \| "ThumbnailGapLine"` | `string \| null` | Gets the current active target in the thumbnail area. Returns `null` before the first active-target event.

Return values:

Value | Description
--- | ---
`null` | No active-target event has been received yet.
`""` | No stable target currently.
`"Thumbnail"` | Thumbnail.
`"ThumbnailGapLine"` | Gap line between thumbnails.

## UndoRedo#

Method | Signature | Returns | Description
--- | --- | --- | ---
`undo` | `(): void` | `void` | Undo.
`redo` | `(): void` | `void` | Redo.
`canUndo` | `(): boolean` | `boolean` | Whether undo is available.
`canRedo` | `(): boolean` | `boolean` | Whether redo is available.

UndoRedo component events:

Event Name | Payload
--- | ---
`UNDO_REDO_STATE_CHANGE` | Raw event parameters

Example:

    if (app.UndoRedo.canUndo()) {
      app.UndoRedo.undo();
    }