RadDocumentEditor
RadDocument has API of its own, but using it has a set of limitations. First of all, adding and removing Blocks and Inlines from the document can be done only before the document has been measured – a procedure that calculates the desired size of the spans, paragraphs and the document altogether in order to calculate its layout. These operations are usually invoked by the framework when the document in shown in a RadRichTextEditor. However, some of the methods of RadDocument and RadRichTextEditor require that the document is measured before their execution, so if such a method is invoked, the document will be measured. Then, adding Paragraphs, Tables, Sections and Spans will break the structure of the document.
Another issue that the use of the methods of RadDocument causes is due to the fact that they are not registered in the undo/redo stack. Thus, once such a method is used, the history stack is cleared and users will no longer be able to undo and redo their previous changes.
What is RadDocumentEditor
On the other hand, RadRichTextEditor provides a much richer API for editing the RadDocument instance in it. All respective methods from that API are located in the IDocumentEditor interface which defines all method that edit fields, annotation ranges, document elements, history, headers and footers and so on and is inherited from RadRichTextEditor. In that regard, if you are modifying the document in a class that knows of the existence of RadRichTextEditor, you can use the methods of RadRichTextEditor in order to manipulate the document in a way transparent to the end user.
The appropriate API, however, should be available in cases when you want to modify a document from code without having a RadRichTextEditor. For this purpose, a RadDocumentEditor class has been introduced. It also implements the IDocumentEditor interface and includes all relevant methods of RadRichTextEditor for manipulating the document programmatically.
How to use RadDocumentEditor
When a RadDocument instance was for some reason created from code – built using the elements hierarchy or imported, it can be passed to a RadDocumentEditor like this:
RadDocumentEditor documentEditor = new RadDocumentEditor(this.radRichTextEditor1.Document);
Dim documentEditor As New RadDocumentEditor(Me.radRichTextEditor1.Document)
The newly created documentEditor instance now provides all capabilities that a RadRichTextEditor provides. Moreover, you can group several methods so that they are added to the Undo/Redo stack as a single item. This can be achieved like this:
documentEditor.BeginUndoGroup();
if (documentEditor.Document.CaretPosition.IsPositionInsideTable)
{
documentEditor.InsertTableRow();
documentEditor.InsertTableRow();
documentEditor.InsertTableRow();
documentEditor.Document.Selection.Clear();
}
documentEditor.EndUndoGroup("Insert three table rows");
documentEditor.BeginUndoGroup()
If documentEditor.Document.CaretPosition.IsPositionInsideTable Then
documentEditor.InsertTableRow()
documentEditor.InsertTableRow()
documentEditor.InsertTableRow()
documentEditor.Document.Selection.Clear()
End If
documentEditor.EndUndoGroup("Insert three table rows")
You can also cancel the execution of the undo group, and it won't be recorded in the history:
documentEditor.BeginUndoGroup();
if (documentEditor.Document.CaretPosition.IsPositionInsideTable)
{
documentEditor.InsertTableRow();
documentEditor.InsertTableRow();
documentEditor.InsertTableRow();
documentEditor.Document.Selection.Clear();
}
documentEditor.CancelUndoGroup();
documentEditor.BeginUndoGroup()
If documentEditor.Document.CaretPosition.IsPositionInsideTable Then
documentEditor.InsertTableRow()
documentEditor.InsertTableRow()
documentEditor.InsertTableRow()
documentEditor.Document.Selection.Clear()
End If
documentEditor.CancelUndoGroup()
One thing to note here is that it is not possible to remove some actions from the undo history altogether, i.e. you cannot perform an action without it getting registered in the Undo/Redo stack. In most cases, however, this is sufficient, as you can group the operations that you do not want to name and show explicitly to the end user with the ones that have been user-initiated and are expected by the person modifying the content of RadRichTextEditor.