CHAPTER 12: Application Settings and User Defaults

415

the usual application delegate class, as well as two additional controller classes and a storyboard file to contain the GUI (see Figure 12–9).

Figure 12–9. Our project created from the Utility Application template. Notice the application delegate, the storyboard, and the main and flipside view controllers.

Working with the Settings Bundle

The Settings application bases the display of preferences for a given application on the contents of the settings bundle inside that application. Each settings bundle must have a property list, called Root.plist, which defines the root-level preferences view. This property list must follow a very precise format, which we’ll talk about when we set up the property list for our application.

When the Settings application starts up, it checks each application for a settings bundle and adds a settings group for each application that includes a settings bundle. If we want our preferences to include any subviews, we need to add property lists to the bundle and add an entry to Root.plist for each child view. You’ll see exactly how to do that in this chapter.

Adding a Settings Bundle to Our Project

In the project navigator, click the AppSettings folder, and then select File New File… or press N. In the left pane, select Resource under the iOS heading, and then select the Settings Bundle icon (see Figure 12–10). Click the Next button, leave the default name of

Settings.bundle, and click Create.

www.it-ebooks.info

416	CHAPTER 12: Application Settings and User Defaults

Figure 12–10. Creating a settings bundle in Xcode

You should now see a new item in the project window, called Settings.bundle. If it’s not already opened, expand Settings.bundle, and you should see two subitems: a folder named en.lproj, containing a file named Root.strings, and an icon named Root.plist. We’ll discuss en.lproj in Chapter 21 when we talk about localizing your application into other languages. Here, we’ll concentrate on Root.plist.

Setting Up the Property List

Select Root.plist, and take a look at the editor pane. You’re looking at Xcode’s property list editor (see Figure 12–11). This editor functions in the same way as the Property List Editor application in /Developer/Applications/Utilities.

Figure 12–11. Root.plist in the property list editor pane. If your editing pane looks slightly different, don’t panic. Control-click in the editing pane and select Show Raw Keys/Values from the contextual menu that appears.

Notice the organization of the items in the property list. Property lists are essentially dictionaries, storing item types and values, and using a key to retrieve them, just as an

NSDictionary does.

Several different types of nodes can be put into a property list. The Boolean, Data, Date, Number, and String node types are meant to hold individual pieces of data, but you also have a couple of ways to deal with whole collections of nodes as well. In addition to

www.it-ebooks.info

CHAPTER 12: Application Settings and User Defaults

417

Dictionary node types, which allow you to store other nodes under a key, there are Array nodes, which store an ordered list of other nodes similar to an NSArray. The Dictionary and Array types are the only property list node types that can contain other nodes.

NOTE: Although you can use most kinds of objects as keys in an NSDictionary, keys in property list dictionary nodes must be strings. However, you are free to use any node type for the

values.

When creating a settings property list, you need to follow a very specific format. Fortunately, Root.plist, the property list that came with the settings bundle you just added to your project, follows this format exactly. Let’s take a look.

In the Root.plist editor pane, names of keys can either be displayed in their true, “raw” form or in a slightly more human-readable form. We’re big fans of seeing things as they truly are whenever possible, so right-click anywhere in the editor and make sure the Show Raw Keys/Values option in the contextual menu is checked (see Figure 12–12). The rest of our discussion here uses the real names for all the keys we’re going to talk about, so this step is important.

Figure 12–12. Control-click anywhere in the property list editing pane and make sure the Show Raw Keys/Values item is checked. This will ensure that real names are used in the property list editor, which makes your editing experience more precise.

CAUTION: As of this writing, leaving the property list, either by editing a different file or by quitting Xcode, resets the Show Raw Keys/Values item to be unchecked. If your text suddenly

looks a little different, take another look at that menu item and make sure it is checked.

One of the items in the dictionary is StringsTable. A strings table is used in translating your application into another language. We’ll cover the strings table in Chapter 21, when we get into localization. Since the strings table is optional, you can delete that entry by clicking it and pressing the delete key. Or you can leave it there if you prefer, since it won’t do any harm.

www.it-ebooks.info

418	CHAPTER 12: Application Settings and User Defaults

In addition to StringsTable, the property list contains a node named PreferenceSpecifiers, which is an array. This array node is designed to hold a set of dictionary nodes, each representing a single preference that the user can enter or a single child view that the user can drill down into.

You’ll notice that Xcode’s template kindly gave us four nodes (see Figure 12–13). Those nodes aren’t likely to reflect our actual preferences, so delete Item 1, Item 2, and Item 3 (select each one and press the delete key, one after another), leaving just Item 0 in place.

NOTE: To select an item in the property list, it is best to click on one side or another of the Key

column, to avoid bringing up the Key column’s drop-down menu.

Figure 12–13. Root.plist in the editor pane, this time with PreferenceSpecifiers expanded

Single-click Item 0 but don’t expand it. Xcode’s property list editor lets you add rows by pressing the return key. The current selection state—including which row is selected and whether or not it’s expanded—determines where the new row will be inserted. When an unexpanded array or dictionary is selected, pressing return adds a sibling node after the selected row. In other words, it will add another node at the same level as the current selection. If you were to press return (but don’t do that now), you would get a new row called Item 1 immediately after Item 0. Figure 12–14 shows an example of hitting return to create a new row. Notice the drop-down menu that allows you to specify the kind of preference specifier this item represents—more on this in a bit.

Figure 12–14. We selected Item 0 and hit return to create a new sibling row. Note the drop-down menu that appears, allowing us to specify the kind of preference specifier this item represents.

www.it-ebooks.info

CHAPTER 12: Application Settings and User Defaults

419

Now expand Item 0, and see what it contains (see Figure 12–15). The editor is now ready to add child nodes to the selected item. If you were to press return at this point (again, don’t actually press it now), you would get a new first child row inside Item 0.

Figure 12–15. When you expand Item 0, You’ll find a row with a key of Type and a second row with a key of Title. This represents a group with a title of Group.

One of the items inside Item 0 has a key of Type. Every property list node in the PreferenceSpecifiers array must have an entry with this key. The Type key is typically the first entry, but order doesn’t matter in a dictionary, so the Type key doesn’t need to be first. The Type key tells the Settings application what type of data is associated with this item.

In Item 0, the Type item has a value of PSGroupSpecifier. This indicates that the item represents the start of a new group. Each item that follows will be part of this group, until the next item with a Type of PSGroupSpecifier.

If you look back at Figure 12–4, you’ll see that the Settings application presents the application settings in a grouped table. Item 0 in the PreferenceSpecifiers array in a settings bundle property list should always be a PSGroupSpecifier so the settings start in a new group, because you need at least one group in every Settings table.

The only other entry in Item 0 has a key of Title, and this is used to set an optional header just above the group that is being started.

Now, take a closer look at the Item 0 row itself, and you’ll see that it’s actually shown as Item 0 (Group – Group). The values in parentheses represent the value of the Type item (the first Group) and the Title item (the second Group). This is a nice shortcut that Xcode gives you so that you can visually scan the contents of a settings bundle.

As shown back in Figure 12–4, we’ve called our first group General Info. Double-click the value next to Title, and change it from Group to General Info (see Figure 12–16). When you enter the new title, you may notice a slight change to Item 0. It’s now shown as Item 0 (Group – General Info) to reflect the new title.

Figure 12–16. We changed the title of the Item 0 group from Group to General Info.

www.it-ebooks.info