SubDocument Class

A sub-document in a document.

Namespace: DevExpress.Blazor.RichEdit

Assembly: DevExpress.Blazor.RichEdit.v24.2.dll

NuGet Package: DevExpress.Blazor.RichEdit

Declaration

public class SubDocument :
    IBatchUpdateHandler

Related API Members

The following members return SubDocument objects:

• ContentChangedEventArgs.SubDocument
• Selection.ActiveSubDocument

Remarks

Document content is divided into parts — sub-documents.

The DxRichEdit control supports the following sub-document types:

Main

Every document contains one main sub-document. Use the DocumentAPI property to access this sub-document.

<DxRichEdit @ref="richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Section firstSection = await documentAPI.Sections.GetAsync(0);
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Header and Footer

A document can contain multiple headers and footers for every section: different variants for odd/even pages and a specific version for the first page. To obtain a section’s header or footer, call the GetHeaderAsync or GetFooterAsync method, respectively.

<DxRichEdit @ref="richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Section section = await documentAPI.Sections.GetAsync(0);
            var footer = await section.GetFooterAsync(HeaderFooterType.Primary, true);
            await footer.AddTextAsync(DateTime.Now.Year.ToString());
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

TextBox

Each text box is an individual sub-document that can be placed in other sub-documents.

Use the Type property to identify a sub-document’s type.

Active Sub-Document

The sub-document to which the caret position belongs (or intervals of the current selection belong) is the active sub-document. Use the ActiveSubDocument property to get the active sub-document.

<DxRichEdit @bind-Selection="@selection" @ref="@richEdit" />

@code {
    DxRichEdit richEdit;
    Selection selection;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
        @* ... *@
            // Checks whether the main sub-document is active
            if (selection.ActiveSubDocument.Type == SubDocumentType.Main) {/*...*/}
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Structural Elements

A SubDocument object allows you to get information about structural elements that it contains. Use the following properties to access element collections:

• Bookmarks - provides access to a collection of Bookmark objects.
• Fields - provides access to a collection of Field objects.
• Hyperlinks - provides access to a collection of Hyperlink objects.
• Images - provides access to a collection of Image objects.
• InlineImages - provides access to a collection of InlineImage objects.
• Paragraphs - provides access to a collection of Paragraph objects.
• Tables - provides access to a collection of Table objects.

Work with Sub-Document Text

The SubDocument class implements methods that allow you to work with its text.

Add Text

Call an AddTextAsync method overload to add text to the sub-document.

await richEdit.DocumentAPI.AddTextAsync(0, "Ayn Rand was a Russian-American novelist...");

To add RTF text, call an AddRtfAsync method overload.

string path = @"C:\Temp\sample.rtf";
string rtfContent = File.ReadAllText(path);
await richEdit.DocumentAPI.AddRtfAsync(rtfContent);

To add HTML markup, call AddHtmlAsync method overloads.

string path = @"C:\Temp\html-sample.html";
string htmlContent = File.ReadAllText(path);
await richEdit.DocumentAPI.AddHtmlAsync(htmlContent);

Find Text

Call the FindAllAsync(String, Boolean, CancellationToken) method to find all matches of the specified text in the sub-document.

var DX_Intervals = await richEdit.DocumentAPI.FindAllAsync("DevExpress", true);

Get Element Text

Use the GetIntervalAsync(CancellationToken) method to access a sub-document’s interval that corresponds to the desired structural element (for example, the document header). Then pass the returned interval to the GetRtfAsync(Interval, CancellationToken) method to get the element’s RTF text.

Section section = await richEdit.DocumentAPI.Sections.GetAsync(0);
SubDocument header = await section.GetHeaderAsync();
Interval interval = await header.GetIntervalAsync();
string headerContent = await header.GetRtfAsync(interval);

To obtain HTML markup of the main sub-document, call GetHtmlAsync method overloads.

Interval interval = await document.GetIntervalAsync();
var htmlContent = await document.GetHtmlAsync(interval);
await File.WriteAllTextAsync(pathHtml, htmlContent);

Format Text

Call a GetTextSpanAsync method overload to get the text span placed within the specified interval. Then call the ChangePropertiesAsync(Action<CharacterProperties>, CancellationToken) method to customize properties of the text span’s characters.

// Applies bold formatting to characters in the selected intervals.
IReadOnlyList<Interval> intervals = selection.Intervals;
foreach (Interval interval in intervals) {
  TextSpan boldTextSpan = await richEdit.DocumentAPI.GetTextSpanAsync(interval);
  await boldTextSpan.ChangePropertiesAsync(properties => {
      properties.FontBold = true;
  });
}

Clear Formatting

The ChangeDefaultCharacterPropertiesAsync method allows you to change the document’s default character formatting. To reset character formatting in a sub-document or its interval to the default settings, call the sub-document’s ClearFormattingAsync method overload.

The following code snippet configures the default character formatting and applies it to a document once the document is loaded in the Rich Text Editor:

<DxRichEdit DocumentLoaded=OnDocumentLoaded/>

@code {
    async Task OnDocumentLoaded(Document document) {
        await document.ChangeDefaultCharacterPropertiesAsync(properties => {
            properties.FontName = "Times New Roman";
            properties.FontSize = 12;
        });
        await document.ClearFormattingAsync();
    }
}

Remove Text

Call a RemoveAsync method overload to remove the specified text interval.

firstParagraph = await documentAPI.Paragraphs.GetAsync(0);
await documentAPI.RemoveAsync(firstParagraph.Interval);

Implements

DevExpress.Utils.IBatchUpdateHandler

Inheritance

Object

SubDocument

Document