Aspose::Words::Drawing::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.

class Shape : public Aspose::Words::Drawing::ShapeBase,
              public Aspose::Words::Drawing::Core::ITextBox,
              public Aspose::Words::Drawing::Core::IStrokable

Methods

MethodDescription
Accept(System::SharedPtr<Aspose::Words::DocumentVisitor>) overrideAccepts a visitor.
AcceptEnd(System::SharedPtr<Aspose::Words::DocumentVisitor>) override
AcceptStart(System::SharedPtr<Aspose::Words::DocumentVisitor>) override
AdjustWithEffects(System::Drawing::RectangleF)Adds to the source rectangle values of the effect extent and returns the final rectangle.
AppendChild(T)
Clone(bool)Creates a duplicate of the node.
get_AllowOverlap()Gets or sets a value that specifies whether this shape can overlap other shapes.
get_AlternativeText()Defines alternative text to be displayed instead of a graphic.
get_AnchorLocked()Specifies whether the shape’s anchor is locked.
get_AspectRatioLocked()Specifies whether the shape’s aspect ratio is locked.
get_BehindText()Specifies whether the shape is below or above text.
get_Bottom()Gets the position of the bottom edge of the containing block of the shape.
get_Bounds()Gets or sets the location and size of the containing block of the shape.
get_BoundsInPoints()Gets the location and size of the containing block of the shape in points, relative to the anchor of the topmost shape.
get_BoundsWithEffects()Gets final extent that this shape object has after applying drawing effects. Value is measured in points.
get_CanHaveImage()Returns true if the shape type allows the shape to have an image.
get_Chart()Provides access to the chart properties if this shape has a Chart.
get_CoordOrigin()The coordinates at the top-left corner of the containing block of this shape.
get_CoordSize()The width and height of the coordinate space inside the containing block of this shape.
get_Count()Gets the number of immediate children of this node.
get_CustomNodeId() constSpecifies custom node identifier.
get_DistanceBottom()Returns or sets the distance (in points) between the document text and the bottom edge of the shape.
get_DistanceLeft()Returns or sets the distance (in points) between the document text and the left edge of the shape.
get_DistanceRight()Returns or sets the distance (in points) between the document text and the right edge of the shape.
get_DistanceTop()Returns or sets the distance (in points) between the document text and the top edge of the shape.
virtual get_Document() constGets the document to which this node belongs.
get_ExtrusionEnabled()Returns true if an extrusion effect is enabled.
get_Fill()Gets fill formatting for the shape.
get_FillColor()Defines the brush color that fills the closed path of the shape.
get_Filled()Determines whether the closed path of the shape will be filled.
get_FirstChild() constGets the first child of the node.
get_FirstParagraph()Gets the first paragraph in the shape.
get_FlipOrientation()Switches the orientation of a shape.
get_Font()Provides access to the font formatting of this object.
get_HasChart()Returns true if this Shape has a Chart.
get_HasChildNodes()Returns true if this node has any child nodes.
get_HasImage()Returns true if the shape has image bytes or links an image.
get_HasSmartArt()Returns true if this Shape has a SmartArt object.
get_Height()Gets or sets the height of the containing block of the shape.
get_HeightRelative()Gets the value that represents the percentage of shape’s relative height.
get_HorizontalAlignment()Specifies how the shape is positioned horizontally.
get_HorizontalRuleFormat()Provides access to the properties of the horizontal rule shape. For a shape that is not a horizontal rule, returns null.
get_HRef()Gets or sets the full hyperlink address for a shape.
get_ImageData()Provides access to the image of the shape. Returns null if the shape cannot have an image.
get_IsComposite() overrideReturns true as this node can have child nodes.
get_IsDecorative()Gets or sets the flag that specifies whether the shape is decorative in the document.
get_IsDeleteRevision()Returns true if this object was deleted in Microsoft Word while change tracking was enabled.
get_IsGroup()Returns true if this is a group shape.
get_IsHorizontalRule()Returns true if this shape is a horizontal rule.
get_IsImage()Returns true if this shape is an image shape.
get_IsInline()A quick way to determine if this shape is positioned inline with text.
get_IsInsertRevision()Returns true if this object was inserted in Microsoft Word while change tracking was enabled.
get_IsLayoutInCell()Gets or sets a flag indicating whether the shape is displayed inside a table or outside of it.
get_IsMoveFromRevision()Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled.
get_IsMoveToRevision()Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled.
get_IsSignatureLine()Indicates that shape is a SignatureLine.
get_IsTopLevel()Returns true if this shape is not a child of a group shape.
get_IsWordArt()Returns true if this shape is a WordArt object.
get_LastChild() constGets the last child of the node.
get_LastParagraph()Gets the last paragraph in the shape.
get_Left()Gets or sets the position of the left edge of the containing block of the shape.
get_LeftRelative()Gets the value that represents shape’s relative left position in percent.
get_MarkupLanguage() constGets MarkupLanguage used for this graphic object.
get_Name()Gets or sets the optional shape name.
get_NextNode() const
get_NextSibling()Gets the node immediately following this node.
get_NodeType() const overrideReturns Shape.
get_OleFormat()Provides access to the OLE data of a shape. For a shape that is not an OLE object or ActiveX control, returns null.
get_ParentNode()Gets the immediate parent of this node.
get_ParentParagraph()Returns the immediate parent paragraph.
get_PreviousSibling()Gets the node immediately preceding this node.
get_PrevNode() const
get_Range()Returns a Range object that represents the portion of a document that is contained in this node.
get_RelativeHorizontalPosition()Specifies relative to what the shape is positioned horizontally.
get_RelativeHorizontalSize()Gets or sets the value of shape’s relative size in horizontal direction.
get_RelativeVerticalPosition()Specifies relative to what the shape is positioned vertically.
get_RelativeVerticalSize()Gets or sets the value of shape’s relative size in vertical direction.
get_Right()Gets the position of the right edge of the containing block of the shape.
get_Rotation()Defines the angle (in degrees) that a shape is rotated. Positive value corresponds to clockwise rotation angle.
get_ScreenTip()Defines the text displayed when the mouse pointer moves over the shape.
get_ShadowEnabled()Returns true if a shadow effect is enabled.
get_ShadowFormat()Gets shadow formatting for the shape.
get_ShapeType()Gets the shape type.
get_SignatureLine()Gets SignatureLine object if the shape is a signature line. Returns null otherwise.
get_SizeInPoints()Gets the size of the shape in points.
get_StoryType()Returns Textbox.
get_Stroke()Defines a stroke for a shape.
get_StrokeColor()Defines the color of a stroke.
get_Stroked()Defines whether the path will be stroked.
get_StrokeWeight()Defines the brush thickness that strokes the path of a shape in points.
get_Target()Gets or sets the target frame for the shape hyperlink.
get_TextBox()Defines attributes that specify how text is displayed in a shape.
get_TextPath()Defines the text of the text path (of a WordArt object).
get_Title()Gets or sets the title (caption) of the current shape object.
get_Top()Gets or sets the position of the top edge of the containing block of the shape.
get_TopRelative()Gets the value that represents shape’s relative top position in percent.
get_VerticalAlignment()Specifies how the shape is positioned vertically.
get_Width()Gets or sets the width of the containing block of the shape.
get_WidthRelative()Gets the value that represents the percentage of shape’s relative width.
get_WrapSide()Specifies how the text is wrapped around the shape.
get_WrapType()Defines whether the shape is inline or floating. For floating shapes defines the wrapping mode for text around the shape.
get_ZOrder()Determines the display order of overlapping shapes.
GetAncestor(Aspose::Words::NodeType)Gets the first ancestor of the specified NodeType.
GetAncestorOf()
GetChild(Aspose::Words::NodeType, int32_t, bool)Returns an Nth child node that matches the specified type.
GetChildNodes(Aspose::Words::NodeType, bool)Returns a live collection of child nodes that match the specified type.
GetEnumerator() overrideProvides support for the for each style iteration over the child nodes of this node.
GetShapeRenderer()Creates and returns an object that can be used to render this shape into an image.
GetText() overrideGets the text of this node and of all its children.
GetType() const override
IndexOf(const System::SharedPtr<Aspose::Words::Node>&)Returns the index of the specified child node in the child node array.
InsertAfter(T, const System::SharedPtr<Aspose::Words::Node>&)
InsertBefore(T, const System::SharedPtr<Aspose::Words::Node>&)
Is(const System::TypeInfo&) const override
IsAncestorNode(const System::SharedPtr<Aspose::Words::Node>&)
LocalToParent(System::Drawing::PointF)Converts a value from the local coordinate space into the coordinate space of the parent shape.
NextPreOrder(const System::SharedPtr<Aspose::Words::Node>&)Gets next node according to the pre-order tree traversal algorithm.
static NodeTypeToString(Aspose::Words::NodeType)A utility method that converts a node type enum value into a user friendly string.
PrependChild(T)
PreviousPreOrder(const System::SharedPtr<Aspose::Words::Node>&)Gets the previous node according to the pre-order tree traversal algorithm.
Remove()Removes itself from the parent.
RemoveAllChildren()Removes all the child nodes of the current node.
RemoveChild(T)
RemoveSmartTags()Removes all SmartTag descendant nodes of the current node.
SelectNodes(const System::String&)Selects a list of nodes matching the XPath expression.
SelectSingleNode(const System::String&)Selects the first Node that matches the XPath expression.
set_AllowOverlap(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_AllowOverlap.
set_AlternativeText(const System::String&)Defines alternative text to be displayed instead of a graphic.
set_AnchorLocked(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_AnchorLocked.
set_AspectRatioLocked(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_AspectRatioLocked.
set_BehindText(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_BehindText.
set_Bounds(System::Drawing::RectangleF)Setter for Aspose::Words::Drawing::ShapeBase::get_Bounds.
set_CoordOrigin(System::Drawing::Point)Setter for Aspose::Words::Drawing::ShapeBase::get_CoordOrigin.
set_CoordSize(System::Drawing::Size)Setter for Aspose::Words::Drawing::ShapeBase::get_CoordSize.
set_CustomNodeId(int32_t)Setter for Aspose::Words::Node::get_CustomNodeId.
set_DistanceBottom(double)Setter for Aspose::Words::Drawing::ShapeBase::get_DistanceBottom.
set_DistanceLeft(double)Setter for Aspose::Words::Drawing::ShapeBase::get_DistanceLeft.
set_DistanceRight(double)Setter for Aspose::Words::Drawing::ShapeBase::get_DistanceRight.
set_DistanceTop(double)Setter for Aspose::Words::Drawing::ShapeBase::get_DistanceTop.
set_FillColor(System::Drawing::Color)Setter for Aspose::Words::Drawing::Shape::get_FillColor.
set_Filled(bool)Setter for Aspose::Words::Drawing::Shape::get_Filled.
set_FlipOrientation(Aspose::Words::Drawing::FlipOrientation)Setter for Aspose::Words::Drawing::ShapeBase::get_FlipOrientation.
set_Height(double)Setter for Aspose::Words::Drawing::ShapeBase::get_Height.
set_HeightRelative(float)Sets the value that represents the percentage of shape’s relative height.
set_HorizontalAlignment(Aspose::Words::Drawing::HorizontalAlignment)Setter for Aspose::Words::Drawing::ShapeBase::get_HorizontalAlignment.
set_HRef(const System::String&)Setter for Aspose::Words::Drawing::ShapeBase::get_HRef.
set_IsDecorative(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_IsDecorative.
set_IsLayoutInCell(bool)Setter for Aspose::Words::Drawing::ShapeBase::get_IsLayoutInCell.
set_Left(double)Setter for Aspose::Words::Drawing::ShapeBase::get_Left.
set_LeftRelative(float)Sets the value that represents shape’s relative left position in percent.
set_Name(const System::String&)Setter for Aspose::Words::Drawing::ShapeBase::get_Name.
set_NextNode(const System::SharedPtr<Aspose::Words::Node>&)
set_PrevNode(const System::SharedPtr<Aspose::Words::Node>&)
set_RelativeHorizontalPosition(Aspose::Words::Drawing::RelativeHorizontalPosition)Setter for Aspose::Words::Drawing::ShapeBase::get_RelativeHorizontalPosition.
set_RelativeHorizontalSize(Aspose::Words::Drawing::RelativeHorizontalSize)Setter for Aspose::Words::Drawing::ShapeBase::get_RelativeHorizontalSize.
set_RelativeVerticalPosition(Aspose::Words::Drawing::RelativeVerticalPosition)Setter for Aspose::Words::Drawing::ShapeBase::get_RelativeVerticalPosition.
set_RelativeVerticalSize(Aspose::Words::Drawing::RelativeVerticalSize)Setter for Aspose::Words::Drawing::ShapeBase::get_RelativeVerticalSize.
set_Rotation(double)Setter for Aspose::Words::Drawing::ShapeBase::get_Rotation.
set_ScreenTip(const System::String&)Setter for Aspose::Words::Drawing::ShapeBase::get_ScreenTip.
set_StrokeColor(System::Drawing::Color)Setter for Aspose::Words::Drawing::Shape::get_StrokeColor.
set_Stroked(bool)Setter for Aspose::Words::Drawing::Shape::get_Stroked.
set_StrokeWeight(double)Setter for Aspose::Words::Drawing::Shape::get_StrokeWeight.
set_Target(const System::String&)Setter for Aspose::Words::Drawing::ShapeBase::get_Target.
set_Title(const System::String&)Setter for Aspose::Words::Drawing::ShapeBase::get_Title.
set_Top(double)Setter for Aspose::Words::Drawing::ShapeBase::get_Top.
set_TopRelative(float)Sets the value that represents shape’s relative top position in percent.
set_VerticalAlignment(Aspose::Words::Drawing::VerticalAlignment)Setter for Aspose::Words::Drawing::ShapeBase::get_VerticalAlignment.
set_Width(double)Setter for Aspose::Words::Drawing::ShapeBase::get_Width.
set_WidthRelative(float)Sets the value that represents the percentage of shape’s relative width.
set_WrapSide(Aspose::Words::Drawing::WrapSide)Setter for Aspose::Words::Drawing::ShapeBase::get_WrapSide.
set_WrapType(Aspose::Words::Drawing::WrapType)Setter for Aspose::Words::Drawing::ShapeBase::get_WrapType.
set_ZOrder(int32_t)Setter for Aspose::Words::Drawing::ShapeBase::get_ZOrder.
SetParent(const System::SharedPtr<Aspose::Words::Node>&)
SetTemplateWeakPtr(uint32_t) override
Shape(const System::SharedPtr<Aspose::Words::DocumentBase>&, Aspose::Words::Drawing::ShapeType)Creates a new shape object.
ToString(Aspose::Words::SaveFormat)Exports the content of the node into a string in the specified format.
ToString(const System::SharedPtr<Aspose::Words::Saving::SaveOptions>&)Exports the content of the node into a string using the specified save options.
static Type()
UpdateSmartArtDrawing()Updates SmartArt pre-rendered drawing by using Aspose.Words’s SmartArt cold rendering engine.

Remarks

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

An important property of a shape is its 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.

Examples

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

auto doc = MakeObject<Document>(MyDir + u"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.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);

ASSERT_EQ(9, shapes->LINQ_Count([](SharedPtr<Node> s) { return (System::ExplicitCast<Shape>(s))->get_HasImage(); }));

int imageIndex = 0;
for (const auto& shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape>>()))
{
    if (shape->get_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.
        String imageFileName =
            String::Format(u"File.ExtractImages.{0}{1}", imageIndex, FileFormatUtil::ImageTypeToExtension(shape->get_ImageData()->get_ImageType()));
        shape->get_ImageData()->Save(ArtifactsDir + imageFileName);
        imageIndex++;
    }
}

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

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

// Insert a floating image that will appear behind the overlapping text and align it to the page's center.
SharedPtr<Shape> shape = builder->InsertImage(ImageDir + u"Logo.jpg");
shape->set_WrapType(WrapType::None);
shape->set_BehindText(true);
shape->set_RelativeHorizontalPosition(RelativeHorizontalPosition::Page);
shape->set_RelativeVerticalPosition(RelativeVerticalPosition::Page);
shape->set_HorizontalAlignment(HorizontalAlignment::Center);
shape->set_VerticalAlignment(VerticalAlignment::Center);

doc->Save(ArtifactsDir + u"Image.CreateFloatingPageCenter.docx");

Shows how to delete all shapes from a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

// Insert two shapes along with a group shape with another shape inside it.
builder->InsertShape(ShapeType::Rectangle, 400, 200);
builder->InsertShape(ShapeType::Star, 300, 300);

auto group = MakeObject<GroupShape>(doc);
group->set_Bounds(System::Drawing::RectangleF(100.0f, 50.0f, 200.0f, 100.0f));
group->set_CoordOrigin(System::Drawing::Point(-1000, -500));

auto subShape = MakeObject<Shape>(doc, ShapeType::Cube);
subShape->set_Width(500);
subShape->set_Height(700);
subShape->set_Left(0);
subShape->set_Top(0);

group->AppendChild(subShape);
builder->InsertNode(group);

ASSERT_EQ(3, doc->GetChildNodes(NodeType::Shape, true)->get_Count());
ASSERT_EQ(1, doc->GetChildNodes(NodeType::GroupShape, true)->get_Count());

// Remove all Shape nodes from the document.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);
shapes->Clear();

// All shapes are gone, but the group shape is still in the document.
ASSERT_EQ(1, doc->GetChildNodes(NodeType::GroupShape, true)->get_Count());
ASSERT_EQ(0, doc->GetChildNodes(NodeType::Shape, true)->get_Count());

// Remove all group shapes separately.
SharedPtr<NodeCollection> groupShapes = doc->GetChildNodes(NodeType::GroupShape, true);
groupShapes->Clear();

ASSERT_EQ(0, doc->GetChildNodes(NodeType::GroupShape, true)->get_Count());
ASSERT_EQ(0, doc->GetChildNodes(NodeType::Shape, true)->get_Count());

See Also