How to create a settings page for Windows Phone 8
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
This topic introduces you to the steps needed to create a Settings page for your Windows Phone app.
This topic contains the following sections.
- Create a Settings Class
- Creating a Settings page that doesn’t require a confirmation button
- Creating a Settings page that requires a confirmation button
- Related Topics
Create a Settings Class
The first step in creating a Settings page for your Windows Phone app is to create a class to hold your settings and to save and load your settings from the local folder. For more information about how to store settings in key-value pairs in the local folder, see IsolatedStorageSettings. For more information about data storage in general, see Data for Windows Phone 8.
The class will contain a method to add or update a value in the local folder. In the following code, it is called AddOrUpdateValue. There is also a method to read a value or assign a default value if the setting has never been set. In the following code, it is called GetValueOrDefault.
For each setting or property, there are accessor functions. The following code contains several, called CheckBoxSetting, ListBoxSetting, and PasswordSetting. You can add your own properties by adding in your own accessor functions. For each setting, there is a string constant that defines the key name, and a constant that defines the default value.
using System;
using System.IO.IsolatedStorage;
using System.Diagnostics;
using System.Collections.Generic;
namespace SettingsSample
{
public class AppSettings
{
// Our settings
IsolatedStorageSettings settings;
// The key names of our settings
const string CheckBoxSettingKeyName = "CheckBoxSetting";
const string ListBoxSettingKeyName = "ListBoxSetting";
const string RadioButton1SettingKeyName = "RadioButton1Setting";
const string RadioButton2SettingKeyName = "RadioButton2Setting";
const string RadioButton3SettingKeyName = "RadioButton3Setting";
const string UsernameSettingKeyName = "UsernameSetting";
const string PasswordSettingKeyName = "PasswordSetting";
// The default value of our settings
const bool CheckBoxSettingDefault = true;
const int ListBoxSettingDefault = 0;
const bool RadioButton1SettingDefault = true;
const bool RadioButton2SettingDefault = false;
const bool RadioButton3SettingDefault = false;
const string UsernameSettingDefault = "";
const string PasswordSettingDefault = "";
/// <summary>
/// Constructor that gets the application settings.
/// </summary>
public AppSettings()
{
// Get the settings for this application.
settings = IsolatedStorageSettings.ApplicationSettings;
}
/// <summary>
/// Update a setting value for our application. If the setting does not
/// exist, then add the setting.
/// </summary>
/// <param name="Key"></param>
/// <param name="value"></param>
/// <returns></returns>
public bool AddOrUpdateValue(string Key, Object value)
{
bool valueChanged = false;
// If the key exists
if (settings.Contains(Key))
{
// If the value has changed
if (settings[Key] != value)
{
// Store the new value
settings[Key] = value;
valueChanged = true;
}
}
// Otherwise create the key.
else
{
settings.Add(Key, value);
valueChanged = true;
}
return valueChanged;
}
/// <summary>
/// Get the current value of the setting, or if it is not found, set the
/// setting to the default setting.
/// </summary>
/// <typeparam name="T"></typeparam>
/// <param name="Key"></param>
/// <param name="defaultValue"></param>
/// <returns></returns>
public T GetValueOrDefault<T>(string Key, T defaultValue)
{
T value;
// If the key exists, retrieve the value.
if (settings.Contains(Key))
{
value = (T)settings[Key];
}
// Otherwise, use the default value.
else
{
value = defaultValue;
}
return value;
}
/// <summary>
/// Save the settings.
/// </summary>
public void Save()
{
settings.Save();
}
/// <summary>
/// Property to get and set a CheckBox Setting Key.
/// </summary>
public bool CheckBoxSetting
{
get
{
return GetValueOrDefault<bool>(CheckBoxSettingKeyName, CheckBoxSettingDefault);
}
set
{
if (AddOrUpdateValue(CheckBoxSettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a ListBox Setting Key.
/// </summary>
public int ListBoxSetting
{
get
{
return GetValueOrDefault<int>(ListBoxSettingKeyName, ListBoxSettingDefault);
}
set
{
if (AddOrUpdateValue(ListBoxSettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a RadioButton Setting Key.
/// </summary>
public bool RadioButton1Setting
{
get
{
return GetValueOrDefault<bool>(RadioButton1SettingKeyName, RadioButton1SettingDefault);
}
set
{
if (AddOrUpdateValue(RadioButton1SettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a RadioButton Setting Key.
/// </summary>
public bool RadioButton2Setting
{
get
{
return GetValueOrDefault<bool>(RadioButton2SettingKeyName, RadioButton2SettingDefault);
}
set
{
if (AddOrUpdateValue(RadioButton2SettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a RadioButton Setting Key.
/// </summary>
public bool RadioButton3Setting
{
get
{
return GetValueOrDefault<bool>(RadioButton3SettingKeyName, RadioButton3SettingDefault);
}
set
{
if (AddOrUpdateValue(RadioButton3SettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a Username Setting Key.
/// </summary>
public string UsernameSetting
{
get
{
return GetValueOrDefault<string>(UsernameSettingKeyName, UsernameSettingDefault);
}
set
{
if (AddOrUpdateValue(UsernameSettingKeyName, value))
{
Save();
}
}
}
/// <summary>
/// Property to get and set a Password Setting Key.
/// </summary>
public string PasswordSetting
{
get
{
return GetValueOrDefault<string>(PasswordSettingKeyName, PasswordSettingDefault);
}
set
{
if (AddOrUpdateValue(PasswordSettingKeyName, value))
{
Save();
}
}
}
}
}
Creating a Settings page that doesn’t require a confirmation button
For pages that do not require the user to press a confirmation button, you can use data binding to make the settings changes effective immediately and save the values in the local folder. All changes are made in the XAML for the settings page. Note that the data-binding mode of TwoWay makes the changes effective immediately.
Note
For guidelines about designing the UI of your Settings page, see the Design library for Windows Phone.
Start by adding the xmlns:local="clr-namespace:SettingsSample" namespace declaration to the phone:PhoneApplicationPage element of your page. The following code shows the namespace declaration from the SettingsWithoutConfirmation.xaml page.
<phone:PhoneApplicationPage
x:Class="SettingsSample.SettingsWithoutConfirmation"
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://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"
xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:local="clr-namespace:SettingsSample"
FontFamily="{StaticResource PhoneFontFamilyNormal}"
FontSize="{StaticResource PhoneFontSizeNormal}"
Foreground="{StaticResource PhoneForegroundBrush}"
SupportedOrientations="Portrait" Orientation="Portrait"
mc:Ignorable="d" d:DesignHeight="768" d:DesignWidth="480"
shell:SystemTray.IsVisible="True">
Then, add the <local:AppSettings x:Key="appSettings"></local:AppSettings> local resource.
<phone:PhoneApplicationPage.Resources>
<local:AppSettings x:Key="appSettings"></local:AppSettings>
</phone:PhoneApplicationPage.Resources>
For each setting on the page, set up the data binding from the property to the control.
<Grid x:Name="ContentGrid" Grid.Row="1">
<CheckBox Content="CheckBox Setting" Height="Auto" HorizontalAlignment="Left" Margin="60,20,0,0" Name="checkBoxSetting" VerticalAlignment="Top"
IsChecked="{Binding Source={StaticResource appSettings}, Path=CheckBoxSetting, Mode=TwoWay}" />
<ListBox Height="140" HorizontalAlignment="Left" Margin="70,150,0,0" Name="listBoxSetting"
VerticalAlignment="Top" Width="360" SelectedIndex="{Binding Source={StaticResource appSettings}, Path=ListBoxSetting, Mode=TwoWay}">
<ListBoxItem Content="Times New Roman" FontSize="24" FontFamily="Times New Roman" />
<ListBoxItem Content="Arial" FontSize="24" FontFamily="Arial" />
<ListBoxItem Content="Comic Sans MS" FontSize="24" FontFamily="Comic Sans MS" />
</ListBox>
<RadioButton Content="Choice One" Height="Auto" HorizontalAlignment="Left" Margin="60,0,0,235" Name="radioButton1" VerticalAlignment="Bottom" GroupName="GroupOne" IsChecked="{Binding Source={StaticResource appSettings}, Path=RadioButton1Setting, Mode=TwoWay}" />
<RadioButton Content="Choice Two" Height="Auto" HorizontalAlignment="Left" Margin="60,350,0,0" Name="radioButton2" VerticalAlignment="Top" GroupName="GroupOne" IsChecked="{Binding Source={StaticResource appSettings}, Path=RadioButton2Setting, Mode=TwoWay}"/>
<RadioButton Content="Choice Three" Height="Auto" HorizontalAlignment="Left" Margin="60,400,0,0" Name="radioButton3" VerticalAlignment="Top" GroupName="GroupOne" IsChecked="{Binding Source={StaticResource appSettings}, Path=RadioButton3Setting, Mode=TwoWay}"/>
</Grid>
No additional code or work is needed. The Settings page is complete.
Creating a Settings page that requires a confirmation button
Settings that require text input, such as a username or password, may require the user to press a confirmation button when input has been completed. For Settings pages like these, you can add an app bar to the constructor to add the OK and Cancel buttons to the page.
For pages that require the user to press a confirmation button, you can use one-way data binding to load the current value, but any changes that the user makes are not effective immediately.
Start by adding the xmlns:local="clr-namespace:SettingsSample" namespace declaration to the phone:PhoneApplicationPage element of your page. The following code shows the namespace declaration from the SettingsWithConfirmation.xaml page.
<phone:PhoneApplicationPage
x:Class="SettingsSample.SettingsWithConfirmation"
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://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"
xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:local="clr-namespace:SettingsSample"
FontFamily="{StaticResource PhoneFontFamilyNormal}"
FontSize="{StaticResource PhoneFontSizeNormal}"
Foreground="{StaticResource PhoneForegroundBrush}"
SupportedOrientations="Portrait" Orientation="Portrait"
mc:Ignorable="d" d:DesignHeight="768" d:DesignWidth="480"
shell:SystemTray.IsVisible="True">
Then, add the <local:AppSettings x:Key="appSettings"></local:AppSettings> local resource.
<phone:PhoneApplicationPage.Resources>
<local:AppSettings x:Key="appSettings"></local:AppSettings>
</phone:PhoneApplicationPage.Resources>
For each setting on the page, set up the one-way data binding from the property to the control.
<Grid x:Name="ContentGrid" Grid.Row="1">
<TextBlock Height="60" HorizontalAlignment="Left" Margin="65,12,0,0" Name="textBlock1" Text="Username" VerticalAlignment="Top" Width="169" />
<TextBox Height="78" HorizontalAlignment="Left" Margin="60,60,0,0" Name="textBoxUsername"
Text="{Binding Path=UsernameSetting, Mode=OneWay, Source={StaticResource appSettings}}" VerticalAlignment="Top" Width="274" />
<TextBlock Height="60" HorizontalAlignment="Left" Margin="65,160,0,0" Name="textBlock2" Text="Password" VerticalAlignment="Top" Width="169" />
<PasswordBox Height="78" HorizontalAlignment="Left" Margin="60,208,0,0" Name="passwordBoxPassword"
Password="{Binding Path=PasswordSetting, Mode=OneWay, Source={StaticResource appSettings}}" VerticalAlignment="Top" Width="274" />
</Grid>
In the constructor of the page, add an app bar that has OK and Cancel buttons.
public SettingsWithConfirmation()
{
InitializeComponent();
// Add an Application Bar that has a 'done' confirmation button and
// a 'cancel' button
ApplicationBar = new ApplicationBar();
ApplicationBar.IsMenuEnabled = true;
ApplicationBar.IsVisible = true;
ApplicationBar.Opacity = 1.0;
ApplicationBarIconButton doneButton = new ApplicationBarIconButton(new Uri("/Images/appbar.check.rest.png", UriKind.Relative));
doneButton.Text = "done";
doneButton.Click += new EventHandler(doneButton_Click);
ApplicationBarIconButton cancelButton = new ApplicationBarIconButton(new Uri("/Images/appbar.cancel.rest.png", UriKind.Relative));
cancelButton.Text = "cancel";
cancelButton.Click += new EventHandler(cancelButton_Click);
ApplicationBar.Buttons.Add(doneButton);
ApplicationBar.Buttons.Add(cancelButton);
}
If the user confirms the changes, the values are saved.
void doneButton_Click(object sender, EventArgs e)
{
settings.UsernameSetting = textBoxUsername.Text;
settings.PasswordSetting = passwordBoxPassword.Password;
NavigationService.GoBack();
}
However, if the user cancels the changes, we just navigate out of the page.
void cancelButton_Click(object sender, EventArgs e)
{
NavigationService.GoBack();
}