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

The shared pasteboard object to use for general content.

+ pasteboardByFilteringData:ofType:

Creates a new pasteboard object that supplies the specified data in as many types as possible based on the available filter services.

+ pasteboardByFilteringFile:

Creates a new pasteboard object that supplies the specified file in as many types as possible based on the available filter services.

+ pasteboardByFilteringTypesInPasteboard:

Creates a new pasteboard object that supplies the specified pasteboard data in as many types as possible based on the available filter services.

+ pasteboardWithName:

Returns the pasteboard with the specified name.

NSPasteboardName

Constants for the standard pasteboard names.

+ 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 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.

NSPasteboardType

The supported pasteboard types.

Reading Data

- readObjectsForClasses:options:

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

NSPasteboardReadingOptionKey

Options for reading pasteboard data.

NSPasteboardReadingOptions

Options to specify how data on the pasteboard should be interpreted to initialize pasteboard data.

pasteboardItems

An array that contains all the items held by the pasteboard.

- 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.

Preparing the Pasteboard for Content

- prepareForNewContentsWithOptions:

Prepares the pasteboard to receive new contents, removing the existing pasteboard contents.

NSPasteboardContentsOptions

Options for preparing the pasteboard.

Getting Information about a Pasteboard

name

The receiver’s name.

changeCount

The receiver’s change count.

Writing Data (macOS 10.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 (macOS 10.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.

NSPasteboardContentsOptions

Options for preparing the pasteboard.