In this article

11/17/2011

15 minutes to read

In this article

RichTextBox Overview

RichTextBox is a control that enables you to display or edit rich content including paragraphs, hyperlinks, and inline images. This topic introduces the RichTextBox control, describes some of its features, and shows examples of how to use it in XAML and code.

This topic contains the following sections.

TextBlock, TextBox, or RichTextBox

Content Model

Creating a RichTextBox

Hyperlinks

Inline Images or Other Elements

Read-Only Mode

Traversing the Content

Selecting and Formatting Text at Run Time

XAML

Undo

Related Topics

TextBlock, TextBox, or RichTextBox

Silverlight includes three core text controls: TextBlock, TextBox, and RichTextBox. The text control that you use depends on the scenario. The following table lists some scenarios and the recommended control.

Block Elements

Paragraph is used to group content into a paragraph. The simplest and most common use of Paragraph is to create a paragraph of text. A Paragraph can also contain inline elements.

Inline Elements

Inline elements are classes that inherit from Inline, An inline element is either contained within a block element or another inline element. Inline elements are often used as the direct container of content that is rendered to the screen. For example, a Paragraph (block element) can contain Run (inline element), but the Run actually contains the text that is rendered on the screen. Content in each Paragraph element can contain many types of elements including the following:

Span groups other inline content elements together. No inherent rendering is applied to content within a Span element. That is, content is not formatted if it is placed inside a Span element without any attributes. However, elements that inherit from Span, such as Hyperlink, Bold, Italic, and Underline apply formatting to text.

'A RichTextBox with intial content in it.
Private Sub ContentRTB()
'Create a new RichTextBox with its VerticalScrollBarVisibility property set to Auto.
Dim MyRTB As New RichTextBox()
MyRTB.VerticalScrollBarVisibility = ScrollBarVisibility.Auto
' Create a Run of plain text and some bold text.
Dim myRun1 As New Run()
myRun1.Text = "A RichTextBox with "
Dim myBold As New Bold()
myBold.Inlines.Add("initial content ")
Dim myRun2 As New Run()
myRun2.Text = "in it."
' Create a paragraph and add the Run and Bold to it.
Dim myParagraph As New Paragraph()
myParagraph.Inlines.Add(myRun1)
myParagraph.Inlines.Add(myBold)
myParagraph.Inlines.Add(myRun2)
' Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph)
'Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB)
End Sub

//A RichTextBox with intial content in it.
private void ContentRTB()
{
//Create a new RichTextBox with its VerticalScrollBarVisibility property set to Auto.
RichTextBox MyRTB = new RichTextBox();
MyRTB.VerticalScrollBarVisibility = ScrollBarVisibility.Auto;
// Create a Run of plain text and some bold text.
Run myRun1 = new Run();
myRun1.Text = "A RichTextBox with ";
Bold myBold = new Bold();
myBold.Inlines.Add("initial content ");
Run myRun2 = new Run();
myRun2.Text = "in it.";
// Create a paragraph and add the Run and Bold to it.
Paragraph myParagraph = new Paragraph();
myParagraph.Inlines.Add(myRun1);
myParagraph.Inlines.Add(myBold);
myParagraph.Inlines.Add(myRun2);
// Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph);
//Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB);
}

'A RichTextBox with hyperlink.
Private Sub HyperlinkRTB()
'Create a new RichTextBox.
Dim MyRTB As New RichTextBox()
' Create a Run of plain text and hyperlink.
Dim myRun As New Run()
myRun.Text = "Displaying text with "
Dim MyLink As New Hyperlink()
MyLink.Inlines.Add("hyperlink")
MyLink.NavigateUri = New Uri("http://www.msdn.com")
MyLink.TargetName = "_blank"
' Create a paragraph and add the Run and hyperlink to it.
Dim myParagraph As New Paragraph()
myParagraph.Inlines.Add(myRun)
myParagraph.Inlines.Add(MyLink)
' Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph)
'Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB)
End Sub

//A RichTextBox with hyperlink.
private void HyperlinkRTB()
{
//Create a new RichTextBox.
RichTextBox MyRTB = new RichTextBox();
// Create a Run of plain text and hyperlink.
Run myRun = new Run();
myRun.Text = "Displaying text with ";
Hyperlink MyLink = new Hyperlink();
MyLink.Inlines.Add("hyperlink");
MyLink.NavigateUri = new Uri("http://www.msdn.com");
MyLink.TargetName = "_blank";
// Create a paragraph and add the Run and hyperlink to it.
Paragraph myParagraph = new Paragraph();
myParagraph.Inlines.Add(myRun);
myParagraph.Inlines.Add(MyLink);
// Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph);
//Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB);
}

Inline Images or Other Elements

You can display a UIElement, such as an Image or a Button, in a RichTextBox. This enables rich text scenarios, such as displaying content from a chat client and showing emoticons. UI elements are active when the RichTextBox is in read-only mode and inactive in edit mode. For example, they can respond to input and receive focus only when they are in read-only mode. Use the InlineUIContainer tag to add content that is derived from UIElement.

The following shows how to add an image to a RichTextBox in XAML and code.

'A RichTextBox with an image.
Private Sub ImageRTB()
'Create a new RichTextBox.
Dim MyRTB As New RichTextBox()
' Create a Run of plain text and image.
Dim myRun As New Run()
myRun.Text = "Displaying text with inline image"
Dim MyImage As New Image()
MyImage.Source = New BitmapImage(New Uri("flower.jpg", UriKind.RelativeOrAbsolute))
MyImage.Height = 50
MyImage.Width = 50
Dim MyUI As New InlineUIContainer()
MyUI.Child = MyImage
' Create a paragraph and add the paragraph to the RichTextBox.
Dim myParagraph As New Paragraph()
MyRTB.Blocks.Add(myParagraph)
' Add the Run and image to it.
myParagraph.Inlines.Add(myRun)
myParagraph.Inlines.Add(MyUI)
'Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB)
End Sub

Read-Only Mode

RichTextBox has a read-only mode. You can display rich content in read-only mode. UI elements and hyperlinks in a RichTextBox are active only in read-only mode. For example, they can respond to input and receive focus only when they are in read-only mode. You specify read-only mode by setting the IsReadOnly property of RichTextBox to true. The following shows how to set the IsReadOnly property in XAML and code.

Private Sub ReadOnlyRTB()
'Create a new RichTextBox.
Dim MyRTB As RichTextBox = New RichTextBox
' Create a Run of plain text and hyperlink.
Dim myRun As Run = New Run
myRun.Text = " are enabled in a read-only RichTextBox."
Dim MyLink As Hyperlink = New Hyperlink
MyLink.Inlines.Add("Hyperlinks")
MyLink.NavigateUri = New Uri("http://www.msdn.com")
MyLink.TargetName = "_blank"
' Create a paragraph and add the Run and hyperlink to it.
Dim myParagraph As Paragraph = New Paragraph
myParagraph.Inlines.Add(MyLink)
myParagraph.Inlines.Add(myRun)
' Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph)
'Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB)
End Sub

private void ReadOnlyRTB()
{
//Create a new RichTextBox.
RichTextBox MyRTB = new RichTextBox();
// Create a Run of plain text and hyperlink.
Run myRun = new Run();
myRun.Text = " are enabled in a read-only RichTextBox.";
Hyperlink MyLink = new Hyperlink();
MyLink.Inlines.Add("Hyperlinks");
MyLink.NavigateUri = new Uri("http://www.msdn.com");
MyLink.TargetName = "_blank";
// Create a paragraph and add the Run and hyperlink to it.
Paragraph myParagraph = new Paragraph();
myParagraph.Inlines.Add(MyLink);
myParagraph.Inlines.Add(myRun);
// Add the paragraph to the RichTextBox.
MyRTB.Blocks.Add(myParagraph);
//Add the RichTextBox to the StackPanel.
MySP.Children.Add(MyRTB);
}

Traversing the Content

You can traverse the content in a RichTextBox by using the TextPointer class and its members. A TextPointer object represents a position in the content of a RichTextBox. The position can either occur between characters in the content, or between the element tags that define the structure for the content. If the position occurs between the characters in the content, then it becomes an insertion position. That is, new content can be added in that position without breaking any semantic rules for the associated content. In practice, an insertion position is anywhere in content where a cursor may be positioned. In most cases, if the position occurs between the element tags that define the structure of the content, then the position is not an insertion position. An example of a valid TextPointer position that is not an insertion position is the position between two adjacent paragraph tags (that is, between the closing tag of the preceding paragraph and the opening tag of the next paragraph).

Some of the operations that you can do by using the TextPointer class include the following:

Perform an ordinal comparison of the current position with a second specified position. For more information, see the CompareTo method.

A more common scenario would be where you select a portion of the content and then you apply formatting to the selection. A selection of text in the RichTextBox is represented by the TextSelection class. You can access the currently selected text in the RichTextBox by using its Selection property. To perform operations on the selected text, you can use the GetPropertyValue and ApplyPropertyValue methods. The following example shows how to apply bold, italic, and underline formatting to the selected text.

It is also possible to select text programmatically. You can select text in a RichTextBox programmatically by using the Select method. The Select method takes two TextPointer objects as parameters and selects the texts between the two objects. The following code example uses the Select method to programmatically select the last word in a RichTextBox and underline it. In this example, a space character is used as the word boundary. This code example is a part of the larger example used in the TextPointer class.

The following code shows how the XAML is displayed by using the Xaml property.

'Set the xamlTb TextBox with the current XAML of the RichTextBox and make it visible. Any changes to the XAML made
'in xamlTb is also reflected back on the RichTextBox. Note that the Xaml string returned by RichTextBox.Xaml will
'not include any UIElement contained in the current RichTextBox. Hence the UIElements will be lost when you
'set the Xaml back again from the xamlTb to the RichTextBox.
Public Sub btnMarkUp_Checked(ByVal sender As Object, ByVal e As RoutedEventArgs)
If btnMarkUp.IsChecked.Value Then
xamlTb.Visibility = System.Windows.Visibility.Visible
xamlTb.IsTabStop = True
xamlTb.Text = rtb.Xaml
Else
rtb.Xaml = xamlTb.Text
xamlTb.Visibility = System.Windows.Visibility.Collapsed
xamlTb.IsTabStop = False
End If
End Sub

//Set the xamlTb TextBox with the current XAML of the RichTextBox and make it visible. Any changes to the XAML made
//in xamlTb is also reflected back on the RichTextBox. Note that the Xaml string returned by RichTextBox.Xaml will
//not include any UIElement contained in the current RichTextBox. Hence the UIElements will be lost when we
//set the Xaml back again from the xamlTb to the RichTextBox.
public void btnMarkUp_Checked(object sender, RoutedEventArgs e)
{
if (btnMarkUp.IsChecked.Value)
{
xamlTb.Visibility = System.Windows.Visibility.Visible;
xamlTb.IsTabStop = true;
xamlTb.Text = rtb.Xaml;
}
else
{
rtb.Xaml = xamlTb.Text;
xamlTb.Visibility = System.Windows.Visibility.Collapsed;
xamlTb.IsTabStop = false;
}
}

Undo

RichTextBox supports the ability to perform multiple undo operations in response to user actions. In addition, an undo operation can also be reversed, which is called redo. When an undo or redo operation is performed, RichTextBox attempts to set the selection state based on the undo or redo operation.

Undo is supported only if the IsReadOnly property for a RichTextBox is false. Also, programmatic undo operation is not supported.