This article describes the interoperation of pasteboard API from Mac OS X v10.5 and earlier with the APIs introduced in Mac OS X v10.6.
On Mac 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 Mac 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"
.)
You can typically use API from Mac OS X v10.5 and earlier with the APIs introduced in Mac 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 Mac OS X v10.5 and earlier or the APIs introduced in Mac 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 |
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:
Formally declare the new pasteboard type UTI as an exported type declaration.
Ensure the declared UTI conforms to the public.data
type.
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> |
The NSPasteboardItem
, NSPasteboardReading Protocol Reference
, and NSPasteboardWriting Protocol Reference
APIs introduced in Mac 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 Mac 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 Mac OS X v10.6 (the exceptions are PICT and file content types), however they will be deprecated in the future.
The following table shows pasteboard types for which there are new UTIs. The table shows the Mac OS X v10.5 and earlier constant, the Mac OS X v10.6 constant, and the UTI string.
Old Constant | New Constant | UTI String |
---|---|---|
NSColorPboardType | NSPasteboardTypeColor | com.apple.cocoa.pasteboard.color |
NSSoundPboardType | NSPasteboardTypeSound | com.apple.cocoa.pasteboard.sound |
NSFontPboardType | NSPasteboardTypeFont | com.apple.cocoa.pasteboard.character-formatting |
NSRulerPboardType | NSPasteboardTypeRuler | com.apple.cocoa.pasteboard.paragraph-formatting |
NSTabularTextPboardType | NSPasteboardTypeTabularText | com.apple.cocoa.pasteboard.tabular-text |
NSMultipleTextSelectionPboardType | NSPasteboardTypeMultipleTextSelection | com.apple.cocoa.pasteboard.multiple-text-selection |
NSFindPanelSearchOptionsPboardType | NSPasteboardTypeFindPanelSearchOptions | com.apple.cocoa.pasteboard.find-panel-search-options |
The following table shows pasteboard types for which there are existing UTIs. The table shows the Mac OS X v10.5 and earlier constant (where there is one), the Mac OS X v10.6 constant, and the UTI string.
Old Constant | New Constant | UTI String |
---|---|---|
NSStringPboardType | NSPasteboardTypeString | public.utf8-plain-text |
NSPDFPboardType | NSPasteboardTypePDF | com.adobe.pdf |
NSRTFPboardType | NSPasteboardTypeRTF | public.rtf |
NSRTFDPboardType | NSPasteboardTypeRTFD | com.apple.flat-rtfd |
NSTIFFPboardType | NSPasteboardTypeTIFF | public.tiff |
NSPasteboardTypePNG | public.png | |
NSHTMLPboardType | NSPasteboardTypeHTML | public.html |
Some Mac OS X v10.5 constants do not have corresponding constant definitions on Mac OS X v10.6. The following table shows either their deprecation status or what you should use instead.
Constant | Replacement/Comments |
---|---|
NSPICTPboardType | Deprecated in Mac OS X v10.6 |
NSFilesPromisePboardType | Use |
NSVCardPboardType | Use |
NSPostScriptPboardType | Use |
NSInkTextPboardType | Use |
NSURLPboardType | Use |
NSFilenamesPboardType | Use |
Last updated: 2009-05-28