Breadcrumbs

[CodenStuff]

Basic Settings Page

One of the elements when developing Metro Apps Windows 8 Apps that is easy to forget about is the use of the settings pane. The settings pane is used to display settings panels for adjusting various app settings like turning sounds or music on/off, changing display colours etc but is also used to display information about how to use the app.

To can read more about how app settings should be used: http://msdn.microsoft.com/en-us/library ... 70544.aspx

I think if using Javascript it includes a flayout control to make the process of adding settings easy but in XAML there is no such control at least not yet that I am aware of so you have to contain it within a popup instead and although a App settings example is available from the dev center it doesnt actually include the setting flyout display so after some research I managed to get it working with the following code.

This tutorial will show you how to make a basic About settings page.



You may need to add the following imports to the code files:

Code: Select all

Imports Windows.UI.Popups
Imports Windows.UI.ApplicationSettings

First start a new project and call it 'SettingsTest'

To start with lets make the settings flyout itself so add a custom control to your project and call it 'AboutPage'

Now open up its XAML design view and replace the code with this:

Code: Select all

<UserControl
    x:Class="SettingsTest.AboutPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SettingsTest"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="768"
    d:DesignWidth="346">

    <UserControl.Resources>
        <Style x:Key="SettingsBackButtonStyle" TargetType="Button">
            <Setter Property="MinWidth" Value="0"/>
            <Setter Property="FontFamily" Value="Segoe UI Symbol"/>
            <Setter Property="FontWeight" Value="Normal"/>
            <Setter Property="FontSize" Value="36.66667"/>
            <Setter Property="AutomationProperties.AutomationId" Value="BackButton"/>
            <Setter Property="AutomationProperties.Name" Value="Back"/>
            <Setter Property="AutomationProperties.ItemType" Value="Navigation Button"/>
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="Button">
                        <Grid x:Name="RootGrid" Margin="0,0,0,0">
                            <Grid Margin="0,-9,0,0">
                                <TextBlock x:Name="BackgroundGlyph" Text="&#xE0A8;" Foreground="{StaticResource BackButtonBackgroundThemeBrush}"/>
                                <TextBlock x:Name="NormalGlyph" Text="{StaticResource BackButtonGlyph}" Foreground="{StaticResource BackButtonForegroundThemeBrush}"/>
                                <TextBlock x:Name="ArrowGlyph" Text="&#xE0A6;" Foreground="{StaticResource BackButtonPressedForegroundThemeBrush}" Opacity="0"/>
                            </Grid>
                            <Rectangle
                            x:Name="FocusVisualWhite"
                            IsHitTestVisible="False"
                            Stroke="{StaticResource FocusVisualWhiteStrokeThemeBrush}"
                            StrokeEndLineCap="Square"
                            StrokeDashArray="1,1"
                            Opacity="0"
                            StrokeDashOffset="1.5"/>
                            <Rectangle
                            x:Name="FocusVisualBlack"
                            IsHitTestVisible="False"
                            Stroke="{StaticResource FocusVisualBlackStrokeThemeBrush}"
                            StrokeEndLineCap="Square"
                            StrokeDashArray="1,1"
                            Opacity="0"
                            StrokeDashOffset="0.5"/>
                            <VisualStateManager.VisualStateGroups>
                                <VisualStateGroup x:Name="CommonStates">
                                    <VisualState x:Name="Normal" />
                                    <VisualState x:Name="PointerOver">
                                        <Storyboard>
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundGlyph" Storyboard.TargetProperty="Foreground">
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource BackButtonPointerOverBackgroundThemeBrush}"/>
                                            </ObjectAnimationUsingKeyFrames>
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="NormalGlyph" Storyboard.TargetProperty="Foreground">
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource BackButtonPointerOverForegroundThemeBrush}"/>
                                            </ObjectAnimationUsingKeyFrames>
                                        </Storyboard>
                                    </VisualState>
                                    <VisualState x:Name="Pressed">
                                        <Storyboard>
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundGlyph" Storyboard.TargetProperty="Foreground">
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource BackButtonForegroundThemeBrush}"/>
                                            </ObjectAnimationUsingKeyFrames>
                                            <DoubleAnimation
                                            Storyboard.TargetName="ArrowGlyph"
                                            Storyboard.TargetProperty="Opacity"
                                            To="1"
                                            Duration="0"/>
                                            <DoubleAnimation
                                            Storyboard.TargetName="NormalGlyph"
                                            Storyboard.TargetProperty="Opacity"
                                            To="0"
                                            Duration="0"/>
                                        </Storyboard>
                                    </VisualState>
                                    <VisualState x:Name="Disabled">
                                        <Storyboard>
                                            <ObjectAnimationUsingKeyFrames Storyboard.TargetName="RootGrid" Storyboard.TargetProperty="Visibility">
                                                <DiscreteObjectKeyFrame KeyTime="0" Value="Collapsed"/>
                                            </ObjectAnimationUsingKeyFrames>
                                        </Storyboard>
                                    </VisualState>
                                </VisualStateGroup>
                                <VisualStateGroup x:Name="FocusStates">
                                    <VisualState x:Name="Focused">
                                        <Storyboard>
                                            <DoubleAnimation
                                            Storyboard.TargetName="FocusVisualWhite"
                                            Storyboard.TargetProperty="Opacity"
                                            To="1"
                                            Duration="0"/>
                                            <DoubleAnimation
                                            Storyboard.TargetName="FocusVisualBlack"
                                            Storyboard.TargetProperty="Opacity"
                                            To="1"
                                            Duration="0"/>
                                        </Storyboard>
                                    </VisualState>
                                    <VisualState x:Name="Unfocused" />
                                    <VisualState x:Name="PointerFocused" />
                                </VisualStateGroup>
                            </VisualStateManager.VisualStateGroups>
                        </Grid>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>
    </UserControl.Resources>

    <Border BorderBrush="Black" BorderThickness="1,0,0,0">
        <Grid Background="#FFFDFEFF" VerticalAlignment="Stretch">
            <!-- Root grid definition -->
            <Grid.RowDefinitions>
                <RowDefinition Height="80" />
                <RowDefinition Height="*" />
            </Grid.RowDefinitions>

            <!-- Header area for panel -->
            <Grid Background="#FF09ACB4" Grid.Row="0">
                <Grid Margin="10,32,17,13">
                    <Grid.Transitions>
                        <TransitionCollection>
                            <EntranceThemeTransition FromHorizontalOffset="50" />
                        </TransitionCollection>
                    </Grid.Transitions>
                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="30" />
                        <ColumnDefinition Width="*" />
                        <ColumnDefinition />
                    </Grid.ColumnDefinitions>
                    <Button x:Name="SettingsGoBack" Margin="5,0,0,0" Grid.Column="0" HorizontalAlignment="Left" Grid.ColumnSpan="2" Height="35" Width="35" Style="{StaticResource SettingsBackButtonStyle}"/>
                    <TextBlock Margin="27,0,0,0" Grid.Column="1" FontFamily="Segoe UI" FontWeight="SemiLight" FontSize="24.6667" Text="About" HorizontalAlignment="Left" Grid.ColumnSpan="2" Width="251" />
                </Grid>
            </Grid>

            <!-- Settings Panel Content -->
            <Grid Grid.Row="1" Margin="25,24,23,0" VerticalAlignment="Top" Height="219">
                <Grid.Transitions>
                    <TransitionCollection>
                        <EntranceThemeTransition FromHorizontalOffset="120" />
                    </TransitionCollection>
                </Grid.Transitions>
                <TextBlock HorizontalAlignment="Left" TextWrapping="Wrap" Text="PUT YOUR CONTENT IN HERE" VerticalAlignment="Top" Height="127" Width="297" Foreground="#FFF50909" FontSize="36" TextAlignment="Center"/>
            </Grid>

        </Grid>
    </Border>
</UserControl>

After adding that code the designer should automatically adjust to show the new flyout template. You have a back button a title and the main page content and when you are ready to add it to your main project you can simply adjust the title and content to whatever you want to display in there.

Now go into the AboutPage code view and add this button event:

Code: Select all

    Private Sub SettingsGoBack_Click(sender As Object, e As RoutedEventArgs) Handles SettingsGoBack.Click
        If Me.Parent.GetType() Is GetType(Popup) Then
            DirectCast(Me.Parent, Popup).IsOpen = False
        End If
        SettingsPane.Show()
    End Sub

Now when the user presses the back button it closes the AboutPage and displays the main settings pane.

Now we add a ridiculously large amount of code to make it work so we can see our AboutPage in the settings pane.

Open up the App.xaml.vb file and add the code below.

First declare our popup:

Code: Select all

Dim SettingsPopup As Popup

In the OnLaunched event add this handler to activate when the settings pane is opened

Code: Select all

        'Add handler for when the settings pane is opened
        AddHandler SettingsPane.GetForCurrentView().CommandsRequested, AddressOf Settings_CommandsRequested

Now add the handler:

Code: Select all

    Private Sub Settings_CommandsRequested(sender As SettingsPane, args As SettingsPaneCommandsRequestedEventArgs)
        'Add the setting to the settings pane
        args.Request.ApplicationCommands.Add(New SettingsCommand("AboutSettings", "About", New UICommandInvokedHandler(AddressOf FlyOut)))
    End Sub

When the settings pane is opened it will add a new option to it called "About". Notice in the code above we create a new settings command and the first value we give it a unique ID, the second value is the title of our setting and last is the settings handler ie the code which runs when we click the setting option.

New SettingsCommand("UniqueID", "Title", Handler)

Now we add our code to create the popup/settings flyout when the user clicks the About option:

Code: Select all

    Public Sub FlyOut(command As IUICommand)
        'Create the popup that will hold our template
        SettingsPopup = New Popup()
        AddHandler SettingsPopup.Closed, AddressOf OnPopupClosed
        AddHandler Window.Current.Activated, AddressOf OnWindowActivated
        SettingsPopup.IsLightDismissEnabled = True
        SettingsPopup.Width = 346
        SettingsPopup.Height = Window.Current.Bounds.Height

        'Create an instance of our AboutPage control and size it to fit the screen
        Dim About As New AboutPage
        About.Width = 346
        About.Height = Window.Current.Bounds.Height

        'Fill the popup with our template and show it on screen
        SettingsPopup.Child = About
        SettingsPopup.SetValue(Canvas.LeftProperty, Window.Current.Bounds.Width - 346)
        SettingsPopup.SetValue(Canvas.TopProperty, 0)
        SettingsPopup.IsOpen = True
    End Sub

Settings flyouts can be of 2 sizes in width either 346 or 646 depending on what you need to display but the most common will be 346.

Now we add 2 more events to handle popup closed and window activated:

Code: Select all

    Private Sub OnWindowActivated(sender As Object, e As Windows.UI.Core.WindowActivatedEventArgs)
        If e.WindowActivationState = Windows.UI.Core.CoreWindowActivationState.Deactivated Then
            SettingsPopup.IsOpen = False
        End If
    End Sub

    Private Sub OnPopupClosed(sender As Object, e As Object)
        RemoveHandler Window.Current.Activated, AddressOf OnWindowActivated
    End Sub

OnWindowActivated occurs when the user clicks in an area outside the settings pane so it closes and when the popup/settings flyout is OnPopupClosed it removes the handler.

You should now be able to build and run the code to see it in action. Run the app and open the settings pane by swiping top or bottom-right of the screen and you should see the About page listed on it.



Now you know the basics of adding a settings page

Feel free to add your own bits of code to this tutorial or if you know an easier simpler way please share it lol.