How to: Create a Text Decoration

A TextDecoration object is a visual ornamentation you can add to text. There are four types of text decorations: underline, baseline, strikethrough, and overline. The following example shows the locations of the text decorations relative to the text.

Example of text decoration types

To add a text decoration to text, create a TextDecoration object and modify its properties. Use the Location property to specify where the text decoration appears, such as underline. Use the Pen property to specify the appearance of the text decoration, such as a solid fill or gradient color. If you do not specify a value for the Pen property, the decorations defaults to the same color as the text. Once you have defined a TextDecoration object, add it to the TextDecorations collection of the desired text object.

The following example shows a text decoration that has been styled with a linear gradient brush and a dashed pen.

Example of an underline styled with a linear gradient brush and dashed pen

The Hyperlink object is an inline-level flow content element that allows you to host hyperlinks within the flow content. By default, Hyperlink uses a TextDecoration object to display an underline. TextDecoration objects can be performance intensive to instantiate, particularly if you have many Hyperlink objects. If you make extensive use of Hyperlink elements, you may want to consider showing an underline only when triggering an event, such as the MouseEnter event.

In the following example, the underline for the "My MSN" link is dynamic—it only appears when the MouseEnter event is triggered.

Hyperlinks defined with TextDecorations

For more information, see How to: Use a Text Decoration with a Hyperlink.

Example

In the following code example, an underline text decoration uses the default font value.

<!-- Use the default font values for the strikethrough text decoration. -->
<TextBlock
  TextDecorations="Strikethrough"
  FontSize="36" >
  The quick red fox
</TextBlock>

// Use the default font values for the strikethrough text decoration.
private void SetDefaultStrikethrough()
{
    // Set the underline decoration directly to the text block.
    TextBlock1.TextDecorations = TextDecorations.Strikethrough;
}

In the following code example, an underline text decoration is created with a solid color brush for the pen.

<!-- Use a Red pen for the underline text decoration -->
<TextBlock
  FontSize="36" >
  jumped over
  <TextBlock.TextDecorations>
    <TextDecorationCollection>
      <TextDecoration 
        PenThicknessUnit="FontRecommended">
        <TextDecoration.Pen>
          <Pen Brush="Red" Thickness="1" />
        </TextDecoration.Pen>
      </TextDecoration>
    </TextDecorationCollection>
  </TextBlock.TextDecorations>
</TextBlock>

// Use a Red pen for the underline text decoration.
private void SetRedUnderline()
{
    // Create an underline text decoration. Default is underline.
    TextDecoration myUnderline = new TextDecoration();

    // Create a solid color brush pen for the text decoration.
    myUnderline.Pen = new Pen(Brushes.Red, 1);
    myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommended;

    // Set the underline decoration to a TextDecorationCollection and add it to the text block.
    TextDecorationCollection myCollection = new TextDecorationCollection();
    myCollection.Add(myUnderline);
    TextBlock2.TextDecorations = myCollection;
}

In the following code example, an underline text decoration is created with a linear gradient brush for the dashed pen.

<!-- Use a linear gradient pen for the underline text decoration. -->
<TextBlock FontSize="36">the lazy brown dog.
  <TextBlock.TextDecorations>
    <TextDecorationCollection>
      <TextDecoration  
        PenThicknessUnit="FontRecommended">
        <TextDecoration.Pen>
          <Pen Thickness="1.5">
            <Pen.Brush>
              <LinearGradientBrush Opacity="0.5"
                StartPoint="0,0.5"  EndPoint="1,0.5">
                <LinearGradientBrush.GradientStops>
                  <GradientStop Color="Yellow" Offset="0" />
                  <GradientStop Color="Red" Offset="1" />
                </LinearGradientBrush.GradientStops>
              </LinearGradientBrush>
            </Pen.Brush>
            <Pen.DashStyle>
              <DashStyle Dashes="2"/>
            </Pen.DashStyle>
          </Pen>
        </TextDecoration.Pen>
      </TextDecoration>
    </TextDecorationCollection>
  </TextBlock.TextDecorations>
</TextBlock>

// Use a linear gradient pen for the underline text decoration.
private void SetLinearGradientUnderline()
{
    // Create an underline text decoration. Default is underline.
    TextDecoration myUnderline = new TextDecoration();

    // Create a linear gradient pen for the text decoration.
    Pen myPen = new Pen();
    myPen.Brush = new LinearGradientBrush(Colors.Yellow, Colors.Red, new Point(0, 0.5), new Point(1, 0.5));
    myPen.Brush.Opacity = 0.5;
    myPen.Thickness = 1.5;
    myPen.DashStyle = DashStyles.Dash;
    myUnderline.Pen = myPen;
    myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommended;

    // Set the underline decoration to a TextDecorationCollection and add it to the text block.
    TextDecorationCollection myCollection = new TextDecorationCollection();
    myCollection.Add(myUnderline);
    TextBlock3.TextDecorations = myCollection;
}

Note:
For a complete example of using text decorations, see the TextDecorationSample.

See Also

Tasks

How to: Use a Text Decoration with a Hyperlink

Reference

TextDecoration
Hyperlink