Windows Phone 7 : The Silverlight Controls (part 1) - Display Controls -TextBlock Controls, Image Controls, ProgressBar Controls

Let's take a tour through some of the controls that are available for use within your Silverlight pages. We won't cover them all, but will look at those that are most likely to be useful for your games and their user interfaces (UIs).

The controls can be broadly divided into three different groups: those that display information to the user, those that are interactive UI elements that the user can update as well as look at, and layout controls that help organize the presentation of the controls on the screen.

As you read through this section, please spend some time in Visual Studio and experiment with each of the controls—add and configure instances to a page in a test project, and then run them up in the emulator or on a phone to see how they look and how they can be interacted with. Having some basic experience with using the controls will be very beneficial when it comes to using them in your games because you will already have a feel for what each can achieve.

1. Display Controls

The controls that we will look at for the purposes of displaying information and content to the user are the TextBlock, Image, ProgressBar, Ellipse, Rectangle, Line, Polyline and Polygon controls.

1.1. TextBlock Controls

One of the most frequently used controls is the TextBlock, whose responsibility is simply to display a piece of text within the page.

A number of properties are present to control the appearance and position of the text. Its font can be set using the FontFamily property, and its size using the FontSize property. Silverlight renders vector fonts rather than using bitmaps, so specifying a larger font size does not result in additional resource data as it did in XNA. As a result, all text rendered by Silverlight will appear sharp and focused regardless of how large it gets.

The font can also be italicized using the FontStyle property and set to be bold using the FontWeight property. If a specific bold version of the font exists (such as it does for the Segoe WP font), setting the FontWeight will have no effect; instead the appropriate version of the font must be selected for the FontFamily. The TextDecorations property can be left blank or set to Underline to underline the text.

The rendered text can be padded away from the boundaries of the TextBlock by setting the Padding property. It may be horizontally aligned using the TextAlignment property to one of Left, Center, or Right (though note that unfortunately the Justify option does not work and just displays an error message). The text can be configured to word wrap inside the TextBlock area by setting the TextWrapping property appropriately.

What is less obvious is that the control can display much more complex text formatting than the simple Text property would suggest. The Properties window does not offer any support for it, but the TextBlock has an alternative method for setting its text: the Inlines property. This new property is in fact the ContentProperty for the TextBlock, so any content entered directly inside the TextBlock's element will be assigned to it.

Besides simple text, a child element named Run can be added to the text. This can be used a little like a span in HTML, allowing custom formatting to be applied to a section of the text. Listing 1 shows how this can be used in XAML to highlight a word in a different color.

Example 1. Using the Inlines property in a TextBlock

<TextBlock Height="147" FontSize="28" FontFamily="Arial" TextWrapping="Wrap">
            This is an example of using <Run Foreground="Blue">Inlines</Run> in a
            Silverlight TextBlock.
        </TextBlock>

					  

The resulting text shows with the word Inlines in blue text. Note, however, that it does not appear correctly within the Visual Studio page designer, failing to apply any spaces around the formatted text areas; this is just a preview error and it does appear normally when the application is running. Figure 1 shows the final output in a running application on the left, and on the right shows the appearance of the TextBlock within the Visual Studio preview.

Figure 1. The resulting TextBlock, running and in the Visual Studio preview

The text-formatting properties available for the Run element are FontFamily, FontSize, FontStretch, FontStyle, FontWeight, Foreground, and TextDecorations; and so any of them can be customized for the piece of text contained within the element. Note that Run elements cannot be nested, however.

1.2. Image Controls

To display a static image within the page, use an Image control. The image to be displayed is selected using its Source property, and can be added and addressed in exactly the same way as we saw with the ImageBrush .

The selected image can be stretched or shrunk using the Stretch property, which again behaves in the same way for each option as in the ImageBrush. If the displayed image is smaller than the control, it will always appear in the control's top-left corner.

1.3. ProgressBar Controls

Just as in the desktop world, the ProgressBar allows us to provide the user of our application with an indication of how far through a long-running process our code has progressed. This can be useful in gaming, whether it be for initializing a level, loading resources, or downloading content from the Internet. The Windows Phone 7 ProgressBar is space-optimized, allowing it to occupy very little vertical space within the page.

Its progress is set using three properties: Minimum, Maximum, and Value. The progress indication will be calculated by finding the proportion of the value between the minimum and maximum extents. By default, Minimum and Maximum have the values of 0 and 100, allowing Value to provide a percentage-based display. Figure 2 shows a progress bar using this default value range and with an actual Value setting of 25.

Figure 2. A ProgressBar showing 25 percent completion

There is an alternative way in which the control can be used, however, which is useful if you do not know how long your task will actually take to complete. If the IsIndeterminate property is set to be true, the Minimum, Maximum, and Value properties will be ignored, and instead a series of animated dots will appear (which will probably look very familiar to you!). These dots can be displayed while the task is running, and then hidden once the task is complete.