Word.Shape class

Package:

word

Represents a shape in the header, footer, or document body. Currently, only the following shapes are supported: text boxes, geometric shapes, groups, pictures, and canvases.

Extends

OfficeExtension.ClientObject

Remarks

[ API set: WordApiDesktop 1.2 ]

Properties

allowOverlap	Specifies whether a given shape can overlap other shapes.
altTextDescription	Specifies a string that represents the alternative text associated with the shape.
body	Represents the body object of the shape. Only applies to text boxes and geometric shapes.
canvas	Gets the canvas associated with the shape. An object with its isNullObject property set to true will be returned if the shape type isn't "Canvas". For further information, see *OrNullObject methods and properties.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
fill	Returns the fill formatting of the shape.
geometricShapeType	The geometric shape type of the shape. It will be null if isn't a geometric shape.
height	The height, in points, of the shape.
heightRelative	The percentage of shape height to vertical relative size, see Word.RelativeSize. For an inline or child shape, it can't be set.
id	Gets an integer that represents the shape identifier.
isChild	Check whether this shape is a child of a group shape or a canvas shape.
left	The distance, in points, from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition. For an inline shape, it will return 0 and can't be set. For a child shape in a canvas or group, it's relative to the top left corner.
leftRelative	The relative left position as a percentage from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition. For an inline or child shape, it will return 0 and can't be set.
lockAspectRatio	Specifies if the aspect ratio of this shape is locked.
name	The name of the shape.
parentCanvas	Gets the top-level parent canvas shape of this child shape. It will be null if it isn't a child shape of a canvas.
parentGroup	Gets the top-level parent group shape of this child shape. It will be null if it isn't a child shape of a group.
relativeHorizontalPosition	The relative horizontal position of the shape. For an inline shape, it can't be set. For details, see Word.RelativeHorizontalPosition.
relativeHorizontalSize	The relative horizontal size of the shape. For an inline or child shape, it can't be set. For details, see Word.RelativeHorizontalPosition.
relativeVerticalPosition	The relative vertical position of the shape. For an inline shape, it can't be set. For details, see Word.RelativeVerticalPosition.
relativeVerticalSize	The relative vertical size of the shape. For an inline or child shape, it can't be set. For details, see Word.RelativeHorizontalPosition.
rotation	Specifies the rotation, in degrees, of the shape. Not applicable to Canvas shape.
shapeGroup	Gets the shape group associated with the shape. An object with its isNullObject property set to true will be returned if the shape type isn't "GroupShape". For further information, see *OrNullObject methods and properties.
textFrame	Gets the text frame object of the shape.
textWrap	Returns the text wrap formatting of the shape.
top	The distance, in points, from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition. For an inline shape, it will return 0 and can't be set. For a child shape in a canvas or group, it's relative to the top left corner.
topRelative	The relative top position as a percentage from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition. For an inline or child shape, it will return 0 and can't be set.
type	Gets the shape type. Currently, only the following shapes are supported: text boxes, geometric shapes, groups, pictures, and canvases.
visible	Specifies if the shape is visible. Not applicable to inline shapes.
width	The width, in points, of the shape.
widthRelative	The percentage of shape width to horizontal relative size, see Word.RelativeSize. For an inline or child shape, it can't be set.

Methods

delete()	Deletes the shape and its content.
load(options)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
moveHorizontally(distance)	Moves the shape horizontally by the number of points.
moveVertically(distance)	Moves the shape vertically by the number of points.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)	Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.
select(selectMultipleShapes)	Selects the shape.
set(properties, options)	Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)	Sets multiple properties on the object at the same time, based on an existing loaded object.
toJSON()	Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.Shape object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ShapeData) that contains shallow copies of any loaded child properties from the original object.
track()	Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.
untrack()	Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

Property Details

allowOverlap

Specifies whether a given shape can overlap other shapes.

allowOverlap: boolean;

Property Value

boolean

Remarks

[ API set: WordApiDesktop 1.2 ]

altTextDescription

Specifies a string that represents the alternative text associated with the shape.

altTextDescription: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.2 ]

body

Represents the body object of the shape. Only applies to text boxes and geometric shapes.

readonly body: Word.Body;

Property Value

Word.Body

Remarks

[ API set: WordApiDesktop 1.2 ]

canvas

Gets the canvas associated with the shape. An object with its isNullObject property set to true will be returned if the shape type isn't "Canvas". For further information, see *OrNullObject methods and properties.

readonly canvas: Word.Canvas;

Property Value

Word.Canvas

Remarks

[ API set: WordApiDesktop 1.2 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Word.RequestContext

fill

Returns the fill formatting of the shape.

readonly fill: Word.ShapeFill;

Property Value

Word.ShapeFill

Remarks

[ API set: WordApiDesktop 1.2 ]

geometricShapeType

The geometric shape type of the shape. It will be null if isn't a geometric shape.

geometricShapeType: Word.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

Property Value

Word.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus"

Remarks

[ API set: WordApiDesktop 1.2 ]

height

The height, in points, of the shape.

height: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

heightRelative

The percentage of shape height to vertical relative size, see Word.RelativeSize. For an inline or child shape, it can't be set.

heightRelative: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

id

Gets an integer that represents the shape identifier.

readonly id: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

isChild

Check whether this shape is a child of a group shape or a canvas shape.

readonly isChild: boolean;

Property Value

boolean

Remarks

[ API set: WordApiDesktop 1.2 ]

left

The distance, in points, from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition. For an inline shape, it will return 0 and can't be set. For a child shape in a canvas or group, it's relative to the top left corner.

left: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

leftRelative

The relative left position as a percentage from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition. For an inline or child shape, it will return 0 and can't be set.

leftRelative: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

lockAspectRatio

Specifies if the aspect ratio of this shape is locked.

lockAspectRatio: boolean;

Property Value

boolean

Remarks

[ API set: WordApiDesktop 1.2 ]

name

The name of the shape.

name: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.2 ]

parentCanvas

Gets the top-level parent canvas shape of this child shape. It will be null if it isn't a child shape of a canvas.

readonly parentCanvas: Word.Shape;

Property Value

Word.Shape

Remarks

[ API set: WordApiDesktop 1.2 ]

parentGroup

Gets the top-level parent group shape of this child shape. It will be null if it isn't a child shape of a group.

readonly parentGroup: Word.Shape;

Property Value

Word.Shape

Remarks

[ API set: WordApiDesktop 1.2 ]

relativeHorizontalPosition

The relative horizontal position of the shape. For an inline shape, it can't be set. For details, see Word.RelativeHorizontalPosition.

relativeHorizontalPosition: Word.RelativeHorizontalPosition | "Margin" | "Page" | "Column" | "Character" | "LeftMargin" | "RightMargin" | "InsideMargin" | "OutsideMargin";

Property Value

Word.RelativeHorizontalPosition | "Margin" | "Page" | "Column" | "Character" | "LeftMargin" | "RightMargin" | "InsideMargin" | "OutsideMargin"

Remarks

[ API set: WordApiDesktop 1.2 ]

relativeHorizontalSize

The relative horizontal size of the shape. For an inline or child shape, it can't be set. For details, see Word.RelativeHorizontalPosition.

relativeHorizontalSize: Word.RelativeSize | "Margin" | "Page" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin";

Property Value

Word.RelativeSize | "Margin" | "Page" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin"

Remarks

[ API set: WordApiDesktop 1.2 ]

relativeVerticalPosition

The relative vertical position of the shape. For an inline shape, it can't be set. For details, see Word.RelativeVerticalPosition.

relativeVerticalPosition: Word.RelativeVerticalPosition | "Margin" | "Page" | "Paragraph" | "Line" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin";

Property Value

Word.RelativeVerticalPosition | "Margin" | "Page" | "Paragraph" | "Line" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin"

Remarks

[ API set: WordApiDesktop 1.2 ]

relativeVerticalSize

The relative vertical size of the shape. For an inline or child shape, it can't be set. For details, see Word.RelativeHorizontalPosition.

relativeVerticalSize: Word.RelativeSize | "Margin" | "Page" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin";

Property Value

Word.RelativeSize | "Margin" | "Page" | "TopMargin" | "BottomMargin" | "InsideMargin" | "OutsideMargin"

Remarks

[ API set: WordApiDesktop 1.2 ]

rotation

Specifies the rotation, in degrees, of the shape. Not applicable to Canvas shape.

rotation: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

shapeGroup

Gets the shape group associated with the shape. An object with its isNullObject property set to true will be returned if the shape type isn't "GroupShape". For further information, see *OrNullObject methods and properties.

readonly shapeGroup: Word.ShapeGroup;

Property Value

Word.ShapeGroup

Remarks

[ API set: WordApiDesktop 1.2 ]

textFrame

Gets the text frame object of the shape.

readonly textFrame: Word.TextFrame;

Property Value

Word.TextFrame

Remarks

[ API set: WordApiDesktop 1.2 ]

textWrap

Returns the text wrap formatting of the shape.

readonly textWrap: Word.ShapeTextWrap;

Property Value

Word.ShapeTextWrap

Remarks

[ API set: WordApiDesktop 1.2 ]

top

The distance, in points, from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition. For an inline shape, it will return 0 and can't be set. For a child shape in a canvas or group, it's relative to the top left corner.

top: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

topRelative

The relative top position as a percentage from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition. For an inline or child shape, it will return 0 and can't be set.

topRelative: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

type

Gets the shape type. Currently, only the following shapes are supported: text boxes, geometric shapes, groups, pictures, and canvases.

readonly type: Word.ShapeType | "Unsupported" | "TextBox" | "GeometricShape" | "Group" | "Picture" | "Canvas";

Property Value

Word.ShapeType | "Unsupported" | "TextBox" | "GeometricShape" | "Group" | "Picture" | "Canvas"

Remarks

[ API set: WordApiDesktop 1.2 ]

visible

Specifies if the shape is visible. Not applicable to inline shapes.

visible: boolean;

Property Value

boolean

Remarks

[ API set: WordApiDesktop 1.2 ]

width

The width, in points, of the shape.

width: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

widthRelative

The percentage of shape width to horizontal relative size, see Word.RelativeSize. For an inline or child shape, it can't be set.

widthRelative: number;

Property Value

number

Remarks

[ API set: WordApiDesktop 1.2 ]

Method Details

delete()

Deletes the shape and its content.

delete(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Word.Interfaces.ShapeLoadOptions): Word.Shape;

Parameters

options

Word.Interfaces.ShapeLoadOptions

Provides options for which properties of the object to load.

Returns

Word.Shape

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.Shape;

Parameters

propertyNames

string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Word.Shape

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.Shape;

Parameters

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Word.Shape

moveHorizontally(distance)

Moves the shape horizontally by the number of points.

moveHorizontally(distance: number): void;

Parameters

distance

number

Required. Specifies how far the shape is to be moved horizontally, in points. Use a positive value to move the shape right. Use a negative value to move the shape left.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

moveVertically(distance)

Moves the shape vertically by the number of points.

moveVertically(distance: number): void;

Parameters

distance

number

Required. Specifies how far the shape is to be moved vertically, in points. Use a positive value to move the shape up. Use a negative value to move the shape down.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

scaleHeight(scaleFactor, scaleType, scaleFrom)

Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.

scaleHeight(scaleFactor: number, scaleType: Word.ShapeScaleType, scaleFrom?: Word.ShapeScaleFrom): void;

Parameters

scaleFactor

number

Specifies the ratio between the height of the shape after you resize it and the current or original height.

scaleType

Word.ShapeScaleType

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFrom

Word.ShapeScaleFrom

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents that the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

Scales the height of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Parameters

scaleFactor

number

Specifies the ratio between the height of the shape after you resize it and the current or original height.

scaleTypeString

"CurrentSize" | "OriginalSize"

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents that the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

scaleWidth(scaleFactor, scaleType, scaleFrom)

Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.

scaleWidth(scaleFactor: number, scaleType: Word.ShapeScaleType, scaleFrom?: Word.ShapeScaleFrom): void;

Parameters

scaleFactor

number

Specifies the ratio between the width of the shape after you resize it and the current or original width.

scaleType

Word.ShapeScaleType

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFrom

Word.ShapeScaleFrom

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents that the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

Scales the width of the shape by a specified factor. For images, you can indicate whether you want to scale the shape relative to the original or the current size. Shapes other than pictures are always scaled relative to their current height.

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

Parameters

scaleFactor

number

Specifies the ratio between the width of the shape after you resize it and the current or original width.

scaleTypeString

"CurrentSize" | "OriginalSize"

Specifies whether the shape is scaled relative to its original or current size. The original size scaling option only works for images.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Specifies which part of the shape retains its position when the shape is scaled. If omitted, it represents that the shape's upper left corner retains its position.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

select(selectMultipleShapes)

Selects the shape.

select(selectMultipleShapes?: boolean): void;

Parameters

selectMultipleShapes

boolean

Optional. Whether to select multiple floating shapes. The default value is false.

Returns

void

Remarks

[ API set: WordApiDesktop 1.2 ]

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties

Word.Interfaces.ShapeUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options

OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.Shape): void;

Parameters

properties

Word.Shape

Returns

void

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.Shape object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ShapeData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.ShapeData;

Returns

Word.Interfaces.ShapeData

track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.

track(): Word.Shape;

Returns

Word.Shape

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

untrack(): Word.Shape;

Returns

Word.Shape