officefileapi-15315-word-processing-document-api-word-processing-document-shapes.md
The Word Processing Document API allows you to load, save, print, and export documents that contain shapes to PDF. The RichEditDocumentServer supports all shape types from simple lines and rectangles to shapes with advanced effects.
Use the SubDocument.Shapes property to access a document’s collection of drawing objects: shapes, pictures, text boxes, charts, OLE objects, and ActiveX controls.
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.
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.
Use the ShapeCollection.InsertShape method overloads to add a shape to a document. A ShapeGeometryPreset enumeration member defines the shape’s geometry.
The following code snippet creates a rectangle:
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
Call the ShapeCollection.InsertPicture method to insert a picture into a document. Use the Shape.PictureFormat property to access picture settings.
The following image formats are available:
The following code snippet inserts a picture with rounded corners:
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.
You can replace a picture with another picture. Refer to the following example for more information: How to: Replace a Picture with Another Picture
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 following code snippet creates a text box:
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.ShapeFormat.HasText returns true.
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.
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
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.
// 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
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.
| 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:
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
| 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.
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
| 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.
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
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.MarginBottomShape.MarginLeft | |
| Shape.MarginRight | Define the distance between the shape and surrounding text. |
The example below demonstrates how to wrap text around a shape.
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
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.
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
| 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:
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
| 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:
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
| 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:
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
Set the Shape.LockAspectRatio property to true to resize a shape proportionally.
Use the Shape.RotationAngle property to rotate a shape.
The following code snippet rotates all pictures in the document.
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
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.
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
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):
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
Use the following API to attach a hyperlink to a shape:
| Member | Description |
|---|---|
| Shape.AddHyperlink | Creates a new Hyperlink object associated with a shape. This hyperlink is not added to the document’s HyperlinkCollection. |
| 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:
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"
You can specify the following shape accessibility settings:
DrawingObject.AltTextSets the alternative, text-based representation of a shape Alternative text helps people that use screen readers to understand the document content.DrawingObject.DecorativeSpecifies that the shape does not contain meaningful content to a document and is purely decorative. This options helps screen readers ignore these images and prevent unnecessary distractions for users with visual impairments. Decorative images are marked as artifacts when you export a workbook as an PDF/UA document.
The following code snippet specifies the alternative text:
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...
using (var wordProcessor = new RichEditDocumentServer()) {
Document document = wordProcessor.Document;
// Insert a picture.
Shape picture = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("Dog.png"));
// Add image description.
picture.AltText = "Cartoonish black dog with large eyes and tongue out.";
// Mark image as decorative
// picture.Decorative = true;
}
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...
Using wordProcessor = New RichEditDocumentServer()
Dim document As Document = wordProcessor.Document
' Insert a picture.
Dim picture As Shape = document.Shapes.InsertPicture(document.Range.Start, DocumentImageSource.FromFile("Dog.png"))
' Add image description.
picture.AltText = "Cartoonish black dog with large eyes and tongue out."
' Mark image as decorative
' picture.Decorative = true;
End Using
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.
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"))
Consider the following shape and drawing object limitations:
See Also