OLE Objects
- 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. Use the Word Processing Document API to load, add, extract, or remove OLE objects. You can print documents with OLE objects and export them to PDF.
Important
The Word Processing Document API does not support OLE objects in OpenDocument Text (.odt) and encrypted DOC files.
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 = wordProcessor.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. 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.
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 = wordProcessor.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 = wordProcessor.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 = wordProcessor.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 = wordProcessor.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 = wordProcessor.Document;
ShapeCollection shapes = document.Shapes;
for (int i = shapes.Count - 1; i >= 0; i--)
{
if (shapes[i].Type == ShapeType.OleObject)
shapes.Remove(shapes[i]);
}