Mac Developer Library

Developer

AppKit Framework Reference NSPasteboard Class Reference

Options
Deployment Target:

On This Page
Language:

NSPasteboard

NSPasteboard objects transfer data to and from the pasteboard server. The server is shared by all running applications. It contains data that the user has cut or copied, as well as other data that one application wants to transfer to another. NSPasteboard objects are an application’s sole interface to the server and to all pasteboard operations.

An NSPasteboard object is also used to transfer data between applications and service providers listed in each application’s Services menu. The drag pasteboard (NSDragPboard) is used to transfer data that is being dragged by the user.

In OS X v10.6 and later, a pasteboard can contain multiple items. You can directly write or read any object that implements the NSPasteboardWriting or NSPasteboardReading protocol respectively. This allows you to write and read common items such as URLs, colors, images, strings, attributed strings, and sounds without an intermediary object. Your custom classes can also implement these protocols for use with the pasteboard.

The writing methods available in OS X v10.5 and earlier all operate on what is conceptually the first item on the pasteboard. They accept UTIs and pboard type strings. In a future release they may take only UTIs. In OS X v10.6 and later, the writing methods such as setData:forType: still provide a convenient means of writing to the first pasteboard item, without having to create the first pasteboard item. For example, instead of

  • [pboard clearContents];
  • NSPasteboardItem *item = [[[NSPasteboardItem alloc] init]];
  • [item setData:data forType:type];
  • [pboard writeObjects:[NSArray arrayWithObject:item]];

you can write:

  • [pboard clearContents];
  • [pboard setData:data forType:type];

In addition to being more compact, this is also a little more efficient—it avoids the need to create a separate pasteboard item and array.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns the general NSPasteboard object.

    Declaration

    Swift

    class func generalPasteboard() -> NSPasteboard

    Objective-C

    + (NSPasteboard *)generalPasteboard

    Return Value

    The general pasteboard.

    Discussion

    Invokes pasteboardWithName: to obtain the pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a new pasteboard with a unique name that supplies the specified data in as many types as possible given the available filter services.

    Declaration

    Swift

    init(byFilteringData data: NSData, ofType type: String) -> NSPasteboard

    Objective-C

    + (NSPasteboard *)pasteboardByFilteringData:(NSData *)data ofType:(NSString *)type

    Parameters

    data

    The data to be placed on the pasteboard.

    type

    The type of data in the data parameter.

    Return Value

    The new pasteboard object.

    Discussion

    The returned pasteboard also declares data of the supplied type.

    No filter service is invoked until the data is actually requested, so invoking this method is reasonably inexpensive.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a new pasteboard with a unique name that supplies the specified file data in as many types as possible given the available filter services.

    Declaration

    Swift

    init(byFilteringFile filename: String) -> NSPasteboard

    Objective-C

    + (NSPasteboard *)pasteboardByFilteringFile:(NSString *)filename

    Parameters

    filename

    The filename to put on the pasteboard.

    Return Value

    The new pasteboard object.

    Discussion

    No filter service is invoked until the data is actually requested, so invoking this method is reasonably inexpensive.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a new pasteboard with a unique name that supplies the specified pasteboard data in as many types as possible given the available filter services.

    Declaration

    Swift

    init(byFilteringTypesInPasteboard pasteboard: NSPasteboard) -> NSPasteboard

    Objective-C

    + (NSPasteboard *)pasteboardByFilteringTypesInPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    The original pasteboard object.

    Return Value

    The new pasteboard object. This method returns the object in the pasteboard parameter if the pasteboard was returned by one of the pasteboardByFiltering... methods. This prevents a pasteboard from being expanded multiple times.

    Discussion

    This process can be thought of as expanding the pasteboard, because the new pasteboard generally contains more representations of the data than pasteboard.

    This method only returns the original types and the types that can be created as a result of a single filter; the pasteboard does not have defined types that are the result of translation by multiple filters.

    No filter service is invoked until the data is actually requested, so invoking this method is reasonably inexpensive.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the pasteboard with the specified name.

    Declaration

    Swift

    init(name name: String) -> NSPasteboard

    Objective-C

    + (NSPasteboard *)pasteboardWithName:(NSString *)name

    Parameters

    name

    The name of the pasteboard. The names of standard pasteboards are given in Pasteboard Names.

    Return Value

    The pasteboard associated with the given name, or a new NSPasteboard object if the application does not yet have a pasteboard object for the specified name.

    Discussion

    Other names can be assigned to create private pasteboards for other purposes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a new pasteboard with a name that is guaranteed to be unique with respect to other pasteboards on the computer.

    Declaration

    Swift

    class func pasteboardWithUniqueName() -> NSPasteboard

    Objective-C

    + (NSPasteboard *)pasteboardWithUniqueName

    Return Value

    The new pasteboard object.

    Discussion

    This method is useful for applications that implement their own interprocess communication using pasteboards.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Releases the receiver’s resources in the pasteboard server.

    Declaration

    Swift

    func releaseGlobally()

    Objective-C

    - (oneway void)releaseGlobally

    Discussion

    After this method is invoked, no other application can use the receiver.

    Special Considerations

    A temporary, privately named pasteboard can be released this way when it is no longer needed, but a standard pasteboard should never be released globally.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Clears the existing contents of the pasteboard

    Declaration

    Swift

    func clearContents() -> Int

    Objective-C

    - (NSInteger)clearContents

    Return Value

    The change count of the receiver.

    Discussion

    Clears the existing contents of the pasteboard, preparing it for new contents. This is the first step in providing data on the pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Writes an array of objects to the receiver.

    Declaration

    Swift

    func writeObjects(_ objects: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)writeObjects:(NSArray *)objects

    Parameters

    objects

    An array of objects that implement the NSPasteboardWriting protocol (including instances of NSPasteboardItem).

    Return Value

    YEStrue if the array was successfully added, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Sets the given data as the representation for the specified type for the first item on the receiver.

    Declaration

    Swift

    func setData(_ data: NSData, forType dataType: String) -> Bool

    Objective-C

    - (BOOL)setData:(NSData *)data forType:(NSString *)dataType

    Parameters

    data

    The data to write to the pasteboard.

    dataType

    The type of data in the data parameter. The type must have been declared by a previous declareTypes:owner: message.

    Return Value

    YEStrue if the data was written successfully, otherwise NOfalse if ownership of the pasteboard has changed. Any other error raises an NSPasteboardCommunicationException.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the given property list as the representation for the specified type for the first item on the receiver.

    Declaration

    Swift

    func setPropertyList(_ propertyList: AnyObject, forType dataType: String) -> Bool

    Objective-C

    - (BOOL)setPropertyList:(id)propertyList forType:(NSString *)dataType

    Parameters

    propertyList

    The property list data to write to the pasteboard.

    dataType

    The type of property-list data in the propertyList parameter. The type must have been declared by a previous declareTypes:owner: message.

    Return Value

    YEStrue if the data was written successfully, otherwise NOfalse if ownership of the pasteboard has changed. Any other error raises an NSPasteboardCommunicationException.

    Discussion

    This method invokes setData:forType: with a serialized property list parameter.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the given string as the representation for the specified type for the first item on the receiver.

    Declaration

    Swift

    func setString(_ string: String, forType dataType: String) -> Bool

    Objective-C

    - (BOOL)setString:(NSString *)string forType:(NSString *)dataType

    Parameters

    string

    The string to write to the pasteboard.

    dataType

    The type of string data. The type must have been declared by a previous declareTypes:owner: message.

    Return Value

    YEStrue if the data was written successfully, otherwise NOfalse if ownership of the pasteboard has changed. Any other error raises an NSPasteboardCommunicationException.

    Discussion

    This method invokes setData:forType: to perform the write.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Reads from the receiver objects that best match the specified array of classes.

    Declaration

    Swift

    func readObjectsForClasses(_ classArray: [AnyObject], options options: [NSObject : AnyObject]?) -> [AnyObject]?

    Objective-C

    - (NSArray *)readObjectsForClasses:(NSArray *)classArray options:(NSDictionary *)options

    Parameters

    classArray

    An array of class objects.

    Because this method creates an instance of the first class that can read a given pasteboard item, you can order the classes in classArray to match your preferred order of representation. Classes in the array must conform to the NSPasteboardReading protocol.

    options

    A dictionary that specifies options to refine the search for pasteboard items, for example to restrict the search to file URLs with particular content types. For valid dictionary keys, see Pasteboard Reading Options.

    Return Value

    An array containing the best match (if any) for each of the items on the receiver that can be represented by a class specified in classArray. Returns nil if there is an error in retrieving the requested items from the pasteboard, or an empty array if no objects of the specified classes can be created.

    Discussion

    Classes in classArray must implement the NSPasteboardReading protocol. Cocoa classes that implement this protocol include NSImage, NSString, NSURL, NSColor, NSAttributedString, and NSPasteboardItem. For every item on the pasteboard, each class in the provided array will be queried for the types it can read using readableTypesForPasteboard:. An instance is created of the first class found in the provided array whose readable types match a conforming type contained in that pasteboard item. Any instances that could be created from pasteboard item data is returned to the caller. Additional options, such as restricting the search to file URLs with particular content types, can be specified with an options dictionary.

    Only objects of the requested classes are returned. You can always ensure to receive one object per item on the pasteboard by including the NSPasteboardItem class in the array of classes.

    Consider the following example: there are five items on the pasteboard, two contain TIFF data, two contain RTF data, one contains a private data type. The following table shows what objects you get back in the returned array for different classes in classArray.

    Classes in classArray

    Returned objects

    NSImage

    Two NSImage objects.

    NSAttributedString

    Two NSAttributedString objects.

    NSImage, NSAttributedString

    Two NSImage objects, and two NSAttributedString objects.

    NSImage, NSAttributedString, NSPasteboardItem

    Two NSImage objects, two NSAttributedString objects, and one NSPasteboardItem object containing the private data type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • An array that contains all the items held by the receiver or nil if there is an error retrieving pasteboard items. (read-only)

    Declaration

    Swift

    var pasteboardItems: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSArray *pasteboardItems

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the index of the specified pasteboard item.

    Declaration

    Swift

    func indexOfPasteboardItem(_ pasteboardItem: NSPasteboardItem) -> Int

    Objective-C

    - (NSUInteger)indexOfPasteboardItem:(NSPasteboardItem *)pasteboardItem

    Parameters

    pasteboardItem

    A pasteboard item.

    Return Value

    The index of the specified pasteboard item. If pasteboardItem has not been added to any pasteboard, or is owned by another pasteboard, returns NSNotFound.

    Discussion

    An item’s index in the pasteboard is useful for a pasteboard item data provider that has promised data for multiple items, to be able to easily match the pasteboard item to an array of source data from which to derive the promised data.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the data for the specified type from the first item in the receiver that contains the type.

    Declaration

    Swift

    func dataForType(_ dataType: String) -> NSData?

    Objective-C

    - (NSData *)dataForType:(NSString *)dataType

    Parameters

    dataType

    The type of data you want to read from the pasteboard. This value should be one of the types returned by types or availableTypeFromArray:.

    Return Value

    A data object containing the data for the specified type from the first item in the receiver that contains the type, or nil if the contents of the pasteboard changed since they were last checked.

    This method may also return nil if the pasteboard server cannot supply the data in time—for example, if the pasteboard’s owner is slow in responding to a pasteboard:provideDataForType: message and the interprocess communication times out.

    Discussion

    Errors other than a timeout raise an NSPasteboardCommunicationException.

    If nil is returned, the application should put up a panel informing the user that it was unable to carry out the paste operation. Note that sending types or availableTypeFromArray: before invoking dataForType: can help you determine whether a nil result from a reading method is due to something like a pasteboard timeout.

    Special Considerations

    For standard text data types such as string, RTF, and RTFD, the text data from each item is returned as one combined result separated by newlines.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the property list for the specified type from the first item in the receiver that contains the type.

    Declaration

    Swift

    func propertyListForType(_ dataType: String) -> AnyObject?

    Objective-C

    - (id)propertyListForType:(NSString *)dataType

    Parameters

    dataType

    The pasteboard data type containing the property-list data.

    Return Value

    A property list of objects of the specified type, obtained from the first item in the receiver that contains the type. The returned property list can contain any combination of objects, as long as each object is a valid property-list type (for a list of types, see property list).

    Discussion

    This method invokes the dataForType: method.

    Special Considerations

    It’s a good idea to check types or call availableTypeFromArray: before invoking propertyListForType:. Although performing this check isn’t required, doing so can help you determine if a nil result from a reading method is due to something like a pasteboard timeout.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a concatenation of the strings for the specified type from all the items in the receiver that contain the type.

    Declaration

    Swift

    func stringForType(_ dataType: String) -> String?

    Objective-C

    - (NSString *)stringForType:(NSString *)dataType

    Parameters

    dataType

    The pasteboard data type to read.

    Return Value

    A concatenation of the strings for the specified type from all the items in the receiver that contain the type, or nil if none of the items contain strings of the specified type.

    Discussion

    This method invokes dataForType: to obtain the string. If the string cannot be obtained, stringForType: returns nil. See dataForType: for a description of what will cause nil to be returned.

    In OS X v10.6 and later, if the receiver contains multiple items that can provide string, RTF, or RTFD data, the text data from each item is returned as a combined result separated by newlines.

    Special Considerations

    It’s a good idea to check types or call availableTypeFromArray: before invoking stringForType:. Although performing this check isn’t required, doing so can help you determine if a nil result from a reading method is due to something like a pasteboard timeout.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Scans the specified types for a type that the receiver supports.

    Declaration

    Swift

    func availableTypeFromArray(_ types: [AnyObject]) -> String?

    Objective-C

    - (NSString *)availableTypeFromArray:(NSArray *)types

    Parameters

    types

    An array of NSString objects specifying the pasteboard types your application supports, in preferred order.

    Return Value

    The first pasteboard type in types that is available on the pasteboard, or nil if the receiver does not contain any of the types in types.

    Discussion

    You use this method to determine the best representation available on the pasteboard. For example, if your application supports RTFD, RTF, and string data, then you might invoke the method as follows:

    • NSArray *supportedTypes =
    • [NSArray arrayWithObjects: NSRTFDPboardType, NSRTFPboardType, NSStringPboardType, nil];
    • NSString *bestType = [[NSPasteboard generalPasteboard]
    • availableTypeFromArray:supportedTypes];

    If the pasteboard contains RTF and string data, then bestType would contain NSRTFPboardType. If the pasteboard contains none of the types in supportedTypes, then bestType would be nil.

    You must send a types or availableTypeFromArray: message before reading any data from an NSPasteboard object. If you need to see if a type in the returned array matches a type string you have stored locally, use the isEqualToString: method to perform the comparison.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the receiver contains any items that conform to the specified UTIs.

    Declaration

    Swift

    func canReadItemWithDataConformingToTypes(_ types: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)canReadItemWithDataConformingToTypes:(NSArray *)types

    Parameters

    types

    An array of NSString objects containing UTIs.

    Return Value

    YEStrue if the receiver contains any items that conform to the UTIs specified in types, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns a Boolean value that indicates whether the receiver contains any items that can be represented as an instance of any class in a given array.

    Declaration

    Swift

    func canReadObjectForClasses(_ classArray: [AnyObject], options options: [NSObject : AnyObject]?) -> Bool

    Objective-C

    - (BOOL)canReadObjectForClasses:(NSArray *)classArray options:(NSDictionary *)options

    Parameters

    classArray

    An array of class objects.

    Classes in the array must conform to the NSPasteboardReading protocol.

    options

    A dictionary that specifies options to refine the search for pasteboard items, for example to restrict the search to file URLs with particular content types. For valid dictionary keys, see Pasteboard Reading Options.

    Return Value

    YEStrue if the receiver contains any items that can be represented as an instance of a class specified in classArray, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • types types Property

    An array of the receiver’s supported data types. (read-only)

    Declaration

    Swift

    var types: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSArray *types

    Discussion

    The types array is an array of NSString objects containing the union of the types of data declared for all the pasteboard items on the receiver. The returned types are listed in the order they were declared. It’s a good idea to check the value of types (or call availableTypeFromArray:) before reading any data from an NSPasteboard object. If you need to see if a type in the types array matches a type string you have stored locally, use the isEqualToString: method to perform the comparison.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the data types that can be converted to the specified type using the available filter services.

    Declaration

    Swift

    class func typesFilterableTo(_ type: String) -> [AnyObject]

    Objective-C

    + (NSArray *)typesFilterableTo:(NSString *)type

    Parameters

    type

    The target data type.

    Return Value

    An array of NSString objects containing the types that can be converted to the target data type.

    Discussion

    The array also contains the original type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • name name Property

    The receiver’s name. (read-only)

    Declaration

    Swift

    var name: String { get }

    Objective-C

    @property(readonly, copy) NSString *name

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s change count. (read-only)

    Declaration

    Swift

    var changeCount: Int { get }

    Objective-C

    @property(readonly) NSInteger changeCount

    Discussion

    The change count starts at zero when a client creates the receiver and becomes the first owner. The change count subsequently increments each time the pasteboard ownership changes.

    The change count is also returned from clearContents and declareTypes:owner:. You can therefore record the value of changeCount at the time that you take ownership of the pasteboard and compare it with a later value to determine whether you still have ownership.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

These methods all operate on what is conceptually the first item on the pasteboard. They accept UTIs and pboard type strings. In a future release they may take only UTIs.

  • Prepares the receiver for a change in its contents by declaring the new types of data it will contain and a new owner.

    Declaration

    Swift

    func declareTypes(_ newTypes: [AnyObject], owner newOwner: AnyObject?) -> Int

    Objective-C

    - (NSInteger)declareTypes:(NSArray *)newTypes owner:(id)newOwner

    Parameters

    newTypes

    An array of NSString objects that specify the types of data that may be added to the new pasteboard. The types should be ordered according to the preference of the source application, with the most preferred type coming first (typically, the richest representation).

    newOwner

    The object responsible for writing data to the pasteboard, or nil if you provide data for all types immediately. If you specify a newOwner object, it must support all of the types declared in the newTypes parameter and must remain alive for as long as the data is promised on the pasteboard.

    Return Value

    The receiver's new change count.

    Discussion

    This method is the equivalent of invoking clearContents, implicitly writing the first pasteboard item, and then callingaddTypes:owner: to promise types for the first pasteboard item.

    Special Considerations

    In general, you should not use this method with writeObjects:, since writeObjects: will always write additional items to the pasteboard, and will not affect items already on the pasteboard, including the item implicitly created by this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds promises for the specified types to the first pasteboard item.

    Declaration

    Swift

    func addTypes(_ newTypes: [AnyObject], owner newOwner: AnyObject?) -> Int

    Objective-C

    - (NSInteger)addTypes:(NSArray *)newTypes owner:(id)newOwner

    Parameters

    newTypes

    An array of NSString objects, each of which specifies a type of data that can be provided to the pasteboard.

    newOwner

    The object that provides the data for the specified types.

    If the data for those types is provided immediately, the owner can be nil. If the data for the added types will be provided lazily when requested from the pasteboard, an owner object must be provided that implements the -pasteboard:provideDataForType: method of the NSPasteboardOwner informal protocol.

    Return Value

    The new change count, or 0 if there was an error adding the types.

    Discussion

    This method adds promises for the specified types to the first pasteboard item.

    You use this methods to declare additional types of data for the first pasteboard item in the receiver. You can also use it to replace existing types added by a previous declareTypes:owner: or addTypes:owner: message.

    The newTypes parameter specifies the types of data you are promising to the pasteboard. The types should be ordered according to the preference of the source application, with the most preferred type coming first (typically, the richest representation). New types are added to the end of the list containing any existing types, if any.

    If you specify a type that has already been declared, this method replaces the owner of that type with the value in newOwner. In addition, any data already already written to the pasteboard for that type is removed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – changeCount

  • Writes the contents of the specified file to the pasteboard.

    Declaration

    Swift

    func writeFileContents(_ filename: String) -> Bool

    Objective-C

    - (BOOL)writeFileContents:(NSString *)filename

    Parameters

    filename

    The name of the file to write to the pasteboard.

    Return Value

    YEStrue if the data was successfully written, otherwise NOfalse.

    Discussion

    Writes the contents of the file filename to the receiver and declares the data to be of type NSFileContentsPboardType and also of a type appropriate for the file’s extension (as returned by the NSCreateFileContentsPboardType function when passed the files extension), if it has one.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Writes the serialized contents of the specified file wrapper to the pasteboard.

    Declaration

    Swift

    func writeFileWrapper(_ wrapper: NSFileWrapper) -> Bool

    Objective-C

    - (BOOL)writeFileWrapper:(NSFileWrapper *)wrapper

    Parameters

    wrapper

    The file wrapper to write to the pasteboard.

    Return Value

    YEStrue if the data was successfully written, otherwise NOfalse.

    Discussion

    Writes the serialized contents of the file wrapper wrapper to the receiver and declares the data to be of type NSFileContentsPboardType and also of a type appropriate for the file’s extension (as returned by the NSCreateFileContentsPboardType function when passed the files extension), if it has one. If wrapper does not have a preferred filename, this method raises an exception.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

These methods all operate on what is conceptually the first item on the pasteboard. They accept UTIs and pboard type strings. In a future release they may take only UTIs.

  • Reads data representing a file’s contents from the receiver and writes it to the specified file.

    Declaration

    Swift

    func readFileContentsType(_ type: String?, toFile filename: String) -> String?

    Objective-C

    - (NSString *)readFileContentsType:(NSString *)type toFile:(NSString *)filename

    Parameters

    type

    The pasteboard data type to read. You should generally specify a value for this parameter. If you specify nil, the filename extension (in combination with the NSCreateFileContentsPboardType function) is used to determine the type.

    filename

    The file to receive the pasteboard data.

    Return Value

    The name of the file into which the data was actually written.

    Discussion

    Data of any file contents type should only be read using this method. If data matching the specified type is not found on the pasteboard, data of type NSFileContentsPboardType is requested.

    Special Considerations

    You must send an availableTypeFromArray: or types message before invoking readFileContentsType:toFile:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Reads data representing a file’s contents from the receiver and returns it as a file wrapper.

    Declaration

    Swift

    func readFileWrapper() -> NSFileWrapper?

    Objective-C

    - (NSFileWrapper *)readFileWrapper

    Return Value

    A file wrapper containing the pasteboard data, or nil if the receiver contained no data of type NSFileContentsPboardType.

    Discussion

    In OS X v10.5 and earlier, the file contents pboard type allowed you to synthesize a pboard type for a file's contents based on the file's extension. In OS X v10.5 and later, using the UTI of a file to represent its contents now replaces this functionality.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The NSPasteboard class defines the following named pasteboards.

    Declaration

    Swift

    var NSGeneralPboard: NSString! var NSFontPboard: NSString! var NSRulerPboard: NSString! var NSFindPboard: NSString! var NSDragPboard: NSString!

    Objective-C

    NSString *NSGeneralPboard; NSString *NSFontPboard; NSString *NSRulerPboard; NSString *NSFindPboard; NSString *NSDragPboard;

    Constants

    • NSGeneralPboard

      NSGeneralPboard

      The pasteboard that’s used for ordinary cut, copy, and paste operations.

      This pasteboard holds the contents of the last selection that’s been cut or copied.

      Available in OS X v10.0 and later.

    • NSFontPboard

      NSFontPboard

      The pasteboard that holds font and character information and supports Copy Font and Paste Font commands that may be implemented in a text editor.

      Available in OS X v10.0 and later.

    • NSRulerPboard

      NSRulerPboard

      The pasteboard that holds information about paragraph formats in support of the Copy Ruler and Paste Ruler commands that may be implemented in a text editor.

      Available in OS X v10.0 and later.

    • NSFindPboard

      NSFindPboard

      The pasteboard that holds information about the current state of the active application’s find panel.

      This information permits users to enter a search string into the find panel, then switch to another application to conduct another search.

      Available in OS X v10.0 and later.

    • NSDragPboard

      NSDragPboard

      The pasteboard that stores data to be moved as the result of a drag operation.

      For additional information on working with the drag pasteboard, see Drag and Drop Programming Topics.

      Available in OS X v10.0 and later.

  • The NSPasteboard class uses the following constants to define UTIs for common pasteboard data types.

    Declaration

    Swift

    let NSPasteboardTypeString: NSString! let NSPasteboardTypePDF: NSString! let NSPasteboardTypeTIFF: NSString! let NSPasteboardTypePNG: NSString! let NSPasteboardTypeRTF: NSString! let NSPasteboardTypeRTFD: NSString! let NSPasteboardTypeHTML: NSString! let NSPasteboardTypeTabularText: NSString! let NSPasteboardTypeFont: NSString! let NSPasteboardTypeRuler: NSString! let NSPasteboardTypeColor: NSString! let NSPasteboardTypeSound: NSString! let NSPasteboardTypeMultipleTextSelection: NSString! let NSPasteboardTypeFindPanelSearchOptions: NSString!

    Objective-C

    NSString *const NSPasteboardTypeString; NSString *const NSPasteboardTypePDF; NSString *const NSPasteboardTypeTIFF; NSString *const NSPasteboardTypePNG; NSString *const NSPasteboardTypeRTF; NSString *const NSPasteboardTypeRTFD; NSString *const NSPasteboardTypeHTML; NSString *const NSPasteboardTypeTabularText; NSString *const NSPasteboardTypeFont; NSString *const NSPasteboardTypeRuler; NSString *const NSPasteboardTypeColor; NSString *const NSPasteboardTypeSound; NSString *const NSPasteboardTypeMultipleTextSelection; NSString *const NSPasteboardTypeFindPanelSearchOptions;

    Constants

    • NSPasteboardTypeString

      NSPasteboardTypeString

      String data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypePDF

      NSPasteboardTypePDF

      PDF data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeTIFF

      NSPasteboardTypeTIFF

      Tag Image File Format (TIFF) data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypePNG

      NSPasteboardTypePNG

      PNG image data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeRTF

      NSPasteboardTypeRTF

      Rich Text Format (RTF) data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeRTFD

      NSPasteboardTypeRTFD

      RTFD formatted file contents.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeHTML

      NSPasteboardTypeHTML

      HTML data.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeTabularText

      NSPasteboardTypeTabularText

      An NSString object containing tab-separated fields of text.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeFont

      NSPasteboardTypeFont

      Font and character information.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeRuler

      NSPasteboardTypeRuler

      Paragraph formatting information.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeColor

      NSPasteboardTypeColor

      Color data (an NSColor object).

      Available in OS X v10.6 and later.

    • NSPasteboardTypeSound

      NSPasteboardTypeSound

      Sound data (an NSSound object).

      Available in OS X v10.6 and later.

    • NSPasteboardTypeMultipleTextSelection

      NSPasteboardTypeMultipleTextSelection

      Multiple text selection.

      Available in OS X v10.6 and later.

    • NSPasteboardTypeFindPanelSearchOptions

      NSPasteboardTypeFindPanelSearchOptions

      Type for the Find panel metadata property list.

      Available in OS X v10.6 and later.

  • The NSPasteboard class uses the following common pasteboard data types.

    Declaration

    Swift

    var NSColorPboardType: NSString! var NSFileContentsPboardType: NSString! var NSFilenamesPboardType: NSString! var NSFontPboardType: NSString! var NSHTMLPboardType: NSString! var NSPDFPboardType: NSString! var NSPostScriptPboardType: NSString! var NSRulerPboardType: NSString! var NSRTFPboardType: NSString! var NSRTFDPboardType: NSString! var NSStringPboardType: NSString! var NSTabularTextPboardType: NSString! var NSTIFFPboardType: NSString! var NSURLPboardType: NSString! var NSVCardPboardType: NSString! var NSFilesPromisePboardType: NSString! var NSInkTextPboardType: NSString! var NSMultipleTextSelectionPboardType: NSString! let NSPasteboardTypeTextFinderOptions: NSString!

    Objective-C

    NSString *NSStringPboardType; NSString *NSFilenamesPboardType; NSString *NSPostScriptPboardType; NSString *NSTIFFPboardType; NSString *NSRTFPboardType; NSString *NSTabularTextPboardType; NSString *NSFontPboardType; NSString *NSRulerPboardType; NSString *NSFileContentsPboardType; NSString *NSColorPboardType; NSString *NSRTFDPboardType; NSString *NSHTMLPboardType; NSString *NSPICTPboardType; NSString *NSURLPboardType; NSString *NSPDFPboardType; NSString *NSVCardPboardType; NSString *NSFilesPromisePboardType; NSString *NSMultipleTextSelectionPboardType;

    Constants

    • NSColorPboardType

      NSColorPboardType

      NSColor data.

      On OS X v10.6 and later, use NSPasteboardTypeColor (and you read and write colors directly to and from the pasteboard).

      Available in OS X v10.0 and later.

    • NSFileContentsPboardType

      NSFileContentsPboardType

      A representation of a file’s contents.

      The file contents pboard type allowed you to synthesize a pboard type for a file's contents based on the file's extension.

      On OS X v10.6 and later, you should use the UTI of a file to represent its contents instead.

      Available in OS X v10.0 and later.

    • NSFilenamesPboardType

      NSFilenamesPboardType

      An array of NSString objects designating one or more filenames.

      On OS X v10.6 and later, use writeObjects: to write file URLs to the pasteboard.

      Available in OS X v10.0 and later.

    • NSFontPboardType

      NSFontPboardType

      Font and character information.

      On OS X v10.6 and later, use NSPasteboardTypeFont instead.

      Available in OS X v10.0 and later.

    • NSHTMLPboardType

      NSHTMLPboardType

      HTML (which an NSTextView object can read from, but not write to).

      On OS X v10.6 and later, use NSPasteboardTypeHTML instead.

      Available in OS X v10.1 and later.

    • NSPDFPboardType

      NSPDFPboardType

      PDF data.

      On OS X v10.6 and later, use NSPasteboardTypePDF instead.

      Available in OS X v10.0 and later.

    • NSPICTPboardType

      NSPICTPboardType

      QuickDraw picture data.

      The PICT format was formally deprecated in OS X v10.4 along with QuickDraw. You should not be explicitly providing or looking for PICT data on the pasteboard.

      To aid in this deprecation, if PICT is the only image type on the pasteboard, as is sometimes the case when copying images from 32-bit Carbon applications, a translated image type will be automatically reported and provided by NSPasteboard. The translated type is added to the types array ahead of PICT so that the deprecated PICT format is not the preferred format. In addition, when an application provides image data to NSPasteboard, the Carbon Pasteboard Manager will automatically make a PICT translation available to 32-bit Carbon applications.

      Although NSPICTPboardType, and its UTI equivalent kUTTypePICT, will appear in a pasteboard's type array retrieved from the existing NSPasteboard API, it may cease to be reported in future releases.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • NSPostScriptPboardType

      NSPostScriptPboardType

      Encapsulated PostScript (EPS) code.

      On OS X v10.6 and later, use @"com.adobe.encapsulated-postscript" instead.

      Available in OS X v10.0 and later.

    • NSRulerPboardType

      NSRulerPboardType

      Paragraph formatting information.

      On OS X v10.6 and later, use NSPasteboardTypeRuler instead.

      Available in OS X v10.0 and later.

    • NSRTFPboardType

      NSRTFPboardType

      Rich Text Format (RTF) data.

      On OS X v10.6 and later, use NSPasteboardTypeRTF instead.

      Available in OS X v10.0 and later.

    • NSRTFDPboardType

      NSRTFDPboardType

      RTFD formatted file contents.

      On OS X v10.6 and later, use NSPasteboardTypeRTFD instead.

      Available in OS X v10.0 and later.

    • NSStringPboardType

      NSStringPboardType

      NSString data.

      In apps that adopt App Sandbox, use an NSURL object, a bookmark, or a filename pasteboard type instead. In a nonsandboxed app, you can also use the NSPasteboardTypeString pasteboard type.

      Available in OS X v10.0 and later.

    • NSTabularTextPboardType

      NSTabularTextPboardType

      An NSString object containing tab-separated fields of text.

      On OS X v10.6 and later, use NSPasteboardTypeTabularText instead.

      Available in OS X v10.0 and later.

    • NSTIFFPboardType

      NSTIFFPboardType

      Tag Image File Format (TIFF) data.

      On OS X v10.6 and later, use NSPasteboardTypeTIFF instead.

      Available in OS X v10.0 and later.

    • NSURLPboardType

      NSURLPboardType

      NSURL data for one file or resource.

      On OS X v10.6 and later, use writeObjects: to write URLs directly to the pasteboard instead.

      On OS X v10.5 and earlier: to write an URL to a pasteboard you use writeToPasteboard: (NSURL); to get an URL from a pasteboard you use URLFromPasteboard: (NSURL).

      Available in OS X v10.0 and later.

    • NSVCardPboardType

      NSVCardPboardType

      VCard data.

      On OS X v10.6 and later, use (NSString *)kUTTypeVCard instead.

      Available in OS X v10.2 and later.

    • NSFilesPromisePboardType

      NSFilesPromisePboardType

      Promised files.

      On OS X v10.6 and later, use (NSString *)kPasteboardTypeFileURLPromise instead.

      For information on promised files, see Dragging Files in Drag and Drop Programming Topics.

      Available in OS X v10.2 and later.

    • NSInkTextPboardType

      NSInkTextPboardType

      Ink text data.

      On OS X v10.6 and later, use (NSString *)kUTTypeInkText instead.

      For information on ink text objects, see Using Ink Services in Your Application.

      Available in OS X v10.4 and later.

    • NSMultipleTextSelectionPboardType

      NSMultipleTextSelectionPboardType

      Multiple text selection.

      On OS X v10.6 and later, use NSPasteboardTypeMultipleTextSelection instead.

      Available in OS X v10.5 and later.

    • NSPasteboardTypeTextFinderOptions

      NSPasteboardTypeTextFinderOptions

      Type for the Find panel metadata property list..

      Available in OS X v10.7 and later.

    Discussion

    See also NSSoundPboardType (NSSound).

  • These options can be used for both the readObjectsForClasses:options: and canReadObjectForClasses:options: methods, unless otherwise specified. The currently available options allow for customization of how URLS are read from the pasteboard.

    Declaration

    Swift

    let NSPasteboardURLReadingFileURLsOnlyKey: NSString! let NSPasteboardURLReadingContentsConformToTypesKey: NSString!

    Objective-C

    NSString *NSPasteboardURLReadingFileURLsOnlyKey; NSString *NSPasteboardURLReadingContentsConformToTypesKey;

    Constants

    • NSPasteboardURLReadingFileURLsOnlyKey

      NSPasteboardURLReadingFileURLsOnlyKey

      Option for reading URLs to restrict the results to file URLs only.

      The value for this key is an NSNumber object with a boolean value.

      Available in OS X v10.6 and later.

    • NSPasteboardURLReadingContentsConformToTypesKey

      NSPasteboardURLReadingContentsConformToTypesKey

      Option for reading URLs to restrict the results to URLs with contents that conform to any of the provided UTI types.

      If the content type of a URL cannot be determined, it will not be considered to match. The value for this key is an array of UTI type strings.

      Available in OS X v10.6 and later.