Implementing Application Preferences

In traditional desktop applications, preferences are application-specific settings used to configure the behavior or appearance of an application. iOS also supports application preferences, although not as an integral part of your application. Instead of each application displaying a custom user interface for its preferences, all application-level preferences are displayed using the system-supplied Settings application.

In order to integrate your custom application preferences into the Settings application, you must include a specially formatted settings bundle in the top-level directory of your application bundle. This settings bundle provides information about your application preferences to the Settings application, which is then responsible for displaying those preferences and updating the preferences database with any user-supplied values. At runtime, your application retrieves these preferences using the standard retrieval APIs. The sections that follow describe both the format of the settings bundle and the APIs you use to retrieve your preferences values.

Guidelines for Preferences

Adding your application preferences to the Settings application is most appropriate for productivity-style applications and in situations where you have preference values that are typically configured once and then rarely changed. For example, the Mail application uses these preferences to store the user’s account information and message-checking settings. Because the Settings application has support for displaying preferences hierarchically, manipulating your preferences from the Settings application is also more appropriate when you have a large number of preferences. Providing the same set of preferences in your application might require too many screens and might cause confusion for the user.

When your application has only a few options or has options that the user might want to change regularly, you should think carefully about whether the Settings application is the right place for them. For instance, utility applications provide custom configuration options on the back of their main view. A special control on the view flips it over to display the options, and another control flips the view back. For simple applications, this type of behavior provides immediate access to the application’s options and is much more convenient for the user than going to Settings.

For games and other full-screen applications, you can use the Settings application or implement your own custom screens for preferences. Custom screens are often appropriate in games because those screens are treated as part of the game’s setup. You can also use the Settings application for your preferences if you think it is more appropriate for your game flow.

If you do incorporate settings into the Settings application, be sure you respond to the NSUserDefaultsDidChangeNotification notification as described in ‚ÄúResponding to Changes in Your Application‚Äôs Settings.‚Äù

The Preferences Interface

The Settings application implements a hierarchical set of pages for navigating application preferences. The main page of the Settings application displays the system and third-party applications whose preferences can be customized. Selecting a third-party application takes the user to the preferences for that application.

Each application has at least one page of preferences, referred to as the main page. If your application has only a few preferences, the main page may be the only one you need. If the number of preferences gets too large to fit on the main page, however, you can add more pages. These additional pages become child pages of the main page. The user accesses them by tapping on a special type of preference, which links to the new page.

Each preference you display must be of a specific type. The type of the preference defines how the Settings application displays that preference. Most preference types identify a particular type of control that is used to set the preference value. Some types provide a way to organize preferences, however. Table 6-1 lists the different element types supported by the Settings application and points out how you might use each type to implement your own preference pages.

For detailed information about the format of each preference type, see Settings Application Schema Reference. To learn how to create and edit Setting page files, see “Adding and Modifying the Settings Bundle.”

The Settings Bundle

In iOS, you specify your application‚Äôs preferences through a special settings bundle. This bundle has the name Settings.bundle and resides in the top-level directory of your application‚Äôs bundle. This bundle contains one or more Settings Page files that provide detailed information about your application‚Äôs preferences. It may also include other support files needed to display your preferences, such as images or localized strings. Table 6-2 lists the contents of a typical settings bundle.

In addition to the settings bundle, your application bundle can contain a custom icon for your application settings. The Settings application displays the icon you provide next to the entry for your application preferences. For information about application icons and how you specify them, see “Application Icons.”

When the Settings application launches, it checks each custom application for the presence of a settings bundle. For each custom bundle it finds, it loads that bundle and displays the corresponding application‚Äôs name and icon in the Settings main page. When the user taps the row belonging to your application, Settings loads the Root.plist Settings Page file for your settings bundle and uses that file to display your application‚Äôs main page of preferences.

In addition to loading your bundle‚Äôs Root.plist Settings Page file, the Settings application also loads any language-specific resources for that file, as needed. Each Settings Page file can have an associated .strings file containing localized values for any user-visible strings. As it prepares your preferences for display, the Settings application looks for string resources in the user‚Äôs preferred language and substitutes them into your preferences page prior to display.

The Settings Page File Format

Each Settings Page file in your settings bundle is stored in the iPhone Settings property-list file format, which is a structured file format. The simplest way to edit Settings Page files is to use the built-in editor facilities of Xcode; see “Preparing the Settings Page for Editing.” You can also edit property-list files using the Property List Editor application that comes with the Xcode tools.

The root element of each Settings Page file contains the keys listed in Table 6-3. Only one key is actually required, but it is recommended that you include both of them.

Hierarchical Preferences

If you plan to organize your preferences hierarchically, each page you define must have its own separate .plist file. Each .plist file contains the set of preferences displayed only on that page. Your application‚Äôs main preferences page is always stored in the Root.plist file. Additional pages can be given any name you like.

To specify a link between a parent page and a child page, you include a child pane element in the parent page. A child pane element creates a row that, when tapped, displays a new page of settings. The File key of the child pane element identifies the name of the .plist file that defines the contents of the child page. The Title key identifies the title of the child page; this title is also used as the text of the row that the user taps to display the child page. The Settings application automatically provides navigation controls on the child page to allow the user to navigate back to the parent page.

Figure 6-1 shows how this hierarchical set of pages works. The left side of the figure shows the .plist files, and the right side shows the relationships between the corresponding pages.

Figure 6-1  Organizing preferences using child panes

For more information about child pane elements and their associated keys, see Settings Application Schema Reference.

Localized Resources

Because preferences contain user-visible strings, you should provide localized versions of those strings with your settings bundle. Each page of preferences can have an associated .strings file for each localization supported by your bundle. When the Settings application encounters a key that supports localization, it checks the appropriately localized .strings file for a matching key. If it finds one, it displays the value associated with that key.

When looking for localized resources such as .strings files, the Settings application follows the same rules that Mac OS X applications do. It first tries to find a localized version of the resource that matches the user‚Äôs preferred language setting. If a resource does not exist for the user‚Äôs preferred language, an appropriate fallback language is selected.

For information about the format of strings files, language-specific project directories, and how language-specific resources are retrieved from bundles, see Internationalization Programming Topics.

Adding and Modifying the Settings Bundle

Xcode provides a template for adding a Settings bundle to your current project. The default settings bundle contains a Root.plist file and a default language directory for storing any localized resources. You can then expand this bundle to include additional property list files and resources needed by your settings bundle.

Adding the Settings Bundle

To add a settings bundle to your Xcode project:

1. Choose File > New File.

2. Choose the iPhone OS > Settings > Settings Bundle template.

3. Name the file Settings.bundle.

In addition to adding a new settings bundle to your project, Xcode automatically adds that bundle to the Copy Bundle Resources build phase of your application target. Thus, all you have to do is modify the property list files of your settings bundle and add any needed resources.

The newly added Settings.bundle bundle has the following structure:

Settings.bundle/

    Root.plist

    en.lproj/

        Root.strings

Preparing the Settings Page for Editing

After creating your settings bundle using the Settings Bundle template, you can format the contents of your schema files to make them easier to edit. The following steps show you how to do this for the Root.plist file of your settings bundle but the steps are the same for any other schema files you create.

1. Display the contents of the Root.plist file of your settings bundle.

   1. In the Groups & Files list, disclose Settings.bundle to view its contents.

   2. Select the Root.plist file. Its contents appear in the Detail view.

2. In the Detail view, select the Root key of the Root.plist file.

3. Choose View > Property List Type > iPhone Settings plist.

   This command formats the contents of the property list inside the Detail view. Instead of showing the property list key names and values, Xcode substitutes human-readable strings (as shown in Figure 6-2) to make it easier for you to understand and edit the file’s contents.

   Figure 6-2  Formatted contents of the Root.plist file

   

Configuring a Settings Page: A Tutorial

This section contains a tutorial that shows you how to configure a Settings page to display the controls you want. The goal of the tutorial is to create a page like the one in Figure 6-3. If you have not yet created a settings bundle for your project, you should do so as described in “Preparing the Settings Page for Editing” before proceeding with these steps.

Figure 6-3  A root Settings page

1. Change the value of the Settings Page Title key to the name of your application.

   Double-click the YOUR_PROJECT_NAME text and change the text to MyApp.

2. Disclose the Preference Items key to display the default items that come with the template.

3. Change the title of Item 1 to Sound.

   • Disclose Item 1 of Preference Items.

   • Change the value of the Title key from Group to Sound.

   • Leave the Type key set to Group.

4. Create the first toggle switch for the newly renamed Sound group.

   • Select Item 3 of Preference Items and choose Edit > Cut.

   • Select Item 1 and choose Edit > Paste. (This moves the toggle switch item in front of the text field item.)

   • Disclose the toggle switch item to reveal its configuration keys.

   • Change the value of the Title key to Play Sounds.

   • Change the value of the Identifier key to play_sounds_preference. The item should now be configured as shown in the following figure.

     

5. Create a second toggle switch for the Sound group.

   • Select Item 2 (the Play Sounds toggle switch).

   • Select Edit > Copy.

   • Select Edit >Paste. This places a copy of the toggle switch right after the first one.

   • Disclose the new toggle switch item to reveal its configuration keys.

   • Change the value of its Title key to 3D Sound.

   • Change the value of its Identifier key to 3D_sound_preference.

   At this point, you have finished the first group of settings and are ready to create the User Info group.

6. Change Item 4 into a Group element and name it User Info.

   • Click Item 4 in the Preferences Items. This displays a drop-down menu with a list of item types.

   • From the drop-down menu, select Group to change the type of the element.

     

   • Disclose the contents of Item 4.

   • Set the value of the Title key to User Info.

7. Create the Name field.

   • Select Item 5 in the Preferences Item.

   • Using the drop-down menu, change its type to Text Field.

   • Set the value of the Title key to User Info.

   • Set value of the Identifier key to user_name.

   • Toggle the disclosure button of the item to hide its contents.

8. Create the Experience Level settings.

   • Select Item 5 and click the plus (+) button (or press Return) to create a new item.

   • Click the new item and set its type to Multi Value.

   • Disclose the items contents and set its title to Experience Level, its identifier to experience_preference, and its default value to 0.

   • With the Default Value key selected, click the plus button to add a Titles array.

   • Open the disclosure button for the Titles array and click the items button along the right edge of the table. Clicking this button adds a new subitem to Titles.

   • Select the new subitem and click the plus button 2 more times to create 3 total subitems.

   • Set the values of the subitems to Beginner, Expert, and Master.

   • Select the Titles key again and click its disclosure button to hide its subitems.

   • Click the plus button to create the Values array.

   • Add 3 subitems to the Values array and set their values to 0, 1, and 2.

   • Click the disclosure button of Item 6 to hide its contents.

9. Add the final group to your settings page.

   • Create a new item and set its type to Group and its title to Gravity.

   • Create another new item and set its type to Slider, its identifier to gravity_preference, its default value to 1, and its maximum value to 2.

Creating Additional Settings Page Files

The Settings Bundle template includes the Root.plist file, which defines your application‚Äôs top Settings page. To define additional Settings pages, you must add additional property list files to your settings bundle. You can do this either from the Finder or from Xcode.

To add a property list file to your settings bundle in Xcode, do the following:

1. In the Groups and Files pane, open your settings bundle and select the Root.plist file.

2. Choose File > New.

3. Choose Other > Property List.

4. Select the new file and choose View > Property List Type > iPhone Settings plist to configure it as a settings file.

After adding a new Settings page to your settings bundle, you can edit the page’s contents as described in “Configuring a Settings Page: A Tutorial.” To display the settings for your page, you must reference it from a Child Pane element as described in “Hierarchical Preferences.”

Accessing Your Preferences

iOS applications get and set preferences values using either the Foundation or Core Foundation frameworks. In the Foundation framework, you use the NSUserDefaults class to get and set preference values. In the Core Foundation framework, you use several preferences-related functions to get and set values.

Listing 6-1 shows a simple example of how to read a preference value from your application. This example uses the NSUserDefaults class to read a value from the preferences created in ‚ÄúConfiguring a Settings Page: A Tutorial‚Äù and assign it to an application-specific instance variable.

Listing 6-1  Accessing preference values in an application

- (void)applicationDidFinishLaunching:(UIApplication *)application

{

    NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];

    [self setShouldPlaySounds:[defaults boolForKey:@"play_sounds_preference"]];

    // Finish app initialization...

}

For information about the NSUserDefaults methods used to read and write preferences, see NSUserDefaults Class Reference. For information about the Core Foundation functions used to read and write preferences, see Preferences Utilities Reference.

Debugging Preferences for Simulated Applications

When running your application, the iPhone Simulator stores any preferences values for your application in ~/Library/Application Support/iPhone Simulator/User/Applications/<APP_ID>/Library/Preferences, where <APP_ID> is a programmatically generated directory name that iOS uses to identify your application.

Each time you reinstall your application, iOS performs a clean install, which deletes any previous preferences. In other words, building or running your application from Xcode always installs a new version, replacing any old contents. To test preference changes between successive executions, you must run your application directly from the simulator interface and not from Xcode.