Section 14.3. Reading and Writing Preferences

14.3. Reading and Writing Preferences

There are three ways in which to read and write information in the defaults database:

• With the Property List Editor (/Developer/Applications/Utilities) installed as part of the Xcode Tools

• From the command line using the defaults command-line utility

• Converting the file to XML format using plutil and then using TextEdit (found in /Applications/Utilities) or another plain-text editor to modify the file by hand

14.3.1. Property List Editor

The Property List Editor, shown in Figure 14-2, is a GUI application installed with the Xcode Tools that lets you view and edit property list files. When you first open a property list with the Property List Editor, you'll notice that the top root element is

Figure 14-1. The Language section of the International Preference panel

collapsed. Click the disclosure triangle next to it, and you can drill through the various preferences.

As shown in Figure 14-2, there are three columns to the Property List Editor. These are:

Property List

Lists the keys of the property list; that is, the contents of the <key/> tags of a plist XML file.

Class

Lists the classes available for each key definition. This affects the value tags in the XML file as defined in Figure 14-1.

Value

Contains the value for the preference key.

Figure 14-2. The Property List Editor application

To view the XML version of the plist file, click the Dump button in the upper-right corner of the Property List Editor's window. You can't edit the XML source here, but you can see the effects of the changes that you make in the top part of the window.

To edit an item, double-click the item's name that you want to edit, type in the new value, and then hit Return to accept the new value.

14.3.2. The defaults Command-Line Tool

The defaults tool gives you easy access to the defaults system from the command line, letting you read and write the preferences for any Mac OS X application on the system. As with any command-line utility, you can write shell scripts to run several defaults commands automatically, enabling you to set an application's behavior any way you'd like in an instant.

Since defaults provides a simple way to read and write preferences on the command line, you can easily integrate it with your shell scripts. Chapter 13 has more information on putting defaults to use in your scripting projects.

14.3.2.1. Reading preferences

The basic usage of the defaults command for reading an application's preferences is:

     defaults read domain [key]

where domain is the property domain that you want to read the preference from, and key is an optional key name that lets you see the value of a single key for a preference domain. Since a preference key can contain many different kinds of data, the output from this command will vary depending on the kind of data that is associated with a preference key. Example 14-5 shows the output from reading the preferences for a domain.

Example 14-5. Using the defaults command

 $ defaults read com.apple.menuextra.battery {ShowPercent = NO; ShowTime = YES; }

Example 14-6 shows how to read a single key from a domain, in this case, a Boolean value.

Example 14-6. Using the defaults command specifying a key

 $ defaults read com.apple.menuextra.battery ShowPercent NO

Strings and numbers are shown as Boolean values. The only caveat is that a string containing a space is surrounded by quotes. An array associated with a property key is output as a list of items within a set of parentheses, and the items themselves are comma-delimited. Example 14-7 shows the most recently used folders as stored in the com.apple.finder preference domain.

Example 14-7. Recent folders stored in the com.apple.finder domain

 $ defaults read com.apple.finder AppleRecentFolders (     "file://localhost/Macintosh%20HD/Developer/Applications/Utilities/",     "file://localhost/Volumes/Macintosh%20HD//Users/jldera/Documents/Downloads/",     "file://localhost/Volumes/Macintosh%20HD//Users/jldera/Documents/" )

A dictionary associated with a key is output as a set of name-value pairs surrounded by curly braces. Example 14-8 shows a dictionary associated with the InboxViewerAttributes preference in the com.apple.mail preference domain.

Example 14-8. A dictionary of values associated with a preference

 $ defaults read com.apple.mail InboxViewerAttributes {     DisplayInThreadedMode = yes;     SortOrder = "received-date";     SortedDescending = NO; }

You'll also see this format used when you output all of the defaults for a preference domain. Example 14-9 shows the contents of the com.apple.systemuiserver domain, which controls the menu extras shown in the upper-right corner of the screen.

Example 14-9. A dictionary output of the preferences in the com.apple.systemuiserver domain

 $ defaults read com.apple.systemuiserver {     "NSWindow Frame NoTimeLeft" = "274 440 475 163 0 0 1024 746 ";     "_  _NSEnableTSMDocumentWindowLevel" = 1;     menuExtras = (         "/System/Library/CoreServices/Menu Extras/Script Menu.menu",         "/System/Library/CoreServices/Menu Extras/iChat.menu",         "/System/Library/CoreServices/Menu Extras/AirPort.menu",         "/System/Library/CoreServices/Menu Extras/Battery.menu",         "/System/Library/CoreServices/Menu Extras/User.menu",         "/System/Library/CoreServices/Menu Extras/Clock.menu"     ); }

You can also read the preferences for an application by using its name instead of trying to figure out its preference domain. The syntax for this is:

     defaults read -app appname

For example, to read the preferences for Mail, you would use the following command:

     $ defaults read -app Mail

14.3.2.2. Writing preferences

The basic syntax to write preferences to the defaults database is:

     defaults write domain key value

where domain is the preference domain to write the preference to, key is the preference name, and value is the content to associate with that key. For example, to configure the Terminal so it uses a blinking cursor, you would issue the following command:

     $ defaults write com.apple.terminal BlinkCursor YES

If you enter this command into a Terminal window and then open a new window, you'll see the cursor blinking. To reverse this setting, use the following command:

     $ defaults write com.apple.terminal BlinkCursor NO

You can use two commands to write properties to an array. The first associates an array with a preference key and replaces any previous values associated with that key. This command has the syntax:

     defaults write domain key -array element1 element2 element3...

To add new elements to the end of an array for a key without replacing all the elements in the array, use the -array-add option with the following syntax:

     defaults write domain key -array-add element1 element2...

You should always make sure that the application for which you are writing preferences isn't running when you use the defaults command. A running application might write something to the defaults database that overwrites any changes you may have made.

14.3.2.3. Reading and writing host-specific preferences

To work with host-specific preferences, you can use the -currentHost or -host options to the defaults command. For example, to read the preference from the com.apple.idisk preference domain on the machine that you are working on, you would use the following command:

     $ defaults -currentHost read com.apple.idisk

14.3.2.4. Reading and writing global preferences

To access the global preferences (those associated with all applications) use the -g options with the defaults command, as shown in Example 14-10.

Example 14-10. Reading global preferences

 $ defaults read -g {     AppleAntiAliasingThreshold = 8;     AppleCollationOrder = en;     AppleID = jldera;     AppleLanguages = (en, ja, fr, de, es, it, nl, sv, nb, da, fi, pt, "zh-Hans",  "zh-Hant", ko);     AppleLocale = "en_US";     AppleScrollAnimationEnabled = 1;     AppleScrollBarVariant = Single;     NSFavoriteStyles = {         Bold = {NSFontTrait = 2; };         Italic = {NSFontTrait = 1; };         Outlined = {NSStrokeWidth = 3; }; ...

14.3.3. Using TextEdit

As mentioned earlier in the chapter, Tiger's new binary format for plist files makes you jump through an extra couple of hoops if you want to work with the files using a text editor. Fortunately, the plutil command makes those hoops pretty easy to navigate. Once you've used plutil to convert the file into XML format, you can open it up in TextEdit (/Applications/Utilities) and modify the preference data by hand, as shown in Figure 14-3.

Figure 14-3. Modifying a plist file using TextEdit

This is perhaps the riskiest way to work with data in the defaults database, as an error in the file will prevent it from being properly processed, most likely resulting in lost preferences. Once you're done making your changes in TextEdit, make sure you use plutil's -lint switch to check the file out. Otherwise, your changes won't have the desired effect.