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();
Note: You cannot group shapes that already exist in a document.

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.

Showcase Your Apps on DevExpress.com

Highlight your business app and share your development experiences with the DevExpress community. To include your app in our upcoming App Showcase, please forward an application screenshot to clientservices@devexpress.com and tell us which DevExpress products you currently use within your organization.
2 comment(s)
Isa_Tahiri
Isa_Tahiri

Pretty cool ! 

When will the Shapes be available in the ASPXRichEdit ? 

BR

ISA

21 July 2020
Vladimir Frizen (DevExpress)
Vladimir Frizen (DevExpress)

Hi Isa,

Shape support within ASPxRichEdit will not be released in 2020.

I’ll be sure to include it in our 2021 Roadmap survey to gauge demand.

 
22 July 2020

Please login or register to post comments.