Windows 8.1 and Windows 8.1 Phone Convergence. Part 1: Controls

25 May 2014

With the release of the WinRT 8.1 API, the development models for Windows 8.1 and Windows Phone 8.1 (WinRT-based) apps have undergone a dramatic convergence. With some platform-specific considerations, we can now develop apps for Windows and Windows Phone using pretty much the same XAML framework and API. The "old" Windows Phone 8.0 Silverlight-based API will continue to be supported and improved, but clearly the converged WinRT-based model is the way to go in the future.

In the first of a series of posts on the convergence of the Windows and Phone platforms, this article focuses on the controls available to XAML developers using the WinRT 8.1 API.

If you want the definative narrative on developing for Windows Phone 8.1, I strongly suggest reviewing Andy Wigley's Microsoft Virtual Academy course Building Apps for Windows Phone 8.1, which is now available Microsoft on Channel 9.

Summary of available WinRT 8.1 controls

The following table summarizes the controls available for Windows 8.1 and Windows Phone 8.1 apps developed using WinRT 8.1:

Control Uses Win 8.1 WP 8.1 Convergence
AppBar Top Displays an AppBar at the top of the window Y N Win8.1
AppBar Bottom Displays an AppBar at the bottom of the window Y Y Universal
AutoSuggestBox Text input with suggestions N Y WP8.1
Border Visual border Y Y Universal
Button Clickable button Y Y Universal
Canvas Absolute positioning layout container Y Y Universal
CaptureElement Captures input from a camera device Y Y Universal
CheckBox Checkbox Y Y Universal
ComboBox Combobox Y Y Universal
CommandBar
See AppBar
Handles the placement of AppBarButton elements Y Y Universal
ContentControl A control that has a single element of content Y Y Universal
ContentDialog WP8.1 'MessageBox'
See MessageDialog for Win8.1
N Y WP8.1
ContentPresenter Acts as a place-holder in a control template for the control's content Y Y Universal
DatePicker Date selection Y Y Universal
DatePickerFlyout Displays a full-screen date picker N Y WP8.1
Ellipse Shape Y Y Universal
FlipView Displays a collection of items, one at a time Y Y Universal
Flyout Displays a non-modal window Y Y Universal
Grid Used to layout other controls (children) in a row/column matrix Y Y Universal
GridView Displays a horizontal grid of items Y Y Universal
Hub Displays data in horizontal sections Y Y Universal
Hyperlink Displays a hyperlink inside TextBlock and RichTextBlock elements Y Y Universal
HyperlinkButton Displays a hyperlink Y Y Universal
Image Displays an image Y Y Universal
ItemsControl A control that displays a collection of elements Y Y Universal
ItemsPresenter Acts as a place-holder in a control template for a list of items Y Y Universal
Line Shape Y Y Universal
ListBox Displays a list of items Y Y Universal
ListPickerFlyout Displays a full-screen flyout list of items N Y WP8.1
ListView Displays a collection of items in a list that scrolls vertically Y Y Universal
MapControl Displays a map N Y WP8.1
MediaElement Plays audio and video Y Y Universal
MenuFlyout Displays a flyout menu Y Y Universal
MessageDialog Win8.1 'MessageBox'
See ContentDialog for WP8.1
Y N Win8.1
Path Shape Y Y Universal
PasswordBox Displays a password entry text box Y Y Universal
PickerFlyout Creates a custom flyout N Y WP8.1
Pivot Manages a horizontally scrolled collection of page-like pivot items N Y WP8.1
Polygon Shape Y Y Universal
Polyline Shape Y Y Universal
Popup Defines a custom container for other XAML elements Y Y Universal
ProgressBar Displays a progress bar Y Y Universal
ProgressRing Displays a progress ring Y Y Universal
RadioButton Allows the selection of a single item in a group Y Y Universal
Rectangle Shape Y Y Universal
RepeatButton A button that raises a Click event repeatedly until released Y Y Universal
RichEditBox Text box with rich formatting Y Y Universal
RichTextBlock Same as TextBlock but with rich formatting Y Y Universal
ScrollBar Scrollbar with thumb Y Y Universal
ScrollViewer Presents content in a view that may be panned and zoomed Y Y Universal
SearchBox Provides a standarized in-app search mechanism Y N Win8.1
SemanticZoom Allows the user to zoom between two views of a collection of items Y Y Universal
SettingsFlyout Displays a settings flyout for the app Y N Win8.1
Slider Allows the user to quickly specify a value by moving a thumb control Y Y Universal
StackPanel Container that layouts out other elements in a horizontal or vertical fashion Y Y Universal
TextBlock Displays text (non-editable) Y Y Universal
TextBox Allows the user to edit text Y Y Universal
TimePicker Time selection Y Y Universal
TimePickerFlyout Displays a full-screen time picker N Y WP8.1
ToggleButton A button which can represent two states Y Y Universal
ToggleSwitch Displays an "on/off" switch representing a boolean value Y Y Universal
Tooltip Displays context help for an element Y Y Universal
UserControl Allows the creation of custom controls Y Y Universal
VariableSizedWrapGrid Display items in multiple rows and columns. See also WrapGrid Y Y Universal
Viewbox Container that scales content to a specific size Y Y Universal
WebView Displays a browser Y Y Universal
WrapGrid Display items in rows and columns. See also VariableSizedWrapGrid Y Y Universal


Using WinRT Controls

AppBar (Top) (Win8.1)

Displays an AppBar at the top of the window.

Windows 8.1 appearance:

<Page.TopAppBar>
    <CommandBar>
        <AppBarButton Label="Attach file" Icon="Attach" Click="AttachFileClicked" />
        <AppBarButton Label="Buy in shop" Icon="Shop" Click="BuyClicked"/>
    </CommandBar>
</Page.TopAppBar>
  • Note that AppBarButton supports both the Click event and the MVVM-friendly Command and CommandParameter properties (for an example, see AppBarBottom)
  • For Icon values see Windows.UI.Xaml.Controls.Symbol

AppBar (Bottom) (Universal)

Displays an AppBar at the bottom of the window.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<Page.BottomAppBar>
    <CommandBar>
        <CommandBar.PrimaryCommands>
            <AppBarButton Label="List" Icon="Bullets"/>
            <AppBarButton Label="Comments" Icon="Comment"/>
            <AppBarButton Label="Contact us" Icon="Contact">
                <AppBarButton.Flyout>
                    <Flyout>
                        <StackPanel Width="250" Background="Coral">
                            <TextBlock Text="Contact Us" FontSize="24" Foreground="Blue"/>
                        </StackPanel>
                    </Flyout>
                </AppBarButton.Flyout>
            </AppBarButton>
        </CommandBar.PrimaryCommands>

        <CommandBar.SecondaryCommands>
            <AppBarButton Label="Time" Icon="Clock" Click="AppBarButtonClicked"/>
            <AppBarButton 
                Label="Add to favs" 
                Icon="Favorite" 
                Command="{Binding AddToFavsCommand}"/>
        </CommandBar.SecondaryCommands>
    </CommandBar>
</Page.BottomAppBar>
  • Note that AppBarButton supports both the Click event and the MVVM-friendly Command and CommandParameter properties. Examples of their usage can be seen in the <CommandBar.SecondaryCommands> XAML above
  • For brevity, in the above examle XAML most AppBarButton statements don't include click event handlers or commands
  • For Icon values see Windows.UI.Xaml.Controls.Symbol
  • Notice how for WP8.1 the secondary set of commands are interpreted as menu items

AutoSuggestBox (WP8.1)

Text input with suggestions.

Windows Phone 8.1 appearance:

<AutoSuggestBox ItemsSource="{Binding Suggestions}" />
  • In the above example, Suggestions is an ObservableCollection of strings

Border (Universal)

Visual border (e.g. around a StackPanel or other container).

<Border BorderBrush="CornflowerBlue" BorderThickness="3" Margin="5" CornerRadius="5">
    <StackPanel Margin="5">
    </StackPanel>
</Border>

Button (Universal)

A clickable button.

<Button Content="Show Capture" Tapped="ShowCaptureTapped"/>

Canvas (Universal)

Absolute positioning layout container.

Windows 8.1 and Windows Phone 8.1 appearance:

<Canvas Width=120" Height="120"> 
    <Rectangle Fill="Red" Width="25" Height="25" /> 
    <Rectangle Fill="Blue" Width="25" Height="25" Canvas.Left="20" Canvas.Top="20" />
    <Rectangle Fill="Green" Width="25" Height="25" Canvas.Left="40" Canvas.Top="40" />
</Canvas>

CaptureElement (Universal)

Captures input from a camera device.

<Button Content="Show Capture" Tapped="ShowCaptureTapped"/>
<CaptureElement Width="320" Height="240" x:Name="videoCap"/>
private async void ShowCaptureTapped(object sender, TappedRoutedEventArgs e)
{
    // _mediaCaptureMgr is a private of type MediaCapture
    if(_mediaCaptureMgr == null)
    {
        _mediaCaptureMgr = new MediaCapture();
        await _mediaCaptureMgr.InitializeAsync();
        videoCap.Source = _mediaCaptureMgr;
    }

    // _mediaCaptureStreaming is a private bool
    if(_mediaCaptureStreaming)
    {
        await _mediaCaptureMgr.StopPreviewAsync();
        _mediaCaptureStreaming = false;
    }
    else
    {
        await _mediaCaptureMgr.StartPreviewAsync();
        _mediaCaptureStreaming = true;
    }
}
  • The above example requires the Webcam capability to be set in the manifest

CheckBox (Universal)

A checkbox.

Windows 8.1 and Windows Phone 8.1 appearance:

<CheckBox Content="View in HD" Checked="OnCBChecked"/>

ComboBox (Universal)

An expandable list of selectable items.

Windows 8.1 and Windows Phone 8.1 appearance:

<ComboBox ItemsSource="{Binding Suggestions}" SelectionChanged="ComboSelChanged"/>

ContentControl (Universal)

A control that has a single element of content. Controls like Button, CheckBox, etc. are derived from this class.

<ContentControl>
    <TextBlock Text="Hello"/>
</ContentControl>

ContentDialog (WP8.1)

Windows Phone 8.1 'MessageBox'.

Windows Phone 8.1 appearance:

var dlg = new ContentDialog()
{
     Title = "My Dlg", 
     Content = "Test OK?",
     PrimaryButtonText = "Yes",
     SecondaryButtonText = "No"
};

var result = await dlg.ShowAsync();

Debug.WriteLine(result == ContentDialogResult.Primary ? "YES" : "No");

ContentPresenter (Universal)

Acts as a place-holder in a control template for the control's content.

WinRT XAML controls separate behaviour (e.g. behaviour-related properties, methods, events) with appearance. Beyond setting individual visual properties like Background, etc., we can completely redefine a control's visual appearance through the use of a ControlTemplate:

<ControlTemplate x:Key="MyButtonTemplate" TargetType="Button">
    <Border 
        BorderBrush="Magenta" 
        Background="CornflowerBlue"
        BorderThickness="3" 
        Margin="5"
        CornerRadius="5">

        <!-- 
             ContentPresenter is a place-holder for the control's
             content (defined higher up the visual tree) that will
             be presented at runtime
        -->
        <StackPanel HorizontalAlignment="Center">
            <TextBlock Text="-->" TextAlignment="Center"/>
            <ContentPresenter />
        </StackPanel>

    </Border>            
</ControlTemplate>
<Button Template="{StaticResource MyButtonTemplate}" Content="Click Me"/>

DatePicker (Universal)

Date selection.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<DatePicker Header="Select a date:" DateChanged="OnDateSelected" />

DatePickerFlyout (WP8.1)

Displays a full-screen date picker (see also DatePicker).

Windows Phone 8.1 appearance:

To invoke directly from code:

var picker = new DatePickerFlyout();
await picker.ShowAtAsync(grid);
var date = picker.Date;

To launch via a button element:

<Button Content="Display Flyout">
    <Button.Flyout>
        <DatePickerFlyout DatePicked="OnDatePicked" />
    </Button.Flyout>
</Button>

Ellipse (Universal)

An ellipse shape.

Windows 8.1 and Windows Phone 8.1 appearance:

<Ellipse Width="100" Height="100" Fill="DarkMagenta"/>

FlipView (Universal)

Displays a collection of items, one at a time. Users can flip between items back/forwards as desired.

Windows 8.1 and Windows Phone 8.1 appearance:

<FlipView Width="200" Height="200">
    <Image Source="Images/indian/Indian_1_150_C.jpg"/>
    <Image Source="Images/indian/Indian_2_150_C.jpg"/>
    <Image Source="Images/indian/Indian_3_150_C.jpg"/>
</FlipView>

Flyout (Universal)

Displays a non-modal window.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<Button Content="Click me for a flyout!" HorizontalAlignment="Center">
    <Button.Flyout>
        <Flyout>
            <Border BorderThickness="3" BorderBrush="Crimson" >
                <StackPanel HorizontalAlignment="Center" Margin="10">
                    <TextBlock 
                        Text="Hello" 
                        FontSize="12" 
                        TextAlignment="Center" 
                        Foreground="CornflowerBlue"/>

                    <TextBlock 
                        Text="Universal" 
                        FontSize="14" 
                        TextAlignment="Center" 
                        Foreground="Coral"/>

                    <TextBlock 
                        Text="World!" 
                        FontSize="20" 
                        TextAlignment="Center" 
                        Foreground="DarkRed"/>
                </StackPanel>
            </Border>
        </Flyout>
    </Button.Flyout>
</Button>

A Flyout can also easily be created in code:

<Button 
    x:Name="ButtonCreateFlyout"  
    Content="Click me to create a Flyout in code"
    Click="CreateFlyoutClicked"/>
var f = new Flyout();
var sp = new StackPanel();
var tb1 = new TextBlock {Text = "Hello"};
var tb2 = new TextBlock {Text = "World!"};
sp.Children.Add(tb1);
sp.Children.Add(tb2);
f.Content = sp;
f.ShowAt(ButtonCreateFlyout);
  • In Win8.1 you can specify the target element of the flyout (where it will display)
  • In WP8.1, the flyout is always displayed at the top of the screen (target element is ignored)

Grid (Universal)

Used to layout other controls (children) in a row/column matrix.

Windows 8.1 and Windows Phone 8.1 appearance:

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Grid.RowDefinitions>
        <RowDefinition Height="200*"/>
        <RowDefinition Height="200*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="250*"/>
        <ColumnDefinition Width="250*"/>
        <ColumnDefinition Width="250*" />
    </Grid.ColumnDefinitions>
    :
    :
</Grid>

GridView (Universal)

Displays a horizontal grid of items. For vertical scrolling see ListView.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

The following assumes we have an ObservableCollection<FoodItem>, where FoodItem is defined as:

public class FoodItem
{
    public string Name { get; set; }
    public string Country { get; set; }
    public string ImgPath { get; set; }
}

An item template (same for Win8.1 and WP8.1) for each GridView item is defined in the XAML <Page.Resources> section as follows:

<DataTemplate x:Key="FoodDataTemplate">
    <Border 
        BorderBrush="CornflowerBlue" 
        BorderThickness="3" 
        CornerRadius="10" 
        Margin="10">

        <StackPanel 
            Width="150" 
            Height="175" 
            d:DataContext="{Binding Foods}">
            
            <TextBlock 
                FontSize="18" 
                Margin="5" 
                Foreground="Coral"
                TextAlignment="Center" 
                Text="{Binding Name}"/>

            <TextBlock 
                FontSize="18" 
                Margin="5" 
                Foreground="Magenta"
                TextAlignment="Center" 
                Text="{Binding Country}"/>

            <Image 
                Width="75" 
                Height="75" 
                Margin="10" 
                Source="{Binding ImgPath}"/>
        </StackPanel>
    </Border>
</DataTemplate>

The GridView control is declared as follows (the GridView.ItemsPanel element is optional and allows you to define how many rows or columns are displayed):

<GridView 
    HorizontalAlignment="Center"
    VerticalAlignment="Top"
    ItemsSource="{Binding Foods}" 
    ItemTemplate="{StaticResource FoodDataTemplate}">
    <GridView.ItemsPanel>
        <ItemsPanelTemplate>
            <ItemsWrapGrid 
                MaximumRowsOrColumns="2" 
                Orientation="Horizontal" />
        </ItemsPanelTemplate>
    </GridView.ItemsPanel>
</GridView>
  • Note that I've not been able to get horizontal scrolling to work on WP8.1. Only vertical scrolling seems to be supported
  • Placing GridView and ListView controls inside StackPanel elements seems to prevent scrolling from working correctly

Hub (Universal)

Used to layout data in sections (used to be named 'Panorama' in WP8.0).

Very similar to the Pivot control. In general however, the Hub control is suited to displaying views of items that may be regarded as being on the same "logical page" (i.e. think of the Hub control as being a window into a larger page). The Pivot control is well suited to displaying items that represent distinct data sets.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<Hub Header="Microsoft News" Background="CornflowerBlue">
    <HubSection MinWidth="400" Header="Azure">
        <DataTemplate>
            <StackPanel>
                <TextBlock 
                    Text="Windows Azure news..." 
                    Style="{ThemeResource BodyTextBlockStyle}" />
                <Image Source="Images/italian/Italian_1_600_C.jpg"/>
            </StackPanel>
        </DataTemplate>
    </HubSection>

    <HubSection 
        Header="Win8.1" 
        Background="Brown"
        IsHeaderInteractive="True"  
        MinWidth="250">
        <DataTemplate>
            <StackPanel>
                <TextBlock 
                    Text="Windows 8.1 news..." 
                    Style="{ThemeResource BodyTextBlockStyle}" />
                <Image Source="Images/italian/Italian_2_600_C.jpg"/>
            </StackPanel>
        </DataTemplate>
    </HubSection>

    <HubSection 
        Header="WP8.1" 
        Background="DarkGreen"
        IsHeaderInteractive="True"  
        MinWidth="250">
        <DataTemplate>
            <StackPanel>
                <TextBlock 
                    Text="Windows Phone 8.1 news..." 
                    Style="{ThemeResource BodyTextBlockStyle}" />
                <Image Source="Images/italian/Italian_3_600_C.jpg"/>
            </StackPanel>
        </DataTemplate>
    </HubSection>
</Hub>

Displays a hyperlink inside TextBlock and RichTextBlock elements.

<TextBlock>
    <Run Text="Please visit the "/>
    <Hyperlink NavigateUri="http://bbc.co.uk">BBC website</Hyperlink>
</TextBlock>

HyperlinkButton (Universal)

Displays a hyperlink. See also Hyperlink to display a link inside TextBlock elements.

<HyperlinkButton Content="BBC" NavigateUri="http://bbc.co.uk"/>

Image (Universal)

Displays an image.

<Image 
    Source="Images/italian/Italian_1_600_C.jpg"
    Width="300" 
    Stretch="UniformToFill" />

Or, in code:

// Create an Image element and add to a StackPanel
var bitmap = new BitmapImage { UriSource = new Uri("ms-appx:///Images/german/German_2_600_C.jpg") };
var img = new Image { Source = bitmap, Width = 300 };
MyStackPanel.Children.Add(img);

ItemsControl (Universal)

Displays a collection of elements. Normally you would use a control that derives from ItemsControls and adds more features, such as ListView, GridView, etc.

<ItemsControl>
    <Button Content="Hello"/>
    <TextBlock Text="World"/>
</ItemsControl>

Line (Universal)

Shape.

The following draws a horizontal line:

<Line 
    Stroke="CornflowerBlue"
    StrokeThickness="5" 
    X1="5"
    Y1="5"
    X2="100" 
    Y2="5"/>

ItemsPresenter (Win8.1)

Acts as a place-holder for a list of items. Normally used in a ControlTemplate.

WinRT XAML controls separate behaviour (e.g. behaviour-related properties, methods, events) with appearance. Beyond setting individual visual properties like Background, etc., we can completely redefine a control's visual appearance through the use of a ControlTemplate:

<ControlTemplate x:Key="MyListBoxTemplate" TargetType="ListBox">
    <Border 
        BorderBrush="Magenta" 
        Background="Azure"
        BorderThickness="3" 
        Margin="5"
        CornerRadius="5">

        <!-- 
             ItemsPresenter is a place-holder for the list of items
             that will be presented at runtime
        -->
        <ItemsPresenter />

    </Border>
</ControlTemplate>

We can then apply the control template to a control as follows:

<ListBox 
    Template="{StaticResource MyListBoxTemplate}" 
    :
    :
</ListBox>

ListBox (Universal)

Displays a collection of items.

Windows 8.1 and Windows Phone 8.1 appearance:

<ListBox ItemsSource="{Binding Suggestions}"/>

ListPickerFlyout (WP8.1)

Displays a full-screen flyout list of items.

Windows Phone 8.1 appearance:

To display via a XAML element:

<Button Content="Display Flyout">
    <Button.Flyout>
        <ListPickerFlyout 
            ItemsSource="{Binding Suggestions}" 
            ItemsPicked="OnFlyoutItemsSelected" />
    </Button.Flyout>
</Button>

To invoke from code:

private async void ShowListPicker(object sender, RoutedEventArgs e)
{
    var flyout = new ListPickerFlyout {ItemsSource = Suggestions};
    await flyout.ShowAtAsync(FlyoutButton);

    if(flyout.SelectedItem == null) return;
    var itemPicked = flyout.SelectedValue.ToString();
    Debug.WriteLine("Item picked: {0}", itemPicked);
}

MessageDialog (Win8.1)

Windows 8.1 'MessageBox'.

Windows 8.1 appearance:

var dlg = new MessageDialog("Test OK?", "Test dialog");
dlg.Commands.Add(new UICommand("Yes", command => { }, 0));
dlg.Commands.Add(new UICommand("No", command => { }, 1));

var result = await dlg.ShowAsync();
var id = (int) result.Id;

Debug.WriteLine(id == 0 ? "YES" : "NO");

ListView (Universal)

Displays a collection of items in a list that scrolls vertically.

Windows 8.1 and Windows Phone 8.1 appearance:

The following assumes we have an ObservableCollection<FoodItem>, where FoodItem is defined as:

public class FoodItem
{
    public string Name { get; set; }
    public string Country { get; set; }
    public string ImgPath { get; set; }
}

An item template (same for Win8.1 and WP8.1) for each ListView item is defined in the XAML <Page.Resources> section as follows:

<DataTemplate x:Key="FoodDataTemplate">
    <Border 
        BorderBrush="CornflowerBlue" 
        BorderThickness="3" 
        CornerRadius="10" 
        Margin="10">

        <StackPanel 
            Width="150" 
            Height="175" 
            d:DataContext="{Binding Foods}">
            
            <TextBlock 
                FontSize="18" 
                Margin="5" 
                Foreground="Coral"
                TextAlignment="Center" 
                Text="{Binding Name}"/>

            <TextBlock 
                FontSize="18" 
                Margin="5" 
                Foreground="Magenta"
                TextAlignment="Center" 
                Text="{Binding Country}"/>

            <Image 
                Width="75" 
                Height="75" 
                Margin="10" 
                Source="{Binding ImgPath}"/>
        </StackPanel>
    </Border>
</DataTemplate>

The ListView control is declared as follows. An optional ListView.ItemsPanel element may be used to define how many rows or columns are displayed (see GridView):

<ListView 
    HorizontalAlignment="Center"
    VerticalAlignment="Top"
    ItemsSource="{Binding Foods}"
    ItemTemplate="{StaticResource FoodDataTemplate}" />
  • Placing ListView and GridView controls inside StackPanel elements seems to prevent scrolling from working correctly

MapControl (WP8.1)

Displays a map.

Windows Phone 8.1 appearance:

<maps:MapControl 
    Margin="10"
    PedestrianFeaturesVisible="True"
    ColorScheme="Dark" />

MediaElement (Universal)

Plays audio and video.

Windows Phone 8.1 appearance:

<MediaElement 
    Source="Media/BuildingAppsForWindowsPhone81M01_high.mp4"
    Volume="10" 
    AreTransportControlsEnabled="True" />

Displays a menu flyout.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<Button 
    VerticalAlignment="Top"
    Content="Show Menu Flyout"
    Margin="20">
    <Button.Flyout>
        <MenuFlyout>
            <MenuFlyoutItem 
                Text="Apples" 
                Click="OnApplesClicked"/>
            <MenuFlyoutSeparator/>
            <ToggleMenuFlyoutItem 
                Text="Oranges By Default" 
                IsChecked="{Binding ShowOranges, Mode=TwoWay}" />
        </MenuFlyout>
    </Button.Flyout>
</Button>

Note that on WP8.1:

  • the menu separator is ignored
  • the ToggleMenuFlyoutItem appears not to be supported

Path (Universal)

Shape.

Windows 8.1 and Windows Phone 8.1 appearance:

<Path 
    Width="100" 
    Fill="Crimson"
    Stroke="Coral" 
    Height="100">
    <Path.Data>
        <GeometryGroup>
            <RectangleGeometry Rect="50,100,100,5" />
            <EllipseGeometry Center="100, 100" RadiusX="30" RadiusY="30"/>
        </GeometryGroup>
    </Path.Data>
</Path>

PasswordBox (Universal)

A password entry text box.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<PasswordBox 
    Margin="10" 
    Password="{Binding PasswordText, Mode=TwoWay}"
    IsPasswordRevealButtonEnabled="True"/> 

PickerFlyout (WP8.1)

Creates a custom flyout.

Windows Phone 8.1 appearance:

<StackPanel Margin="10">
    <Button 
        x:Name="ShowCustomFlyoutButton"
        Content="Show Custom Flyout"
        Click="OnClickShownCustomFlyout"/>
    
    <FlyoutBase.AttachedFlyout>
        <PickerFlyout x:Name="MyCustomFlyout">
            <StackPanel 
                Orientation="Vertical" 
                Width="250"
                Height="500"
                Background="DarkBlue">
                <TextBox Header="Enter some text"/>
                <Button Content="Submit"/>
            </StackPanel>
        </PickerFlyout>
    </FlyoutBase.AttachedFlyout>
    
</StackPanel>
private async void OnClickShownCustomFlyout(object sender, RoutedEventArgs e)
{
    await MyCustomFlyout.ShowAtAsync(ShowCustomFlyoutButton);
}

Pivot (WP8.1)

Manages a horizontally scrolled collection of page-like pivot items.

Very similar to the Hub control. In general however, the Hub control is suited to displaying views of items that may be regarded as being on the same "logical page" (i.e. think of the Hub control as being a window into a larger page). The Pivot control is well suited to displaying items that represent distinct data sets.

Windows Phone 8.1 appearance:

<Pivot Title="My Pivot Example">
    <PivotItem Header="PivotItem#1">
        <ListView 
            ItemsSource="{Binding Foods}" 
            ItemTemplate="{StaticResource FoodDataTemplate}" />
    </PivotItem>

    <PivotItem Header="PivotItem#2">
        <StackPanel>
            <TextBlock Text="Some food..." FontSize="32"/>
            <Image Source="Images/italian/Italian_1_600_C.jpg"/>
        </StackPanel>
    </PivotItem>

    <PivotItem Header="PivotItem#3">
        <StackPanel>
            <TextBlock Text="More food..." FontSize="32"/>
            <Image Source="Images/italian/Italian_2_600_C.jpg"/>
        </StackPanel>
    </PivotItem>
</Pivot>

Polygon (Universal)

Shape.

Windows 8.1 and Windows Phone 8.1 appearance:

<Polygon 
    Fill="Red" 
    Points="0,0 200,200 0,200"/>

Polyline (Universal)

Shape.

Windows 8.1 and Windows Phone 8.1 appearance:

<Polyline 
    Margin="30"
    Stroke="Crimson"
    Points="0,0 200,200 300,100 300,200"/>

Defines a custom container for other XAML elements. In general, you should first consider using a Flyout, MenuFlyout, ToolTip, MessageDialog, etc.

Windows 8.1 and Windows Phone 8.1 appearance:

<StackPanel HorizontalAlignment="Center" Margin="10">
    <Button Content="Show Popup" Click="OnShowPopup"/>
    <Popup x:Name="MyPopup" VerticalOffset="10">
        <StackPanel 
            Background="CornflowerBlue" 
            HorizontalAlignment="Center">

            <TextBlock 
                Text="Hello" 
                Margin="20"
                TextAlignment="Center" 
                FontSize="32" 
                Foreground="Brown"/>

            <TextBlock 
                Text="World!" 
                Margin="20"
                TextAlignment="Center" 
                FontSize="32" 
                Foreground="Green"/>

            <Button 
                Content="Close" 
                Margin="20" 
                Click="OnClosePopup"/>
        </StackPanel>
    </Popup>
</StackPanel>
private void OnClosePopup(object sender, RoutedEventArgs e)
{
    if(MyPopup.IsOpen) MyPopup.IsOpen = false;
}

private void OnShowPopup(object sender, RoutedEventArgs e)
{
    if(!MyPopup.IsOpen) MyPopup.IsOpen = true;
}

ProgressBar (Universal)

Displays a progress bar. If the IsIndeterminate property is set to true then the bar will immediately display an animated progress bar, in which case the control may be shown/hidden as required using the Visibility property. Otherwise, the bar can be animated as shown in the following example:

Windows 8.1 and Windows Phone 8.1 appearance:

<StackPanel HorizontalAlignment="Center" Margin="10">
    <Button Content="Start Progress Bar" Click="OnStartProgressBar"/>
    <Button Content="Stop Progress Bar" Click="OnStopProgressBar"/>
    
    <ProgressBar 
        x:Name="MyProgBar" 
        IsIndeterminate="False" 
        Value="0" 
        Maximum="60"  />
</StackPanel>
private DispatcherTimer _timer;
:
:
private void OnStartProgressBar(object sender, RoutedEventArgs e)
{
    if(_timer == null)
    {
        _timer = new DispatcherTimer();
        _timer.Tick += (o, o1) =>
        {
            if(MyProgBar.Value == MyProgBar.Maximum) MyProgBar.Value = 0;
            else MyProgBar.Value++;
        };
    }

    if(_timer.IsEnabled) return;

    _timer.Interval = TimeSpan.FromSeconds(1);
    _timer.Start();
}

private void OnStopProgressBar(object sender, RoutedEventArgs e)
{
    if(_timer == null) _timer = new DispatcherTimer();
    if(!_timer.IsEnabled) return;

    _timer.Stop();
}

ProgressRing (Universal)

Displays a progress ring.

Windows 8.1 and Windows Phone 8.1 appearance:

<StackPanel HorizontalAlignment="Center" Margin="10">
    <Button Content="Start Progress Ring" Click="OnStartProgressRing"/>
    <Button Content="Stop Progress Ring" Click="OnStopProgressRing"/>

    <ProgressRing x:Name="MyProgRing" />
</StackPanel>
private void OnStartProgressRing(object sender, RoutedEventArgs e)
{
    MyProgRing.IsActive = true;
}

private void OnStopProgressRing(object sender, RoutedEventArgs e)
{
    MyProgRing.IsActive = false;
}

RadioButton (Universal)

Allows the selection of a single item in a group.

Windows 8.1 and Windows Phone 8.1 appearance:

<RadioButton Content="Item #1" Checked="OnR1Checked"/>
<RadioButton Content="Item #2" Checked="OnR2Checked" IsChecked="True"/>
<RadioButton Content="Item #3" Checked="OnR3Checked" />

Rectangle (Universal)

Shape.

<Rectangle Fill="Crimson" Width="100" Height="100"/>

RepeatButton (Universal)

A button that raises a Click event repeatedly until released.

<RepeatButton Content="Fire!" Click="OnFireButton"/>

RichEditBox (Universal)

Text box with rich (e.g. RTF) formatting.

Windows 8.1 and Windows Phone 8.1 appearance:

<Button Content="Load RTF..." Click="OnLoadRtf"/>
<RichEditBox x:Name="MyEditor" />
private async void OnLoadRtf(object sender, RoutedEventArgs e)
{
    try
    {
        var file = await Package.Current.InstalledLocation.GetFileAsync("test.rtf");
        if(file == null) return;

        var stream = await file.OpenAsync(FileAccessMode.Read);
        if(stream == null) return;

        MyEditor.Document.LoadFromStream(TextSetOptions.FormatRtf, stream);
    }
    catch(Exception ex)
    {
        Debug.WriteLine("Error loading file: {0}", ex.Message);    
    }
}

RichTextBlock (Universal)

Same as TextBlock but with rich formatting.

Windows 8.1 and Windows Phone 8.1 appearance:

<RichTextBlock>
    <Paragraph FontSize="26">
        <Bold Foreground="Crimson">Hello</Bold>
        <Italic Foreground="CornflowerBlue">World!</Italic>
        <InlineUIContainer>
            <Image Source="Images/indian/Indian_1_600_C.jpg"/>
        </InlineUIContainer>
        <Bold>Nice eh?!</Bold>
    </Paragraph>
</RichTextBlock>

ScrollBar (Universal)

Scrollbar with thumb.

Windows 8.1 appearance:

<ScrollBar 
    Orientation="Horizontal" 
    IndicatorMode="MouseIndicator"
    Value="50"
    Height="50"
    Scroll="OnScroll"
    Maximum="100" />
private void OnScroll(object sender, ScrollEventArgs e)
{
    Debug.WriteLine("Scrolled: {0}", e.NewValue);
}

ScrollViewer (Universal)

Presents content in a view that may be panned and zoomed.

Windows 8.1 appearance:

<ScrollViewer 
    ZoomMode="Enabled" 
    MaxZoomFactor="10" 
    HorizontalScrollMode="Enabled" 
    HorizontalScrollBarVisibility="Visible"
    VerticalScrollMode="Enabled"
    VerticalScrollBarVisibility="Visible"
    Height="200" 
    Width="200">
    <Image Source="Images/italian/Italian_4_600_C.jpg"/>
</ScrollViewer>

Provides a standarized in-app search mechanism.

Windows 8.1 appearance:

<SearchBox 
    Height="35" 
    Width="270"
    Margin="10" 
    PlaceholderText="Search..."
    QuerySubmitted="SearchQuerySubmitted"/>

<TextBlock 
    x:Name="SearchResults" 
    Width="270"
    FontSize="24"
    Margin="5" />
private void SearchQuerySubmitted(SearchBox sender, SearchBoxQuerySubmittedEventArgs args)
{
    var searchText = args.QueryText;

    SearchResults.Text = "Found " + searchText;

    // TODO: Add actual in-app search mechanism
}

SemanticZoom (Universal)

Allows the user to zoom between two views (zoomed-in/zoomed-out) of a collection of items.

Windows 8.1 and Windows Phone 8.1 appearance:

<StackPanel HorizontalAlignment="Center" Margin="10" Width="350">

    <SemanticZoom 
        x:Name="MySemanticZoom"
        IsZoomOutButtonEnabled="True" 
        CanChangeViews="True">
        <SemanticZoom.ZoomedInView>
            <GridView>
                <TextBlock Text="Zoomed In" Foreground="Red" FontSize="32"/>
            </GridView>
        </SemanticZoom.ZoomedInView>
        
        <SemanticZoom.ZoomedOutView>
            <GridView>
                <TextBlock Text="Zoomed Out" Foreground="Blue" FontSize="32"/>
            </GridView>
        </SemanticZoom.ZoomedOutView>
    </SemanticZoom>

</StackPanel>

Note that I found that I couldn't get semantic zoom to work on Windows Phone 8.1 in the emulator. Even the following code failed to switch views:

private void OnZoom(object sender, RoutedEventArgs e)
{
    MySemanticZoom.ToggleActiveView();
}

SettingsFlyout (Win8.1)

Displays a settings flyout for the app.

The easiest way to create a new SettingsFlyout is via Project | Add New Item:

Windows 8.1 appearance:

<SettingsFlyout
    x:Class="WPVersesWin81.SettingsFlyout1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    IconSource="Images/chinese/Chinese_1_150_C.jpg"
    Title="My Settings"
    d:DesignWidth="346">

    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch" >

        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">

            <TextBlock Style="{StaticResource TitleTextBlockStyle}" Text="Main Settings" />
            <TextBox Header="Name:" />
            <ToggleSwitch Header="Lights"/>

            <TextBlock Style="{StaticResource TitleTextBlockStyle}" Text="Optional Settings" />
            <ToggleSwitch Header="Turbo"/>
        </StackPanel>
    </StackPanel>
</SettingsFlyout>
private void OnShowSettings(object sender, RoutedEventArgs e)
{
    var settings = new SettingsFlyout1();
    settings.Show();
}

Normally, you'd want to wire-up the settings fly to the Settings Charm as follows:

public MainPage()
{
    this.InitializeComponent();

    // Hook up our settings flyout...
    Windows.UI.ApplicationSettings.SettingsPane.GetForCurrentView().CommandsRequested 
        += CommandsRequested;
}

private void CommandsRequested(
    SettingsPane sender, 
    SettingsPaneCommandsRequestedEventArgs args)
{
    var settingsCommand = new Windows.UI.ApplicationSettings.SettingsCommand(
        "AppUpdateSettings", 
        "My Settings", 
        command =>
        {
            var settingsFlyout = new SettingsFlyout1();
            settingsFlyout.Show();
        });

    args.Request.ApplicationCommands.Add(settingsCommand);
}

Slider (Universal)

Allows the user to quickly specify a value by moving a thumb control.

Windows 8.1 and Windows Phone 8.1 appearance:

<Slider 
    x:Name="MySlider" 
    Minimum="0" 
    Maximum="20" />

<TextBox 
    Header="Value:" 
    Text="{Binding ElementName=MySlider, Path=Value}"/>

StackPanel (Universal)

Container that layouts out other elements in a horizontal or vertical fashion.

Windows 8.1 and Windows Phone 8.1 appearance:

<StackPanel HorizontalAlignment="Center" Margin="10" >
    <TextBlock Text="Test 1" FontSize="32"/>
    <TextBlock Text="Test 2" FontSize="32"/>
    <Button Content="Go"/>
</StackPanel>

TextBlock (Universal)

Displays text (non-editable).

<TextBlock Text="Test 1" FontSize="32"/>

TextBox (Universal)

Allows the user to edit text.

<TextBox Text="{Binding MyText}" FontSize="32"/>

TimePicker (Universal)

Time selection.

Windows 8.1 appearance:

Windows Phone 8.1 appearance:

<TimePicker 
    Header="Select the time:" 
    TimeChanged="OnTimeChanged"
    Time="{Binding MyTimeSpan, Mode=TwoWay}"/>

TimePickerFlyout (WP8.1)

Displays a full-screen time picker.

<Button Content="Select time">
    <Button.Flyout>
        <TimePickerFlyout Time="{Binding MyTimeSpan, Mode=TwoWay}"/>
    </Button.Flyout>
</Button>

ToggleButton (Universal)

A button which can represent two states.

Windows 8.1 and Windows Phone 8.1 appearance:

<Page.Resources>
    <local:BoolToStringConverter x:Key="MyBoolToStringConverter"/>
</Page.Resources>

<Grid>
    <StackPanel HorizontalAlignment="Center" Margin="10">
        <ToggleButton 
            x:Name="MyToggleButton"
            Content="Toggle Me" />
        
        <TextBlock 
            FontSize="24"
            Text="{
                Binding ElementName=MyToggleButton, 
                Path=IsChecked, 
                Converter={StaticResource MyBoolToStringConverter}}"/>
    </StackPanel>
</Grid>

ToggleSwitch (Universal)

Displays an "on/off" switch representing a boolean value.

Windows 8.1 and Windows Phone 8.1 appearance:

<ToggleSwitch Header="Power"/>

Tooltip (Universal)

Displays context help for an element.

Windows 8.1 and Windows Phone 8.1 appearance:

<Button 
    Content="Click Me" 
    ToolTipService.ToolTip="Clicking this button is strictly prohibited!" />

UserControl (Universal)

Allows the creation of custom controls.

The easiest way to create a new UserControl is via Project | Add New Item. The UserControl may then be defined as in the following example:

<UserControl
    x:Class="WPVersesWin81.MyUserControl"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:WPVersesWin81"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300"
    d:DesignWidth="400">
    
    <Grid>
        <StackPanel>
            <TextBox x:Name="ATextBox" Header="Some text:"/>
            <Button x:Name="AButton" Content="Click Me" Click="AButton_OnClick"/>
        </StackPanel>
    </Grid>
</UserControl>

Using the control on a Page is simple:

<StackPanel HorizontalAlignment="Center" Margin="10" >
    <local:MyUserControl />
</StackPanel>

VariableSizedWrapGrid (Universal)

Display items in multiple rows and columns. See also WrapGrid.

Windows 8.1 and Windows Phone 8.1 appearance:

<VariableSizedWrapGrid 
    MaximumRowsOrColumns="3"  
    VerticalChildrenAlignment="Center"
    HorizontalChildrenAlignment="Center"
    ItemHeight="50" 
    ItemWidth="50">
    
    <Rectangle 
        Fill="Red"
        Width="25"/>
    
    <Rectangle 
        Fill="Green" 
        Height="25" 
        VariableSizedWrapGrid.RowSpan="2"/>
    
    <Rectangle 
        Fill="Blue" 
        Width="100" 
        VariableSizedWrapGrid.ColumnSpan="2"/>
    
    <Rectangle 
        Fill="Magenta" 
        Height="80" 
        Width="80" 
        VariableSizedWrapGrid.RowSpan="2" 
        VariableSizedWrapGrid.ColumnSpan="2"/>

Viewbox (Universal)

Container that scales content to a specific size.

<Viewbox MaxWidth="300" MaxHeight="300">
    <Image Source="Images/indian/Indian_1_600_C.jpg"/>
</Viewbox>

WebView (Universal)

Displays a browser.

<WebView Source="http://bbc.co.uk"/>

WrapGrid (Universal)

Display items in multiple rows and columns. See also VariableSizedWrapGrid.

Windows 8.1 and Windows Phone 8.1 appearance:

<ListView 
    HorizontalAlignment="Center"
    ItemsSource="{Binding Foods}"
    ItemTemplate="{StaticResource FoodDataTemplate}">
    <ListView.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid Orientation="Horizontal" MaximumRowsOrColumns="3"/>
        </ItemsPanelTemplate>
    </ListView.ItemsPanel>
</ListView>