Cocoa and Cocoa Touch are the environments used to define Objective-C based applications that run in Mac OS X and iOS respectively. The keys associated with the Cocoa environments provide support for Interface Builder nib files and provide support for other user-facing features vended by your bundle.
Cocoa keys use the prefix NS to distinguish them from other keys. For information about developing Cocoa Touch applications for iOS, see iOS Application Programming Guide. For information about developing Cocoa applications for Mac OS X, see Cocoa Fundamentals Guide.
Table 1 contains an alphabetical listing of Cocoa keys, the corresponding name for that key in the Xcode property list editor, a high-level description of each key, and the platforms on which you use it. Detailed information about each key is available in later sections.
Key | Xcode name | Summary | Availability |
|---|---|---|---|
"Scriptable” | Specifies whether AppleScript is enabled. See “NSAppleScriptEnabled” for details. | Mac OS X | |
"Dock Tile Plugin path” | Specifies the name of application’s Dock tile plug-in, if present. See “NSDockTilePlugIn” for details. | Mac OS X | |
"Copyright (human-readable)” | (Localizable) Specifies the copyright notice for the bundle. See “NSHumanReadableCopyright” for details. | Mac OS X | |
"Cocoa Java application” | Specifies whether the program requires a running Java VM. See “NSJavaNeeded” for details. | Mac OS X | |
"Java classpaths” | An array of paths to classes whose components are preceded by | Mac OS X | |
"Java root directory” | The root directory containing the java classes. See “NSJavaRoot” for details. | Mac OS X | |
"Main nib file base name” | The name of an application’s main nib file. See “NSMainNibFile” for details. | iOS, Mac OS X | |
"Core Data persistent store type” | The type of Core Data persistent store associated with a persistent document type. See “NSPersistentStoreTypeKey” for details. | Mac OS X | |
"Preference Pane icon file” | The name of an image file resource used to represent a preference pane in the System Preferences application. See “NSPrefPaneIconFile” for details. | Mac OS X | |
"Preference Pane icon label” | The name of a preference pane displayed beneath the preference pane icon in the System Preferences application. See “NSPrefPaneIconLabel” for details. | Mac OS X | |
"Principal class” | The name of the bundle’s main class. See “NSPrincipalClass” for details. | Mac OS X | |
"Services” | An array of dictionaries specifying the services provided by an application. See “NSServices” for details. | Mac OS X | |
None | Specifies whether the application may be killed to allow for faster shut down or log out operations. See “NSSupportsSuddenTermination” for details. | Mac OS X | |
“Exported Type UTIs” | An array of dictionaries specifying the UTI-based types supported (and owned) by the application. See “UTExportedTypeDeclarations” for details. | iOS, Mac OS X | |
"Imported Type UTIs” | An array of dictionaries specifying the UTI-based types supported (but not owned) by the application. See “UTImportedTypeDeclarations” for details. | iOS, Mac OS X |
NSAppleScriptEnabled (Boolean or String - Mac OS X). This key identifies whether the application is scriptable. Set the value of this key to true (when typed as Boolean) or “YES” (when typed as String) if your application supports AppleScript.
NSDockTilePlugIn (String - Mac OS X). This key contains the name of a plug-in bundle with the .docktileplugin filename extension and residing in the application’s Contents/PlugIns directory. The bundle must contain the Dock tile plug-in for the application. For information about creating a Dock tile plug-in, see Dock Tile Programming Guide.
NSHumanReadableCopyright (String - Mac OS X). This key contains a string with the copyright notice for the bundle; for example, © 2008, My Company. You can load this string and display it in an About dialog box. This key can be localized by including it in your InfoPlist.strings files. This key replaces the obsolete CFBundleGetInfoString key.
NSJavaNeeded (Boolean or String - Mac OS X). This key specifies whether the Java VM must be loaded and started up prior to executing the bundle code. This key is required only for Cocoa Java applications to tell the system to launch the Java environment. If you are writing a pure Java application, do not include this key.
You can also specify a string type with the value “YES” instead of a Boolean value if desired.
Deprecated in Mac OS X v10.5.
NSJavaPath (Array - Mac OS X). This key contains an array of paths. Each path points to a Java class. The path can be either an absolute path or a relative path from the location specified by the key “NSJavaRoot.” The development environment (or, specifically, its jamfiles) automatically maintains the values in the array.
Deprecated in Mac OS X v10.5.
NSJavaRoot (String - Mac OS X). This key contains a string identifying a directory. This directory represents the root directory of the application’s Java class files.
NSMainNibFile (String - iOS, Mac OS X). This key contains a string with the name of the application’s main nib file (minus the .nib extension). A nib file is an Interface Builder archive containing the description of a user interface along with any connections between the objects of that interface. The main nib file is automatically loaded when an application is launched.
NSPersistentStoreTypeKey (String - Mac OS X). This key contains a string that specifies the type of Core Data persistent store associated with a document type (see “CFBundleDocumentTypes”).
NSPrefPaneIconFile (String - Mac OS X). This key contains a string with the name of an image file (including extension) containing the preference pane’s icon. This key should only be used by preference pane bundles. The image file should contain an icon 32 by 32 pixels in size. If this key is omitted, the System Preferences application looks for the image file using the CFBundleIconFile key instead.
NSPrefPaneIconLabel (String - Mac OS X). This key contains a string with the name of a preference pane. This string is displayed below the preference pane’s icon in the System Preferences application. You can split long names onto two lines by including a newline character (‘\n’) in the string. If this key is omitted, the System Preferences application gets the name from the CFBundleName key.
This key can be localized and included in the InfoPlist.strings files of a bundle.
NSPrincipalClass (String - Mac OS X). This key contains a string with the name of a bundle’s principal class. This key is used to identify the entry point for dynamically loaded code, such as plug-ins and other dynamically-loaded bundles. The principal class of a bundle typically controls all other classes in the bundle and mediates between those classes and any classes outside the bundle. The class identified by this value can be retrieved using the principalClass method of NSBundle. For Cocoa applications, the value for this key is NSApplication by default.
NSServices (Array - Mac OS X). This key contains an array of dictionaries specifying the services provided by the application. Table 2 lists the keys for specifying a service:
Key | Xcode name | Type | Description | Platforms |
|---|---|---|---|---|
"Incoming service port name” |
| This key specifies the name of the port your application monitors for incoming service requests. Its value depends on how the service provider application is registered. In most cases, this is the application name. For more information, see Services Implementation Guide. | Mac OS X | |
"Instance method name” |
| This key specifies the name of the instance method to invoke for the service. In Objective-C, the instance method must be of the form | Mac OS X | |
None |
| This key specifies an array of strings. Each string should contain a UTI defining a supported file type. Only UTI types are allowed; pasteboard types are not permitted. To specify pasteboard types, continue to use the By assigning a value to this key, your service declares that it can operate on files whose type conforms to one or more of the given file types. Your service will receive a pasteboard from which you can read file URLs. Available in Mac OS X v10.6 and later. For information on UTIs, see Uniform Type Identifiers Overview. | Mac OS X | |
"Send Types” |
| This key specifies an optional array of data type names that can be read by the service. The In Mac OS X v10.5 and earlier, this key is required. In Mac OS X v10.6 and later, you should use the | Mac OS X | |
None |
| This key specifies a description of your service that is suitable for presentation to users. This description string may be long to give users adequate information about your service. To localize the menu item text, create a Available in Mac OS X v10.6 and later. | Mac OS X | |
None |
| This key specifies a dictionary with the conditions under which your service is made available to the user. Alternatively, you can specify an array of dictionaries, each of which contains a set of conditions for enabling your service. See the discussion after this table for information about specifying the value of this key. Available in Mac OS X v10.6 and later. | Mac OS X | |
"Return Types” |
| This key specifies an array of data type names that can be returned by the service. The | Mac OS X | |
"Menu” |
| This key contains a dictionary that specifies the text to add to the Services menu. The only key in the dictionary is called In Mac OS X v10.5 and earlier, menu items must be unique. You can ensure a unique name by combining the application name with the command name and separating them with a slash character “ Submenus are not supported (or necessary) in Mac OS X v10.6 and later. If you specify a slash character in Mac OS X v10.6 and later, the slash and any text preceding it are discarded. Instead, services with the same name are disambiguated by adding the application name in parenthesis after the menu item text. To localize the menu item text, create a | Mac OS X | |
"Menu key equivalent” |
| This key is optional and contains a dictionary with the keyboard equivalent used to invoke the service menu command. Similar to | Mac OS X | |
"User Data” |
| This key is an optional string that contains a value of your choice. | Mac OS X | |
"Timeout value (in milliseconds)” |
| This key is an optional numerical string that indicates the number of milliseconds Services should wait for a response from the application providing a service when a response is required. | Mac OS X |
In Mac OS X v10.6 and later, the NSRequiredContext key may contain a dictionary or an array of dictionaries describing the conditions under which the service appears in the Services menu. If you specify a single dictionary, all of the conditions in that dictionary must be met for the service to appear. If you specify an array of dictionaries, all of the conditions in only one of those dictionaries must be met for the service to appear. Each dictionary may contain one or more of the keys listed in Table 3. All keys in the dictionary are optional.
Key | Xcode name | Type | Description | Platform |
|---|---|---|---|---|
None |
| The value of this key is a string or an array of strings, each of which contains the bundle ID ( | Mac OS X | |
None |
| The value of this key is a string or an array of strings, each of which contains a standard four-letter script tag, such as | Mac OS X | |
None |
| The value of this key is a string or an array of strings, each of which contains a BCP-47 tag indicating the language of the desired text. Your service appears if the overall language of the selected text matches one of the specified values. Matching is performed using a prefix-matching scheme. For example, specifying the value en matches text whose full BCP-47 code is | Mac OS X | |
None |
| The value of this key is an integer indicating the maximum number of selected words on which the service can operate. For example, a service to look up a stock by ticker symbol might have a value of 1 because ticker symbols cannot contain spaces. | Mac OS X | |
None |
| The value of this key is a string or an array of strings, each of which contains one of the following values: Note that all of the selected text is provided to the service-vending application, not just the parts found to contain the given data types. | Mac OS X |
For additional information about implementing services in your application, see Services Implementation Guide.
NSSupportsSuddenTermination (Boolean - Mac OS X). This key contains a boolean that indicates whether the system may kill the application outright in order to log out or shut down more quickly. You use this key to specify whether the application can be killed immediately after launch. The application can still enable or disable sudden termination at runtime using the methods of the NSProcessInfo class. The default value of this key is NO.
UTExportedTypeDeclarations (Array - iOS, Mac OS X) declares the uniform type identifiers (UTIs) owned and exported by the application. You use this key to declare your application’s custom data formats and associate them with UTIs. Exporting a list of UTIs is the preferred way to register your custom file types; however, Launch Services recognizes this key and its contents only in Mac OS X v10.5 and later. This key is ignored on versions of Mac OS X prior to version 10.5.
The value for the UTExportedTypeDeclarations key is an array of dictionaries. Each dictionary contains a set of key-value pairs identifying the attributes of the type declaration. Table 4 lists the keys you can include in this dictionary along with the typical values they contain. These keys can also be included in array of dictionaries associated with the “UTImportedTypeDeclarations” key.
Key | Xcode name | Type | Description | Platforms |
|---|---|---|---|---|
"Conforms to UTIs” |
| (Required) Contains an array of strings. Each string identifies a UTI to which this type conforms. These keys represent the parent categories to which your custom file format belongs. For example, a JPEG file type conforms to the | iOS, Mac OS X | |
"Description” |
| A user-readable description of this type. The string associated with this key may be localized in your bundle’s | iOS, Mac OS X | |
"Icon file name” |
| The name of the bundle icon resource to associate with this UTI. You should include this key only for types that your application exports. This file should have a | Mac OS X | |
"Identifier” |
| (Required) The UTI you want to assign to the type. This string uses the reverse-DNS format, whereby more generic types come first. For example, a custom format for your company would have the form | iOS, Mac OS X | |
"Reference URL” |
| The URL for a reference document that describes this type. | Mac OS X | |
None |
| The name of the 64 x 64 pixel icon resource file (located in the application’s bundle) to associate with this UTI. You should include this key only for types that your application exports. | iOS | |
None |
| The name of the 320 x 320 pixel icon resource file (located in the application’s bundle) to associate with this UTI. You should include this key only for types that your application exports. | iOS | |
"Equivalent Types” |
| (Required) A dictionary defining one or more equivalent type identifiers. The key-value pairs listed in this dictionary identify the filename extensions, MIME types, OSType codes, and pasteboard types that correspond to this type. For example, to specify filename extensions, you would use the key | iOS, Mac OS X |
The way you specify icon files in Mac OS X and iOS is different because of the supported file formats on each platform. In iOS, each icon resource file is typically a PNG file that contains only one image. Therefore, it is necessary to specify different image files for different icon sizes. However, when specifying icons in Mac OS X, you use an icon file (with extension .icns), which is capable of storing the icon at several different resolutions.
This key is supported in iOS 3.2 and later and Mac OS X 10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.
UTImportedTypeDeclarations (Array - iOS, Mac OS X) declares the uniform type identifiers (UTIs) inherently supported (but not owned) by the application. You use this key to declare any supported types that your application recognizes and wants to ensure are recognized by Launch Services, regardless of whether the application that owns them is present. For example, you could use this key to specify a file format that is defined by another company but which your program can read and export.
The value for this key is an array of dictionaries and uses the same keys as those for the “UTExportedTypeDeclarations” key. For a list of these keys, see Table 4.
This key is supported in iOS 3.2 and later and Mac OS X 10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.
Last updated: 2010-07-08