App Preferences Workshop 1: Befor You Begin

If you are a new visitor to our site, please read the Getting Started guide, and the Property List Workshop series.

This is a four-part series on how to add settings for your application to the Settings application, and how to access those settings from within your application.

The user of your application can access preferences you’ve set up for it via the Settings application or in the application itself. You should permit the user of your app to access it’s preferences using only one method, not both.

Accessing Preferences in The Settings Application

The iOS Settings application is used for setting preferences of Apple’s apps and your apps.

default_app_icons

To setup preferences for your application the user can access in the Settings application or in the application itself, you need to create a settings.bundle folder in the application, using Xcode’s Settings Bundle template. The template creates a Root.plist file in the bundle folder for you. In Xcode’s Standard editor, you modify the plist file to setup the application’s preferences. You could even set up child preferences by creating one or more plist files in the bundle folder. The Settings application takes care of creating the user interface for the bundle’s root and child plist file content.

Take a look at this image, it should clarify the process of how the user access an application’s preferences using the Settings application.

userpreferences_fig1

Accessing Preferences in The Application

Once you’ve setup preferences for your application in a Settings Bundle folder, you use the NSUserDefaults class to read and write the application’s preferences. The NSUserDefaults class works similarly to the NSDictionary class. The main difference between these classes is that the NSUserDefaults class is limited in the types of object it can store. All preferences for your application are stored as key/value pairs in an instance of the NSUserDefaults class.

Take a look at this image, it should clarify the process of how a user of your application can access and update the application’s preferences via controls placed on a view.

accessing_preferences2

Application Overview

In this tutorial series, you’ll learn how to create settings for an application that list book titles and author names in a table view control. Take a look at Figure 1 below, it shows components of the preferences system you will create for the application. Figure 2 shows what the application you will create preferences for, looks like in the iPhone simulator. Figure 3 shows the user interface, the app user will use to update preferences stored in the Root.plist file.

userpreferences_fig1 userpreferences_fig2 userpreferences_fig3
Figure 1 Figure 2 Figure 3

You will set up two plist files: Root.plist and More.plist in a Settings.bundle folder. The Root.plist file will hold main preferences and the More.plist file will hold child preferences. When the user launch the system’s Settings application, there will be an entry for the Settings.bundle-see the bottom of the middle image in Figure 1.

Create The Application

You are ready to create the App Preferences Workshop series application, so launch Xcode and create a new project using the Tabbed Application template shown in Figure 4. Provided options shown in Figure 5. When prompted, save the project in the iOS Apps folder.

userpreferences_fig4 userpreference_fig5
Figure 4 Figure 5

Add a Settings.bundle in The Project

You need to add a Settings.bundle folder in the project and create the More.plist file in it. In the project navigator panel, click the UserPreference folder, then click the little + button located at the bottom of the navigator panel-see Figure 6 below. Select New File… from the pop up menu.

userpreferences_fig6
Figure 6

In the template window shown in in Figure 7 below, select the Settings Bundle icon before clicking the Next button. In the Save As window shown in Figure 8, accept the default name of Settings by clicking the Create button.

 userpreferences_fig7  userpreferences_fig8
Figure 7 Figure 8

The Settings.bundle item should show up in the project’s Navigator panel. Expand it and you’ll see that the template added the Root.plist file in it for you.

Figure 9
Figure 9

You need to add a second plist file in the bundle folder. Switch to Finder and locate the UserPreferences folder in the iOS Apps folder, then right-click the Settings.bundle folder. Select the Show Package Contents from the pop-up menu. Next, make a copy of the Root.plist file (option + drag the Root.plist file down) and rename it to More.plist. When you are done, the Settings.bundle folder should look like Figure 10.

userpreferences_fig10
Figure 10

Application Images

Download these images and drop them in the App Icons boxes. They will server as the Settings application’s icon, for the UserPreferences app you are developing in this series.

books books@2

Download these images as well, then drop them in the project’s navigation panel. They will be used as the view’s tab images (see image 2 and 3 above).

View The Default Preferences

Press Command-R to run the application. When it is loaded in the simulator, click the Stop button on Xcode’s Toolbar. Now, go to the simulator’s home screen and launch the Settings application. You now see a new entry for the UserPreferences application-see Figure 11 below. Click it to see the user interface of default settings the Settings Bundle template added in the Root.plist file.

fig27
Figure 11: The Settings app’s entries Figure 12: User interface of
default preferences

The Root.plist File

Expanding the Settings.bundle folder, then click the Root.plist file, and you’ll see two items in the code editor window: iPhone Settings Schema and Preference Items.

iPhone Settings Schema

This is the first item in the Root.plist file and it is a dictionary containing a single item-Preference Items.

Preference Items

This is a sub item of the iPhone Setting Schema item. As you can see it is an array. It will hold a set of dictionary nodes, each representing a single preference or a single child view that the user can drill down into. Each preference is represented by an item (known as PreferenceSpecifier), such as Item 0, Item 1, Item 2, and so on. Table 1 below describe PreferenceSpecifiers you can use in the Root.plist file or a child plist file (More.plist).

Table 1: Preference Specifiers
Type Description
Text field The Text Field type displays a Title and an editable text field, similar to a UITextField control. You can use this type for preferences that require the user to specify a custom string value. The raw key for this type is PSTextFieldSpecifier.

Example

prefSpc1

Title The Title type displays a read-only string value, similar to a UILabel control. You can use this type to display read-only preference values. The raw key for this type is PSTitleValueSpecifier.

Example

Toggle switch The Toggle Switch type displays an ON/OFF toggle button. You can use it to configure a preference that can have only one of two values. Although you typically use this type to represent preferences containing Boolean values, you can also use it with preferences containing non-Boolean values. The raw key for this type is PSToggleSwitchSpecifier.

Example

Slider The Slider type displays a slider control. You can use it for a preference that represents a range of values. The value for this type is a real number whose minimum and maximum value you specify. The raw key for this type is PSSliderSpecifier.

Example

Multi Value The Multi Value type lets the user select one value from a list of values. The values can be of any type. The raw key for this type is PSMultiValueSpecifier.

Example

Group The Group type is for organizing groups of preferences on a single page. The group type does not represent a configurable preference. It simply contains a title string that is displayed immediately before one or more configurable preferences. The raw key for this type is PSGroupSpecifier.

Example

Child Pane The Child Pane type lets the user navigate to a new page of preferences. You must create a separate plist file for this preference and add it to the settings.bundle folder. The raw key for this type is PSChildPaneSpecifier.

Example

Display The Root.plist Keys in Their Raw Format

By default, the various items inside the Root.plist and More.plist files are represented using their user-friendly names, such as Preference Items, String Filename, Default Value, and so on. However, for editing purposes (such as adding new keys into the file), it is easier to display item names in their raw format. To do so, control-click a blank area in the code editor window, then select Show Raw Keys/Values from the pop-up menu.

next-iconThat’s all for this week’s lesson; next week, you will add preferences in the Root.plist file. Until then, happy coding. 🙂