Paragraph Class
A paragraph in a sub-document.
Namespace: DevExpress.Blazor.RichEdit
Assembly: DevExpress.Blazor.RichEdit.v23.2.dll
NuGet Package: DevExpress.Blazor.RichEdit
Declaration
public class Paragraph :
DocumentElementBase,
IParagraphProperties,
IParagraphPropertiesRemarks
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.
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 code sample below 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:
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 shows how to delete 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.
