Preferences and Settings Programming Guide Contents
Total Page:16
File Type:pdf, Size:1020Kb
Preferences and Settings Programming Guide Contents About Preferences and Settings 5 At a Glance 5 You Decide What Preferences You Want to Expose 5 Apps Provide Their Own Preferences Interface 5 Apps Access Preferences Using the User Defaults Object 6 iCloud Stores Shared Preference and Configuration Data 6 Defaults Are Grouped into Domains in OS X 6 A Settings Bundle Manages Preferences for iOS Apps 6 See Also 7 About the User Defaults System 8 What Makes a Good Preference? 8 Providing a Preference Interface 8 The Organization of Preferences 9 The Argument Domain 10 The Application Domain 10 The Global Domain 11 The Languages Domains 11 The Registration Domain 11 Viewing Preferences Using the Defaults Tool 12 Accessing Preference Values 13 Registering Your App’s Default Preferences 13 Getting and Setting Preference Values 14 Synchronizing and Detecting Preference Changes 15 Managing Preferences Using Cocoa Bindings 16 Managing Preferences Using Core Foundation 16 Setting a Preference Value Using Core Foundation 16 Getting a Preference Value Using Core Foundation 17 Storing Preferences in iCloud 19 Strategies for Using the iCloud Key-Value Store 19 Configuring Your App to Use the Key-Value Store 20 Accessing Values in the Key-Value Store 21 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 2 Contents Defining the Scope of Key-Value Store Changes 22 Implementing an iOS Settings Bundle 23 The Settings App Interface 23 The Settings Bundle 25 The Settings Page File Format 26 Hierarchical Preferences 26 Localized Resources 27 Creating and Modifying the Settings Bundle 28 Adding the Settings Bundle 28 Preparing the Settings Page for Editing 28 Configuring a Settings Page: A Tutorial 30 Creating Additional Settings Page Files 32 Debugging Preferences for Simulated Apps 33 Document Revision History 34 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 3 Figures, Tables, and Listings About the User Defaults System 8 Table 1-1 Options for displaying preferences to the user 8 Table 1-2 Search order for domains 10 Accessing Preference Values 13 Listing 2-1 Registering default preference values 14 Listing 2-2 Writing a simple default 17 Listing 2-3 Reading a simple default 17 Storing Preferences in iCloud 19 Listing 3-1 Updating local preference values using iCloud 21 Implementing an iOS Settings Bundle 23 Figure 4-1 Organizing preferences using child panes 27 Figure 4-2 Formatted contents of the Root.plist file 29 Figure 4-3 A root Settings page 30 Table 4-1 Preference control types 24 Table 4-2 Contents of the Settings.bundle directory 25 Table 4-3 Root-level keys of a preferences Settings page file 26 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 4 About Preferences and Settings Preferences are pieces of information that you store persistently and use to configure your app. Apps often expose preferences to users so that they can customize the appearance and behavior of the app. Most preferences are stored locally using the Cocoa preferences system—known as the user defaults system. Apps can also store preferences in a user’s iCloud account using the key-value store. The user defaults system and key-value store are both designed for storing simple data types—strings, numbers, dates, Boolean values, URLs, data objects, and so forth—in a property list. The use of a property list also means you can organize your preference data using array and dictionary types. It is also possible to store other objects in a property list by encoding them into an NSData object first. At a Glance Apps integrate preferences in several ways, including programmatically at various points throughout your code and as part of the user interface. Preferences are supported in both iOS and Mac apps. You Decide What Preferences You Want to Expose Preferences are different for each app, and it is up to you to decide what parts of your app you want to make configurable. Configuration involves checking the value of a stored preference from your code and taking action based on that value. Thus, the preference value itself should always be simple and have a specific meaning that is then implemented by your app. Relevant section: What Makes a Good Preference? (page 8) Apps Provide Their Own Preferences Interface Because each app’s preferences are different, the app itself is responsible for deciding how best to present those preferences to the user, if at all. Both iOS and OS X provide some standard places for you to incorporate a preferences interface, but you are still responsible for designing that interface and displaying it at the appropriate time. 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 5 About Preferences and Settings At a Glance Relevant section: Providing a Preference Interface (page 8) Apps Access Preferences Using the User Defaults Object Apps access locally stored preferences using a user defaults object, which is either an NSUserDefaults object (iOS and OS X) or an NSUserDefaultsController object (OS X only). In addition to retrieving preference values, apps can use this object to register default values for preferences and manage other aspects of the preferences system. Relevant chapter: Accessing Preference Values (page 13) iCloud Stores Shared Preference and Configuration Data Apps that support iCloud can put some of their preference data in the user’s iCloud account and make it available to instances of the app running on the user’s other devices. You use this capability to supplement (not replace) your app’s existing preferences data and provide a more coherent experience across the user’s devices. For example, a magazine app might store information about the page number and issue last read by the user so that the app running on a different device can show that same page. Relevant chapter: Storing Preferences in iCloud (page 19) Defaults Are Grouped into Domains in OS X OS X preferences are grouped by domains so that system preferences can be differentiated from app preferences. Splitting preferences in this manner lets the user specify some preferences globally and then override one or more of those preferences inside an app. Relevant section: The Organization of Preferences (page 9) A Settings Bundle Manages Preferences for iOS Apps An iOS, apps can display preferences from the Settings app, which is a good place to put preferences that the user does not need to configure frequently. To display preferences in the Settings app, an app’s bundle must include a special resource called a Settings bundle that defines the preferences to display, the proper way to display them, and the information needed to record the user’s selections. 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 6 About Preferences and Settings See Also Note: Apps are not required to use a Settings bundle to manage all preferences. For preferences that the user is likely to change frequently, the app can display its own custom interface for managing those preferences. Relevant chapter: Implementing an iOS Settings Bundle (page 23) See Also For information about property lists, see Property List Programming Guide. For more advanced information about using Core Foundation to manage preferences, see Preferences Programming Topics for Core Foundation. 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 7 About the User Defaults System The user defaults system manages the storage of preferences for each user. Most preferences are stored persistently and therefore do not change between subsequent launch cycles of your app. Apps use preferences to track user-initiated and program-initiated configuration changes. What Makes a Good Preference? When defining your app’s preferences, it is better to use simple values and data types whenever possible. The preferences system is built around property-list data types such as strings, numbers, and dates. Although you can use an NSData object to store arbitrary objects in preferences, doing so is not recommended in most cases. Storing objects persistently means that your app has to decode that object at some point. In the case of preferences, a stored object means decoding the object every time you access the preference. It also means that a newer version of your app has to ensure that it is able to decode objects created and written to disk using an earlier version of your app, which is potentially error prone. A better approach for preferences is to store simple strings and values and use them to create the objects your app needs. Storing simple values means that your app can always access the value. The only thing that changes from release to release is the interpretation of the simple value and the objects your app creates in response. Providing a Preference Interface For user-facing preferences, Table 1-1 lists the options for displaying those preferences to the user. As you can see from this table, most options involve the creation of a custom user interface for managing and presenting preferences. If you are creating an iOS app, you can use a Settings bundle to present preferences, but you should do so only for settings the user changes infrequently. Table 1-1 Options for displaying preferences to the user Preference iOS OS X Frequently changed preferences Custom UI Custom UI Infrequently changed preferences Settings bundle Custom UI 2013-10-22 | Copyright © 2013 Apple Inc. All Rights Reserved. 8 About the User Defaults System The Organization of Preferences Note: An example of preferences that might change frequently include things like the volume levels or control options of a game. An example of preferences that might change infrequently are the email address and server settings in the Mail app. For iOS apps, it is ultimately up to you to decide whether it is appropriate to expose preferences from the Settings app or from inside your app.