101 Windows Phone 7 Apps: In Case of Emergency

This chapter is from the book

101 Windows Phone 7 Apps, Volume I: Developing Apps 1-50

Learn More Buy

This chapter is from the book

This chapter is from the book 

101 Windows Phone 7 Apps, Volume I: Developing Apps 1-50

Learn More Buy

The User Interface

Listing 3.1 contains the XAML for "In Case of Emergency," which consists of the standard header, four text boxes, and four corresponding text blocks. The resulting user interface is shown in Figure 3.4.

Figure 3.4 The "In Case of Emergency" user interface, shown in the dark theme and themes.

Listing 3.1. MainPage.xaml—The User Interface for "In Case of Emergency"

<phone:PhoneApplicationPage x:Class="WindowsPhoneApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
    xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
    FontFamily="{StaticResource PhoneFontFamilyNormal}"
    FontSize="{StaticResource PhoneFontSizeNormal}"
    Foreground="{StaticResource PhoneForegroundBrush}"
    SupportedOrientations="PortraitOrLandscape"
    shell:SystemTray.IsVisible="True">
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <!-- The standard header, with some tweaks -->
    <StackPanel Grid.Row="0" Margin="24,16,0,12">
      <TextBlock Text="IN CASE OF EMERGENCY" Margin="-1,0,0,0"
                 FontFamily="{StaticResource PhoneFontFamilySemiBold}"
                 FontSize="{StaticResource PhoneFontSizeMedium}"/>
      <TextBlock Text="tap here to call" Foreground="Red" Margin="-3,-10,0,0"
                 FontFamily="{StaticResource PhoneFontFamilySemiLight}"
                 FontSize="{StaticResource PhoneFontSizeExtraExtraLarge}"
                 MouseLeftButtonUp="TapHereToCall_MouseLeftButtonUp"/>
    </StackPanel>

    <!-- Scrollable pane (for the sake of the landscape orientation) -->
    <ScrollViewer Grid.Row="1">
      <!-- Four text block / text box pairs stacked vertically -->
      <StackPanel>
        <TextBlock Text="Emergency contact name" Margin="24,17,24,-5"
                   Foreground="{StaticResource PhoneSubtleBrush}"/>
        <TextBox x:Name="ContactNameTextBox" InputScope="PersonalFullName"
                 Margin="{StaticResource PhoneHorizontalMargin}"
                 GotFocus="TextBox_GotFocus" KeyDown="TextBox_KeyDown"/>

        <TextBlock Text="Emergency contact phone number" Margin="24,17,24,-5"
                   Foreground="{StaticResource PhoneSubtleBrush}"/>
        <TextBox x:Name="PhoneNumberTextBox" InputScope="TelephoneNumber"
                 Margin="{StaticResource PhoneHorizontalMargin}"
                 GotFocus="TextBox_GotFocus" KeyDown="TextBox_KeyDown"/>

        <TextBlock Text="Phone owner name" Margin="24,17,24,-5"
                   Foreground="{StaticResource PhoneSubtleBrush}"/>
        <TextBox x:Name="OwnerNameTextBox" InputScope="PersonalFullName"
                 Margin="{StaticResource PhoneHorizontalMargin}"
                 GotFocus="TextBox_GotFocus" KeyDown="TextBox_KeyDown"/>

        <TextBlock Text="Phone owner medical notes" Margin="24,17,24,-5"
                   Foreground="{StaticResource PhoneSubtleBrush}"/>
        <!-- A multiline text box -->
        <TextBox x:Name="MedicalNotesTextBox" InputScope="Text"
                 AcceptsReturn="True" MinHeight="236" TextWrapping="Wrap"
                 Margin="{StaticResource PhoneHorizontalMargin}" />
      </StackPanel>
    </ScrollViewer>
  </Grid>
</phone:PhoneApplicationPage>

Notes:

• This page supports all orientations due to its use of typing. However, because its contents are too long to fit on the screen in a landscape orientation, a scroll viewer is used to enable scrolling in this situation. Scroll viewers are discussed in the following section.
• The two text blocks in the standard header are given new margins and explicit font settings that are different from what Visual Studio generates when you create a page. That's because the automatically-generated page unfortunately doesn't do a good enough job of matching the header style of built-in apps. I ignored this annoyance in Chapter 1 (and Chapter 2, "Flashlight," didn't have a header), but from now on, every app goes out of its way to look as good as possible.
• The "tap here to call" text block is given a hard-coded red foreground to convey the sense of emergency. Fortunately, this looks fine over both possible theme backgrounds, as seen in Figure 3.4.
• The "tap here to call" text block has a MouseLeftButtonUp event handler for handling a tap to launch the Phone app. (Unlike buttons, text blocks do not have a Click event.) This disobeys a design guideline that page titles should not be interactive, but in this case breaking the rule seems appropriate.
• Each of the four main text blocks is given a PhoneSubtleBrush foreground and very specific margins to match the style of such labels used by built-in apps. PhoneSubtleBrush is a theme-defined gray color that varies ever so slightly for the dark and light themes.
• Whereas text blocks are static labels, text boxes are meant for editable text. Text boxes contain several advanced methods and properties for grabbing chunks of text as well as methods for converting between a character index and a physical region within the control. They also define TextChanged and SelectionChanged events.
• Each text box is given an explicit theme-defined margin (PhoneHorizontalMargin, which is 12 pixels on the left and right). Text boxes naturally have 12 pixels of space on all sides, but the text boxes used in built-in apps are usually seen with 24 pixels of space on the left and right. Therefore, adding this margin to the existing spacing makes these text boxes match the style of built-in apps. Margins are discussed in an upcoming section.
• The first three text boxes have handlers for their GotFocus and KeyDown events to enable subtle but important behaviors discussed in the code-behind section.
• Each text box is marked with an appropriate (and non-default) input scope. The first and third use PersonalFullName, which appropriately auto-capitalizes the first letter and doesn't attempt to offer suggestions as you type someone's name. The second text box uses TelephoneNumber because that is exactly what it wants. The last text box uses Text because text suggestions are appropriate for what you might type in this box. As shown in Figure 3.5, this comes in very handy when attempting to type a long and difficult word like Amoxicillin!
  

  Figure 3.5 Listing 3.1 uses three different input scopes to provide the best typing experience.

• The duplication of the margin and foreground settings on each text block is not very satisfactory from a code-maintenance perspective. Property values that are repeatedly applied to elements should usually be abstracted into a custom style to reduce the amount of duplicated code. We will start doing this in Chapter 9, "Fake Call," which explains styles in depth. The same technique will be used to avoid duplicating the new margin and font settings on the standard header in every app.

Figure 3.6 shows the appearance of the first keyboard (and the corresponding focused text box) under the light theme and under a landscape orientation, as this book has not yet shown what these situations look like.

Figure 3.6 The on-screen keyboard for the first text box, viewed with the light theme and with a landscape orientation.

How do I create a multiline text box?

Set its AcceptsReturn property to true, as done with the medical notes text box in Listing 3.1. In some cases, depending on the page layout, the text box might also have to be given an explicit height (or explicit minimum height) so multiple lines of text can be seen simultaneously. This is done in Listing 3.1 because a text box in a vertical stack panel is the height of a single line of text by default. If this text box were in a grid, it would stretch to fill its grid cell in both dimensions.

Note that a text box always supports multiple lines of text programmatically. If Text is set to a string containing newline characters, it displays the multiple lines regardless of the value of AcceptsReturn. Also, the multiline support is completely independent from text wrapping. Text wrapping applies only to individual lines of text that are wider than the control.

Now that we're starting to use a lot of text in an app, it's a good time to explain the Windows Phone guidelines for capitalization and punctuation. When looking at "In Case of Emergency," you might wonder, "Why don't the four main text blocks end in colons?" or "Why don't they use title capitalization?" Here is why:

Capitalization guidelines:

• Use all capital letters for the application title, the AM/PM used for time, and occasionally for items in a panorama control. (Panoramas are covered in Part IV, "Pivot, Panorama, Charts, & Graphs.")
• Use all lowercase letters for the page title, button text (or other command labels), list items, list titles, group titles, panorama and pivot control headings, and example text. Proper names, however, should still be capitalized as they normally are.
• Use sentence capitalization in labels for everything else: text boxes, check boxes, radio buttons, toggle switches, and so on. Also use it for progress, notification, status, and explanatory text.
• Title capitalization is almost never used for anything other than proper names, although it is sometimes used for standalone links that aren't part of a sentence (such as the "Privacy Statement" link in Internet Explorer's settings page).

Punctuation guidelines:

• Never use a colon on any labels unless it is directly introducing a value (typically a number) in the same label, such as "Score: 100" or "Carrier: AT&T". Notice that no colons are used in Figure 3.4.
• Never use an ellipsis unless it's at the end of active progress text. Using an ellipsis in a button is common on a PC (such as having a "Browse..." button) but is not appropriate for Windows Phone.
• Do not use ending punctuation—even when using sentence capitalization—except in instructional text. Question marks are okay for questions, but you should avoid asking a question unless it is a message box title. When using multiple sentences (which should only be for instructional text), you should separate them with one space (not two).
• Avoid using parentheses, but they are okay for acronyms or other short information.
• When referring to a list of items, they should all be separated by commas (including a comma between the last two items).
• It's okay to use an ampersand in labels rather than spelling out "and."

These guidelines are based not just on Microsoft documents (which are sometimes inaccurate) but also on what built-in apps on Windows Phone actually do. They may seem silly and arbitrary (and in some ways they are), but it's important to follow them for consistency with the rest of the phone and its apps.

Scroll Viewer

For user interfaces meant to fit on the screen without scrolling, using a grid as the root element inside a page is the best way to dynamically adjust to different page dimensions. For user interfaces meant to scroll when there is not enough space—such as this app—scroll viewer comes to the rescue.

By wrapping any element in a scroll viewer, the element automatically becomes scrollable when there is not enough space to render it all at once. For this app, the entire stack panel with all eight elements fits on the screen in the portrait orientation, so the scroll viewer isn't needed. In a landscape orientation, however, the scroll viewer kicks in and enables the page to be swiped up and down. Figure 3.7 shows the page before the user touches it, and then shows it while the user scrolls it about halfway down.

Figure 3.7 The scroll viewer ensures that the entire page is accessible in a landscape orientation even though it can't all be seen at once.

According to design guidelines, the application and page titles (if present) should never scroll out of view unless the on-screen keyboard pushes them out of the way. By placing the scroll viewer around the stack panel (and not the entire grid), this page complies.

A scroll viewer may only contain a single direct child element, but this child element is typically a complex panel such as a grid or, in this case, a stack panel. A scroll viewer contains several properties and methods for more advanced or programmatic manipulation of scrolling (such as a ScrollToVerticalOffset method that can be passed a number of pixels), but its two most important properties are VerticalScrollBarVisibility and HorizontalScrollBarVisibility. Both of these properties are of type ScrollBarVisibility, an enumeration that determines the behavior of its two scroll bars. ScrollBarVisibility has four values, but two of them are redundant. The values are

• Visible and Auto—Enables scrolling in the relevant dimension. The scroll bar automatically becomes visible while the user is dragging the screen (and the content is long enough to scroll in that dimension).
• Disabled and Hidden— Disables scrolling in the relevant dimension.

The default value for VerticalScrollBarVisibility is Auto, and the default value for HorizontalScrollBarVisibility is Disabled, to match the scrolling behavior used by almost all apps. If you were to mark the scroll viewer in Listing 3.1with HorizontalScrollBarVisibility="Auto" and manually set the Width property on one of the text boxes to a large enough value, you would be able to scroll the page horizontally.

When the on-screen keyboard appears, the text box with focus might need to be scrolled upward in order to remain in view above the keyboard. Fortunately, this happens automatically, even when no scroll viewer is used. Notice that in the last image in Figures 3.5 and 3.6, the entire page has been magically scrolled, even the normally unscrollable header! When the keyboard is dismissed, the page returns to its normal state.

Controlling the Size of Elements

Silverlight elements tend to size to their content, meaning that they try to be large enough to fit their content and no larger. This size can be influenced via several straightforward properties.

Elements have simple Height and Width properties (of type double), and they also have MinHeight, MaxHeight, MinWidth, and MaxWidth properties that can be used to specify a range of acceptable values. Any or all of these can be easily set on elements in C# or in XAML.

Avoid setting explicit sizes!

Giving controls explicit sizes opens up the risk of cutting off text when content is dynamic or if you decide to localize your app for other languages. Therefore, you should avoid setting explicit sizes unless absolutely necessary. Fortunately, setting explicit sizes is rarely necessary, thanks to the panels described in the next chapter.

Notice that the medical notes text box in Listing 3.1 uses MinHeight="236" rather than Height="236", but for a different reason. Although a multiline text box supports some amount of internal scrolling if the text doesn't fit, this is hard to do. (It involves holding your finger down to reveal the caret, then dragging the caret.) Instead, because the text box already resides inside a scroll viewer, allowing it to grow as a user adds more lines of text results in an interface that is much easier to use.

An element naturally stays as small as possible, so if you use MinHeight or MinWidth, it is rendered at that height/width unless its content forces it to grow. In addition, that growth can be limited by using MaxHeight and MaxWidth (as long as these values are larger than their Min counterparts). When using an explicit Height and Width at the same time as their Min and Max counterparts, Height and Width take precedence as long as they are in the range from Min to Max. The default value of MinHeight and MinWidth is 0, and the default value of MaxHeight and MaxWidth is Double.PositiveInfinity (which can be set in XAML as simply "Infinity").

To complicate matters, elements also contain ActualHeight and ActualWidth properties. Unlike the other six properties that are input to the layout process, however, these are read-only properties representing output from the layout process.

ActualHeight and ActualWidth represent the final size of an element after layout is complete. That's right: Whether an element specified an explicit size, specified a range of acceptable sizes, or didn't specify anything at all, the behavior of other elements can alter an element's final size on the screen. These three properties are, therefore, useful for advanced scenarios in which you need to programmatically act on an element's size. The values of all the other size-related properties, on the other hand, aren't very interesting to base logic on. For example, when not set explicitly, the value of Height and Width are Double.NaN, regardless of the element's true size.

Margins and Padding

Silverlight elements have a Margin property that gives you control over how much extra space gets placed around the outside edges of the element. Many elements also have a Padding property that gives you control over how much extra space gets placed around the inside edges of the element. Margins are used very often to get an appropriate-looking user interface. Padding is normally not used, nor should it be used with standard elements, because they are already given default padding that gives them a consistent look with the rest of the phone.

Both Margin and Padding are of type Thickness, an interesting class that can represent one, two, or four values. Here is how the values are interpreted when set in XAML:

• When set to a list of four values, as done many times with Margin in Listing 3.1, the numbers represent the left, top, right, and bottom edges, respectively.
• When set to a list of two values, the first number is used for the left and right edges and the second number is used for the top and bottom edges. So "12,24" is a shortcut way of specifying "12,24,12,24".
• When set to a single value, it is used for all four sides. So "12" is a shortcut way of specifying "12,12", which is a shortcut for "12,12,12,12".
• Negative values may be used for margins (and often are), but are not allowed for padding.
• The commas are optional. You can use spaces instead of, or in addition to, commas. "12,24" is the same as "12 24" and "12, 24".

When creating a Thickness in C#, you can use its constructor that accepts either a single value or all four values:

this.TextBox.Margin = new Thickness(12);          // Margin="12" in XAML
this.TextBox.Margin = new Thickness(12,24,12,24); // Margin="12,24" in XAML

Note that the handy two-number syntax is a shortcut only available through XAML. Thickness does not have a two-parameter constructor.

By default, text boxes have a padding of 2 (on all sides). Figure 3.8 demonstrates how explicitly setting different values affects their appearance, done with the following XAML:

<StackPanel>
  <TextBox Text="padding = 0" Padding="0"/>
  <TextBox Text="padding = 2 (default)"/>
  <TextBox Text="padding = 10" Padding="10"/>
  <TextBox Text="padding = 40,2" Padding="40,2"/>
</StackPanel>

Figure 3.8 The effect of Padding on four text boxes.

The first text box has two fewer pixels of space around the text than the default one, and the third text box has eight more pixels of space around the text. When the text boxes are stacked like this, these two settings also change the overall height of each text box but not the width (because the text boxes are getting stretched horizontally to the width of the parent page). The final text box keeps the default padding on the top and bottom, but gets 40 pixels of padding on the left and right.

Although done here for demonstration purposes, you should avoid overriding the padding on standard controls. The default padding values were carefully chosen to match design guidelines. A valid place to use padding would be in the design of your own custom control, or a control with special-purpose content that already makes it appear non-standard.