Class

NSPasteboard

An object that transfers data to and from the pasteboard server.

Declaration

@interface NSPasteboard : NSObject

Overview

The pasteboard server is shared by all running apps. 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 apps and service providers listed in each application’s Services menu. The drag pasteboard is used to transfer data that is being dragged by the user.

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.

Writing methods such as setData:forType: provide a convenient means of writing to the first pasteboard item, without having to create the first pasteboard item. You can use code like this, for example:

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

The general pasteboard, available by way of the generalPasteboard class method, automatically participates with the Universal Clipboard feature in macOS 10.12 and later and in iOS 10.0 and later. There is no macOS API for interacting with this feature.

Topics

Creating and Releasing a Pasteboard

generalPasteboard

Returns the general NSPasteboard object.

pasteboardByFilteringData:ofType:

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.

pasteboardByFilteringFile:

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.

pasteboardByFilteringTypesInPasteboard:

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.

pasteboardWithName:

Returns the pasteboard with the specified name.

NSPasteboardName

The NSPasteboard class defines the following named pasteboards.

pasteboardWithUniqueName

Creates and returns a new pasteboard with a name that is guaranteed to be unique with respect to other pasteboards in the system.

releaseGlobally

Releases the receiver’s resources in the pasteboard server.

Writing Data

clearContents

Clears the existing contents of the pasteboard

writeObjects:

Writes an array of objects to the receiver.

setData:forType:

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

setPropertyList:forType:

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

setString:forType:

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

Reading Data

readObjectsForClasses:options:

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

NSPasteboardReadingOptionKey

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.

pasteboardItems

An array that contains all the items held by the receiver or nil if there is an error retrieving pasteboard items.

indexOfPasteboardItem:

Returns the index of the specified pasteboard item.

dataForType:

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

propertyListForType:

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

stringForType:

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

Validating Contents

availableTypeFromArray:

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

canReadItemWithDataConformingToTypes:

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

canReadObjectForClasses:options:

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.

types

An array of the receiver’s supported data types.

typesFilterableTo:

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

Getting Information about a Pasteboard

name

The receiver’s name.

changeCount

The receiver’s change count.

Writing Data (OS X v10.5 and Earlier)

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.

declareTypes:owner:

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

addTypes:owner:

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

writeFileContents:

Writes the contents of the specified file to the pasteboard.

writeFileWrapper:

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

Reading Data (OS X v10.5 and Earlier)

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.

readFileContentsType:toFile:

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

readFileWrapper

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

Relationships

Inherits From

See Also

Pasteboard

NSPasteboardItem

An item on a pasteboard.

NSPasteboardReading

A set of methods that defines the interface for initializing an object from a pasteboard.

NSPasteboardWriting

A set of methods that defines the interface for retrieving a representation of an object that can be written to a pasteboard.

NSPasteboardItemDataProvider

A set of methods implemented by the data provider of a pasteboard item to provide the data for a particular UTI type.