Text Formatting
- 8 minutes to read
RichEditControl provides two ways to format document text.
-
Allows you to change individual formatting attributes for a given range.
-
Styles can change multiple attributes at the same time. Styles created in code are automatically available to end-users. If you change the style settings, all linked document fragments will be updated automatically.
Both approaches described above are available in API and in the User Interface.
Direct Formatting
To set the default character and paragraph formatting for a loaded or newly created document, use the following properties.
- Document.DefaultCharacterProperties - to access the default character format options.
- Document.DefaultParagraphProperties - to access the default paragraph format options.
The code snippet below illustrates how to apply default formatting to a loaded document.
private void RichEditControl1_DocumentLoaded(object sender, EventArgs e)
{
//Set the default font, size and forecolor
richEditControl.Document.DefaultCharacterProperties.FontName = "Arial";
richEditControl.Document.DefaultCharacterProperties.FontSize = 16;
richEditControl.Document.DefaultCharacterProperties.ForeColor = Color.Red;
//Specify the default alignment
richEditControl.Document.DefaultParagraphProperties.Alignment = ParagraphAlignment.Center;
richEditControl.Document.AppendText("Document created at " + DateTime.Now.ToLongTimeString());
}
To modify the document title as shown in the image below, use both character and paragraph formatting.
Format Characters
The following members allow you to change character formatting for a given range.
| Member | Description |
|---|---|
| SubDocument.BeginUpdateCharacters | Initiates the update session and provides access to CharacterProperties for the specified range. |
| CharacterProperties | Holds the character formatting options. |
| SubDocument.EndUpdateCharacters | Finalizes the character formatting update. |
The code sample below uses this API to modify the text color and the font type.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/text-formatting-simple-example-t456449.
'The target range is the first paragraph
Dim range As DocumentRange = document.Paragraphs(0).Range
'Provide access to the character properties
Dim titleFormatting As CharacterProperties = document.BeginUpdateCharacters(range)
'Set the character size, font name and color
titleFormatting.FontSize = 20
titleFormatting.FontName = "Helvetica"
titleFormatting.ForeColor = Color.DarkBlue
document.EndUpdateCharacters(titleFormatting)
Format Paragraphs
To change the title’s alignment, left indent or any other paragraph option, use the following API.
| Member | Description |
|---|---|
| SubDocument.BeginUpdateParagraphs | Initiates the update session and provides access to the ParagraphProperties for the specified range. |
| ParagraphProperties | Specifies the paragraph formatting properties. |
| SubDocument.EndUpdateParagraphs | Finalizes the character formatting update. |
Note
A complete sample project is available at https://github.com/DevExpress-Examples/text-formatting-simple-example-t456449.
'The target range is the first paragraph
Dim titleParagraph As DocumentRange = document.Paragraphs(0).Range
'Provide access to the paragraph options
Dim titleParagraphFormatting As ParagraphProperties = document.BeginUpdateParagraphs(titleParagraph)
'Set the paragraph alignment
titleParagraphFormatting.Alignment = ParagraphAlignment.Center
'Set left indent at 0.5".
'Default unit is 1/300 of an inch (a document unit).
titleParagraphFormatting.LeftIndent = Units.InchesToDocumentsF(0.5F)
titleParagraphFormatting.SpacingAfter = Units.InchesToDocumentsF(0.3F)
'Set tab stop at 1.5"
Dim tbiColl As TabInfoCollection = titleParagraphFormatting.BeginUpdateTabs(True)
Dim tbi As New TabInfo()
tbi.Alignment = TabAlignmentType.Center
tbi.Position = Units.InchesToDocumentsF(1.5F)
tbiColl.Add(tbi)
titleParagraphFormatting.EndUpdateTabs(tbiColl)
document.EndUpdateParagraphs(titleParagraphFormatting)
Document Styles
RichEditControl supports the use of two types of document styles: paragraph and character. The character style can be used if only the character options need to be modified. To change both character (a font type, size, color, etc.) and paragraph (alignment, spacing before and after, etc.) attributes as in the current example, use the paragraph style.
The image below demonstrates chapter titles modified using the paragraph style.
By default, RichEditControl doesn’t have any predefined document styles. To create a new document style, use the members from the table below.
Member | Description |
|---|---|
Opens the document for editing. | |
Provides access to the CharacterStyleCollection Provides access to the ParagraphStyleCollection. | |
Creates a new CharacterStyle object. Creates a new ParagraphStyle object. | |
Specifies the base style for the created instance. | |
Allows you to synchronize the character and paragraph styles to create a linked style. | |
Adds the created style to the collection. | |
Sets the style to the given paragraph. | |
Specifies the style to the given character range. | |
Finalizes style creation. |
The code sample below demonstrates how to create a new paragraph style and apply it to every chapter.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/text-formatting-simple-example-t456449.
'Open the document for editing
document.BeginUpdate()
'Create a new paragraph style instance
'and specify the required properties
Dim chapterStyle As ParagraphStyle = document.ParagraphStyles.CreateNew()
chapterStyle.Name = "MyTitleStyle"
chapterStyle.ForeColor = Color.SteelBlue
chapterStyle.FontSize = 16
chapterStyle.FontName = "Segoe UI Semilight"
chapterStyle.Alignment = ParagraphAlignment.Left
chapterStyle.SpacingBefore = Units.InchesToDocumentsF(0.2F)
chapterStyle.SpacingAfter = Units.InchesToDocumentsF(0.2F)
chapterStyle.OutlineLevel = 2
'Add the object to the document collection
document.ParagraphStyles.Add(chapterStyle)
'Finalize the editing
document.EndUpdate()
'Apply the created style to every chapter in the document
For i As Integer = 0 To document.Paragraphs.Count - 1
Dim var As String = document.GetText(document.Paragraphs(i).Range)
If var.Contains("Chapter ") Then
document.Paragraphs(i).Style = chapterStyle
End If
Next i
Return
If the loaded document already has document styles, they are automatically added to the document’s StyleCollection and you can use them as shown in the code snippet below.
//Apply style to the paragraph
richEditControl.Document.Paragraphs[1].Style = richEditControl.Document.ParagraphStyles["Heading 2"];
//Apply style to the character range
DocumentRange range = richEditControl.Document.Paragraphs[1].Range;
CharacterProperties rangeProperties = richEditControl.Document.BeginUpdateCharacters(range);
rangeProperties.Style = richEditControl.Document.CharacterStyles["Heading 2"];
richEditControl.Document.EndUpdateCharacters(rangeProperties);
Tip
To fill the collection of a newly created document with the predefined styles, load an empty document created in Microsoft® Word® using the Document.LoadDocument method in the RichEditControl.EmptyDocumentCreated event handler.
Linked Styles
To format the document annotation, use a linked style. A linked style carries both character and paragraph formatting rules, but applies them according to the target object. If the style is applied to the Paragraph instance, both formatting options will be applied. With the style applied to the DocumentRange instance, only character formatting is used.
The code sample below demonstrates how to synchronize a paragraph and character style to create a linked style.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/text-formatting-simple-example-t456449.
Dim annotationStyle As ParagraphStyle = document.ParagraphStyles("Annotation")
document.BeginUpdate()
'Create a new paragraph style
'and set the required settings
annotationStyle = document.ParagraphStyles.CreateNew()
annotationStyle.Name = "Annotation"
annotationStyle.Alignment = ParagraphAlignment.Right
annotationStyle.LineSpacingMultiplier = 1.5F
annotationStyle.FirstLineIndentType = ParagraphFirstLineIndent.Hanging
annotationStyle.FirstLineIndent = 3
document.ParagraphStyles.Add(annotationStyle)
'Create a new character style and link it
'to the custom paragraph style
Dim annotationCharStyle As CharacterStyle = document.CharacterStyles.CreateNew()
annotationCharStyle.Name = "AnnotationChar"
document.CharacterStyles.Add(annotationCharStyle)
annotationCharStyle.LinkedStyle = annotationStyle
'Specify the style options
annotationCharStyle.Italic = True
annotationCharStyle.FontSize = 12
annotationCharStyle.FontName = "Segoe UI"
annotationCharStyle.ForeColor = Color.Gray
document.EndUpdate()
'Apply the created style to the fisrt paragraph of the annotation
document.Paragraphs(1).Style = annotationStyle
'Apply the linked style to the range of the annotation's second paragraph
Dim annotationProperties As CharacterProperties = document.BeginUpdateCharacters(document.Paragraphs(2).Range)
annotationProperties.Style = annotationCharStyle
document.EndUpdateCharacters(annotationProperties)
The image below illustrates the result of the code execution.
Text Formatting In the User Interface
End-users can change the required format settings using the Font and Paragraph groups of the Home ribbon tab.
The Style Gallery allows end-users to preview and apply the desired document style to the selected text fragment.
To learn how to provide the application with the Ribbon Command UI, refer to the How to: Create a Simple Word Processor with a Ribbon UI topic.
Additionally, the Rich Text Editor application is provided with the following dialogs, which allow end-users to set the character and paragraph formatting options and manage the document styles.
You can prevent end-users from formatting the document. As a result, the corresponding ribbon buttons and the context menu items will be disabled or hidden.
The following members allow you to accomplish this task.
Member | Description |
|---|---|
Allows you to restrict end-users from direct formatting. | |
Allows you to disable using document styles at runtime. |