Show.Chart

Show.Chart is an object type of the Presentation module (Office.show(iframe)). 50 methods.

Generated from the SDK type definitions

Presentation · 10 object types · 586 methods · namespace Show. This reference is generated from the API document artifact (sdk-api-doc.html) produced with the SDK build. Descriptions are the editor's API comments as published. Pin the SDK and Office versions together and regenerate when either changes.

Remarks

• Module: Presentation · Office.show(iframe) · namespace Show
• Obtained from: Document.findCharts(slides, filter), Slide.findCharts(filter)
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
align(alignType)	Aligns the shape relative to the slide.
flip(direction)	Flips the shape vertically or horizontally.
getAxisTitle(axis)	Returns the title of the given axis.
getDataLabelPosition()	Returns the data label position.
getGridLine(axis)	Returns the gridline type of the given axis.
getHeight()	Returns the shape's height.
getHyperlink()	Returns the hyperlink set on the shape.
getLegendPosition()	Returns the legend position.
getPlaceholderType()	Returns the placeholder type of the shape.
getPresetId()	Returns the shape's OOXML preset id (prst).
getRotation()	Returns the rotation angle of the shape.
getState()	Returns the formatting state of the chart at once.
getTitle()	Returns the chart title.
getTransform()	Returns the position, size, and rotation of the shape.
getType()	Returns the chart type.
getWidth()	Returns the shape's width.
getX()	Returns the shape's X coordinate.
getY()	Returns the shape's Y coordinate.
getZOrderIndex()	Returns the z-order index of the shape within its parent (the slide, or the group for a group child).
hasText()	Returns whether the shape contains text.
isChart()	Checks whether this handle is a Chart (a type guard for union narrowing).
isControl()	Checks whether this handle is a Control (a type guard for union narrowing).
isDiagram()	Checks whether this handle is a Diagram (a type guard for union narrowing).
isEditable()	Returns whether this chart can be edited.
isFlippedH()	Returns whether the shape is flipped horizontally.
isFlippedV()	Returns whether the shape is flipped vertically.
isGroup()	Checks whether this handle is a Group (a type guard for union narrowing).
isImage()	Checks whether this handle is an Image (a type guard for union narrowing).
isLine()	Checks whether this handle is a Line (a type guard for union narrowing).
isOleObject()	Checks whether this handle is an OleObject (a type guard for union narrowing).
isPlaceholder()	Returns whether the shape is a placeholder (title, body frame, etc.).
isShape()	Checks whether this handle is a Shape (a type guard for union narrowing).
isTable()	Checks whether this handle is a Table (a type guard for union narrowing).
moveBy(distance)	Moves the shape by x, y relative to its current position.
removeHyperlink()	Removes the shape's hyperlink.
reorder(order)	Changes the shape's z-order (forward/backward).
setAxisTitle(axis, title)	Sets the title of the given axis.
setDataLabelPosition(position)	Sets the data label position.
setGridLine(axis, gridType)	Sets the gridlines of the given axis.
setHeight(height)	Sets the height of the shape.
setHyperlink(hyperlink)	Sets a hyperlink on the shape (symmetric with getHyperlink - the returned object can be passed back to copy a hyperlink).
setLegendPosition(position)	Sets the legend position.
setRotation(rotation)	Sets the rotation angle of the shape as an absolute value.
setStyle(style)	Changes the chart's preset style.
setTitle(title)	Sets the chart title.
setTransform(transform)	Sets the position, size, and rotation of the shape in one call.
setType(chartType)	Changes the chart type.
setWidth(width)	Sets the width of the shape.
setX(x)	Sets the X coordinate of the shape as an absolute value.
setY(y)	Sets the Y coordinate of the shape as an absolute value.

Method details

align(alignType)

Aligns the shape relative to the slide. Ignored for shapes that cannot be moved. Group children also move relative to the slide, not within the group (same as the editor). If a child moves outside its group, the group grows to contain it.

align(alignType: AlignType): Promise<void>;

Parameters

Name	Type	Description
alignType	AlignType	Alignment type

Returns

Promise<void>

flip(direction)

Flips the shape vertically or horizontally. This toggles the current flip state; read whether it is currently flipped with isFlippedH()/isFlippedV(). Ignored for shapes that cannot be rotated. For a rotated shape the angle is mirrored as well (getRotation() becomes 360 - previous angle).

flip(direction: FlipDirection): Promise<void>;

Parameters

Name	Type	Description
direction	FlipDirection	Flip direction

Returns

Promise<void>

getAxisTitle(axis)

Returns the title of the given axis. It is an empty string when no title is set, and null for chart types that have no axis title (pie family, doughnut, radar).

getAxisTitle(axis: ChartAxis): Promise<string | null>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to read the title from (horizontal or vertical)

Returns

Promise<string | null>

getDataLabelPosition()

Returns the data label position. A chart that does not show data labels returns "none".

getDataLabelPosition(): Promise<ChartDataLabelPosition>;

Returns

Promise<ChartDataLabelPosition>

getGridLine(axis)

Returns the gridline type of the given axis. An axis with gridlines turned off is "none", and chart types that have no gridlines for that axis (both axes for the pie family and doughnut, the vertical axis for radar) return null.

getGridLine(axis: ChartAxis): Promise<ChartGridLineType | null>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to read the gridlines from (horizontal or vertical)

Returns

Promise<ChartGridLineType | null>

getHeight()

Returns the shape's height. (Symmetric with setHeight.)

getHeight(): Promise<number | null>;

Returns

Promise<number | null> - Height (px). null if the target shape is gone

getHyperlink()

Returns the hyperlink set on the shape. The returned object can be passed straight to setHyperlink. null if an unsupported kind (run program, macro, etc.) is attached.

getHyperlink(): Promise<Hyperlink | null>;

Returns

Promise<Hyperlink | null> - Hyperlink information. null if there is no hyperlink (action)

getLegendPosition()

Returns the legend position. A chart with the legend hidden is "none", and a chart whose position cannot be determined is reported as "right".

getLegendPosition(): Promise<ChartLegendPosition>;

Returns

Promise<ChartLegendPosition>

getPlaceholderType()

Returns the placeholder type of the shape.

getPlaceholderType(): Promise<PlaceholderType | null>;

Returns

Promise<PlaceholderType | null> - Placeholder type. null if the shape is not a placeholder or the target shape is gone

getPresetId()

Returns the shape's OOXML preset id (prst).

getPresetId(): Promise<string | null>;

Returns

Promise<string | null> - Preset id (prst); null if none

getRotation()

Returns the rotation angle of the shape. (counterpart of setRotation)

getRotation(): Promise<number | null>;

Returns

Promise<number | null> - Rotation angle (degrees). null if the target shape is gone

getState()

Returns the formatting state of the chart at once. Each value follows the same contract as the getter of the same name. null for axisTitle and gridLine means that chart type has no axis title or gridlines at all, while "none" means it can have them but they are turned off.

getState(): Promise<{ type: string; title: string; legendPosition: ChartLegendPosition; dataLabelPosition: ChartDataLabelPosition; axisTitle: { horizontal: string | null; vertical: string | null }; gridLine: { horizontal: ChartGridLineType | null; vertical: ChartGridLineType | null } }>;

Returns

Promise<{ type: string; title: string; legendPosition: ChartLegendPosition; dataLabelPosition: ChartDataLabelPosition; axisTitle: { horizontal: string | null; vertical: string | null }; gridLine: { horizontal: ChartGridLineType | null; vertical: ChartGridLineType | null } }>

getTitle()

Returns the chart title. It returns an empty string when no title is set.

getTitle(): Promise<string>;

Returns

Promise<string>

getTransform()

Returns the position, size, and rotation of the shape. x/y are the top-left corner of the shape regardless of flip, so passing the returned value to another shape's setTransform places both shapes at the same spot. Values are rounded to the editor's input units - size to one decimal place, position to integers. The setters use the same units, so shapes placed more finely (e.g. imported documents) move by that amount when the value is passed back.

getTransform(): Promise<ShapeTransform | null>;

Returns

Promise<ShapeTransform | null> - Position, size, and rotation of the shape. null if the target shape is gone (e.g. deleted during collaboration)

getType()

Returns the chart type. A type that is not in ChartType returns "unknown".

getType(): Promise<string>;

Returns

Promise<string>

getWidth()

Returns the shape's width. (Symmetric with setWidth.)

getWidth(): Promise<number | null>;

Returns

Promise<number | null> - Width (px). null if the target shape is gone

getX()

Returns the shape's X coordinate. (Symmetric with setX.)

getX(): Promise<number | null>;

Returns

Promise<number | null> - X coordinate (px). null if the target shape is gone

getY()

Returns the shape's Y coordinate. (Symmetric with setY.)

getY(): Promise<number | null>;

Returns

Promise<number | null> - Y coordinate (px). null if the target shape is gone

getZOrderIndex()

Returns the z-order index of the shape within its parent (the slide, or the group for a group child). 0 is the back; larger values are further to the front.

getZOrderIndex(): Promise<number | null>;

Returns

Promise<number | null> - z-order index. null if the target shape is gone

hasText()

Returns whether the shape contains text. Uses the same criterion the editor uses for empty text - true when there is only whitespace or two or more empty paragraphs (only line breaks), false when there is a single empty paragraph. Kinds without shape-level text (table, group, chart) are always false. (query tables per cell)

hasText(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Whether text exists. null if the target shape is gone

isChart()

Checks whether this handle is a Chart (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isChart(): Promise<this is Chart>;

Returns

Promise<this is Chart>

isControl()

Checks whether this handle is a Control (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isControl(): Promise<this is Control>;

Returns

Promise<this is Control>

isDiagram()

Checks whether this handle is a Diagram (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isDiagram(): Promise<this is Diagram>;

Returns

Promise<this is Diagram>

isEditable()

Returns whether this chart can be edited. A chart sourced from external data can only be read, not edited.

isEditable(): Promise<boolean>;

Returns

Promise<boolean>

isFlippedH()

Returns whether the shape is flipped horizontally. (calling flip(FlipDirection.HORIZONTAL) toggles this value)

isFlippedH(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Horizontal flip state. null if the target shape is gone

isFlippedV()

Returns whether the shape is flipped vertically. (calling flip(FlipDirection.VERTICAL) toggles this value)

isFlippedV(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Vertical flip state. null if the target shape is gone

isGroup()

Checks whether this handle is a Group (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isGroup(): Promise<this is Group>;

Returns

Promise<this is Group>

isImage()

Checks whether this handle is an Image (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isImage(): Promise<this is Image>;

Returns

Promise<this is Image>

isLine()

Checks whether this handle is a Line (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isLine(): Promise<this is Line>;

Returns

Promise<this is Line>

isOleObject()

Checks whether this handle is an OleObject (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isOleObject(): Promise<this is OleObject>;

Returns

Promise<this is OleObject>

isPlaceholder()

Returns whether the shape is a placeholder (title, body frame, etc.).

isPlaceholder(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Placeholder state. null if the target shape is gone

isShape()

Checks whether this handle is a Shape (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isShape(): Promise<this is Shape>;

Returns

Promise<this is Shape>

isTable()

Checks whether this handle is a Table (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isTable(): Promise<this is Table>;

Returns

Promise<this is Table>

moveBy(distance)

Moves the shape by x, y relative to its current position. (Absolute placement is setX / setY.)

moveBy(distance: ShapeMoveDistance): Promise<void>;

Parameters

Name	Type	Description
distance	ShapeMoveDistance	Distance to move (px)

Returns

Promise<void>

removeHyperlink()

Removes the shape's hyperlink.

removeHyperlink(): Promise<void>;

Returns

Promise<void>

reorder(order)

Changes the shape's z-order (forward/backward). Ignored if it is already at the target position.

reorder(order: ShapeZOrder): Promise<void>;

Parameters

Name	Type	Description
order	ShapeZOrder	Reorder type

Returns

Promise<void>

setAxisTitle(axis, title)

Sets the title of the given axis. Axis titles are supported by every chart type except the pie family, doughnut, and radar.

setAxisTitle(axis: ChartAxis, title: string): Promise<void>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to set the title on (horizontal or vertical)
title	string	title to show on the axis

Returns

Promise<void>

setDataLabelPosition(position)

Sets the data label position. Passing "none" hides the data labels. The available positions differ by chart type, and "none" works for every type.

setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;

Parameters

Name	Type	Description
position	ChartDataLabelPosition	where to put the data labels

Returns

Promise<void>

setGridLine(axis, gridType)

Sets the gridlines of the given axis. Passing "none" hides the gridlines of that axis. Chart types that have no gridlines for that axis (both axes for the pie family and doughnut, the vertical axis for radar) raise an error for any value, "none" included.

setGridLine(axis: ChartAxis, gridType: ChartGridLineType): Promise<void>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to set the gridlines on (horizontal or vertical)
gridType	ChartGridLineType	gridline type to show

Returns

Promise<void>

setHeight(height)

Sets the height of the shape. Ignored for shapes that cannot be resized.

setHeight(height: number): Promise<void>;

Parameters

Name	Type	Description
height	number	Height (px, rounded to one decimal place)

Returns

Promise<void>

setHyperlink(hyperlink)

Sets a hyperlink on the shape (symmetric with getHyperlink - the returned object can be passed back to copy a hyperlink). An unsupported kind or an invalid target, such as a deleted slide, is ignored.

setHyperlink(hyperlink: Hyperlink): Promise<void>;

Parameters

Name	Type	Description
hyperlink	Hyperlink	The same Hyperlink object as returned by getHyperlink(). Ignored if type is missing

Returns

Promise<void>

setLegendPosition(position)

Sets the legend position. Passing "none" hides the legend.

setLegendPosition(position: ChartLegendPosition): Promise<void>;

Parameters

Name	Type	Description
position	ChartLegendPosition	where to put the legend

Returns

Promise<void>

setRotation(rotation)

Sets the rotation angle of the shape as an absolute value. Ignored for shapes that cannot be rotated. (counterpart of getRotation)

setRotation(rotation: number): Promise<void>;

Parameters

Name	Type	Description
rotation	number	Rotation angle (degrees)

Returns

Promise<void>

setStyle(style)

Changes the chart's preset style. The actual colors behind a number follow the document theme.

setStyle(style: number): Promise<void>;

Parameters

Name	Type	Description
style	number	style number (integer 1-12); the numbers form color groups of three (1-3, 4-6, 7-9, 10-12), and the three numbers inside a group differ only in background (translucent background, white background, colored background with series borders, in that order)

Returns

Promise<void>

setTitle(title)

Sets the chart title.

setTitle(title: string): Promise<void>;

Parameters

Name	Type	Description
title	string	title to show on the chart

Returns

Promise<void>

setTransform(transform)

Sets the position, size, and rotation of the shape in one call. The value returned by getTransform() can be passed as is. (counterpart of getTransform) Only the fields given a value are applied, in the order size → position → rotation; omitted fields keep their current value. As with the individual setters, each field is ignored on shapes that do not support that operation (resize/move/rotate).

setTransform(transform?: Partial<ShapeTransform>): Promise<void>;

Parameters

Name	Type	Description
transform (optional)	Partial<ShapeTransform>	Position/size (px) · rotation (degrees)

Returns

Promise<void>

setType(chartType)

Changes the chart type. Passing the current type changes nothing.

setType(chartType: ChartType): Promise<void>;

Parameters

Name	Type	Description
chartType	ChartType	chart type to change to (enum string, for example "clustered_column")

Returns

Promise<void>

setWidth(width)

Sets the width of the shape. Ignored for shapes that cannot be resized.

setWidth(width: number): Promise<void>;

Parameters

Name	Type	Description
width	number	Width (px, rounded to one decimal place)

Returns

Promise<void>

setX(x)

Sets the X coordinate of the shape as an absolute value. Ignored for shapes that cannot be moved. (use moveBy for a relative move)

setX(x: number): Promise<void>;

Parameters

Name	Type	Description
x	number	X coordinate (px, rounded to an integer)

Returns

Promise<void>

setY(y)

Sets the Y coordinate of the shape as an absolute value. Ignored for shapes that cannot be moved.

setY(y: number): Promise<void>;

Parameters

Name	Type	Description
y	number	Y coordinate (px, rounded to an integer)

Returns

Promise<void>