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>
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 an Info.plist
file
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 the InfoPlist.strings
file
because it needs to be localized.
CFBundlePackageType
.
A four-character code that specifies the bundle’s type. For applications,
use APPL
.
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 the CFBundleVersion
key.
You should put this in the InfoPlist.strings
file
so it can be localized.
CFBundleGetInfoString
.
A text string displayed to users in the Finder’s Info window. You
should include this property in the InfoPlist.strings
file 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 the InfoPlist.strings
file for
localization. You can use this if you want a richer representation
than that provided by the CFBundleGetInfoString
property.
If you define both properties, CFBundleGetInfoHTML
supersedes CFBundleGetInfoString
.
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.plist
file
(those you can see in the Application Settings pane) with those
in the InfoPlist.strings
file.
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.plist
and InfoPlist.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 the Info.plist
file.
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.