When setting text in a TextBlock, you can also use an intuitive inner text form rather than an explicit Text property set, as in the following example:
<TextBlock>Hello, world!</TextBlock>
.gif) Note: |
|---|
Leading or trailing white space is not preserved when setting the Text property, only internal whitespace is preserved. For details on whitespace handling in XAML, see XAML Overview. |
Using the Run and LineBreak Objects
Rather than presenting a single string, a TextBlock can also present a series of strings contained in different Run elements, where each element can have different character-level font attributes. The LineBreak object represents an explicit new line in a TextBlock, and is generally used between surrounding Run elements. LineBreak and Run share a base class (Inline), which makes it possible for a TextBlock to hold a strongly typed InlineCollection of its text model content. That InlineCollection is also the TextBlock XAML content property, and the end result is that to specify items in the TextBlock model you simply specify various Run and LineBreak elements as child elements of the TextBlock.
The following XAML example shows how to define several differently formatted text strings in a TextBlock by using Run objects, separated with LineBreak.
<!-- Display formatted text as Run objects within a TextBlock. -->
<Canvas>
<TextBlock
FontFamily="Arial" Width="400" Text="Sample text formatting runs">
<LineBreak/>
<Run Foreground="Maroon" FontFamily="Courier New" FontSize="24">Courier New 24</Run>
<LineBreak/>
<Run Foreground="Teal" FontFamily="Times New Roman" FontSize="18" FontStyle="Italic">Times New Roman Italic 18</Run>
<LineBreak/>
<Run Foreground="SteelBlue" FontFamily="Verdana" FontSize="14" FontWeight="Bold">Verdana Bold 14</Run>
</TextBlock>
</Canvas>
The following illustration shows the rendered formatted text from the previous XAML content example.
TextBlock rendering multiple Run objects
.png)
LineBreak forces the text in each Run to display on a separate line. Without the LineBreak, the text in each Run would flow together as one line and would often be clipped due to exceeding the TextBlock object width or the width of the Silverlight content area. The following illustration shows how the formatted text would render without using LineBreak objects.
TextBlock rendering multiple Run objects without LineBreak objects
.png)
Accessing the TextBlock Text Model in Code
There are really two properties involved in the TextBlock text model: Text, and Inlines. Changing the value of Text is not always advisable, because it can flatten any existing font element formatting on the individual Run items as well as strip the LineBreak elements for a TextBlock that was originally constructed with inlines and not just Text. For details, see Inlines.
Wrapping Text
The TextWrapping property declares how text should wrap in a TextBlock. By default, text in a TextBlock does not wrap. With no wrapping, one of two things might happen to the text, depending on other settings:
If the TextBlock does not have an explicit Width set, the TextBlock expands based on the size of text within it, updating the value of ActualWidth. However, a TextBlock is always within some other container parent, and somewhere up the chain of layout parents there is inevitably a width constraint. This will result in the text being clipped if it exceeds the acting layout constraint width.
If the TextBlock has an explicit Width set, the TextBlock itself clips the text if it exceeds the fixed Width.
In order to use text wrapping, set TextWrapping to the enumeration value Wrap. For example, in XAML: <TextBlock Text="The quick red fox jumped over the lazy brown dog." TextWrapping="Wrap" />. With text wrapping on:
If the TextBlock does not have an explicit Width set, the text wraps at the acting layout constraint width.
If the TextBlock has an explicit Width set, the text wraps at the fixed Width.
You can detect clipped text programmatically because ActualWidth for a TextBlock always reports the expanded size of the text, even if it does not fit in the layout container. So long as you know where to read the Width for the layout container that is doing the clipping, you can compare these two values.
For more information, see TextBlock or TextWrapping.
TextBlock rendering non-wrapped and wrapped text
.png)
How TextWrapping affects ActualWidth and ActualHeight
.png)
Multiline TextBlock Text
Applying Transforms to TextBlock Text
Transforms can alter the display of text in your application. Transforms are a general UI element concept that can be applied to many different classes, including text elements. Transforms you might use for text and some possible scenarios for them include the following:
RotateTransform, to invert text
ScaleTransform, for larger text than the maximum size supported inherently in the font
SkewTransform, for shearing or italics simulation
TranslateTransform, for offsets and shadow effects
When you apply transforms to text, you should first consider whether there is another way to obtain the same or similar results using a specific text element property. For example, if a font family supports an italic FontStyle, the result is more visually appealing than applying a SkewTransform, or you would obtain better results setting FontSize and using the hinting and other characteristics enabled by the font than you would by setting a ScaleTransform on the text.
One scenario where you might use transforms on text is so that you can animate the transform, for a visual effect.
Animating TextBlock Text
The value of many text properties can be animated including the text size of FontSize, position through a TranslateTransform, and color. See Animation Overview for more information on which property value types support animation.
Animating properties of text (particularly size or the foreground brush) can potentially use a lot of system resources. This is because when Silverlight renders text, it uses hinting to smooth each text glyph. If you animate the text size (by using a Transform or FontSize), Silverlight will hint the glyphs for each frame, which is costly and could cause frame dropping. If your application requires dynamic scale changes of large text, it may be better to use one of the following two alternatives: