All docs
V21.1
21.2 (EAP/Beta)
21.1
20.2
20.1
The page you are viewing does not exist in version 20.1. This link will take you to the root page.
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

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.

Rich Text Editor - Insert OLE Object 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.

Insert a Linked 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.

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.

Insert an Embedded OLE Object

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.

Insert an OLE Object as an Icon

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));

Group OLE Objects

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:

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]);
}
See Also