Working with Shapes

This topic discusses how to work programmatically with shapes using Aspose.Words.

The shapes in Aspose.Words represent an object in the drawing layer, such as an AutoShape, textbox, freeform, OLE object, ActiveX control, or picture. A Word document can contain one or more different shapes. Shapes of the document are represented by the Shape class.

Inserting Shapes Using Document Builder

You can insert inline shape with specified type and size and free-floating shape with the specified position, size and text wrap type into a document using insert_shape method. The insert_shape method allows inserting DML shape into the document model. The document must be saved in the format, which supports DML shapes, otherwise, such nodes will be converted to VML shape, while document saving.

The following code example shows how to insert these types of shapes into the document:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

shape = builder.insert_shape(aw.drawing.ShapeType.TEXT_BOX, aw.drawing.RelativeHorizontalPosition.PAGE, 100,
    aw.drawing.RelativeVerticalPosition.PAGE, 100, 50, 50, aw.drawing.WrapType.NONE)
shape.rotation = 30.0

builder.writeln()

shape = builder.insert_shape(aw.drawing.ShapeType.TEXT_BOX, 50, 50)
shape.rotation = 30.0

saveOptions = aw.saving.OoxmlSaveOptions(aw.SaveFormat.DOCX)
saveOptions.compliance = aw.saving.OoxmlCompliance.ISO29500_2008_TRANSITIONAL
    

doc.save(docs_base.artifacts_dir + "WorkingWithShapes.insert_shape.docx", saveOptions)

Set Aspect Ratio Locked

Using Aspose.Words, you can specify whether the shape’s aspect ratio is locked through the aspect_ratio_locked property.

The following code example shows how to work with the AspectRatioLocked property:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

shape = builder.insert_image(docs_base.images_dir + "Transparent background logo.png")
shape.aspect_ratio_locked = False

doc.save(docs_base.artifacts_dir + "WorkingWithShapes.aspect_ratio_locked.docx")

Set Shape Layout In Cell

You can also specify whether the shape is displayed inside a table or outside of it using the is_layout_in_cell property.

The following code example shows how to work with the IsLayoutInCell property:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.start_table()
builder.row_format.height = 100
builder.row_format.height_rule = aw.HeightRule.EXACTLY

for i in range(0, 31) :
    
    if (i != 0 and i % 7 == 0) :
        builder.end_row()
    builder.insert_cell()
    builder.write("Cell contents")
    

builder.end_table()

watermark = aw.drawing.Shape(doc, aw.drawing.ShapeType.TEXT_PLAIN_TEXT)
    
watermark.relative_horizontal_position = aw.drawing.RelativeHorizontalPosition.PAGE
watermark.relative_vertical_position = aw.drawing.RelativeVerticalPosition.PAGE
watermark.is_layout_in_cell = True # Display the shape outside of the table cell if it will be placed into a cell.
watermark.width = 300
watermark.height = 70
watermark.horizontal_alignment = aw.drawing.HorizontalAlignment.CENTER
watermark.vertical_alignment = aw.drawing.VerticalAlignment.CENTER
watermark.rotation = -40
    

watermark.fill_color = drawing.Color.gray
watermark.stroke_color = drawing.Color.gray

watermark.text_path.text = "watermarkText"
watermark.text_path.font_family = "Arial"

watermark.name = "WaterMark_" + str(uuid.uuid4())
watermark.wrap_type = aw.drawing.WrapType.NONE

run = doc.get_child_nodes(aw.NodeType.RUN, True)[doc.get_child_nodes(aw.NodeType.RUN, True).count - 1].as_run()

builder.move_to(run)
builder.insert_node(watermark)
doc.compatibility_options.optimize_for(aw.settings.MsWordVersion.WORD2010)

doc.save(docs_base.artifacts_dir + "WorkingWithShapes.layout_in_cell.docx")

Create Snip Corner Rectangle

You can create a snip corner rectangle using Aspose.Words. The shape types are SINGLE_CORNER_SNIPPED, TOP_CORNERS_SNIPPED, DIAGONAL_CORNERS_SNIPPED, TOP_CORNERS_ONE_ROUNDED_ONE_SNIPPED, SINGLE_CORNER_ROUNDED, TOP_CORNERS_ROUNDED, and DIAGONAL_CORNERS_ROUNDED.

The DML shape is created using insert_shape method with these shape types. These types cannot be used to create VML shapes. Attempt to create shape by using the public constructor of the Shape class raises the “NotSupportedException” exception.

The following code example shows how to insert these type of shapes into the document:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.insert_shape(aw.drawing.ShapeType.TOP_CORNERS_SNIPPED, 50, 50)

saveOptions = aw.saving.OoxmlSaveOptions(aw.SaveFormat.DOCX)
saveOptions.compliance = aw.saving.OoxmlCompliance.ISO29500_2008_TRANSITIONAL
    
doc.save(docs_base.artifacts_dir + "WorkingWithShapes.add_corners_snipped.docx", saveOptions)

Get Actual Shape Bounds Points

Using Aspose.Words API, you can get the location and size of the shape containing block in points, relative to the anchor of the topmost shape. To do this, use the bounds_in_points property.

The following code example shows how to work with the BoundsInPoints property:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

shape = builder.insert_image(docs_base.images_dir + "Transparent background logo.png")
shape.aspect_ratio_locked = False

print("\nGets the actual bounds of the shape in points: ")
print(shape.get_shape_renderer().bounds_in_points)

Specify Vertical Anchor

You can specify the text vertical alignment within a shape using the vertical_anchor property.

The following code example shows how to work with the VerticalAnchor property:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

textBox = builder.insert_shape(aw.drawing.ShapeType.TEXT_BOX, 200, 200)
textBox.text_box.vertical_anchor = aw.drawing.TextBoxAnchor.BOTTOM
    
builder.move_to(textBox.first_paragraph)
builder.write("Textbox contents")

doc.save(docs_base.artifacts_dir + "WorkingWithShapes.vertical_anchor.docx")

Detect SmartArt Shape

Aspose.Words also allows to detect if the Shape has a SmartArt object. To do this, use the has_smart_art property property.

The following code example shows how to work with the HasSmartArt property:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "SmartArt.docx")

count = 0
for shape in doc.get_child_nodes(aw.NodeType.SHAPE, True) :
    shape = shape.as_shape()
    if(shape.has_smart_art) :
        count += 1

print("The document has 0 shapes with SmartArt.", count)

Insert Horizontal Rule into Document

You can insert horizontal rule shape into a document using the insert_horizontal_rule method.

The following code example shows how to do this:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.writeln("Insert a horizontal rule shape into the document.")
builder.insert_horizontal_rule()

doc.save(docs_base.artifacts_dir + "AddContentUsingDocumentBuilder.insert_horizontal_rule.docx")

Aspose.Words API provides the horizontal_rule_format property to access the properties of the horizontal rule shape. The HorizontalRuleFormat class exposes basic properties like height, color, no_shade etc. for the formatting of a horizontal rule.

The following code example demonstrates how to set HorizontalRuleFormat:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
builder = aw.DocumentBuilder()

shape = builder.insert_horizontal_rule()
            
horizontalRuleFormat = shape.horizontal_rule_format
horizontalRuleFormat.alignment = aw.drawing.HorizontalRuleAlignment.CENTER
horizontalRuleFormat.width_percent = 70
horizontalRuleFormat.height = 3
horizontalRuleFormat.color = drawing.Color.blue
horizontalRuleFormat.no_shade = True

builder.document.save(docs_base.artifacts_dir + "AddContentUsingDocumentBuilder.horizontal_rule_format.docx")

Insert OLE Object as an Icon

Aspose.Words API provides Shape.insert_ole_object_as_icon function to insert an embedded or linked OLE object as an icon into the document. This function allows specifying the icon file and the caption. The OLE object type shall be detected using the file extension.

The following code example demonstrates how to set insert OLE object as an Icon into the document:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

builder.insert_ole_object_as_icon(docs_base.my_dir + "Presentation.pptx", False, docs_base.images_dir + "Logo icon.ico", "My embedded file")

doc.save(docs_base.artifacts_dir + "WorkingWithOleObjectsAndActiveX.insert_ole_object_as_icon.docx")

Maximum size of the icon must be 32x32 for the correct display.

Import Shapes with Math XML as Shapes into DOM

You can use convert_shape_to_office_math property to convert the shapes with EquationXML to Office Math objects. The default value of this property corresponds to MS Word behavior i.e. shapes with equation XML are not converted to Office math objects.

The following code example shows how to convert shapes to Office Math objects:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
loadOptions = aw.loading.LoadOptions()
loadOptions.convert_shape_to_office_math = True 

doc = aw.Document(docs_base.my_dir + "Office math.docx", loadOptions)

doc.save(docs_base.artifacts_dir + "WorkingWithLoadOptions.convert_shape_to_office_math.docx", aw.SaveFormat.DOCX)