Shape Interface

A drawing object embedded in a document.

Namespace : DevExpress.XtraRichEdit.API.Native

Assembly : DevExpress.RichEdit.v25.2.Core.dll

NuGet Package : DevExpress.RichEdit.Core

Declaration

C#
VB.NET

csharp

[ComVisible(true)]
public interface Shape :
    DrawingObject

<ComVisible(True)>
Public Interface Shape
    Inherits DrawingObject

The following members return Shape objects:

Show 34 links

Remarks

Use the SubDocument.Shapes property to access a collection of drawing objects: shapes, pictures, text boxes, charts, watermarks, OLE objects, and ActiveX controls.

Access Shapes

The ShapeCollection.Item property uses a shape’s name or index to return the corresponding Shape object from the collection. Use the Shape.Type property to determine the shape type.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Access the first shape in the collection.
Shape shape1 = document.Shapes[0];

// Access the shape with the specified name. 
Shape shape2 = document.Shapes["Rectangle 1"];

Dim document As Document = wordProcessor.Document
' Access the first shape in the collection.
Dim shape1 As Shape = document.Shapes(0)

' Access the shape with the specified name. 
Dim shape2 As Shape = document.Shapes("Rectangle 1")

Tip

Use the ReadOnlyShapeCollection.Get method to retrieve all shapes from the specified document range.

Create Shapes

Use the ShapeCollection.InsertShape method overloads to add a shape to a document. A ShapeGeometryPreset enumeration member defines the shape’s geometry.

The example below creates a rectangle.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, new RectangleF(1.5f, 1f, 2f, 1.5f));
// Fill the rectangle with color.
rectangle.Fill.SetSolidFill(Color.FromArgb(0xFF, 0xEE, 0xAD));
// Format the rectangle border.
ShapeLine border = rectangle.Line;
border.Color = Color.FromArgb(0x4D, 0x64, 0x8D);
border.Thickness = 6;
border.JoinType = LineJoinType.Miter;

Dim document As Document = wordProcessor.Document
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, New RectangleF(1.5F, 1F, 2F, 1.5F))
' Fill the rectangle with color.
rectangle.Fill.SetSolidFill(Color.FromArgb(&HFF, &HEE, &HAD))
' Format the rectangle border.
Dim border As ShapeLine = rectangle.Line
border.Color = Color.FromArgb(&H4D, &H64, &H8D)
border.Thickness = 6
border.JoinType = LineJoinType.Miter

Insert Pictures

Call the ShapeCollection.InsertPicture method to insert a picture into a document. Use the Shape.PictureFormat property to access picture settings.

The example below inserts a picture with rounded corners.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Insert a picture.
Shape picture = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("Dog.png"));
// Change the picture's form.
picture.PictureFormat.Preset = ShapeGeometryPreset.RoundedRectangle;
// Display a border around the picture.
picture.Line.Color = Color.Black;
picture.Line.Thickness = 3;
// Align the picture.
picture.VerticalAlignment = ShapeVerticalAlignment.Top;
picture.HorizontalAlignment = ShapeHorizontalAlignment.Center;

Dim document As Document = wordProcessor.Document
' Insert a picture.
Dim picture As Shape = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("Dog.png"))
' Change the picture's form.
picture.PictureFormat.Preset = ShapeGeometryPreset.RoundedRectangle
' Display a border around the picture.
picture.Line.Color = Color.Black
picture.Line.Thickness = 3
' Align the picture.
picture.VerticalAlignment = ShapeVerticalAlignment.Top
picture.HorizontalAlignment = ShapeHorizontalAlignment.Center

Note

Pictures are stored in two collections: ShapeCollection and DocumentImageCollection.

Create Text Boxes

Call the ShapeCollection.InsertTextBox method to add a text box to a document. Use the Shape.ShapeFormat.TextBox.Document property to access and modify text box content.

The example below creates a text box.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Create a text box.
Shape myTextBox = document.Shapes.InsertTextBox(document.Range.Start, new RectangleF(1.5f, 1f, 1.5f, 0.5f));
// Specify the text box background color.
myTextBox.Fill.Color = System.Drawing.Color.WhiteSmoke;
// Draw a border around the text box.
myTextBox.Line.Color = System.Drawing.Color.Black;
myTextBox.Line.Thickness = 1;
// Modify text box content.
SubDocument textBoxDocument = myTextBox.ShapeFormat.TextBox.Document;
textBoxDocument.AppendText("Text box");
CharacterProperties cp = textBoxDocument.BeginUpdateCharacters(textBoxDocument.Range.Start, 4);
cp.ForeColor = System.Drawing.Color.Orange;
cp.FontSize = 24;
textBoxDocument.EndUpdateCharacters(cp);

Dim document As Document = wordProcessor.Document
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Create a text box.
Dim myTextBox As Shape = document.Shapes.InsertTextBox(document.Range.Start, New RectangleF(1.5F, 1F, 1.5F, 0.5F))
' Specify the text box background color.
myTextBox.Fill.Color = System.Drawing.Color.WhiteSmoke
' Draw a border around the text box.
myTextBox.Line.Color = System.Drawing.Color.Black
myTextBox.Line.Thickness = 1
' Modify text box content.
Dim textBoxDocument As SubDocument = myTextBox.ShapeFormat.TextBox.Document
textBoxDocument.AppendText("Text box")
Dim cp As CharacterProperties = textBoxDocument.BeginUpdateCharacters(textBoxDocument.Range.Start, 4)
cp.ForeColor = System.Drawing.Color.Orange
cp.FontSize = 24
textBoxDocument.EndUpdateCharacters(cp)

Use the following properties to determine whether a drawing object is a text box:

DrawingObject.Type is Shape;
DrawingObject.ShapeFormat.HasText returns true.

Insert OLE Objects

Linked Objects

Use the ShapeCollection.InsertOleObject method overload with the fileName parameter to create an OLE object that stores a link to a specified file. You can use constant fields of the OleObjectType class to specify the file type. The OLE object is displayed in the document as an image.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Insert an OLE object. Link it to an Excel worksheet.
Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
    OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
// Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
oleObject.Offset = new PointF(0, 0);
// Specify how text wraps around the object. 
oleObject.TextWrapping = TextWrappingType.TopAndBottom;

Dim document As Document = wordProcessor.Document
' Insert an OLE object. Link it to an Excel worksheet.
Dim oleObject As Shape = document.Shapes.InsertOleObject(document.CreatePosition(1780), "D:\ExcelWorkbook.xlsx", _ 
    OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Spreadsheet.png"))
' Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
oleObject.Offset = New PointF(0, 0)
' Specify how text wraps around the object. 
oleObject.TextWrapping = TextWrappingType.TopAndBottom

Open the document in Microsoft® Word® and double-click the image to open the file associated with the OLE object.

Embedded Objects

Use the ShapeCollection.InsertOleObject method overload with the stream parameter to embed data from an external file in the document. You can use constant fields of the OleObjectType class to specify the content type. The OLE object is displayed in the document as an image.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Embed data from an Excel worksheet in the document.
using (Stream excelStream = File.Open(@"D:\ExcelWorkbook.xlsx", FileMode.Open))
{
    Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), excelStream,
        OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
    // Specify the object position on the page.
    oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
    oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
    oleObject.Offset = new PointF(0, 0);
    // Specify how text wraps around the object. 
    oleObject.TextWrapping = TextWrappingType.TopAndBottom;
}

Dim document As Document = wordProcessor.Document
' Embed data from an Excel worksheet in the document.
Using excelStream As Stream = File.Open("D:\ExcelWorkbook.xlsx", FileMode.Open)
    Dim oleObject As Shape = document.Shapes.InsertOleObject(document.CreatePosition(1780), excelStream, _
    OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Spreadsheet.png"))
    ' Specify the object position on the page.
    oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
    oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
    oleObject.Offset = New PointF(0, 0)
    ' Specify how text wraps around the object. 
    oleObject.TextWrapping = TextWrappingType.TopAndBottom
End Using

Open the document in Microsoft® Word® and double-click the OLE object to modify the embedded data.

Display OLE Objects as Icons

Use the ShapeCollection.InsertOleObjectAsIcon method overloads to insert OLE objects as icons.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Insert an OLE object. Link it to an Excel worksheet.
// The OLE object is displayed in the document as an icon.
Shape oleObject = document.Shapes.InsertOleObjectAsIcon(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
    OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Excel.ico"));
// Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
oleObject.Offset = new PointF(0, 0);
// Specify how text wraps around the object. 
oleObject.TextWrapping = TextWrappingType.TopAndBottom;

Dim document As Document = wordProcessor.Document
' Insert an OLE object. Link it to an Excel worksheet.
' The OLE object is displayed in the document as an icon.
Dim oleObject As Shape = document.Shapes.InsertOleObjectAsIcon(document.CreatePosition(1780), "D:\ExcelWorkbook.xlsx", _ 
    OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Excel.ico"))
' Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
oleObject.Offset = New PointF(0, 0)
' Specify how text wraps around the object. 
oleObject.TextWrapping = TextWrappingType.TopAndBottom

Open the document in Microsoft® Word® and double-click the icon to open the file associated with the OLE object.

Insert Drawing Canvas

The ShapeCollection.InsertCanvas method inserts a drawing canvas into a document. Use the Shape.CanvasItems property to access the canvas item collection. The collection’s Add methods allow you to add shapes and pictures to the canvas.

The example below adds a drawing canvas to the document.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Insert a drawing canvas.
Shape canvas = document.Shapes.InsertCanvas(document.Range.Start, new RectangleF(1.5f, 1f, 6f, 1.5f));
// Access the collection of canvas items. 
var canvasItems = canvas.CanvasItems;
// Add a rectangle to the canvas.
var shape1 = canvasItems.AddShape(ShapeGeometryPreset.Rectangle, new RectangleF(0f, 0f, 2f, 1.5f));
shape1.Fill.SetSolidFill(Color.FromArgb(0xA4, 0xFF, 0xFF));
shape1.Line.Color = Color.DarkGray;
shape1.Line.Thickness = 2;
// Add a picture to the canvas.
var shape2 = canvasItems.AddPicture(DocumentImageSource.FromFile("Picture_Arrow.png"), new PointF(2.1f, 0.3f));
// Add a parallelogram to the canvas.
var shape3 = canvasItems.AddShape(ShapeGeometryPreset.Parallelogram, new RectangleF(3.8f, 0f, 2f, 1.5f));
shape3.Fill.SetSolidFill(Color.FromArgb(0xFF, 0xA5, 0xA5));
shape3.Line.Color = Color.DarkGray;
shape3.Line.Thickness = 2;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Insert a drawing canvas.
Dim canvas As Shape = document.Shapes.InsertCanvas(document.Range.Start, New RectangleF(1.5F, 1F, 6F, 1.5F))
' Access the collection of canvas items. 
Dim canvasItems As CanvasShapeCollection = canvas.CanvasItems
' Add a rectangle to the canvas.
Dim shape1 As NestedShape = canvasItems.AddShape(ShapeGeometryPreset.Rectangle, New RectangleF(0F, 0F, 2F, 1.5F))
shape1.Fill.SetSolidFill(Color.FromArgb(&HA4, &HFF, &HFF))
shape1.Line.Color = Color.DarkGray
shape1.Line.Thickness = 2
' Add a picture to the canvas.
Dim shape2 As NestedShape = canvasItems.AddPicture(DocumentImageSource.FromFile("Picture_Arrow.png"), New PointF(2.1F, 0.3F))
' Add a parallelogram to the canvas.
Dim shape3 As NestedShape = canvasItems.AddShape(ShapeGeometryPreset.Parallelogram, New RectangleF(3.8F, 0F, 2F, 1.5F))
shape3.Fill.SetSolidFill(Color.FromArgb(&HFF, &HA5, &HA5))
shape3.Line.Color = Color.DarkGray
shape3.Line.Thickness = 2

Format Shapes

Use the following properties to customize shape appearance:

Property	Description
Shape.Fill	Provides access to shape fill options.
Shape.Line	Provides access to format settings for a line or a shape’s border.
ShapeLine.Fill	Specifies line fill options.

The example below shows how to create a rectangle and change its border settings.

C#
VB.NET

csharp

// Add a rectangle to a document.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, new RectangleF(300, 200, 500, 300));
// Fill the rectangle with color.
rectangle.Fill.SetSolidFill(Color.FromArgb(0xFF, 0xEE, 0xAD));
// Format the rectangle border.
ShapeLine border = rectangle.Line;
border.Color = Color.FromArgb(0x4D, 0x64, 0x8D);
border.Thickness = 6;
border.JoinType = LineJoinType.Miter;
border.DashType = LineDashType.Solid;
border.CompoundType = LineCompoundType.ThickThin;

' Add a rectangle to a document.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, New RectangleF(300, 200, 500, 300))
' Fill the rectangle with color.
rectangle.Fill.SetSolidFill(Color.FromArgb(&HFF, &HEE, &HAD))
' Format the rectangle border.
Dim border As ShapeLine = rectangle.Line
border.Color = Color.FromArgb(&H4D, &H64, &H8D)
border.Thickness = 6
border.JoinType = LineJoinType.Miter
border.DashType = LineDashType.Solid
border.CompoundType = LineCompoundType.ThickThin

Position Shapes

A shape is anchored to a document range defined by the Shape.Range property. You can position the shape anywhere on the page that contains the anchor.

Horizontal and vertical alignment

Property	Description
Shape.HorizontalAlignment	Aligns a shape horizontally relative to the element specified by the Shape.RelativeHorizontalPosition property.
Shape.VerticalAlignment	Aligns a shape vertically relative to the element specified by the Shape.RelativeVerticalPosition property.

The following example displays a rectangle in the center of the page below the top margin:

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, new SizeF(500, 300));
// Align the rectangle horizontally and vertically.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page;
rectangle.HorizontalAlignment = ShapeHorizontalAlignment.Center;
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Margin;
rectangle.VerticalAlignment = ShapeVerticalAlignment.Top;

Dim document As Document = wordProcessor.Document
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, New SizeF(500, 300))
' Align the rectangle horizontally and vertically.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page
rectangle.HorizontalAlignment = ShapeHorizontalAlignment.Center
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Margin
rectangle.VerticalAlignment = ShapeVerticalAlignment.Top

Absolute position

Property	Description
Shape.OffsetX	Specifies a shape’s horizontal position relative to the element defined by the Shape.RelativeHorizontalPosition property.
Shape.OffsetY	Specifies a shape’s vertical position relative to the element defined by the Shape.RelativeVerticalPosition property.
Shape.Offset	Allows you to specify a shape’s horizontal and vertical positions.

Note

The Offset properties are in effect when the Shape.HorizontalAlignment and Shape.VerticalAlignment properties are set to None.

The example below creates a rectangle and places it on the page as follows:

the absolute horizontal position is two inches to the right of the page;
the absolute vertical position is one inch below the page.
C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, new SizeF(2.5f, 1.5f));
// Specify the rectangle position on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page;
rectangle.OffsetX = 2;
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page;
rectangle.OffsetY = 1;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, New SizeF(2.5F, 1.5F))
' Specify the rectangle position on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page
rectangle.OffsetX = 2
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page
rectangle.OffsetY = 1

Relative position

Property	Description
Shape.OffsetXRelative	Specifies a shape’s horizontal position (as a percentage) relative to the element defined by the Shape.RelativeHorizontalPosition property.
Shape.OffsetYRelative	Specifies a shape’s vertical position (as a percentage) relative to the element defined by the Shape.RelativeVerticalPosition property.
Shape.OffsetRelative	Allows you to specify a shape’s relative horizontal and vertical positions.

Note

The OffsetRelative properties are in effect when the Shape.HorizontalAlignment and Shape.VerticalAlignment properties are set to None.

The example below creates a rectangle and places it on the page as follows:

the horizontal offset is equal to 20% of the page width,
the vertical offset is equal to 10% of the page height.
C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, new SizeF(2.5f, 1.5f));
// Specify the rectangle position on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page;
rectangle.OffsetXRelative = 0.2f;
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page;
rectangle.OffsetYRelative = 0.1f;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle, New SizeF(2.5F, 1.5F))
' Specify the rectangle position on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page
rectangle.OffsetXRelative = 0.2F
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page
rectangle.OffsetYRelative = 0.1F

Text Wrapping

Use the following properties to specify how text wraps around a shape:

Property	Description
Shape.TextWrapping	Specifies the text wrapping style.
Shape.TextWrappingSide	Allows you to specify which sides to wrap text around.
Shape.MarginTop
Shape.MarginBottom Shape.MarginLeft
Shape.MarginRight	Define the distance between the shape and surrounding text.

The example below demonstrates how to wrap text around a shape.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
document.LoadDocument("FirstLook.docx");
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;

// Create a rectangle with a folded corner.
Shape rectangle = document.Shapes.InsertShape(document.CreatePosition(100), ShapeGeometryPreset.FoldedCorner);
// Center the rectangle on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page;
rectangle.HorizontalAlignment = ShapeHorizontalAlignment.Center;
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page;
rectangle.VerticalAlignment = ShapeVerticalAlignment.Center;

// Wrap text around the rectangle.
rectangle.TextWrapping = TextWrappingType.Square;

// Set the distance between the rectangle and text.
rectangle.MarginTop = 0.1f;
rectangle.MarginBottom = 0.1f;
rectangle.MarginLeft = 0.2f;
rectangle.MarginRight = 0.2f;

Dim document As Document = wordProcessor.Document
document.LoadDocument("FirstLook.docx")
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch

' Create a rectangle with a folded corner.
Dim rectangle As Shape = document.Shapes.InsertShape(document.CreatePosition(100), ShapeGeometryPreset.FoldedCorner)
' Center the rectangle on the page.
rectangle.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Page
rectangle.HorizontalAlignment = ShapeHorizontalAlignment.Center
rectangle.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Page
rectangle.VerticalAlignment = ShapeVerticalAlignment.Center

' Wrap text around the rectangle.
rectangle.TextWrapping = TextWrappingType.Square

' Set the distance between the rectangle and text.
rectangle.MarginTop = 0.1F
rectangle.MarginBottom = 0.1F
rectangle.MarginLeft = 0.2F
rectangle.MarginRight = 0.2F

Inline drawing objects

Set the Shape.TextWrapping property to TextWrappingType.InLineWithText to convert a floating object to an inline shape.

The example below demonstrates how to insert an inline shape.

C#
VB.NET

csharp

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

// Append text to the document.
document.AppendText("The plus sign is a binary operator that indicates addition.");

// Create a plus sign.
Shape rectangle = document.Shapes.InsertShape(document.CreatePosition(13), ShapeGeometryPreset.Plus);
// Set the shape size.
rectangle.Size = new SizeF(0.25f, 0.25f);

// Place the shape in line with text.
rectangle.TextWrapping = TextWrappingType.InLineWithText;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch

' Append text to the document.
document.AppendText("The plus sign is a binary operator that indicates addition.")

' Create a plus sign.
Dim rectangle As Shape = document.Shapes.InsertShape(document.CreatePosition(13), ShapeGeometryPreset.Plus)
' Set the shape size.
rectangle.Size = New SizeF(0.25F, 0.25F)

' Place the shape in line with text.
rectangle.TextWrapping = TextWrappingType.InLineWithText

Resize Shapes

Absolute Size

Property	Description
Shape.Height	Specifies the shape’s height in measurement units defined by the Document.Unit property.
Shape.Width	Specifies the shape’s width in measurement units defined by the Document.Unit property.
Shape.Size	Allows you to specify the shape’s width and height.

The following code creates a rectangle and specifies its height and width:

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle);
// Specify its width and height.
rectangle.Width = 2;
rectangle.Height = 1;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle)
' Specify its width and height.
rectangle.Width = 2
rectangle.Height = 1

Relative Size

Property	Description
Shape.HeightRelative	Specifies the shape’s height (as a percentage) relative to the element defined by the RelativeVerticalSize property.
Shape.WidthRelative	Specifies the shape’s width (as a percentage) relative to the element defined by the RelativeHorizontalSize property.
Shape.SizeRelative	Allows you to specify the shape’s relative width and height.

The following example creates a rectangle and sets its width and height to 50% of the page size:

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Create a rectangle.
Shape rectangle = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle);
// Set the rectangle width to 50% of the page width.
rectangle.RelativeHorizontalSize = ShapeRelativeHorizontalSize.Page;
rectangle.WidthRelative = 0.5f;
// Set the rectangle height to 50% of the page height.
rectangle.RelativeVerticalSize = ShapeRelativeVerticalSize.Page;
rectangle.HeightRelative = 0.5f;

Dim document As Document = wordProcessor.Document
' Create a rectangle.
Dim rectangle As Shape = document.Shapes.InsertShape(document.Range.Start, ShapeGeometryPreset.Rectangle)
' Set the rectangle width to 50% of the page width.
rectangle.RelativeHorizontalSize = ShapeRelativeHorizontalSize.Page
rectangle.WidthRelative = 0.5F
' Set the rectangle height to 50% of the page height.
rectangle.RelativeVerticalSize = ShapeRelativeVerticalSize.Page
rectangle.HeightRelative = 0.5F

Scale Factor

Property	Description
Shape.ScaleX	Scales a shape horizontally relative to its original size.
Shape.ScaleY	Scales a shape vertically relative to its original size.

The following example resizes all pictures in the document:

C#
VB.NET

csharp

document.LoadDocument("FirstLook.docx", DevExpress.XtraRichEdit.DocumentFormat.Docx);
foreach (Shape s in document.Shapes)
{
    // Scale pictures.
    if (s.Type == ShapeType.Picture)
    {
        s.ScaleX = 0.8f;
        s.ScaleY = 0.8f;
    }
}

document.LoadDocument("FirstLook.docx", DevExpress.XtraRichEdit.DocumentFormat.Docx)
For Each s As Shape In document.Shapes
    ' Scale pictures.
    If s.Type = ShapeType.Picture Then
        s.ScaleX = 0.8F
        s.ScaleY = 0.8F
    End If
Next s

Lock Aspect Ratio

Set the Shape.LockAspectRatio property to true to resize a shape proportionally.

Rotate Shapes

Use the Shape.RotationAngle property to rotate a shape.

The example below rotates all pictures in the document.

C#
VB.NET

csharp

document.LoadDocument("FirstLook.docx", DevExpress.XtraRichEdit.DocumentFormat.Docx);
foreach (Shape s in document.Shapes)
{
    // Rotate pictures.
    if (s.Type == ShapeType.Picture)
    {
        s.RotationAngle = 45;
    }
}

document.LoadDocument("FirstLook.docx", DevExpress.XtraRichEdit.DocumentFormat.Docx)
For Each s As Shape In document.Shapes
    ' Rotate pictures.
    If s.Type = ShapeType.Picture Then
        s.RotationAngle = 45
    End If
Next s

Group Shapes

Call the ShapeCollection.InsertGroup method to create a shape group. The Shape.GroupItems property returns a collection of group elements. Use the collection’s Add methods to add nested groups, shapes, and pictures to the group.

Note

You cannot group shapes that already exist in a document.

The example below creates a shape group in the document.

C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Insert a shape group.
Shape group = document.Shapes.InsertGroup(document.Range.Start);
// Specify the group position relative to the left and top edges of the page. 
group.Offset = new PointF(1.5f, 1f);
// Access the collection of group items. 
var groupItems = group.GroupItems;
// Add a rectangle to the group.
var shape1 = groupItems.AddShape(ShapeGeometryPreset.Rectangle, new RectangleF(0f, 0f, 2f, 1.5f));
shape1.Fill.SetSolidFill(Color.FromArgb(0xA4, 0xFF, 0xFF));
shape1.Line.Color = Color.DarkGray;
shape1.Line.Thickness = 2;
// Add a picture to the group.
var shape2 = groupItems.AddPicture(DocumentImageSource.FromFile("Picture_Arrow.png"), new PointF(2.1f, 0.3f));
// Add a parallelogram to the group.
var shape3 = groupItems.AddShape(ShapeGeometryPreset.Parallelogram, new RectangleF(3.8f, 0f, 2f, 1.5f));
shape3.Fill.SetSolidFill(Color.FromArgb(0xFF, 0xA5, 0xA5));
shape3.Line.Color = Color.DarkGray;
shape3.Line.Thickness = 2;

Dim document As Document = wordProcessor.Document
' Set the measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Insert a shape group.
Dim group As Shape = document.Shapes.InsertGroup(document.Range.Start)
' Specify the group position relative to the left and top edges of the page. 
group.Offset = New PointF(1.5F, 1F)
' Access the collection of group items. 
Dim groupItems As GroupShapeCollection = group.GroupItems
' Add a rectangle to the group.
Dim shape1 As NestedShape = groupItems.AddShape(ShapeGeometryPreset.Rectangle, New RectangleF(0F, 0F, 2F, 1.5F))
shape1.Fill.SetSolidFill(Color.FromArgb(&HA4, &HFF, &HFF))
shape1.Line.Color = Color.DarkGray
shape1.Line.Thickness = 2
' Add a picture to the group.
Dim shape2 As NestedShape = groupItems.AddPicture(DocumentImageSource.FromFile("Picture_Arrow.png"), New PointF(2.1F, 0.3F))
' Add a parallelogram to the group.
Dim shape3 As NestedShape = groupItems.AddShape(ShapeGeometryPreset.Parallelogram, New RectangleF(3.8F, 0F, 2F, 1.5F))
shape3.Fill.SetSolidFill(Color.FromArgb(&HFF, &HA5, &HA5))
shape3.Line.Color = Color.DarkGray
shape3.Line.Thickness = 2

Ungroup Shapes

Use the Shape.GroupItems.Ungroup method to split an existing shape group into individual drawing objects.

The example below shows how to split all shape groups in the document (including nested groups):

C#
VB.NET

csharp

using System.Linq;
// ...

Document document = wordProcessor.Document;
List<DrawingObject> groups = document.Shapes.Flatten()
    .Where(x => x.Type == ShapeType.Group)
    .ToList();
for (int i = groups.Count - 1; i >= 0; i--)
{
    groups[i].GroupItems.Ungroup();
}

Imports System.Linq
' ...

Private document As Document = wordProcessor.Document
Private groups As List(Of DrawingObject) = document.Shapes.Flatten() _
        .Where(Function(x) x.Type = ShapeType.Group) _
        .ToList()
For i As Integer = groups.Count - 1 To 0 Step -1
    groups(i).GroupItems.Ungroup()
Next i

Add Hyperlinks to Shapes

Use the following API to attach a hyperlink to a shape:

Member	Description
Shape.AddHyperlink	Creates a new Hyperlink object associated with a shape.
Hyperlink.NavigateUri	Specifies the hyperlink’s destination.
Hyperlink.ToolTip	Adds a tooltip to the hyperlink. This text is displayed when the mouse pointer hovers over the shape.

The following example inserts a picture and attaches a hyperlink to it:

C#
VB.NET

csharp

Document document = wordProcessor.Document;
Shape picture = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("DevExpress.png"));
Hyperlink pictureHyperlink = picture.AddHyperlink();
pictureHyperlink.NavigateUri = "https://community.devexpress.com/blogs/";
pictureHyperlink.ToolTip = "Check the recent DevExpress blogs";

Dim document As Document = wordProcessor.Document
Dim picture As Shape = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("DevExpress.png"))
Dim pictureHyperlink As Hyperlink = picture.AddHyperlink()
pictureHyperlink.NavigateUri = "https://community.devexpress.com/blogs/"
pictureHyperlink.ToolTip = "Check the recent DevExpress blogs"

Remove Shapes

Use one of the following methods to remove a shape from the document:

ShapeCollection.Remove - removes a specific shape from the collection;
ShapeCollection.RemoveAt - removes a shape with the specified index from the collection;
ShapeCollection.Clear - clears the collection.
C#
VB.NET

csharp

Document document = wordProcessor.Document;
// Access the shape collection.
ShapeCollection shapes = document.Shapes;

// Delete the first shape from the collection.
shapes.RemoveAt(0);

// Delete the "Rectangle 1" shape.
shapes.Remove(shapes["Rectangle 1"]);

Dim document As Document = wordProcessor.Document
' Access the shape collection.
Dim shapes As ShapeCollection = document.Shapes

' Delete the first shape from the collection.
shapes.RemoveAt(0)

' Delete the "Rectangle 1" shape.
shapes.Remove(shapes("Rectangle 1"))

Shape Interface

Shape Interface

Declaration

Related API Members

Remarks

Access Shapes

Create Shapes

Insert Pictures

Create Text Boxes

Insert OLE Objects

Linked Objects

Embedded Objects

Display OLE Objects as Icons

Insert Drawing Canvas

Format Shapes

Position Shapes

Horizontal and vertical alignment

Absolute position

Relative position

Text Wrapping

Inline drawing objects

Resize Shapes

Absolute Size

Relative Size

Scale Factor

Lock Aspect Ratio

Rotate Shapes

Group Shapes

Ungroup Shapes

Add Hyperlinks to Shapes

Remove Shapes