Skip to content

Latest commit

 

History

History
196 lines (140 loc) · 11.7 KB

richtextblock.md

File metadata and controls

196 lines (140 loc) · 11.7 KB
Raw
-api-id -api-type
T:Microsoft.UI.Xaml.Controls.RichTextBlock
winrt class

Microsoft.UI.Xaml.Controls.RichTextBlock

-description

Represents a rich text display container that supports formatted text, hyperlinks, inline images, and other rich content. RichTextBlock supports a built-in overflow model.

-xaml-syntax

<RichTextBlock .../>
-or-
<RichTextBlock ...>
  blocksContent
</RichTextBlock>

-remarks

Tip

For more info, design guidance, and code examples, see Rich text block.

The RichTextBlock control displays read-only text, and provides several features for advanced text layout. Use a RichTextBlock when you need support for paragraphs, inline UI elements, or overflow text.

TextBlock provides a simpler content model, so it's typically easier to use, and it can provide better text rendering performance than RichTextBlock. It also provides many of the same formatting options for customizing how your text is rendered. However, RichTextBlock provides several unique features that TextBlock doesn't provide.

For more info and examples, see the RichTextBlock control guide.

Paragraphs and formatting

The content property of RichTextBlock is the Blocks property, which is based on the Paragraph element. Set the indentation for paragraphs by setting the TextIndent property.

You can use text elements and the attached properties of the Typography class to apply character and paragraph formatting to the text in the RichTextBlock. For example, you can apply Bold, Italic, and Underline to any portion of the text in the control.

Inline UI elements

You can use an InlineUIContainer in the content of a RichTextBlock to embed elements that are derived from UIElement, such as images, in your text.

Overflow content

You can use a RichTextBlock with RichTextBlockOverflow elements to create advanced page layouts, such as multi-column text. The content for a RichTextBlockOverflow element always comes from a RichTextBlock element. You link RichTextBlockOverflow elements by setting them as the OverflowContentTarget of a RichTextBlock or another RichTextBlockOverflow.

Font fallback

The default FontFamily for RichTextBlock is Segoe UI and the default FontSize is 15 device-independent pixel (DIP). By default, RichTextBlock utilizes a font fallback mechanism to show glyphs that are not included in the specified font. If the glyph that is needed in a RichTextBlock is not available in the specified font, the font fallback mechanism goes through a list of fonts on the system to try and display the required characters in a different font.

-examples

Tip

For more info, design guidance, and code examples, see Rich text block.

[!div class="nextstepaction"] Open the WinUI 3 Gallery app and see the RichTextBlock in action

The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub

This example shows a RichTextBlock with text selection and text wrapping enabled.

In XAML, the creation of content elements is implicit, so you can add the text directly to the Paragraph element, and the Paragraph directly to the RichTextBlock element.

In code, you have to explicitly create each Run element, set its Text property, and add it to the Paragraph.Inlines collection. Then, add each Paragraph to the RichTextBlock.Blocks collection.

<RichTextBlock IsTextSelectionEnabled="True" TextWrapping="Wrap" Width="200" >
    <Paragraph>
        This is some sample text to show the wrapping behavior.
    </Paragraph>
</RichTextBlock>
// Create a RichTextBlock, a Paragraph and a Run.
RichTextBlock richTextBlock = new RichTextBlock();
Paragraph paragraph = new Paragraph();
Run run = new Run();

// Customize some properties on the RichTextBlock.
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.TextWrapping = TextWrapping.Wrap;
run.Text = "This is some sample text to show the wrapping behavior.";
richTextBlock.Width = 200;

// Add the Run to the Paragraph, the Paragraph to the RichTextBlock.
paragraph.Inlines.Add(run);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

This example shows a RichTextBlock with customization of FontWeight, FontFamily, FontStyle, Foreground, and SelectionHighlightColor for a single run of text.

In XAML, the creation of content elements is implicit, so you can add the text directly to the Paragraph element, and the Paragraph directly to the RichTextBlock element.

In code, you have to explicitly create each Run element, set its Text property, and add it to the Paragraph.Inlines collection. Then, add each Paragraph to the RichTextBlock.Blocks collection.

<RichTextBlock IsTextSelectionEnabled="True" SelectionHighlightColor="Pink" 
               FontWeight="Light" FontFamily="Arial" FontStyle="Italic" 
               Foreground="Blue">
    <Paragraph>
        This is some sample text to demonstrate some properties.
    </Paragraph>
</RichTextBlock>
// Create a RichTextBlock, a Paragraph and a Run.
RichTextBlock richTextBlock = new RichTextBlock();
Paragraph paragraph = new Paragraph();
Run run = new Run();

// Customize some properties on the RichTextBlock.
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.SelectionHighlightColor = new SolidColorBrush(Colors.Pink);
richTextBlock.Foreground = new SolidColorBrush(Colors.Blue);
richTextBlock.FontWeight = FontWeights.Light;
richTextBlock.FontFamily = new FontFamily("Arial");
richTextBlock.FontStyle = Windows.UI.Text.FontStyle.Italic;
run.Text = "This is some sample text to demonstrate some properties.";

//Add the Run to the Paragraph, the Paragraph to the RichTextBlock.
paragraph.Inlines.Add(run);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

This example shows a RichTextBlock with customization of FontWeight, FontFamily, FontStyle, Foreground, and SelectionHighlightColor for different runs of text.

In XAML, the creation of content elements is implicit, so you can add the text directly to the Paragraph element, and the Paragraph directly to the RichTextBlock element.

In code, you have to explicitly create each Run element, set its Text property, and add it to the Paragraph.Inlines collection. Then, add each Paragraph to the RichTextBlock.Blocks collection.

<RichTextBlock IsTextSelectionEnabled="True" SelectionHighlightColor="Pink" FontFamily="Arial"  >
    <Paragraph>
        <Run Foreground="Blue" FontWeight="Light" Text="This is some" ></Run>
        <Span FontWeight="SemiBold">
            <Run FontStyle="Italic">sample text to</Run>
            <Run Foreground="Red">demonstrate some properties.</Run>
        </Span>
    </Paragraph>
</RichTextBlock>
RichTextBlock richTextBlock = new RichTextBlock();
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.SelectionHighlightColor = new SolidColorBrush(Colors.Pink);
richTextBlock.FontFamily = new FontFamily("Arial");

Paragraph paragraph = new Paragraph();
Run run = new Run();
run.Foreground = new SolidColorBrush(Colors.Blue);
run.FontWeight = FontWeights.Light;
run.Text = "This is some";

Span span = new Span();
span.FontWeight = FontWeights.SemiBold;

Run run1 = new Run();
run1.FontStyle = Windows.UI.Text.FontStyle.Italic;
run1.Text = " sample text to ";

Run run2 = new Run();
run2.Foreground = new SolidColorBrush(Colors.Red);
run2.Text = "demonstrate some properties.";

span.Inlines.Add(run1);
span.Inlines.Add(run2);
paragraph.Inlines.Add(run);
paragraph.Inlines.Add(span);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

Here, a RichTextBlock targets a RichTextBlockOverflow element to create a multi-column text layout. The first RichTextBlockOverflow element then targets a second RichTextBlockOverflow element that receives its content overflow. The controlling layout factor for how the text overflow is calculated is the constrained Width and Height of the parent Grid, and the ColumnDefinition settings that divide the Grid into three equal columns of 300 pixels height/width. Overflow is also affected by FontSize and many other text formatting properties that change characters in the text.

[!code-xamlRichTextOverflow]

-see-also

Rich text block overview, Paragraph, OverflowContentTarget, RichTextBlockOverflow, RichTextBlockOverflow.OverflowContentTarget, XAML text display sample