Text and Fonts

The TextBlock object is the primary element for displaying read-only text in Silverlight-based applications. The following XAML shows how to define a TextBlock element and set its Text property to a string.

<TextBlock Text="Hello, world!" />

The following illustration displays the result of the previous XAML.

TextBlock also supports a basic text model for its content, which is discussed in the "TextBlock Text Model" section of this topic.

TextBlock is not the only Silverlight UI element that directly displays text. RichTextBlock, TextBox, PasswordBox, and RichTextBox are also text elements. These classes derive from the Control class, which implements a number of properties that are relevant to text and fonts. However, it is not always true that a class that derives from Control is capable of displaying text, or even supports a content model that can contain a text element. The following is a list of the relevant text and font properties that are implemented on the Control class:

Control.FontFamily

Control.FontSize

Control.FontStretch

Control.FontStyle

Control.FontWeight

Also, although not exclusively used as a font property, Foreground supplies the Brush for the displayed text in Silverlight text elements.

One reason why the text and font properties are implemented at the level of Control is so that controls can support property value inheritance for font properties. This makes it possible to define a control with composite parts that come from a template, and to have the font properties of the parent control apply to any of the composite parts or content that display text strings.

For example, a ComboBox is an items control that might display other elements, or might display text. If you set font properties on ComboBox, the font properties are automatically inherited by the other elements or by the displayed text (without requiring any special handling by the control's logic). For displayed text, inheritance of font properties is particularly useful because there would not be a way to apply attributes to that text. Composite parts and text content in a custom control can inherit its Control-based font properties in exactly the same way.

Property inheritance of font properties works when the composite part is a TextBlock. This is true even though TextBlock is not technically a control and does not share the property implementations with its parent. That is one reason why the font properties between controls and TextBlock are parallel.

If you set text element properties through a Style or an applied template, child elements inherit the properties at run time. Run-time changes to text element properties also propagate their new values to inheriting child text elements.

The font that you specify may not necessarily be the font that Silverlight uses. Silverlight chooses the font from the supported local fonts, from the fonts provided in a packaged file referenced in the FontFamily property, or from the stream-based zip or .ttf file passed to the FontSource property. The displayed result is the best match based on the values of the FontFamily, FontStretch, FontStyle, and FontWeight properties. It is important to specify all four of these font properties to make sure that an accurate and consistent font selection is made for your text element.

Silverlight does not include any fonts in its installation package, it relies on local system fonts for its defaults. If you want to use a font for a text element that is not on the list of supported local fonts, you can specify the font in XAML by using the FontFamily property, or in code using the FontSource property. The FontFamily property can specify a single font file or a zip file containing font files, and can incorporate a fallback sequence. Any font file referenced for a XAML FontFamily usage must be embedded within an assembly as a resource. When using FontSource, your code can load the source font file for the font (or a zip of fonts) from a stream such as isolated storage, or from XAP packaging.

For more information, see the relevant class pages: FontFamily and FontSource.

Instead of displaying a single string, a TextBlock can also display a series of strings contained in different Run elements, where each element can have different character-level formatting. 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 shows how to define several strings in a TextBlock with different formatting by using Run objects, separated with LineBreak objects.

<!-- 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.

TextBlock rendering multiple Run objects

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.

There are really two properties involved in the TextBlock text model: Text, and Inlines. Changing the value of Text at run time is not recommended, 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 more information, see Inlines.

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.

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" />.

Text wrapping exhibits the following behavior:

• 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. If you know where to read the Width for the layout container that is doing the clipping, you can compare these two values.

The following illustrations show text wrapping behavior.

For more information, see TextBlock or TextWrapping.

Either due to wrapping or to explicit LineBreak elements, the text in a TextBlock is potentially multiline text. Two properties of TextBlock affect how multiline text displays: LineHeight, and LineStackingStrategy. LineHeight sets the height of every line of content in the overall TextBlock. LineHeight is truly the baseline to baseline height, so if you set a LineHeight that is smaller than the FontSize, your text might be cut off in the vertical dimension. Typically, you leave LineHeight unset, and rely on a default behavior that renders an effective line height based on FontSize plus an offset. LineStackingStrategy affects that default algorithm if it is used. LineStackingStrategy.MaxHeight (the default) bases the effective line height on the maximum height of any character in the font. LineStackingStrategy.BlockLineHeight bases the effective line height on the "block" font design measure that is also stored as a value in the font.

Transforms can alter the display of text in your application. Transforms can be applied to many different UI elements, including text elements. One scenario where you might use transforms on text is so that you can animate the transform, for a visual effect. The following are some transforms you might use for text:

• 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.

The value of many text properties can be animated including the text size of FontSize, position through a TranslateTransform, and color. For more information about animation that applies to animating text elements and their properties, see Animation Overview.

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:

• Simulate the text with vector graphics, such as a Path.

• Set the attached property TextOptions.TextHintingMode to the value Animated on the element where text is being animated. For more information, see TextOptions.

The TextBox control supports text wrapping. By default, the TextWrapping property is set to NoWrap. Without text wrapping, if the entered text exceeds either the explicit Width or a width constraint imposed by a parent layout container, the text will scroll such that the cursor always remains in view. If you set TextWrapping to Wrap, then the text does not scroll horizontally and wraps within the TextBox. It is still possible to produce a situation where input text is not visible, if the Height or effective render height of the TextBox is exceeded.

TextBox can potentially support multiline text, if you set AcceptsReturn to true. In this mode, the ENTER/RETURN key is recorded as a new line. Any entered character for new line is potentially included in the Text or SelectedText values in this case.

TextBox includes several APIs that are related to any selected area of text:

• The SelectionBackground and SelectionForeground properties affect how the selected area displays.

• The SelectedText property gets the selected text and is also potentially settable.

• The SelectionStart and SelectionLength properties get the selection range within the overall Text, and are potentially settable.

• The SelectionChanged event occurs whenever SelectedText or SelectionStart change.

By default, you select text by dragging the mouse, or by holding down the SHIFT key and then pressing the ARROW keys. For this and other reasons, the TextBox control sometimes handles and suppresses some of the general input events, such as MouseLeftButtonDown, or KeyDown for specific keys. The specific keys are keys that that can move the cursor, such as the ARROW keys.

Label is a control that displays content and can be associated with another control. Label derives from ContentControl and also can display text. Label has a Target property and automation support to associate it with another control that it references. Typically a Label just uses a string as Content, but it is possible to supply a container element for more control over the text formatting. Label is available in the Silverlight SDK client libraries.

AutoCompleteBox is a composite control that provides a TextBox for user input and a drop-down that contains possible matches based on the input in the TextBox. AutoCompleteBox has a Text property, but instead of exposing the various text element properties directly, it exposes a TextBoxStyle so that you can apply style setters that affect the TextBox composite part. AutoCompleteBox is available in the Silverlight SDK client libraries.

ItemsControl or HeaderedItemsControl have capabilities for displaying text items using content presenters. The text within the items is just text as a string, and does not support separate styling or a text object model. However, you can use the property value inheritance characteristic of the text element properties to set the values on the control parent, which then applies to the items text. ComboBox has similar capabilities (it is also an ItemsControl).

Popup is often used to display text, but it does not have a property that takes a string. Instead, it has a Child property that can take any UIElement. Typically you use a TextBlock as the Child value, set a Text value, and optionally style the text using the other TextBlock properties.

ToolTip uses the ToolTipService.ToolTip attached property for placement, and you can use a string for this value and not even include a ToolTip element in the XAML. Otherwise, you should specify a ToolTip object element as the ToolTipService.ToolTip property element value. For example, you can use a TextBlock and set its Text property.

Neither Popup nor ToolTip content will inherit font element properties, not even from the XAML page root element. This is because these objects are considered outside the general Silverlight visual tree when displayed, and the text element property values inherit from the visual tree. If you want to style the text within a Popup or ToolTip, set attributes or apply styles on an explicit TextBlock that you declare as content. Otherwise you will get the content presenter defaults for text, which are the same as the TextBlock defaults.