Integrating with OS X v10.5 and Earlier
This article describes the interoperation of pasteboard API from OS X v10.5 and earlier with the APIs introduced in OS X v10.6.
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:
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>
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.
Pasteboard Types with New UTIs
The following table shows pasteboard types for which there are new UTIs. The table shows the OS X v10.5 and earlier constant, the 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 |
Constants for Common Pasteboard Types with Existing UTIs
The following table shows pasteboard types for which there are existing UTIs. The table shows the OS X v10.5 and earlier constant (where there is one), the 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 |
Pasteboard Types Without Direct Replacement
Some OS X v10.5 constants do not have corresponding constant definitions on OS X v10.6. The following table shows either their deprecation status or what you should use instead.
Constant | Replacement/Comments |
---|---|
NSPICTPboardType | Deprecated in OS X v10.6 |
NSFilesPromisePboardType | Use |
NSVCardPboardType | Use |
NSPostScriptPboardType | Use |
NSInkTextPboardType | Use |
NSURLPboardType | Use |
NSFilenamesPboardType | Use |
Copyright © 2010 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2010-09-01