Word Processing - Shape API Enhancements (v20.1)

Our most recent release (v20.1) ships with an extended Shape API for our Word Processing Document API and Rich Text Editors (WinForms and WPF). This new API allows you to execute the following actions:

• Create different shapes (rectangles, lines, arrows, callouts, etc.)
• Position shapes on a page
• Change a shape’s fill and outline
• Group and ungroup shapes
• Remove shapes from a document.

Create and Format Drawing Objects

To demonstrate the capabilities of our Shape API, we’ll create the following simple flowchart:

1. Use the ShapeCollection.InsertPicture method to add a picture to a document. This will be the first block in our flowchart.

   Document document = wordProcessor.Document;
   // Set measurement unit to inches.
   document.Unit = DevExpress.Office.DocumentUnit.Inch;
           
   // Insert a picture.
   Shape block1 = document.Shapes.InsertPicture(document.Range.Start,
   	DocumentImageSource.FromFile("Picture_Block1.png"));
   // Specify picture position relative to the top left corner of the page.
   block1.Offset = new PointF(1.0f, 0.5f);

2. Use the ShapeCollection.InsertShape method to create a shape (an arrow in our example). The method includes parameters to help you specify a shape’s geometry, size, and location.

   // Create an arrow and specify its location and size.
   Shape arrow = document.Shapes.InsertShape(document.Range.Start,
   	ShapeGeometryPreset.RightArrow, new RectangleF(3.1f, 0.9f, 0.5f, 0.5f));
   // Apply a gradient fill to the arrow.
   arrow.Fill.SetGradientFill(GradientType.Linear, Color.FromArgb(0xA5, 0xA5, 0xA5),
   	Color.FromArgb(0x6E, 0x6E, 0x6E));
   // Remove the outline.
   arrow.Line.Fill.SetNoFill();

3. Call the ShapeCollection.InsertTextBox method to insert a text box. This will be the second block in our flowchart. Use the Shape.ShapeFormat.TextBox.Document property to access and modify text box content.

   // Create a text box and specify its location and size. 
   Shape block2 = document.Shapes.InsertTextBox(document.Range.Start,
   	new RectangleF(3.7f, 0.5f, 2f, 1.25f));
   // Change text box geometry.
   block2.ShapeFormat.Preset = ShapeGeometryPreset.RoundedRectangle;
   // Fill the text box with a specific color.
   block2.Fill.SetSolidFill(Color.FromArgb(0x92, 0xD0, 0x50));
   // Remove the outline.
   block2.Line.Fill.SetNoFill();
   // Access text box settings.
   DevExpress.XtraRichEdit.API.Native.TextBox textBox = block2.ShapeFormat.TextBox;
   // Specify text box content.
   SubDocument textBoxDocument = textBox.Document;
   textBoxDocument.AppendText("Step 2");
   // Align text horizontally and vertically.
   textBoxDocument.Paragraphs[0].Alignment = ParagraphAlignment.Center;
   textBox.VerticalTextAlignment = VerticalTextAlignmentType.Center;
   // Change text size and color.
   DocumentRange range = textBoxDocument.Paragraphs[0].Range;
   CharacterProperties cp = textBoxDocument.BeginUpdateCharacters(range);
   cp.ForeColor = System.Drawing.Color.White;
   cp.FontSize = 28;
   textBoxDocument.EndUpdateCharacters(cp);

Group and Ungroup Shapes

The ShapeCollection.InsertGroup method allows you to create a shape group. Use the Add methods of the Shape.GroupItems collection to add shapes and pictures to the group.

The example below describes how you can generate the following shape group:

Document document = wordProcessor.Document;
// Set measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;

// Insert a shape group.
Shape group = document.Shapes.InsertGroup(document.Range.Start);
// Specify group position relative to the left and top edges of the page. 
group.Offset = new PointF(1f, 0.5f);
            
// Access the group items collection. 
var groupItems = group.GroupItems;
// Add a rectangle to the group.
NestedShape shape1 = groupItems.AddShape(ShapeGeometryPreset.RoundedRectangle, 
	new RectangleF(0f, 0f, 2f, 1.25f));
shape1.Fill.SetSolidFill(Color.FromArgb(0x4F, 0x81, 0xBD));
shape1.Line.Fill.SetNoFill();

// Add an arrow to the group.
NestedShape shape2 = groupItems.AddShape(ShapeGeometryPreset.RightArrow, 
	new RectangleF(2.1f, 0.4f, 0.5f, 0.5f));
shape2.Fill.SetSolidFill(Color.FromArgb(0xA5, 0xA5, 0xA5));
shape2.Line.Fill.SetNoFill();
            
// Add a second rectangle to the group.
NestedShape shape3 = groupItems.AddShape(ShapeGeometryPreset.RoundedRectangle, 
	new RectangleF(2.7f, 0f, 2f, 1.25f));
shape3.Fill.SetSolidFill(Color.FromArgb(0x92, 0xD0, 0x50));
shape3.Line.Fill.SetNoFill();

Ungroup Shapes

Use the GroupShapeCollection.Ungroup method to split a group into individual shapes.

group.GroupItems.Ungroup();

Delete Shapes

The following example demonstrates how to remove shapes from a document:

// Delete the first shape in the collection.
document.Shapes.RemoveAt(0);

// Remove a specific shape from the collection.
document.Shapes.Remove(document.Shapes["Rectangle 1"]);

// Clear the entire collection.
// document.Shapes.Clear();

Your Feedback Matters

As always, we welcome your thoughts. Please comment below and let us know what you think of our new Shape API.

Should you have technical questions, feel free to contact us via the DevExpress Support Center.