Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 12:56:06 GMT

Initial conversion from Docbook

New page

{{Learning Cocoa with Objective-C/TOC}}
Most applications need to store and retrieve ''preferences'' that allow for user customization of an application's behavior and keep track of configuration settings. Mac OS X provides, as part of its Core Foundation framework, a preferences system that provides a simple and standard way to maintain these preferences. Cocoa calls these preferences ''defaults''.

If you go to the ''~/Library/Preferences'' folder, you will see the user-preferences database used by the applications you run on your system. In fact, many of the applications we have created in this book have written preferences to this database. Take a look, and you'll see that you probably have ''Dot View.plist'', ''Menu.plist'', and ''RTF Edit.plist'' files. These contain preferences used by some of the various Cocoa base classes used in the sample applications we've built throughout the book.

In this chapter we'll show you how to take advantage of the user-preferences system from your applications using Cocoa.

== How Preferences Work ==

The preference system in Mac OS X allows you to store values associated with a key—the name of a property—that can later be used to look up the preference value when you need it. These key-value pairs are scoped using a combination of username and application ID. All of the preferences for a user are stored in his ''~/Library /Preferences'' folder.

There are multiple domains—or different scopes of coverage—in which a preference can exist. When you request a preference, the following resources are searched—in order—until a match is found:

# The list of arguments that were passed to an application. This lets an application start up with a preference setting to override all other values for that preference's key.
# The users preferences stored in the ''~/Library/Preferences''folder. This is where preferences that are unique to a user and that need to last between invocations of an application are kept.
# A set of global preferences used across all applications that a user may use. For example, rulers in text views will obtain a user's preferred unit of measurement. These preferences are stored in the ''~/Library/Preferences/GlobalPreferences.plist''file. Many of these preferences are set using the System Preferences application.
# The set of preferences that your application registers as the defaults for your application. If a value for a preference is not found anywhere else, then this allows your application to provide a default value.

Preferences in the ''~/Library/Preferences''folder are stored in the same property-list file format used by the ''Info.plist'' file included with application bundles. Preference value objects can be of any of the following types:

* <tt>NSString</tt> for storing string values
* <tt>NSNumber</tt> for storing number values derived from integers, floats, and other numeric types
* <tt>NSBoolean</tt> for storing YES or NO values
* <tt>NSDate</tt> for storing date information
* <tt>NSData</tt> for storing arbitrary data
* <tt>NSArray</tt> for storing arrays that consists of any of the previously listed types
* <tt>NSDictionary</tt> for storing name/value dictionaries that have values of any of the previously listed types

<div class="warning">
'''Warning'''

While it is possible to edit the files in your ''~/Library/Preferences'' folder yourself using any text editor, you probably should not. You might introduce accidental errors into the XML syntax of the files. We'll see some other ways to edit these files in just a bit.
</div>

== Using Defaults ==

To show how to use the <tt>NSUserDefaults</tt> class, the mechanism by which Cocoa provides access to Mac OS X's preference system, we'll build a simple application to keep track of a few of our favorite things.

<ol>
<li><div>Create a new Cocoa application project in Project Builder (File → New Project → Application → Cocoa Application) named "Favorites", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''MainMenu.nib'' file in Interface Builder.
</div></li>

<li><div>Lay out the user interface as shown in [[Learning Cocoa with Objective-C/Miscellaneous Topics/Defaults and Preferences#learncocoa2-CHP-15-FIG-1|Figure 15-1]].

<div id="learncocoa2-CHP-15-FIG-1">
'''Figure 15-1. Favorites application interface'''

[[Image:Learning Cocoa with Objective-C_I_4_tt540.png|Favorites application interface]]
</div>
</div></li>

<li><div>Create a subclass of <tt>NSObject</tt> in Interface Builder. Click on the Classes tab of the MainMenu.nib window, find <tt>NSObject</tt>, Control-click it, and select Subclass NSObject from the pop-up menu. Name the subclass "Controller".
</div></li>

<li><div>Create the following outlets on the Controller class:

* <tt>bookField</tt>
* <tt>colorField</tt>
* <tt>foodField</tt>
* <tt>cityField</tt>
</div></li>

<li><div>Create an action named <tt>textFieldChanged:</tt>. This action will tell the preferences database when an item has changed.
</div></li>

<li><div>Generate the source-code files for the Controller class (Classes → Create Files for Controller).
</div></li>

<li><div>Instantiate the Controller class (Classes → Instantiate Controller).
</div></li>

<li><div>Connect the four text fields on the user interface to their respective outlets by control-dragging a connection from the Controller instance to each of the fields in turn.
</div></li>

<li><div>Connect each of the four text fields to the Controller's <tt>textFieldChanged</tt> action method by control-dragging a connection from the text field to the Controller instance.
</div></li>

<li><div>Save (File → Save, or [[Image:Learning Cocoa with Objective-C_I_4_tt541.png|]] -S) the nib file, and return to Project Builder.
</div></li>

<li><div>Edit the ''Controller.h''file as shown, adding an instance variable that will hold a reference to a <tt>NSUserDefaults</tt> object.

#import <Cocoa/Cocoa.h>

@interface Controller : NSObject
{
IBOutlet id bookField;
IBOutlet id cityField;
IBOutlet id colorField;
IBOutlet id foodField;
''' NSUserDefaults * prefs;'''
}
- (IBAction)textFieldChanged:(id)sender;
@end
</div></li>

<li><div>Add an <tt>init</tt> method to the ''Controller.m'' file. This will set the <tt>prefs</tt> instance variable.

'''- (id)init'''
'''{'''
''' [super init];'''
''' NSMutableDictionary * defaultPrefs = [NSMutableDictionary dictionary]; // a'''

''' [defaultPrefs setObject:@"Learning Cocoa" forKey:@"FavBook"]; // b'''
''' [defaultPrefs setObject:@"San Francisco" forKey:@"FavCity"];'''
''' [defaultPrefs setObject:@"Red" forKey:@"FavColor"];'''
''' [defaultPrefs setObject:@"Mexican" forKey:@"FavFood"];'''

'''<nowiki> prefs = [[NSUserDefaults standardUserDefaults] retain]; // c</nowiki>'''
''' [prefs registerDefaults:defaultPrefs]; // d'''

''' return self;'''
'''}'''

This code does the following things:

# Creates a new mutable dictionary that will serve as the container for the default values the application will use
# Sets four key/value pairs that correspond to the default values we want to store in the preferences system
# Obtains a reference to the preferences system
# Indicates to the <tt>prefs</tt> object that we want to use the <tt>defaultPrefs</tt> dictionary as the set of default preferences
</div></li>

<li><div>Add a <tt>dealloc</tt> method so that the class cleans up after itself properly.

'''- (void)dealloc'''
'''{'''
''' [prefs release];'''
''' [super dealloc];'''
'''}'''

</div></li>

<li><div>Add an <tt>awakeFromNib</tt> method to populate the user interface from any settings that are in the <tt>prefs</tt> object.

'''- (void)awakeFromNib'''
'''{'''
'''<nowiki> [bookField setStringValue:[prefs stringForKey:@"FavBook"]];</nowiki>'''
'''<nowiki> [cityField setStringValue:[prefs stringForKey:@"FavCity"]];</nowiki>'''
'''<nowiki> [colorField setStringValue:[prefs stringForKey:@"FavColor"]];</nowiki>'''
'''<nowiki> [foodField setStringValue:[prefs stringForKey:@"FavFood"]];</nowiki>'''
'''}'''

</div></li>

<li><div>Implement the <tt>textFieldChanged:</tt> action method so that the key values are saved as they change to the <tt>prefs</tt> object.

- (IBAction)textFieldChanged:(id)sender
{
''' if (sender == bookField) {'''
''' [prefs setObject:[bookField stringValue] forKey:@"FavBook"];'''
''' } else if (sender == cityField) {'''
''' [prefs setObject:[cityField stringValue] forKey:@"FavCity"];'''
''' } else if (sender == colorField) {'''
''' [prefs setObject:[colorField stringValue] forKey:@"FavColor"];'''
''' } else if (sender == foodField ){'''
''' [prefs setObject:[foodField stringValue] forKey:@"FavFood"];'''
''' }'''
}
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt547.png|]]-R) the application. You should see the interface launch as shown in [[Learning Cocoa with Objective-C/Miscellaneous Topics/Defaults and Preferences#learncocoa2-CHP-15-FIG-2|Figure 15-2]].

<div id="learncocoa2-CHP-15-FIG-2">
'''Figure 15-2. Our application running'''

[[Image:Learning Cocoa with Objective-C_I_4_tt548.png|Our application running]]
</div>
</div></li>

<li><div>Change some of the values. Quit the application, then restart to see if the values were saved.
</div></li>

<li><div>Find the ''Favorites.plist'' file in your ''~/Library/Preferences''folder. Double-click the file to launch the Property List Editor (''/Applications/Utilities''), which allows you to see the values that you changed in the file, as shown in [[Learning Cocoa with Objective-C/Miscellaneous Topics/Defaults and Preferences#learncocoa2-CHP-15-FIG-3|Figure 15-3]]. To see the XML representation of the ''plist'' file, click the Dump button. You can also, if needed, edit the property list here, save the changes, and then launch the application we built to see the changes.

<div id="learncocoa2-CHP-15-FIG-3">
'''Figure 15-3. The preferences file under the hood'''

[[Image:Learning Cocoa with Objective-C_I_4_tt549.png|The preferences file under the hood]]
</div>
</div></li>

</ol>

<div class="sidebar">
'''Overriding Preferences Using Launch Arguments'''

Sometimes, when you are developing an application, it is useful to override preference settings for a particular run of an application. To do this, simply specify the preference key names and values as launch arguments when you launch your application from the Terminal. These arguments are given following the pattern:

Application -[''Key name''] [''Value name''] ...

For example, to override the favorite city when we launch the Favorites application, enter the following command into a Terminal window:

open ~/LearningCocoa/Favorites/build/Favorites.app - FavCity "New Orleans"

Of course, you can apply this concept to any application on your system as long as you know the name of the preference to use. The best way to find out preference names is to look in the ''plist'' files that they leave in the ''~/Library/Preferences''folder.
</div>

== Command-Line Preferences Access ==

You can access your preferences from the Terminal by using the ''defaults'' command. For example, to see the defaults for the Favorites application we just built, type the following into a Terminal window:

'''defaults read Favorites'''

Something like the following should print:

{
FavBook = "Stranger in a Strange Land";
FavCity = "Dallas Texas";
FavColor = Black;
FavFood = Thai;
}

If you want to modify a preference from the command line, you can use the ''defaults''command's ''write'' option. For example, to change our favorite city to Sedona, Arizona, issue the following command (the quotes are needed to accommodate the comma in the value string we are using):

'''defaults write Favorites FavCity "Sedona, Arizona"'''

Now go back to Project Builder, and build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt555.png|]]-R) the Favorites application again to see the changes.

== Using Unique Application Identifiers ==

As we said before, preferences are stored in files using an application's ID. So far, our sample applications haven't specified a particular application ID, so the system has used the name of the application as its ID.

However, when you browse through your ''~/Library/Preferences'' folder, you'll see that quite a few of the files have long names like ''com.apple.iPhoto.plist''. When Apple created the iPhoto application, they assigned it an application ID of ''com.apple.iPhoto—''Apple's domain name followed by the application name—to reduce the possibility of somebody else's application named iPhoto interfering with the preferences used by the system. Obviously, for an application like iPhoto, there probably won't be a collision. But for applications with more common names—like the ones that we have been creating in this book—this level of namespace protection is valuable.

For example, all of the Mac OS X applications created by O'Reilly & Associates should have application IDs that start with ''com.oreilly''. Following this logic, our Favorites application should have an application ID of ''com.oreilly.Favorites''. To specify this application ID:

<ol>
<li><div>Open up the main target of the application, navigate the outline view to Info.plist Entries → Simple View → Basic information, and change the Identifier field, as shown in [[Learning Cocoa with Objective-C/Miscellaneous Topics/Defaults and Preferences#learncocoa2-CHP-15-FIG-4|Figure 15-4]].

<div id="learncocoa2-CHP-15-FIG-4">
'''Figure 15-4. Setting the application identifier'''

[[Image:Learning Cocoa with Objective-C_I_4_tt556.png|Setting the application identifier]]
</div>
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt557.png|]]-R) the application, change the values, and quit the application.
</div></li>

<li><div>Using the Finder, you can see that there is now a ''com.oreilly.Favorites.plist''file in your ''~/Library/Preferences''folder. If you wanted to read this file from the command line, you could use the following command:

defaults read com.oreilly.Favorites
</div></li>

</ol>

== Exercises ==

# Take a look at the contents of the Favorites preference list file using Property List Editor.
# Add a reset button to the Favorites application that will reset the values to their original state.
# Modify the Favorites application so that it reads its application defaults from a ''.plist'' file contained as a resource in its application bundle.
# Modify the Currency Converter application from [[Learning Cocoa with Objective-C/Single-Window Applications/Graphical User Interfaces|Chapter 5]] to remember the exchange rate between invocations of the application.

Learning Cocoa with Objective-C/Miscellaneous Topics/Defaults and Preferences - Revision history

Docbook2Wiki: Initial conversion from Docbook