officefileapi-devexpress-dot-xtrarichedit-dot-api-dot-native-dot-subdocument-e69faedb.md
Returns the collection of drawing objects in the document.
Namespace : DevExpress.XtraRichEdit.API.Native
Assembly : DevExpress.RichEdit.v25.2.Core.dll
NuGet Package : DevExpress.RichEdit.Core
ShapeCollection Shapes { get; }
ReadOnly Property Shapes As ShapeCollection
| Type | Description |
|---|---|
| ShapeCollection |
The collection of Shape objects.
|
Use the ShapeCollection.InsertShape method overloads to add shapes to a document. A ShapeGeometryPreset enumeration member defines the shape’s geometry.
The example below 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 example below 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. Images imported from an HTML/MHT document are placed into the SubDocument.Images collection only.
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.
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 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.
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.
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.
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.
Use the ShapeCollection.InsertOleObjectAsIcon method overloads to insert OLE objects as icons.
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.
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
Call the ShapeCollection.InsertGroup method to create a shape group. The Shape.GroupItems property returns the collection of group elements. Use the collection’s Add methods to add nested groups, shapes, and pictures to the group.
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 the shape group into individual drawing objects.
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 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"))
The following code snippets (auto-collected from DevExpress Examples) contain references to the Shapes property.
Note
The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.
winforms-richedit-document-api/CS/RichEditAPISample/CodeExamples/Shapes.cs#L27
document.Unit = DevExpress.Office.DocumentUnit.Centimeter;
Shape myPicture = document.Shapes[1];
// Clear the qualitative positioning to allow positioning by specifying the numerical offset.
wpf-richedit-document-api/CS/DXRichEditControlAPISample/CodeExamples/ShapesActions.cs#L38
document.Unit = DevExpress.Office.DocumentUnit.Centimeter;
Shape myPicture = document.Shapes[1];
// Clear the qualitative positioning to allow positioning by specifying the numerical offset.
word-document-api-examples/CS/CodeExamples/ShapesActions.cs#L53
// Access a picture.
Shape myPicture = document.Shapes[1];
winforms-richedit-iterate-through-all-sub-documents/CS/SubDocumentHelper.cs#L16
subDocumentProcessor(document);
ProcessShapes(document.Shapes, subDocumentProcessor);
ProcessComments(document.Comments, subDocumentProcessor);
word-document-api-iterate-through-all-sub-documents/CS/SubDocumentHelper.cs#L16
subDocumentProcessor(document);
ProcessShapes(document.Shapes, subDocumentProcessor);
ProcessComments(document.Comments, subDocumentProcessor);
winforms-richedit-document-api/VB/RichEditAPISample/CodeExamples/Shapes.vb#L24
document.Unit = DevExpress.Office.DocumentUnit.Centimeter
Dim myPicture As DevExpress.XtraRichEdit.API.Native.Shape = document.Shapes(1)
' Clear the qualitative positioning to allow positioning by specifying the numerical offset.
wpf-richedit-document-api/VB/DXRichEditControlAPISample/CodeExamples/ShapesActions.vb#L31
document.Unit = DevExpress.Office.DocumentUnit.Centimeter
Dim myPicture As Shape = document.Shapes(1)
' Clear the qualitative positioning to allow positioning by specifying the numerical offset.
word-document-api-examples/VB/CodeExamples/ShapesActions.vb#L48
' Access a picture.
Dim myPicture As DevExpress.XtraRichEdit.API.Native.Shape = document.Shapes(1)
' Clear the horizontal and vertical alignment values.
winforms-richedit-iterate-through-all-sub-documents/VB/SubDocumentHelper.vb#L13
subDocumentProcessor(document)
ProcessShapes(document.Shapes, subDocumentProcessor)
ProcessComments(document.Comments, subDocumentProcessor)
word-document-api-iterate-through-all-sub-documents/VB/SubDocumentHelper.vb#L13
subDocumentProcessor(document)
ProcessShapes(document.Shapes, subDocumentProcessor)
ProcessComments(document.Comments, subDocumentProcessor)
See Also
Shapes, Pictures, and Other Graphic Objects in Word Documents