Show.Control

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

Remarks

• Module: Presentation · Office.show(iframe) · namespace Show
• Obtained from: returned as a value by the methods listed in the summary tables of other object types
• 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.
getHeight()	Returns the shape's height.
getHyperlink()	Returns the hyperlink set on the shape.
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.
getTransform()	Returns the position, size, and rotation of the shape.
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).
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).
setHeight(height)	Sets the height of the shape.
setHyperlink(hyperlink)	Sets a hyperlink on the shape (counterpart of getHyperlink; the returned object can be passed back to copy a hyperlink).
setRotation(rotation)	Sets the rotation angle of the shape as an absolute value.
setTransform(transform)	Sets the position, size, and rotation of the shape in one call.
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

none

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

none

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 to setHyperlink as is. Returns null if an unsupported kind (run program, macro, etc.) is attached. Only the click hyperlink (hlinkClick) is read; it is the same target as setHyperlink/removeHyperlink, so a get → set round trip holds (hover-only links are outside this API layer). Text links attached per run are read with Shape.getTextHyperlink.

getHyperlink(): Promise<Hyperlink | null>;

Returns

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

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

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)

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>

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

none

removeHyperlink()

Removes the shape's hyperlink. Text links attached per run are removed with Shape.removeTextHyperlink.

removeHyperlink(): Promise<void>;

Returns

none

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

none

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

none

setHyperlink(hyperlink)

Sets a hyperlink on the shape (counterpart of getHyperlink; the returned object can be passed back to copy a hyperlink). Unsupported kinds and invalid targets (such as a deleted slide) are ignored. Text links attached per run are set with Shape.setTextHyperlink.

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

none

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

none

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

none

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

none

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

none

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

none