Windows Phone 8 : Windows Phone Toolkit (part 4) - ToggleSwitch Control, ExpanderView Control, PhoneTextBox Control

6 This control continues to be available in the Windows Phone Toolkit but these same changes were made to the built-in control, therefore making this control unnecessary except for backward compatibility with Windows Phone 7 and 7.1 applications.

You can simply use this control as your progress bar, instead of the built-in one, wherever you might expect to put the ProgressBar, like so:

<ProgressBar IsIndeterminate="{BindingIsBusy}" />

Replace this with the Toolkit version, like so:

<toolkit:PerformanceProgressBar IsIndeterminate="{BindingIsBusy}" />

FIGURE 11 ToggleSwitch example

The ToggleSwitch allows users to either tap the switch to change its value or actually slide it to the right to enable the option (or to the left to disable it). The ToggleSwitch is made up of three sections, as shown in Figure 12.

FIGURE 12 ToggleSwitch components

The Header property controls what is in the section labeled #1 in Figure 12. The Content property controls what is in the section labeled #2. And the switch itself is shown in the section labeled #3. The Content of the control is usually changed as the state of the control is changed (for example, the default is On for checked and Off for unchecked). You can see the creation of a ToggleSwitch in the following XAML:

<toolkit:ToggleSwitch Header="This one is enabled"
                      Content="On"
                      IsChecked="true"/>
<toolkit:ToggleSwitch Header="This one is disabled"
                      Content="On" />

FIGURE 13 ExpanderView in action

To use the control, you need an instance of the ExpanderView in your XAML. There are two parts to the control: the header and the items. The header is the part of the control that is always shown, and the items contain the content that is shown after the user taps on the header. For example:

<toolkit:ExpanderView Header="Click here to Expand">
  <TextBlock>This is hidden by default</TextBlock>
</toolkit:ExpanderView>

The Header property can be text (as is shown in the previous example), or it can be a more complex control using the expanded XAML syntax:

<toolkit:ExpanderView x:Name="theExpander">
  <toolkit:ExpanderView.Header>
    <TextBlock FontWeight="Bold"
                Margin="4">Click here to expand</TextBlock>
  </toolkit:ExpanderView.Header>
</toolkit:ExpanderView>

For the content, you can just include a list of controls to show simple content or use the ItemsSource to specify a collection (much like the way a ListBox works):

public partial class MainPage : PhoneApplicationPage
{
  // Constructor
  public MainPage()
  {
    InitializeComponent();

    expander.ItemsSource = new string[]
     { "Blue", "Red", "Green", "Orange" };
  }
}

Like the ItemsSource property, you can also use data templates (like the ItemTemplate) to control what each item looks like in the ExpanderView. You should think of the ExpanderView as similar to other list controls .

FIGURE 14 PhoneTextBox with the Hint and ActionIcon shown

To specify these, you can simply instantiate the control and specify the Hint attribute and the ActionIcon attribute as necessary:

<toolkit:PhoneTextBox x:Name="tweetText"
  ActionIcon="Toolkit.Content/ApplicationBar.Cancel.png"
  Hint="Enter Tweet" />

The PhoneTextBox includes an event to use when the ActionIcon is tapped. This event is called ActionIconTapped:

public partial class MainPage : PhoneApplicationPage
{
  // Constructor
  public MainPage()
  {
    InitializeComponent();

    tweetText.ActionIconTapped += tweetText_ActionIconTapped;
  }

  private void tweetText_ActionIconTapped(object sender, EventArgs e)
  {
    tweetText.Text = "";
  }
}

This example shows clearing the PhoneTextBox when the user clicks the cancel icon. This is a common usability improvement over the standard TextBox.

The PhoneTextBox also supports the ability to show the user how many characters she has typed. As the user types in the control, it can show the number of characters (as well as the maximum number of characters that will be allowed), as shown in Figure 15.

FIGURE 15 PhoneTextBox’s length indication support

The length indicator is supported by setting the LengthIndicatorVisible attribute to True. The LengthIndicatorThreshold attribute is also used to indicate how many characters have to be shown before the indicator is shown. This enables you to not show the indicator until the user is approaching the maximum number of characters. Finally, the DisplayedMaxLength attribute is used to indicate the maximum number in the indicator. Note that this does not limit the length of the field, but simply shows the maximum number in the indicator (which is why it’s called DisplayedMaxLength). You can see the XAML where these are specified here:

<toolkit:PhoneTextBox x:Name="tweetText"
                      DisplayedMaxLength="140"
                      LengthIndicatorVisible="True"
                      LengthIndicatorThreshold="20" />

Lastly, you can also indicate that the control should support pressing the Return key to expand the text box to include multiple lines of text. When the user uses this functionality, pressing Enter on the keyboard (or the SIP) will expand the PhoneTextBox to include the multiple lines (see Figure 16).

FIGURE 16 PhoneTextBox’s AcceptReturn functionality

You specify this by using the AcceptsReturn attribute as shown here:

<toolkit:PhoneTextBox x:Name="tweetText"
                      AcceptsReturn="True" />