Property lists offer a uniform and architecture-independent means to organize, store, and access data for your application. They are used frequently in Mac OS X, particularly by the Finder to determine what to do when it encounters an application or one of its documents. (The Finder is the application that manages the user’s desktop and mediates access to applications, documents, and other items in the file system.) Some of the most common data included in a property list are application name, version, type, creator code, and icon filename.
There are a number of reasons why you’ll need to modify your application’s property list. Property lists store essential configuration information that your program code or the operating system can access at runtime. Application name and version properties are used to display information to the user in an About window or a Finder Info window. If your application opens documents, you need to set up properties to let the Finder know which documents can be opened by your application.
You’ve already seen in Chapter 3
that a property list (the Info.plist file)
is part of every Mac OS X application bundle. In Chapter 8
we discussed localizing properties that will be seen in the interface
and putting them in an InfoPlist.strings file.
We actually haven’t looked at the contents of an Info.plist file
or taken a look at the default properties associated with a Carbon application.
So, in this chapter, we’ll:
See what Project Builder provides in the default information property list
Modify the information property list for the Moon Travel Planner application
Look at what an About window can display from a property list
Create an About window for the Moon Travel Planner application using Interface Builder to create the window, and write code to display property list information in the window
The information property list (Info.plist)
is a special form of property list that has predefined keys for
specifying application properties of interest to the Finder and
other applications. The Info.plist is
stored inside the application’s bundle, as you saw in Chapter 3.
Like all property lists, Info.plist is
a text file that contains key-value pairs in XML syntax. (A collection of
key-value
pairs is referred to as a dictionary.) For example,
the following entry in the information property list sets a key
named CFBundlePackageType to
the string APPL. It signifies
the bundle is an application:
<key>CFBundlePackageType</key>
<string>APPL</string>
Note
XML stands for Extensible Markup Language and was developed in 1996 as an outgrowth of SGML (Structured Generalized Markup Language). XML is a popular format for data because it is platform-independent, well-supported, and relatively easy to use.
XML is an HTML-like language for structuring data with custom-defined tags. XML looks similar to HTML in that it uses tags to enclose data. Unlike HTML, the tags in XML are simply delimiters; they do not have any standard meaning as they do in HTML.
For more information about XML, see Learning XML and XML in a Nutshell, both available through O’Reilly & Associates.
You don’t need to learn XML to read or modify the information property list. You can view and modify the information property list using Project Builder or the Property List Editor application provided with Mac OS X. In fact, it is not safe to edit the XML data by hand unless you are very familiar with XML syntax.
There are two categories of predefined keys for an application’s properties:
You will need to know the key for any property whose value
you want to retrieve programmatically. (You’ll do this in Section 10.2). The
header file CFBundle.h defines
constants for many common property list keys. Although you can define
your own properties, you should use the predefined property keys
where appropriate rather than define your own.
Table 10.1 lists the default information properties supplied by Project Builder when you create a project. The first five are Standard keys; the rest are Finder keys.
Table 10-1. Default Information Properties Provided for a Project Builder Project Named Sample Application
| Key | Value |
|---|---|
CFBundleInfoDictionaryVersion
| 6.0 |
CFBundleExecutable
| Sample Application |
CFBundleVersion
| 0.1 |
CFBundleDevelopmentRegion
| English |
CFBundleName
| Sample Application |
CFBundlePackageType
| APPL |
CFBundleSignature
| ???? |
CFBundleShortVersionString
| Sample Application version 0.1 |
CFBundleGetInfoString
|
Sample Application version 0.1, copyright 2000 My Great Software. |
There are five standard keys available to a Carbon application. Four of them are included in the default information property list. They are:
CFBundleInfoDictionaryVersion. This key supports future versioning of the dictionary format. (The key-value pair format used in anInfo.plistfile is called a dictionary.) You shouldn’t modify this value.CFBundleExecutable. The name of the main executable for the bundle. For an application, this is the application’s executable file. For a loadable bundle, it is the binary that will be loaded dynamically by the bundle. For a framework, it is the shared library for the framework (in the case of a framework, the executable must have the same name as the framework). The executable name should not include an extension.CFBundleIdentifier. The unique identifier string for the bundle, with a Java-style package name (think of it as a reverse URL). For example,com.mycompany.mysoftware. The identifier locates the bundle at runtime.CFBundleVersion. The application version number. The value should be a string; used internally for version identification.CFBundleDevelopmentRegion. The language or region in which the application was developed.
These keys are used by the Finder to store important information about a bundle. Among other things, the Finder uses these properties to locate and display an application’s icon and recognize document types associated with the application:
CFBundleName. The short name of the bundle suitable for displaying in the user interface, such as in the Application menu and the About window. This key is usually in theInfoPlist.stringsfile because it needs to be localized.CFBundlePackageType. A four-character code that specifies the bundle’s type. For applications, useAPPL.CFBundleSignature. A four-character code that specifies the creator, sometimes referred to as the application signature.CFBundleShortVersionString. A description of the bundles’s version that can be displayed to users in the Finder’s Info window. (See the version information shown in Figure 10.1 for an example.) This does not have to be the same string you supply for theCFBundleVersionkey. You should put this in theInfoPlist.stringsfile so it can be localized.CFBundleGetInfoString. A text string displayed to users in the Finder’s Info window. You should include this property in theInfoPlist.stringsfile for localization.CFBundleIconFile. The filename of the bundle resource that contains the icon the Finder (or other applications) should use to display this bundle. It’s optional for filename to have an extension. If it doesn’t have one, the operating system appends an appropriate extension.CFBundleGetInfoHTML. An HTML string that’s displayed in the Finder’s Info Window. This property is usually included in theInfoPlist.stringsfile for localization. You can use this if you want a richer representation than that provided by theCFBundleGetInfoStringproperty. If you define both properties,CFBundleGetInfoHTMLsupersedesCFBundleGetInfoString.CFBundleDocumentTypes. An array of type definitions for the document types an application can recognize. Each document type for a Carbon application can be specified using the following keys:CFBundleTypeIconFile. The name of the icon file, without the extension, that contains the icon the Finder should display for the type.CFBundleTypeRole. Defines the application’s role with respect to the type; the role can be Editor, Viewer, or None.CFBundleTypeOSTypes. An array of four-character codes that map to this type.CFBundleTypeExtensions. An array of filename extensions that map to this type.
CFBundleURLTypes. An array of URL schemes the application can handle. Each URL scheme can be specified using these keys:
Project Builder provides a set of default properties when you create your project. You’ll need to view the default list and modify the values to suit your application. You may also need to add properties.
There are three ways you can view and modify property lists
in Project Builder: simple or expert views in the Application Settings
pane and by opening the InfoPlist.strings file. The
method you choose depends on your level of expertise and whether
you want to access properties that should be localized.
The Application Settings pane in Project Builder provides
access to properties in the Info.plist file.
Recall this is the master list of information properties, and can
include those that should be localized as well as those that don’t
need to be localized. You can view the properties in Simple or Expert
views. The Simple mode is shown in Figure 10.2. To view the simple mode:
The keys are listed in a more “readable” form than the CFBundle property
names. For example, the CFBundleExecutable key
is listed as Executable, and so forth. The simple listing lets you
see the core group of information properties that you should set
up for your application. If you want to add properties, you’ll
need to use the Expert view.
The Expert view, shown in Figure 10.3 lets you view Standard, Finder and user-defined keys: the property’s key, class (that is, data type), and current value. You can add new properties by clicking New Sibling, then typing a key, class, and value. To modify a property, double-click its value and type the new value.
Any changes you make in the Simple mode are reflected in the Expert view. Any change you make in Expert view is shown in Simple view as long as the property is one of the core properties listed in the Simple view.
The third way you can view and modify properties is to open
the InfoPlist.strings file. This
is the subset of the information property list—it should contain
those properties that need to be localized. Figure 10.4 shows the default InfoPlist.strings file
you get when you create a Project Builder project.
To view this file, click the Files tab, then click InfoPlist.strings in
the Resources group of the Groups & Files list. Note the syntax;
string values must be enclosed by straight quotation marks:
<key> = <value>;
There are two important things to remember about information properties:
Project Builder does not coordinate the properties in the
Info.plistfile (those you can see in the Application Settings pane) with those in theInfoPlist.stringsfile. In other words, a change made to one file is not reflected in the other. You may need to make an entry in each file.If a property exists in both places (
Info.plistandInfoPlist.strings), the value of the localized version is always used. Any function from the Carbon programming interface that gets property list information first looks for the localized version. If one isn’t found, the function looks for the property in theInfo.plistfile.
An About window is a modeless window (the user can leave it open and perform other tasks in the application) that contains your application’s version and copyright information. Figure 10.5 shows two typical About windows. The numbers in the bottom window denote pixel spacing.
As you might guess from looking at the window, you can get most of the information from the application’s information property list. Using the property list assures that the About window displays current information; when the version or copyright information changes, you only need to change it in the property list. It also makes localization easy, because the localized property list values are always returned to your application if they are available.
Items in the window should be centered with the spacing from the bottom of one element to the top of another as indicated in the figure. An application’s About window should have a title bar and be movable, and provide the Close button as the only active window control. You’ll create one in the next section, after you modify the property list.