OLE Objects in Rich Text Documents
- 9 minutes to read
OLE (Object Linking and Embedding) technology allows you to insert data (spreadsheets, images, presentations, charts, equations, etc.) from external applications into your document. You can load, create, extract, remove, print, and export OLE objects to PDF.
Important
The WinForms Rich Text Editor does not support OLE objects in OpenDocument Text (.odt) and encrypted DOC files.
OLE Objects in the User Interface
The WinForms Rich Text Editor ships with the Object dialog that allows users to insert OLE objects. Click the Object button on the Insert tab to invoke this dialog.
The Rich Text Editor displays OLE objects as images. You cannot modify embedded data or open files associated with OLE objects.
Access OLE Objects
OLE objects are stored in the SubDocument.Shapes collection. Use the ShapeCollection.Item property to return an OLE object from the collection. The Shape.Type property helps you distinguish between different drawing object types in the document.
The DrawingObject.OleFormat property returns the OLE object’s characteristics.
| Property | Description |
|---|---|
| OleFormat.InsertType | Indicates whether the OLE object is embedded in the document or linked to an external file. |
| OleFormat.ObjectRepresentation | Indicates how the OLE object is displayed in the document (as an image or an icon). |
| OleFormat.ProgId | Returns the content type associated with the OLE object. |
| OleFormat.SourceFileName | Returns a path to the source file associated with the linked OLE object. |
| OleFormat.AutoUpdate | Specifies whether to automatically update the OLE object with data from the linked file. |
| OleFormat.IsLocked | Specifies whether the linked OLE object can be updated. |
| OleFormat.OlePackage | Returns properties for the OLE object of the Package type. |
The following example retrieves all linked objects from the document:
using System.Linq;
// ...
Document document = richEditControl1.Document;
List<DrawingObject> linkedObjects = document.Shapes.Flatten()
.Where(x => x.Type == ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Linked)
.ToList();
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.
Document document = richEditControl1.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;
The WinForms Rich Text Editor displays the OLE object as an image. You cannot open the file associated with the 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.
Document document = richEditControl1.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;
}
The WinForms Rich Text Editor displays the OLE object as an image. You cannot modify the embedded data.
Display OLE Objects as Icons
Use the ShapeCollection.InsertOleObjectAsIcon method overloads to insert OLE objects as icons.
Document document = richEditControl1.Document;
// Insert an OLE object. Link it to an Excel worksheet.
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;
The WinForms Rich Text Editor displays the OLE object as an icon. You cannot open the file associated with the object.
Group OLE Objects
Call the ShapeCollection.InsertGroup method to create a shape group. The Shape.GroupItems property returns a collection of group elements. Use the collection’s AddOleObject and AddOleObjectAsIcon methods to add OLE objects to the group.
The following example groups two OLE objects:
Document document = richEditControl1.Document;
// Set measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Insert a shape group.
Shape group = document.Shapes.InsertGroup(document.Range.Start);
// Specify the group position relative to the left and top edges of the page.
group.Offset = new PointF(1f, 6f);
// Access the collection of group items.
var groupItems = group.GroupItems;
// Add the first OLE object to the group.
groupItems.AddOleObjectAsIcon(@"D:\ExcelWorkbook.xlsx", OleObjectType.ExcelWorksheet,
DocumentImageSource.FromFile(@"Images\Excel.ico"), new PointF(0f, 0f));
// Add the second OLE object to the group.
groupItems.AddOleObjectAsIcon(@"D:\PowerPointPresentation.pptx", OleObjectType.PowerPointPresentation,
DocumentImageSource.FromFile(@"Images\PowerPoint.ico"), new PointF(1.5f, 0f));
Change OLE Object Display Style
Use the OleFormat.ChangeRepresentation method to change how an existing OLE object is displayed in the document.
Document document = richEditControl1.Document;
// Insert an OLE object. Link it to an Excel worksheet.
// The OLE object is displayed in the document as an image.
Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
// Display the OLE object as an icon.
oleObject.OleFormat.ChangeRepresentation(OleObjectRepresentationType.Icon,
DocumentImageSource.FromFile(@"Images\Excel.ico"));
Retrieve Embedded Data
Extract Raw Data
Use the OleFormat.GetRawData method to retrieve an embedded OLE object’s data.
The following example loads spreadsheet data from a Word document into the Spreadsheet Document API component. You can modify and save this data to a file.
Important
You need a license to the DevExpress Office File API or DevExpress Universal Subscription to use this example in production code. Refer to the following page for pricing information: DevExpress Subscriptions.
using System.Linq;
using DevExpress.XtraRichEdit.API.Native;
// Add references to DevExpress.Docs.dll
// and DevExpress.Spreadsheet.Core.dll.
using DevExpress.Spreadsheet;
// ...
Document document = richEditControl1.Document;
// Obtain an OLE object that stores spreadsheet data.
DevExpress.XtraRichEdit.API.Native.Shape embeddedObject = document.Shapes.FirstOrDefault(
x => x.Type == DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Embedded &&
x.OleFormat.ProgId == OleObjectType.ExcelWorksheet);
if (embeddedObject != null)
{
// Retrieve data from the OLE object.
byte[] spreadsheetData = embeddedObject.OleFormat.GetRawData();
// Create a Workbook instance.
using (Workbook workbook = new Workbook()) {
// Load data into the workbook.
workbook.LoadDocument(spreadsheetData);
// Modify data.
// ...
// Save the document.
workbook.SaveDocument("ExcelDocument.xlsx", DevExpress.Spreadsheet.DocumentFormat.Xlsx);
}
}
Save Data to a File
Use the OleFormat.SaveAs method to save an embedded OLE object’s data to a file.
using System.Linq;
using DevExpress.XtraRichEdit.API.Native;
// ...
Document document = richEditControl1.Document;
// Obtain an OLE object that stores spreadsheet data.
DevExpress.XtraRichEdit.API.Native.Shape embeddedObject = document.Shapes.FirstOrDefault(
x => x.Type == DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Embedded &&
x.OleFormat.ProgId == OleObjectType.ExcelWorksheet);
if (embeddedObject != null)
{
// Save the OLE object's data as an XLSX document.
embeddedObject.OleFormat.SaveAs("ExcelDocument.xlsx");
}
Remove OLE Objects
Use one of the following methods to remove an OLE object from the document:
ShapeCollection.Remove - removes a specific object from the collection;
ShapeCollection.RemoveAt - removes an object with the specified index from the collection;
ShapeCollection.Clear - clears the shape collection.
The following example removes all OLE objects from the collection:
Document document = richEditControl1.Document;
ShapeCollection shapes = document.Shapes;
for (int i = shapes.Count - 1; i >= 0; i--)
{
if (shapes[i].Type == ShapeType.OleObject)
shapes.Remove(shapes[i]);
}