Shape class

Shape class

Represents an object in the drawing layer, such as an AutoShape, textbox, freeform, OLE object, ActiveX control, or picture. To learn more, visit the Working with Shapes documentation article.

Remarks

Using the Shape class you can create or modify shapes in a Microsoft Word document.

An important property of a shape is its ShapeBase.shapeType. Shapes of different types can have different capabilities in a Word document. For example, only image and OLE shapes can have images inside them. Most of the shapes can have text, but not all.

Shapes that can have text, can contain Paragraph and Table nodes as children.

Inheritance: ShapeShapeBaseCompositeNodeNode

Constructors

NameDescription
Shape(doc, shapeType)Creates a new shape object.

Properties

NameDescription
adjustmentsProvides access to the adjustment raw values of a shape. For a shape that does not contain any adjustment raw values, it returns an empty collection.
allowOverlapGets or sets a value that specifies whether this shape can overlap other shapes.
(Inherited from ShapeBase)
alternativeTextDefines alternative text to be displayed instead of a graphic.
(Inherited from ShapeBase)
anchorLockedSpecifies whether the shape’s anchor is locked.
(Inherited from ShapeBase)
aspectRatioLockedSpecifies whether the shape’s aspect ratio is locked.
(Inherited from ShapeBase)
behindTextSpecifies whether the shape is below or above text.
(Inherited from ShapeBase)
bottomGets the position of the bottom edge of the containing block of the shape.
(Inherited from ShapeBase)
bounds2
(Inherited from ShapeBase)
boundsInPoints2
(Inherited from ShapeBase)
boundsWithEffects2
(Inherited from ShapeBase)
canHaveImageReturns true if the shape type allows the shape to have an image.
(Inherited from ShapeBase)
chartProvides access to the chart properties if this shape has a Chart.
coordOrigin2
(Inherited from ShapeBase)
coordSize2
(Inherited from ShapeBase)
countGets the number of immediate children of this node.
(Inherited from CompositeNode)
customNodeIdSpecifies custom node identifier.
(Inherited from Node)
distanceBottomReturns or sets the distance (in points) between the document text and the bottom edge of the shape.
(Inherited from ShapeBase)
distanceLeftReturns or sets the distance (in points) between the document text and the left edge of the shape.
(Inherited from ShapeBase)
distanceRightReturns or sets the distance (in points) between the document text and the right edge of the shape.
(Inherited from ShapeBase)
distanceTopReturns or sets the distance (in points) between the document text and the top edge of the shape.
(Inherited from ShapeBase)
documentGets the document to which this node belongs.
(Inherited from Node)
extrusionEnabledReturns true if an extrusion effect is enabled.
fillGets fill formatting for the shape.
(Inherited from ShapeBase)
fillColorDefines the brush color that fills the closed path of the shape.
filledDetermines whether the closed path of the shape will be filled.
firstChildGets the first child of the node.
(Inherited from CompositeNode)
firstParagraphGets the first paragraph in the shape.
flipOrientationSwitches the orientation of a shape.
(Inherited from ShapeBase)
fontProvides access to the font formatting of this object.
(Inherited from ShapeBase)
glowGets glow formatting for the shape.
(Inherited from ShapeBase)
hasChartReturns true if this Shape has a Chart.
hasChildNodesReturns true if this node has any child nodes.
(Inherited from CompositeNode)
hasImageReturns true if the shape has image bytes or links an image.
hasSmartArtReturns true if this Shape has a SmartArt object.
heightGets or sets the height of the containing block of the shape.
(Inherited from ShapeBase)
heightRelativeGets or sets the value that represents the percentage of shape’s relative height.
(Inherited from ShapeBase)
hiddenGets or sets a boolean value indicating whether the shape is visible.
(Inherited from ShapeBase)
horizontalAlignmentSpecifies how the shape is positioned horizontally.
(Inherited from ShapeBase)
horizontalRuleFormatProvides access to the properties of the horizontal rule shape. For a shape that is not a horizontal rule, returns null.
hrefGets or sets the full hyperlink address for a shape.
(Inherited from ShapeBase)
imageDataProvides access to the image of the shape. Returns null if the shape cannot have an image.
isCompositeReturns true if this node can contain other nodes.
(Inherited from Node)
isDecorativeGets or sets the flag that specifies whether the shape is decorative in the document.
(Inherited from ShapeBase)
isDeleteRevisionReturns true if this object was deleted in Microsoft Word while change tracking was enabled.
(Inherited from ShapeBase)
isGroupReturns true if this is a group shape.
(Inherited from ShapeBase)
isHorizontalRuleReturns true if this shape is a horizontal rule.
(Inherited from ShapeBase)
isImageReturns true if this shape is an image shape.
(Inherited from ShapeBase)
isInlineA quick way to determine if this shape is positioned inline with text.
(Inherited from ShapeBase)
isInsertRevisionReturns true if this object was inserted in Microsoft Word while change tracking was enabled.
(Inherited from ShapeBase)
isLayoutInCellGets or sets a flag indicating whether the shape is displayed inside a table or outside of it.
(Inherited from ShapeBase)
isMoveFromRevisionReturns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
(Inherited from ShapeBase)
isMoveToRevisionReturns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
(Inherited from ShapeBase)
isSignatureLineIndicates that shape is a SignatureLine.
(Inherited from ShapeBase)
isTopLevelReturns true if this shape is not a child of a group shape.
(Inherited from ShapeBase)
isWordArtReturns true if this shape is a WordArt object.
(Inherited from ShapeBase)
lastChildGets the last child of the node.
(Inherited from CompositeNode)
lastParagraphGets the last paragraph in the shape.
leftGets or sets the position of the left edge of the containing block of the shape.
(Inherited from ShapeBase)
leftRelativeGets or sets the value that represents shape’s relative left position in percent.
(Inherited from ShapeBase)
markupLanguageGets MarkupLanguage used for this graphic object.
(Inherited from ShapeBase)
nameGets or sets the optional shape name.
(Inherited from ShapeBase)
nextSiblingGets the node immediately following this node.
(Inherited from Node)
nodeTypeReturns NodeType.Shape.
oleFormatProvides access to the OLE data of a shape. For a shape that is not an OLE object or ActiveX control, returns null.
parentNodeGets the immediate parent of this node.
(Inherited from Node)
parentParagraphReturns the immediate parent paragraph.
(Inherited from ShapeBase)
previousSiblingGets the node immediately preceding this node.
(Inherited from Node)
rangeReturns a Range object that represents the portion of a document that is contained in this node.
(Inherited from Node)
reflectionGets reflection formatting for the shape.
(Inherited from ShapeBase)
relativeHorizontalPositionSpecifies relative to what the shape is positioned horizontally.
(Inherited from ShapeBase)
relativeHorizontalSizeGets or sets the value of shape’s relative size in horizontal direction.
(Inherited from ShapeBase)
relativeVerticalPositionSpecifies relative to what the shape is positioned vertically.
(Inherited from ShapeBase)
relativeVerticalSizeGets or sets the value of shape’s relative size in vertical direction.
(Inherited from ShapeBase)
rightGets the position of the right edge of the containing block of the shape.
(Inherited from ShapeBase)
rotationDefines the angle (in degrees) that a shape is rotated. Positive value corresponds to clockwise rotation angle.
(Inherited from ShapeBase)
screenTipDefines the text displayed when the mouse pointer moves over the shape.
(Inherited from ShapeBase)
shadowEnabledReturns true if a shadow effect is enabled.
shadowFormatGets shadow formatting for the shape.
(Inherited from ShapeBase)
shapeTypeGets the shape type.
(Inherited from ShapeBase)
signatureLineGets SignatureLine object if the shape is a signature line. Returns null otherwise.
sizeInPoints2
(Inherited from ShapeBase)
softEdgeGets soft edge formatting for the shape.
(Inherited from ShapeBase)
storyTypeReturns StoryType.Textbox.
strokeDefines a stroke for a shape.
strokeColorDefines the color of a stroke.
strokeWeightDefines the brush thickness that strokes the path of a shape in points.
strokedDefines whether the path will be stroked.
targetGets or sets the target frame for the shape hyperlink.
(Inherited from ShapeBase)
textBoxDefines attributes that specify how text is displayed in a shape.
textPathDefines the text of the text path (of a WordArt object).
titleGets or sets the title (caption) of the current shape object.
(Inherited from ShapeBase)
topGets or sets the position of the top edge of the containing block of the shape.
(Inherited from ShapeBase)
topRelativeGets or sets the value that represents shape’s relative top position in percent.
(Inherited from ShapeBase)
verticalAlignmentSpecifies how the shape is positioned vertically.
(Inherited from ShapeBase)
widthGets or sets the width of the containing block of the shape.
(Inherited from ShapeBase)
widthRelativeGets or sets the value that represents the percentage of shape’s relative width.
(Inherited from ShapeBase)
wrapSideSpecifies how the text is wrapped around the shape.
(Inherited from ShapeBase)
wrapTypeDefines whether the shape is inline or floating. For floating shapes defines the wrapping mode for text around the shape.
(Inherited from ShapeBase)
zorderDetermines the display order of overlapping shapes.
(Inherited from ShapeBase)

Methods

NameDescription
adjustWithEffects(source)
(Inherited from ShapeBase)
appendChild(newChild)Adds the specified node to the end of the list of child nodes for this node.
(Inherited from CompositeNode)
asBody()Cast node to Body.
(Inherited from Node)
asBookmarkEnd()Cast node to BookmarkEnd.
(Inherited from Node)
asBookmarkStart()Cast node to BookmarkStart.
(Inherited from Node)
asBuildingBlock()Cast node to BuildingBlock.
(Inherited from Node)
asCell()Cast node to Cell.
(Inherited from Node)
asComment()Cast node to Comment.
(Inherited from Node)
asCommentRangeEnd()Cast node to CommentRangeEnd.
(Inherited from Node)
asCommentRangeStart()Cast node to CommentRangeStart.
(Inherited from Node)
asCompositeNode()Cast node to CompositeNode.
(Inherited from Node)
asDocument()Cast node to Node.document.
(Inherited from Node)
asEditableRangeEnd()Cast node to EditableRangeEnd.
(Inherited from Node)
asEditableRangeStart()Cast node to EditableRangeStart.
(Inherited from Node)
asFieldEnd()Cast node to FieldEnd.
(Inherited from Node)
asFieldSeparator()Cast node to FieldSeparator.
(Inherited from Node)
asFieldStart()Cast node to FieldStart.
(Inherited from Node)
asFootnote()Cast node to Footnote.
(Inherited from Node)
asFormField()Cast node to FormField.
(Inherited from Node)
asGlossaryDocument()Cast node to GlossaryDocument.
(Inherited from Node)
asGroupShape()Cast node to GroupShape.
(Inherited from Node)
asHeaderFooter()Cast node to HeaderFooter.
(Inherited from Node)
asOfficeMath()Cast node to OfficeMath.
(Inherited from Node)
asParagraph()Cast node to Paragraph.
(Inherited from Node)
asRow()Cast node to Row.
(Inherited from Node)
asRun()Cast node to Run.
(Inherited from Node)
asSection()Cast node to Section.
(Inherited from Node)
asShape()Cast node to Shape.
(Inherited from Node)
asSmartTag()Cast node to SmartTag.
(Inherited from Node)
asSpecialChar()Cast node to SpecialChar.
(Inherited from Node)
asStructuredDocumentTag()Cast node to StructuredDocumentTag.
(Inherited from Node)
asStructuredDocumentTagRangeEnd()Cast node to StructuredDocumentTagRangeEnd.
(Inherited from Node)
asStructuredDocumentTagRangeStart()Cast node to StructuredDocumentTagRangeStart.
(Inherited from Node)
asSubDocument()Cast node to SubDocument.
(Inherited from Node)
asTable()Cast node to Table.
(Inherited from Node)
clone(isCloneChildren)Creates a duplicate of the node.
(Inherited from Node)
getAncestor(ancestorType)Gets the first ancestor of the specified NodeType.
(Inherited from Node)
getBuildingBlock(index, isDeep)
(Inherited from CompositeNode)
getChild(nodeType, index, isDeep)Returns an Nth child node that matches the specified type.
(Inherited from CompositeNode)
getChildNodes(nodeType, isDeep)Returns a live collection of child nodes that match the specified type.
(Inherited from CompositeNode)
getComment(index, isDeep)
(Inherited from CompositeNode)
getEditableRangeStart(index, isDeep)
(Inherited from CompositeNode)
getFootnote(index, isDeep)
(Inherited from CompositeNode)
getGroupShape(index, isDeep)
(Inherited from CompositeNode)
getOfficeMath(index, isDeep)
(Inherited from CompositeNode)
getParagraph(index, isDeep)
(Inherited from CompositeNode)
getRun(index, isDeep)
(Inherited from CompositeNode)
getSdt(index, isDeep)
(Inherited from CompositeNode)
getSdtRangeEnd(index, isDeep)
(Inherited from CompositeNode)
getSdtRangeStart(index, isDeep)
(Inherited from CompositeNode)
getShape(index, isDeep)
(Inherited from CompositeNode)
getShapeRenderer()Creates and returns an object that can be used to render this shape into an image.
(Inherited from ShapeBase)
getSmartTag(index, isDeep)
(Inherited from CompositeNode)
getTable(index, isDeep)
(Inherited from CompositeNode)
getText()Gets the text of this node and of all its children.
(Inherited from Node)
indexOf(child)Returns the index of the specified child node in the child node array.
(Inherited from CompositeNode)
insertAfter(newChild, refChild)Inserts the specified node immediately after the specified reference node.
(Inherited from CompositeNode)
insertBefore(newChild, refChild)Inserts the specified node immediately before the specified reference node.
(Inherited from CompositeNode)
localToParent(value)
(Inherited from ShapeBase)
nextPreOrder(rootNode)Gets next node according to the pre-order tree traversal algorithm.
(Inherited from Node)
nodeTypeToString(nodeType)A utility method that converts a node type enum value into a user friendly string.
(Inherited from Node)
prependChild(newChild)Adds the specified node to the beginning of the list of child nodes for this node.
(Inherited from CompositeNode)
previousPreOrder(rootNode)Gets the previous node according to the pre-order tree traversal algorithm.
(Inherited from Node)
referenceEquals(other)
(Inherited from Node)
remove()Removes itself from the parent.
(Inherited from Node)
removeAllChildren()Removes all the child nodes of the current node.
(Inherited from CompositeNode)
removeChild(oldChild)Removes the specified child node.
(Inherited from CompositeNode)
removeSmartTags()Removes all SmartTag descendant nodes of the current node.
(Inherited from CompositeNode)
selectNodes(xpath)Selects a list of nodes matching the XPath expression.
(Inherited from CompositeNode)
selectSingleNode(xpath)Selects the first Node that matches the XPath expression.
(Inherited from CompositeNode)
toString(saveFormat)Exports the content of the node into a string in the specified format.
(Inherited from Node)
toString(saveOptions)Exports the content of the node into a string using the specified save options.
(Inherited from Node)
updateSmartArtDrawing()Updates SmartArt pre-rendered drawing by using Aspose.Words’s SmartArt cold rendering engine.

Examples

Shows how to extract images from a document, and save them to the local file system as individual files.

let doc = new aw.Document(base.myDir + "Images.docx");

// Get the collection of shapes from the document,
// and save the image data of every shape with an image as a file to the local file system.
let nodes = [...doc.getChildNodes(aw.NodeType.Shape, true)];

expect(nodes.filter(s => s.asShape().hasImage).length).toEqual(9);

let imageIndex = 0;
for (let node of nodes)
{
  let shape = node.asShape();
  if (shape.hasImage)
  {
    // The image data of shapes may contain images of many possible image formats. 
    // We can determine a file extension for each image automatically, based on its format.
    let imageFileName =
      `File.ExtractImages.${imageIndex}${aw.FileFormatUtil.imageTypeToExtension(shape.imageData.imageType)}`;
    shape.imageData.save(base.artifactsDir + imageFileName);
    imageIndex++;
  }
}

Shows how to insert a floating image to the center of a page.

let doc = new aw.Document();
let builder = new aw.DocumentBuilder(doc);

// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
let shape = builder.insertImage(base.imageDir + "Logo.jpg");
shape.wrapType = aw.Drawing.WrapType.None;
shape.behindText = true;
shape.relativeHorizontalPosition = aw.Drawing.RelativeHorizontalPosition.Page;
shape.relativeVerticalPosition = aw.Drawing.RelativeVerticalPosition.Page;
shape.horizontalAlignment = aw.Drawing.HorizontalAlignment.Center;
shape.verticalAlignment = aw.Drawing.VerticalAlignment.Center;

doc.save(base.artifactsDir + "Image.CreateFloatingPageCenter.docx");

Shows how to delete all shapes from a document.

let doc = new aw.Document();
let builder = new aw.DocumentBuilder(doc);

// Insert two shapes along with a group shape with another shape inside it.
builder.insertShape(aw.Drawing.ShapeType.Rectangle, 400, 200);
builder.insertShape(aw.Drawing.ShapeType.Star, 300, 300);

let group = new aw.Drawing.GroupShape(doc);
group.bounds2 = new aw.JSRectangleF(100, 50, 200, 100);
group.coordOrigin2 = new aw.JSPoint(-1000, -500);

let subShape = new aw.Drawing.Shape(doc, aw.Drawing.ShapeType.Cube);
subShape.width = 500;
subShape.height = 700;
subShape.left = 0;
subShape.top = 0;

group.appendChild(subShape);
builder.insertNode(group);

expect(doc.getChildNodes(aw.NodeType.Shape, true).count).toEqual(3);
expect(doc.getChildNodes(aw.NodeType.GroupShape, true).count).toEqual(1);

// Remove all Shape nodes from the document.
let shapes = doc.getChildNodes(aw.NodeType.Shape, true);
shapes.clear();

// All shapes are gone, but the group shape is still in the document.
expect(doc.getChildNodes(aw.NodeType.GroupShape, true).count).toEqual(1);
expect(doc.getChildNodes(aw.NodeType.Shape, true).count).toEqual(0);

// Remove all group shapes separately.
let groupShapes = doc.getChildNodes(aw.NodeType.GroupShape, true);
groupShapes.clear();

expect(doc.getChildNodes(aw.NodeType.GroupShape, true).count).toEqual(0);
expect(doc.getChildNodes(aw.NodeType.Shape, true).count).toEqual(0);

See Also