windowsforms-9333-controls-and-libraries-rich-text-editor-import-and-export.md
This document describes how to load and save documents in different formats.
End users can click the Open button on the File ribbon tab to invoke the Open dialog. Select the file you want to open and click Open.
The Save and Save As buttons on the File ribbon tab allow users to save the changes made to the current document or save it as a new file. Click the Save As button to invoke the Save As dialog used to save a copy as a new file, specify the document’s location, name, and format. Refer to the How to: Create the RichEditControl with a Ribbon UI for details on how to provide a ribbon UI for the RichEditControl.
The DocumentSaveOptions.CurrentFileName property returns the current document’s file name (including the path and extension).
Tip
You can prohibit end users from creating, loading or saving documents. Set the RichEditBehaviorOptions.CreateNew, RichEditBehaviorOptions.Open, RichEditBehaviorOptions.Save or RichEditBehaviorOptions.SaveAs property to DocumentCapability.Disabled to disable or hide the corresponding commands in the Ribbon UI and pop-up menu.
The RichEditControl provides the following methods to load or save the document and specify its options. Refer to the Files examples section for code samples.
| Member | Description |
|---|---|
| RichEditControl.LoadDocument | Loads a document from a file or stream. The document format can be specified by one of the DocumentFormat enumeration values or detected automatically. |
| RichEditControl.LoadDocumentTemplate | Loads a document template from the specified file or stream so that it cannot be overwritten automatically. |
| Document.LoadDocument | Loads a document from the specified file or stream. Its content can be specified by one of the DocumentFormat enumeration values or is automatically determined based on the file’s format. |
| SubDocument.InsertDocumentContent | Inserts content from the selected range into the current document at the specified position. |
| SubDocument.AppendDocumentContent | Appends content from the selected range. |
| RichEditControl.SaveDocument | Saves the control’s document to a file or stream and specifies the document’s format. |
| RichEditControl.SaveDocumentAs | Invokes the Save As dialog and saves a document. |
| Document.SaveDocument | Saves the document to a file or stream and specifies the document’s format. |
Note
The SaveDocumentCommand and SaveDocumentAsCommand execution sets the RichEditControl.Modified property to false. The RichEditControl.SaveDocument, RichEditControl.SaveDocumentAs or Document.SaveDocument method call does not automatically change the Modified property value.
The following code snippet loads the document from a file stream when the form is opened and saves the result to the file when the form is closed. Refer to the How to: Load a Document and How to: Save a Document examples for more code samples.
private void Form1_Load(object sender, EventArgs e)
{
using (Stream stream = new FileStream("FirstLook.docx", FileMode.Open))
{
richEditControl.LoadDocument(stream);
}
}
...
private void Form1_FormClosed(object sender, FormClosedEventArgs e)
{
richEditControl.SaveDocument("Result.docx", DocumentFormat.Docx);
}
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
Using stream As Stream = New FileStream("FirstLook.docx", FileMode.Open)
richEditControl.LoadDocument(stream)
End Using
End Sub
...
Private Sub Form1_FormClosed(ByVal sender As Object, ByVal e As FormClosedEventArgs)
richEditControl.SaveDocument("Result.docx", DocumentFormat.Docx)
End Sub
Note
We do not recommend that you use the DocumentFormat.Undefined field as the SaveDocument method parameter. Otherwise, the document is saved with invalid format.
The table below lists document formats the RichEditControl supports, and the API used to set format-specific import and export options. You can specify these options in the RichEditControl.BeforeImport or RichEditControl.BeforeExport event handlers.
Tip
Use the SubDocument‘s Get… methods to retrieve and format a part of the document. Refer to the Positions and Ranges topic for more information.
Tip
Check the Import and Export examples section for more information on how to accomplish an import- or export-related task.
The following code snippet handles RichEditControl.BeforeImport event for different document formats:
private void RichEditControl_BeforeImport(object sender, BeforeImportEventArgs e)
{
if (e.DocumentFormat == DocumentFormat.PlainText)
{
//Detect plain text encoding automatically:
((DevExpress.XtraRichEdit.Import.PlainTextDocumentImporterOptions)e.Options).AutoDetectEncoding = true;
}
if (e.DocumentFormat == DocumentFormat.Doc)
{
//Disable loading comments added to removed ranges in DOC documents
((DevExpress.XtraRichEdit.Import.DocDocumentImporterOptions)e.Options).KeepCommentsForRemovedRanges = false;
}
if (e.DocumentFormat == DocumentFormat.Html)
{
//Load images synchronously with HTML documents
((DevExpress.XtraRichEdit.Import.HtmlDocumentImporterOptions)e.Options).AsyncImageLoading = false;
}
}
Private Sub RichEditControl_BeforeImport(ByVal sender As Object, ByVal e As BeforeImportEventArgs)
If e.DocumentFormat = DocumentFormat.PlainText Then
'Detect plain text encoding automatically:
(CType(e.Options, DevExpress.XtraRichEdit.Import.PlainTextDocumentImporterOptions)).AutoDetectEncoding = True
End If
If e.DocumentFormat = DocumentFormat.Doc Then
'Disable loading comments added to removed ranges in DOC documents
(CType(e.Options, DevExpress.XtraRichEdit.Import.DocDocumentImporterOptions)).KeepCommentsForRemovedRanges = False
End If
If e.DocumentFormat = DocumentFormat.Html Then
'Load images synchronously with HTML documents
(CType(e.Options, DevExpress.XtraRichEdit.Import.HtmlDocumentImporterOptions)).AsyncImageLoading = False
End If
End Sub
The following code snippet specifies export options for different formats in the RichEditControl.BeforeExport event handler.
private void RichEditControl_BeforeExport(object sender, BeforeExportEventArgs e)
{
if (e.DocumentFormat == DocumentFormat.PlainText)
{
//Include document fields in the exported plain text:
PlainTextDocumentExporterOptions plainTextOptions = e.Options as PlainTextDocumentExporterOptions;
plainTextOptions.ExportHiddenText = true;
plainTextOptions.FieldCodeEndMarker = ">";
plainTextOptions.FieldCodeStartMarker = "[<";
plainTextOptions.FieldResultEndMarker = "]";
}
if (e.DocumentFormat == DocumentFormat.Docx)
{
//Specify what DOCX document properties to export:
OpenXmlDocumentExporterOptions docxOptions = e.Options as OpenXmlDocumentExporterOptions;
docxOptions.ExportedDocumentProperties = DocumentPropertyNames.Title | DocumentPropertyNames.LastModifiedBy | DocumentPropertyNames.Modified;
}
if (e.DocumentFormat == DocumentFormat.Html)
{
//Specify HTML export options:
HtmlDocumentExporterOptions htmlOptions = e.Options as HtmlDocumentExporterOptions;
htmlOptions.EmbedImages = true;
htmlOptions.CssPropertiesExportType = CssPropertiesExportType.Style;
htmlOptions.UseFontSubstitution = false;
}
}
Private Sub RichEditControl_BeforeExport(ByVal sender As Object, ByVal e As BeforeExportEventArgs)
If e.DocumentFormat = DocumentFormat.PlainText Then
'Include document fields in the exported plain text:
Dim plainTextOptions As PlainTextDocumentExporterOptions = TryCast(e.Options, PlainTextDocumentExporterOptions)
plainTextOptions.ExportHiddenText = True
plainTextOptions.FieldCodeEndMarker = ">"
plainTextOptions.FieldCodeStartMarker = "[<"
plainTextOptions.FieldResultEndMarker = "]"
End If
If e.DocumentFormat = DocumentFormat.Docx Then
'Specify what DOCX document properties to export:
Dim docxOptions As OpenXmlDocumentExporterOptions = TryCast(e.Options, OpenXmlDocumentExporterOptions)
docxOptions.ExportedDocumentProperties = DocumentPropertyNames.Title Or DocumentPropertyNames.LastModifiedBy Or DocumentPropertyNames.Modified
End If
If e.DocumentFormat = DocumentFormat.Html Then
'Specify HTML export options:
Dim htmlOptions As HtmlDocumentExporterOptions = TryCast(e.Options, HtmlDocumentExporterOptions)
htmlOptions.EmbedImages = True
htmlOptions.CssPropertiesExportType = CssPropertiesExportType.Style
htmlOptions.UseFontSubstitution = False
End If
End Sub
Control Document Elements
HTML Tag Support