Dealing with Multiple Items

On OS X v10.6, NSPasteboard allows you to write multiple items to the pasteboard. If you take advantage of this ability, you may need to consider how your application will interact with others that have not yet adopted this feature.

If you place multiple items on the pasteboard, an application that uses the OS X v10.5 and earlier API will typically retrieve just the best representation of the first item on the pasteboard (using dataForType:, -stringForType:, or propertyListForType:). You should therefore typically ensure that the first item you place on the pasteboard is that likely to be “most interesting” to clients that use the 10.5 and earlier API.

The exception to this pattern is text. If a 10.6-based application writes to the pasteboard multiple items that provide text (strings and attributed strings), then if a 10.5-based application reads text from the pasteboard the text from the items is combined using return characters. (You can think of this as akin to the pasteboard putting the individual strings from the items into an array then joining them with componentsJoinedByString:"@\r".)

Methods

You can typically use API from OS X v10.5 and earlier with the APIs introduced in OS X v10.6 together in the same application. This allows you to migrate your code to the new API in a gradual fashion. With any given sequence of interaction, however, you should be consistent in using either the API from OS X v10.5 and earlier or the APIs introduced in OS X v10.6. For example, the following combination will not work:

NSArray *fileURLs = <#An array of file URLs#>;

NSPasteboard *pboard = [NSPasteboard generalPasteboard];

NSArray *typeArray = [NSArray arrayWithObject:NSURLPboardType];

[pboard declareTypes:typeArray owner:nil]; // 10.5

[pboard writeObjects:fileURLs]; // 10.6

Backwards Compatibility

If your application currently defines a public pasteboard type that other applications rely on, you need to perform the following steps to ensure that existing applications will continue to see your pasteboard type even after your application has moved from pboard types to UTIs:

1. Formally declare the new pasteboard type UTI as an exported type declaration.

2. Ensure the declared UTI conforms to the public.data type.

3. Add a tag specification for the com.apple.nspboard-type tag to the type declaration. The value you provide should be the literal string value of the pboard type, not the name of the constant. The following example shows how to create a tag specification to associate a UTI with a pboard type:

   <key>UTTypeTagSpecification</key>

   <dict>

   <key>com.apple.nspboard-type</key>

   <string>MyCustomPboardType</string>

   </dict>

Pasteboard Types and UTIs

The NSPasteboardItem, NSPasteboardReading, and NSPasteboardWriting APIs introduced in OS X v10.6 use UTIs to specify representation types. Over time, Cocoa will be moving away from the old pboard types, and towards using UTIs exclusively on the pasteboard.

On OS X v10.6 and later, you should use UTIs to identify pasteboard types. Most of the existing pasteboard type constants are not deprecated in OS X v10.6 (the exceptions are PICT and file content types), however they will be deprecated in the future.