ShapeCollection Interface
A collection of drawing objects (shapes, pictures, text boxes, charts, watermarks, OLE objects, and ActiveX controls).
Namespace: DevExpress.XtraRichEdit.API.Native
Assembly: DevExpress.RichEdit.v24.2.Core.dll
NuGet Package: DevExpress.RichEdit.Core
Declaration
[ComVisible(true)]
public interface ShapeCollection :
ReadOnlyShapeCollection,
ISimpleCollection<Shape>,
IEnumerable<Shape>,
IEnumerable,
ICollectionRelated API Members
The following members return ShapeCollection objects:
Remarks
Insert Drawing Objects
Shapes
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;
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.
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;
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.
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.
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);
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.
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;
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.
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;
}
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.
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;
Open the document in Microsoft® Word® and double-click the icon to open the file associated with the OLE object.
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.
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;
Shape Group
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;
Use the Shape.GroupItems.Ungroup method to split the shape group into individual drawing objects.
Access 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"];
Tip
Use the ReadOnlyShapeCollection.Get method to retrieve all shapes from the specified document range.
Remove Drawing Objects
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"]);