The Settings Page File Format

Each Settings page file 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 app that comes with the Xcode tools.

The root element of each Settings page file contains the keys listed in Table 4-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 app’s main preferences page is always stored in a file called Root.plist. 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 control in the parent page. A child pane control creates a row that, when tapped, displays a new page of settings. The File key of the child pane control identifies the name of the .plist file with 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 control used to display the child page. The Settings app automatically provides navigation controls on the child page to allow the user to navigate back to the parent page.

Figure 4-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.

For more information about child pane controls 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 app 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 app follows the same rules that other iOS apps follow. It first tries to find a localized version of the resource that matches the user’s preferred language setting. If no such resource exists, 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 and Localization Guide.

Adding the Settings Bundle

To add a Settings bundle to your Xcode project:

1. Choose File > New > New File.

2. Under iOS, choose Resource, and then select the 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 app target. Thus, all you have to do is modify the property listfiles of your Settings bundle and add any needed resources.

The new Settings bundle has the following structure:

Settings.bundle/

    Root.plist

    en.lproj/

        Root.strings

Preparing the Settings Page for Editing

Before editing any of the property-list files in your Settings bundle, you should configure the Xcode editor to format the contents of those files as iPhone settings. Xcode does this automatically for the Root.plist file, but you may need to format additional property-list files manually. To format a file as iPhone Settings, do the following:

1. Select the file.

2. Control-click the editor window and choose Property List Type > iPhone Settings plist if it is not already chosen.

   Formatting a property list makes it easier to understand and edit the file’s contents. Xcode substitutes human-readable strings (as shown in Figure 4-2) that are appropriate for the selected format.

   

Configuring a Settings Page: A Tutorial

This section 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 4-3. If you have not yet created a Settings bundle for your project, you should do so as described in Adding the Settings Bundle before proceeding with these steps.

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

2. Change the title of Item 0 to Sound.

   • Disclose Item 0 of Preference Items.

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

   • Leave the Type key set to Group.

   • Click the disclosure triangle of the item to hide its contents.

3. Create the first toggle switch for the renamed Sound group.

   • Select Item 2 (the toggle switch item) of Preference Items and choose Edit > Cut.

   • Select Item 0 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.

   • Click the disclosure triangle of the item to hide its contents.

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

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

   • Choose Edit > Copy.

   • Choose Edit >Paste to place 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.

   • Click the disclosure triangle of the item to hide its contents.

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

5. Change Item 3 into a Group control and name it User Info.

   • Click Item 3 in the Preferences Items. This displays a pop-up menu with a list of item types.

   • From the pop-up menu, choose Group to change the type of the control.

   • Disclose the contents of Item 3.

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

   • Click the disclosure triangle of the item to hide its contents.

6. Create the Name field.

   • Select Item 4 in the Preferences Items.

   • Using the pop-up menu, change its type to Text Field.

   • Set the value of the Title key to Name.

   • Set the value of the Identifier key to user_name.

   • Click the disclosure triangle of the item to hide its contents.

7. Create the Experience Level settings.

   • Select Item 4.

   • Control-click the editor window and select Add Row to add a new item.

   • Set the type of the new item to Multi Value.

   • Disclose the item’s 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, Control-click and select Add Row to add a Titles array.

   • Select the Titles array and press Return to add a new subitem.

   • Add two more subitems to create a total of three items.

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

   • Hide the key’s subitems.

   • Add a new item for the Values array.

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

   • Hide the contents of Item 5.

8. 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 app’s top Settings page. To define additional Settings pages, you must add additional property list files to your Settings bundle.

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

1. Choose File > New > New File.

2. Under iOS, select Resource, and then select the Property List template.

3. Select the new file to display its contents in the editor.

4. Control-click the editor pane and choose Property List Type > iPhone Settings plist to format the contents.

5. Control-click the editor pane again and choose Add Row to add a new key.

6. Add and configure any additional keys you need.

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 control as described in Hierarchical Preferences.