< Previous PageNext Page >

Hide TOC

Storing Document Types Information in the Application's Property List

Applications use an information property list file, which is stored in the application’s bundle and named Info.plist, to specify various information that can be used at runtime. Document-based applications use this property list to specify the document types the application can edit or view. This information can be used by the application and system entities such as the Finder and Launch Services (an API for launching applications in Mac OS X) as well.

For example, when the NSDocumentController object creates a new document or opens an existing document, it searches the property list for such items as the document class that handles a document type, the filename extensions for the type, and whether the application can edit or merely view the type. (Similarly, Launch Services may use information about the icon file for the type.) Supplying this information in a property list allows an application to support the Open and Save panels with little effort.

Document types information is associated with the CFBundleDocumentTypes key as an array of dictionaries, each of which contains the key-value pairs that define the document type. For a list of possible keys and their values, see Property List Key Reference.

Although you can create and edit information property lists directly in the Property List Editor application (located in /Developer/Applications), Xcode also provides convenient options for viewing and editing document types information (and other property list information). Figure 1 shows the Properties pane of the Xcode inspector for the TextEdit target. In this view, you can select and edit any of the document types as well as add and delete entries.

Note: The Properties pane is visible only for targets that create products with Info.plist files, and you cannot configure Info.plist entries for legacy targets, such as Jam-based Project Builder targets, in the target inspector. To edit the Info.plist entries for Jam-based targets in Xcode, select the target in the Groups & Files list and double-click the target to launch the target editor.

Figure 1 Document types information for TextEdit application in Xcode

Because the TextEdit application doesn’t subclass NSDocument, there is no entry in the Class column in Figure 1. However, if your application subclasses NSDocument to handle a specific document type, you should specify the document subclass name as the Sketch application (which is available in /Developer/Examples/AppKit/Sketch) does with SKTDrawDocument .

The top section of the Properties pane allows you to edit basic information about the product, such as the name of the associated executable, the identifier, type and creator, version information, and an icon to associate with the finished product. The name of the icon here must match the name of an icon file (extension .icns) that resides in the Resources folder of the product bundle.

The Principal Class and Main Nib File options are specific to Cocoa applications and bundles, and Automator actions. The Principal Class field corresponds to the information property list key NSPrincipalClass. The Main Nib File field specifies the nib file that’s automatically loaded when the application is launched. It corresponds to the information property list key NSMainNibFile.

The Document Types table allows you to specify which documents your finished product can handle. You can add and remove document types from this list using the plus and minus buttons. You should list the application's primary document type first because the document controller uses that type by default when the user requests a new document. Here is what’s in the Document Types table:

Name. The name of the document type. You use this name to specify the document type in APIs such as the NSDocumentController method makeUntitledDocumentOfType:error:.
UTI. A list of Uniform Type Identifier (UTI) strings for the document. UTIs are strings that uniquely identify abstract types. They can be used to describe a file format or data type but can also be used to describe type information for other sorts of entities, such as directories, volumes, or packages. For more information on UTIs, see the header file UTType.h, available as part of LaunchServices.framework in Mac OS X v10.3 and later.
Extensions. A list of the filename extensions for this document type. Don’t include the period in the extension.
MIME Types. A list of the Multipurpose Internet Mail Extensions (MIME) types for the document. MIME types identify content types for Internet applications.
OS Types. A list of four-letter codes for the document. These codes are stored in the document's resources or information property list files.
Class. The subclass of NSDocument that this document uses.
Icon File. The name of the file that contains the document type’s icon.
Store Type. The format of persistent data store used for the document.
Role. A description of how the application uses the documents of this type. You can choose from four values:
- Editor. The application can display, edit, and save documents of this type.
- Viewer. The application can display, but not edit, documents of this type.
- Shell. The application provides runtime services for other processes—for example, a Java applet viewer.
- None. The application can neither display nor edit documents of this type but instead uses them in some other way. For example, Sketch uses this role to declare types it can export but not read.
Package. Specifies whether the document is a single file or a file package—that is, a directory that is treated as a single file by certain applications, such as the Finder.

To edit a document type, click the type’s line in the Document Types list and double-click the individual fields in each column to add or change the document type information.

Listing 1 shows the document types information from the information property list file for the TextEdit application (which is available in /Developer/Examples/AppKit/TextEdit). This listing omits some values that are used only by Apple applications. Entries where LSTypeIsPackage is true indicate a document is expected to be a package.

Listing 1 Document types information for the TextEdit application

<key>CFBundleDocumentTypes</key>

    <array>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>rtf</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>rtf.icns</string>

            <key>CFBundleTypeMIMETypes</key>

            <array>

                <string>text/rtf</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSRTFPboardType</string>

            <key>CFBundleTypeOSTypes</key>

            <array>

                <string>RTF </string>

            </array>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>doc</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>Microsoft Word Document</string>

            <key>CFBundleTypeOSTypes</key>

            <array>

                <string>W8BN</string>

                <string>W6BN</string>

            </array>

            <key>CFBundleTypeRole</key>

            <string>Viewer</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>rtfd</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>rtfd.icns</string>

            <key>CFBundleTypeName</key>

            <string>NSRTFDPboardType</string>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

            <key>LSTypeIsPackage</key>

            <true/>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>txt</string>

                <string>text</string>

                <string>*</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>txt.icns</string>

            <key>CFBundleTypeMIMETypes</key>

            <array>

                <string>text/plain</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSStringPboardType</string>

            <key>CFBundleTypeOSTypes</key>

            <array>

                <string>****</string>

            </array>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

        </dict>

        <dict>

            <key>CFBundleTypeIconFile</key>

            <string>txt.icns</string>

            <key>CFBundleTypeName</key>

            <string>Apple SimpleText document</string>

            <key>CFBundleTypeOSTypes</key>

            <array>

                <string>TEXT</string>

                <string>sEXT</string>

                <string>ttro</string>

            </array>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>html</string>

                <string>htm</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>html.icns</string>

            <key>CFBundleTypeName</key>

            <string>Apple HTML document</string>

            <key>CFBundleTypeRole</key>

            <string>Viewer</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>webarchive</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>Apple Web archive</string>

            <key>CFBundleTypeRole</key>

            <string>Viewer</string>

        </dict>

This property list specifies that the TextEdit application supports a number of native document types (rtf, rtfd, text, and Apple SimpleText, Microsoft Word, Apple HTML, and Apple Web archive). It also specifies filename extensions, which are used to filter the files shown in Open and Save panels; the first extension in each list is automatically added to the “Save as:” filename presented in the Save panel. (TextEdit specifies its CFBundleTypeRole for Word, HTML, and web archive types as Viewer, although it can write them, to indicate that it is not a primary handler of these types. So, for example, Launch Services would prefer Word to edit .doc documents.)

The TextEdit application is unusual in that it’s a document-based application that doesn’t subclass NSDocument, so the dictionaries in Listing 1 don’t specify a document class name. However, document-based Cocoa applications typically do subclass NSDocument and should specify the document class name to handle each specific document type the application can view or edit. For example, Listing 2 shows the document types entry for the information property list from the Sketch application. The first entry specifies a document class name of SKTDrawDocument, Sketch’s native document type.

Specifying the document class is important because when opening a document, the NSDocumentController object can use the information to create instances of the NSDocument subclass appropriate to a data type. As a result, you don’t have to allocate and initialize your subclass of NSDocument explicitly in your code; it is done automatically for you.

Listing 2 Document types information for the Sketch application

<key>CFBundleDocumentTypes</key>

    <array>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>sketch</string>

                <string>draw2</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>Draw2File</string>

            <key>CFBundleTypeName</key>

            <string>Apple Sketch Graphic Format</string>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

            <key>NSDocumentClass</key>

            <string>SKTDrawDocument</string>

            <key>NSExportableAs</key>

            <array>

                <string>NSPDFPboardType</string>

                <string>NSTIFFPboardType</string>

            </array>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>pdf</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSPDFPboardType</string>

            <key>CFBundleTypeRole</key>

            <string>None</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>tiff</string>

                <string>tif</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSTIFFPboardType</string>

            <key>CFBundleTypeRole</key>

            <string>None</string>

        </dict>

    </array>

The three required keys for defining a document type are CFBundleTypeExtensions, CFBundleTypeName, and CFBundleTypeRole. The second and third entries in Listing 2 specify just the required keys. A role of None usually indicates the application does not understand the data but is just declaring information about the type, as when the Finder declares the icon for fonts. In this case, Sketch is declaring the extensions for types it can write but not read. That is, the first entry (for Sketch's native document type) declares these types under the key NSExportableAs as data formats to which Sketch can export the document contents. The user can choose exportable types only during Save As operations, not Save operations.

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.