Adding app settings
Use the Settings contract to let users access your app's settings from the Settings charm.
Why use the Settings contract?
- Provide users with fast, in-context access to settings that affect their current Windows Store app. A light-dismiss settings UI allows users to quickly adjust the behavior of the app and resume their previous app activity.
- Expose app-specific settings along with settings and information automatically exposed by the system.
- Provide access to your settings UI without sacrificing app real estate or having to build navigation to and from a settings page.
All Windows Store apps automatically participate in the Settings contract. Even if you never modify your app's settings, a user will be able to click on the Settings charm from within your app and see a default Settings pane. This pane is always 346 pixels wide and contains a list of up to seven settings commands. If a user clicks on one of these commands, the Settings flyout associated with that command replaces the Settings pane onscreen. The default, system-provided Settings pane includes a "Permissions" command and, once your app is installed, a "Rate and review" command that sends a user's feedback about your app directly to the Windows Store.
In addition to these two default commands, you can add custom settings to the Settings pane displayed in your app by Windows. The following topics show you how to create a new Settings flyout (WinJS.UI.Flyout) for your app and add a custom command to the Settings pane that'll open it.
If you’d like to try working with app settings and other key Windows 8 features, download the hands-on labs for Windows 8. These labs provide a modular, step-by-step introduction to creating a sample Windows Store app in the programming language of your choice (JavaScript and HTML or C# and XAML).
See the sample: For an example of how to integrate new settings with the Settings charm, download the App settings sample.
Using C#/VB/C++ and XAML? See the topics in the Adding app settings (Windows Store apps using C#/VB/C++ and XAML) section.
In this section
| Topic | Description |
|---|---|
This Quickstart walks you through implementing the Settings contract by using HTML and the SettingsFlyout class for the Windows Library for JavaScript. |
|
This quickstart walks you through implementing the Settings contract using Windows Runtime classes. However, we recommend you should instead follow the steps in the Quickstart: Adding app settings using Windows Library for JavaScript. |
|
For Windows Store apps, all settings are applied as soon as the user changes their values. This model is important because the user can walks you through instantly committing settings using the WinJS Settings flyout and local application data. |