Class

NSPasteboard

NSPasteboard objects transfer data to and from the pasteboard server. The 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.

Overview

An NSPasteboard object is also used to transfer data between apps 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.

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 general() 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.

Symbols

Creating and Releasing a Pasteboard

class func general()

Returns the general NSPasteboard object.

init(byFilteringData: Data, ofType: String)

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.

init(byFilteringFile: String)

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.

init(byFilteringTypesIn: NSPasteboard)

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.

init(name: String)

Returns the pasteboard with the specified name.

class func withUniqueName()

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

func releaseGlobally()

Releases the receiver’s resources in the pasteboard server.

Writing Data

func clearContents()

Clears the existing contents of the pasteboard

func writeObjects([NSPasteboardWriting])

Writes an array of objects to the receiver.

func setData(Data?, forType: String)

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

func setPropertyList(Any, forType: String)

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

func setString(String, forType: String)

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

Reading Data

func readObjects(forClasses: [AnyClass], options: [String : Any]? = nil)

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

var pasteboardItems: [NSPasteboardItem]?

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

func index(of: NSPasteboardItem)

Returns the index of the specified pasteboard item.

func data(forType: String)

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

func propertyList(forType: String)

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

func string(forType: String)

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

Validating Contents

func availableType(from: [String])

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

func canReadItem(withDataConformingToTypes: [String])

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

func canReadObject(forClasses: [AnyClass], options: [String : Any]? = nil)

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.

var types: [String]?

An array of the receiver’s supported data types.

class func types(filterableTo: String)

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

Getting Information about a Pasteboard

var name: String

The receiver’s name.

var changeCount: Int

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.

func declareTypes([String], owner: Any?)

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

func addTypes([String], owner: Any?)

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

func writeFileContents(String)

Writes the contents of the specified file to the pasteboard.

func write(FileWrapper)

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.

func readFileContentsType(String?, toFile: String)

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

func readFileWrapper()

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

Constants

Pasteboard Names

The NSPasteboard class defines the following named pasteboards.

Types for Standard Data (macOS 10.6 and later)

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

Types for Standard Data (OS X v10.5 and earlier)

The NSPasteboard class uses the following common pasteboard data types.

Pasteboard Reading Options

These options can be used for both the readObjects(forClasses:options:) and canReadObject(forClasses:options:) methods, unless otherwise specified. The currently available options allow for customization of how URLS are read from the pasteboard.

Relationships

Inherits From

Conforms To