Paragraph Class

A paragraph in a sub-document.

Namespace: DevExpress.Blazor.RichEdit

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

NuGet Package: DevExpress.Blazor.RichEdit

Declaration

public class Paragraph :
    DocumentElementBase,
    IParagraphProperties,
    IParagraphProperties

Remarks

A paragraph is a sub-document element that consists of characters, inline images, and/or floating objects, and ends with a paragraph mark (¶). A sub-document consists of at least one paragraph.

Run Demo: Rich Text Editor — Document API

The Rich Text Editor hides paragraph marks and other non-printable characters. Select the Home → Show/Hide ¶ ribbon command to show hidden document content.

The image below shows a main sub-document that contains four paragraphs.

Use the Paragraphs property to access methods that allow you to create and access paragraphs.

Paragraph Properties

Paragraph properties specify how the paragraph’s content is formatted. For instance, the Alignment property defines the paragraph alignment and the BackgroundColor property defines the background color.

The image below demonstrates how the following paragraph properties affect the layout of a paragraph: FirstLineIndent, LeftIndent, RightIndent, LineSpacing, SpacingAfter, SpacingBefore.

Change Paragraph Properties

Specify property values of a ParagraphProperties class instance and pass it to the ChangePropertiesAsync(Action<ParagraphProperties>, CancellationToken) method to change a paragraph’s properties. Alternatively, you can call the CopyFrom(Paragraph) method to copy properties from another paragraph.

The following example shows how you can access all paragraphs of the main sub-document and set their Alignment property to Justify:

<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;
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
            foreach (Paragraph p in paragraphs)
                await p.ChangePropertiesAsync(properties => {
                    if (p.Alignment != ParagraphAlignment.Justify)
                        properties.Alignment = ParagraphAlignment.Justify;
                });
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Create Paragraphs

Call a CreateAsync method to create a paragraph and append a paragraph mark to it.

The following code snippet creates five paragraphs that contain “New Paragraph” text in the main 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;
            for (int i = 0; i < 5; i++) {
                await documentAPI.AddTextAsync("New Paragraph");
                await documentAPI.Paragraphs.CreateAsync();
            }
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Access Paragraphs

Call the GetAsync(Int32, CancellationToken) method to access a paragraph by its index in a sub-document. To get all paragraphs a sub-document contains, call the GetAllAsync(CancellationToken) method.

The following example shows how to access the first paragraph and all paragraphs in the main 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;
            Paragraph firstParagraph = await documentAPI.Paragraphs.GetAsync(0);
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

The following example shows how to access the selected paragraph:

<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 {
        @* ... *@
            Document documentAPI = richEdit.DocumentAPI;
            Paragraph selectedParagraph;
            // Checks whether the main sub-document is active
            if (selection.ActiveSubDocument.Type == SubDocumentType.Main) {
                // Obtains all paragraphs in the main sub-document
                IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
                // Gets the caret position
                int caretPosition = selection.CaretPosition;
                for (int i = 0; i < paragraphs.Count; i++) {
                    // Gets the interval that contains the current paragraph
                    Interval interval = paragraphs[i].Interval;
                    // Checks whether the caret is within the current paragraph
                    if (interval.Start <= caretPosition & caretPosition <= interval.Start + interval.Length - 1) {
                        selectedParagraph = paragraphs[i];
                        break;
                    }
                }
            }
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Modify Paragraph Content

A paragraph’s Interval property allows you to get the interval in the sub-document where the paragraph is stored.

A paragraph can contain the following sub-document elements:

• Bookmarks
• Fields
• Hyperlinks
• Images
• Inline images

Refer to an element’s page for more information on how to create/delete the element.

Insert Text

Pass the paragraph interval’s position to the sub-document’s AddTextAsync(Int32, String, CancellationToken) method to insert text into the paragraph..

The following example inserts the paragraph’s serial number to the end of each paragraph in the main 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;
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
            Paragraph curParagraph;
            int position;
            for (int i = 0; i < paragraphs.Count; i++) {
                curParagraph = await documentAPI.Paragraphs.GetAsync(i);
                position = curParagraph.Interval.Start + curParagraph.Interval.Length - 1;
                await documentAPI.AddTextAsync(position, (i + 1).ToString());
            }
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Remove Text

Pass the paragraph’s subinterval to the sub-document’s RemoveAsync method to remove text from the paragraph.

The following example deletes the first 4 characters from each paragraph in the main 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;
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
            Paragraph currentParagraph;
            for (int i = 0; i < paragraphs.Count; i++) {
                currentParagraph = await documentAPI.Paragraphs.GetAsync(i);
                await documentAPI.RemoveAsync(currentParagraph.Interval.Start, 4);
            }
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

List Operations

A list in a document is a series of paragraphs. Each paragraph contains information about the list (ListIndex) and the list level (ListLevelIndex) to which it belongs.

The image below shows a list that consists of five paragraphs.

Add Paragraphs to a List

Call a paragraph’s AddToListAsync(List, Int32, CancellationToken) method to set the ListIndex and ListLevelIndex properties, apply a list format style to the paragraph, and add a paragraph to a list.

The following example creates a new list from the main sub-document’s paragraphs:

<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;
            List multiLevelList = await documentAPI.Lists.CreateAsync(ListType.MultiLevel);
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
            foreach (Paragraph p in paragraphs) {
                await p.AddToListAsync(multiLevelList, 0);
            }
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Remove Paragraphs from the List

Call the RemoveFromListAsync(CancellationToken) method to set the paragraph’s ListIndex and ListLevelIndex properties to null. This operation removes the list format style from the paragraph and removes the paragraph from the list.

The following example converts all list items into oridnary paragraphs:

<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;
            List multiLevelList = await documentAPI.Lists.CreateAsync(ListType.MultiLevel);
            IReadOnlyList<Paragraph> paragraphs = await documentAPI.Paragraphs.GetAllAsync();
            foreach (Paragraph p in paragraphs)
                if (p.ListIndex != null)
                    await p.RemoveFromListAsync();
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Delete Paragraphs

A paragraph’s Interval property allows you to get the interval that contains the paragraph. Pass the paragraph’s interval to the sub-document’s RemoveAsync(Interval, CancellationToken) method to delete the paragraph and its content.

The following example deletes the first paragraph of the main 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;
            Paragraph firstParagraph = await documentAPI.Paragraphs.GetAsync(0);
            await documentAPI.RemoveAsync(firstParagraph.Interval);
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Join Paragraphs

Paragraph marks (¶) divide a sub-document into paragraphs. If a user deletes a paragraph mark, the paragraph merges with the next paragraph’s content.

The following example deletes a paragraph mark at the end of the first paragraph and appends the second paragraph’s content to the first paragraph’s content:

<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;
            Paragraph firstParagraph = await documentAPI.Paragraphs.GetAsync(0);
            await documentAPI.RemoveAsync(firstParagraph.Interval.Start + firstParagraph.Interval.Length - 1, 1);
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

The Paragraph Dialog

The Rich Text Editor invokes this dialog when a user selects the Paragraph… context menu command. The Paragraph dialog allows users to change properties of the selected paragraphs.

Inheritance

Object

DocumentElementBase

Paragraph