---

NSPasteboard

Class at a Glance

An NSPasteboard object is an interface to a pasteboard server that allows you to transfer data between applications, as in copy, cut, and paste operations. The data can be placed in the pasteboard server in a variety of representations.

Principal Attributes

• Owners

• Change count

• Data types

• Name

Creation

generalPasteboard

Returns the general NSPasteboard.

pasteboardWithName

Returns a named NSPasteboard.

Commonly Used Methods

types

Returns an NSArray of pasteboard data types.

declareTypes

Prepares NSPasteboard to receive new data.

dataForType

Reads data from a pasteboard.

setDataForType

Writes data to a pasteboard.

stringForType

Reads a String from a pasteboard.

setStringForType

Writes a String to a pasteboard.

Overview

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.

The drag pasteboard (NSDragPboard) is used to transfer data that is being dragged by the user.

NSPasteboard is also used to transfer data between applications and service providers listed in each application’s Services menu.

Tasks

Constructors

• NSPasteboard

Creating and Releasing an NSPasteboard Object

• generalPasteboard
• pasteboardByFilteringData
• pasteboardByFilteringFile
• pasteboardByFilteringTypesInPasteboard
• pasteboardWithName
• pasteboardWithUniqueName
• typesFilterableTo
• releaseGlobally

Referring to a Pasteboard by Name

• name

Writing Data

• addTypes
• declareTypes
• setDataForType
• setPropertyListForType
• setStringForType
• writeFileContents
• writeFileWrapper

Determining Types

• availableTypeFromArray
• types

Reading Data

• changeCount
• dataForType
• propertyListForType
• readFileContentsTypeToFile
• readFileWrapper
• stringForType

Methods implemented by the owner

• pasteboardChangedOwner  delegate method
• pasteboardProvideDataForType  delegate method

Static Methods

generalPasteboard

Returns the general NSPasteboard.

public static NSPasteboard generalPasteboard()

Discussion

Invokes pasteboardWithName to obtain the pasteboard.

pasteboardByFilteringData

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

public static NSPasteboard pasteboardByFilteringData(NSData data, String type)

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.

pasteboardByFilteringFile

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

public static NSPasteboard pasteboardByFilteringFile(String filename)

Discussion

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

pasteboardByFilteringTypesInPasteboard

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

public static NSPasteboard pasteboardByFilteringTypesInPasteboard(NSPasteboard pasteboard)

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 returns pasteboard if pasteboard was returned by one of the pasteboardByFiltering... methods, so a pasteboard cannot be expanded multiple times. 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.

pasteboardWithName

Returns the pasteboard for the name name.

public static NSPasteboard pasteboardWithName(String name)

Discussion

A new object is created only if the application does not yet have an NSPasteboard object for the specified name; otherwise, the existing one is returned. To get a standard pasteboard, name should be one of the following variables:

• GeneralPboard

• FontPboard

• RulerPboard

• FindPboard

• DragPboard

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

pasteboardWithUniqueName

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

public static NSPasteboard pasteboardWithUniqueName()

Discussion

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

typesFilterableTo

Returns an array listing the types of data that can be converted to type by available filter services.

public static NSArray typesFilterableTo(String type)

Discussion

The array contains the original type.

Instance Methods

addTypes

Adds the data types in newTypes to the receiver and declares a new owner newOwner.

public int addTypes(NSArray newTypes, Object newOwner)

Discussion

This method can be useful when multiple entities (such as a combination of application and library methods) contribute data for a single copy command. This method should be invoked only after a declareTypes message has been sent for the same types. The owner for the new types may be different from the owner(s) of the previously declared types.

Returns the new change count, or 0 in case of an error.

See Also

• changeCount

availableTypeFromArray

Scans types and returns the first type that matches a type declared on the receiver.

public String availableTypeFromArray(NSArray types)

Discussion

A types or availableTypeFromArray message should be sent before reading any data from an NSPasteboard.

changeCount

Returns the receiver’s change count.

public int changeCount()

Discussion

The change count starts at zero when a client creates the receiver and becomes the first owner. The change count increments for reasons other than ownership changes. Basically any modification of the pasteboard increments the change count. For example, when an owner converts a promise to actual data, the change count is incremented.

See Also

• declareTypes

dataForType

Reads the dataType representation of the current contents of the receiver.

public NSData dataForType(String dataType)

Discussion

dataType should be one of the types returned by the types method. A types or availableTypeFromArray message should be sent before invoking dataForType.

If the data is successfully read, this method returns the data. It returns null if the contents of the pasteboard have changed (if the change count has been incremented by a declareTypes message) since they were last checked with the types method. It also returns null if the pasteboard server cannot supply the data in time—for example, if the pasteboard’s owner is slow in responding to a pasteboardProvideDataForType message and the interprocess communication times out. The integer seconds timeout value is obtained from PasteboardPromiseTimeout, or is 120 seconds if the default does not exist. All other errors throw an PasteboardCommunicationException.

If null is returned, the application should put up a panel informing the user that it was unable to carry out the paste operation.

See Also

• setDataForType

declareTypes

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

public int declareTypes(NSArray newTypes, Object newOwner)

Discussion

This is the first step in responding to a user’s copy or cut command and must precede the messages that actually write the data. A declareTypes message essentially changes the contents of the receiver: It invalidates the current contents of the receiver and increments its change count.

The newTypes argument is an array of Strings that specifies the types the new contents of the pasteboard may assume. The types should be ordered according to the preference of the source application, with the most preferred type coming first (typically, the richest representation).

The newOwner argument is the object responsible for writing data to the pasteboard in all the types listed in newTypes. You can write the data immediately after declaring the types or wait until it is required for a paste operation. If you wait, the owner will receive a pasteboardProvideDataForType message requesting the data in a particular type when it is needed. You might choose to write data immediately for the most preferred type, but wait for the others to see whether they’ll be requested.

The newOwner argument can be null if data is provided for all types immediately. Otherwise, the owner should be an object that will not be released. It should not, for example, be the NSView that displays the data if that NSView is in a window that might be closed.

Returns the receiver’s new change count.

See Also

• setStringForType
• addTypes
• changeCount

name

Returns the receiver’s name.

public String name()

See Also

• pasteboardWithName

propertyListForType

Returns a property list object using the type specified by dataType.

public Object propertyListForType(String dataType)

Discussion

A property list is an object of NSArray, NSData, NSDictionary, or String objects—or any combination thereof.

A types or availableTypeFromArray message should be sent before invoking propertyListForType.

This method invokes dataForType.

See Also

• setPropertyListForType

readFileContentsTypeToFile

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

public String readFileContentsTypeToFile(String type, String filename)

Discussion

An availableTypeFromArray or types message should be sent before invoking readFileContentsTypeToFile.

Data of any file contents type should only be read using this method. type should generally be specified; if type is null, a type based on the extension of filename is substituted. If data matching type is not found on the NSPasteboard, data of type FileContentsPboardType is requested. Returns the name of the file the data was actually written to.

See Also

• writeFileContents

readFileWrapper

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

public NSFileWrapper readFileWrapper()

Discussion

If there is no data of type FileContentsPboardType on the receiver, this method returns null.

releaseGlobally

Releases the receiver’s resources in the pasteboard server.

public void releaseGlobally()

Discussion

After this method is invoked, no other application can use the named pasteboard. 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.

setDataForType

Writes data to the pasteboard server.

public boolean setDataForType(NSData data, String dataType)

Discussion

dataType gives the type of data being written; it must be a type declared in the previous declareTypes message. data points to the data to be sent to the pasteboard server.

Returns true if the data is successfully written or false if ownership of the pasteboard has changed. Any other error throws a PasteboardCommunicationException.

See Also

• dataForType
• setPropertyListForType
• setStringForType

setPropertyListForType

Writes propertyList to the pasteboard server.

public boolean setPropertyListForType(Object propertyList, String dataType)

Discussion

dataType gives the type of data being written; it must be a type declared in the previous declareTypes message. propertyList points to the data to be sent to the pasteboard server.

This method invokes setDataForType with a serialized property list parameter.

Returns true if the data is successfully written or false if ownership of the pasteboard has changed. Any other error throws a PasteboardCommunicationException.

See Also

• propertyListForType
• setStringForType

setStringForType

Writes string to the pasteboard server.

public boolean setStringForType(String string, String dataType)

Discussion

dataType gives the type of data being written; it must be a type declared in the previous declareTypes message. string points to the data to be sent to the pasteboard server.

This method invokes setDataForType to perform the write.

Returns true if the data is successfully written or false if ownership of the pasteboard has changed. Any other error throws a PasteboardCommunicationException.

See Also

• stringForType
• setDataForType
• setPropertyListForType

stringForType

Returns a String using the type specified by dataType.

public String stringForType(String dataType)

Discussion

types or availableTypeFromArray should be sent before invoking stringForType.

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

See Also

• setStringForType

types

Returns an array of the receiver’s data types.

public NSArray types()

Discussion

Returns an array of the types declared for the current contents of the NSPasteboard. The array is an array of Strings holding the type names. Types are listed in the order they were declared.

The types or availableTypeFromArray method should be sent before reading any data from the receiver.

See Also

• declareTypes
• dataForType

writeFileContents

public boolean writeFileContents(String filename)

Discussion

Writes the contents of the file filename to the receiver and declares the data to be of type FileContentsPboardType and also of a type appropriate for the file’s extension, if it has one. Returns true if the data from filename was successfully written to the receiver and false otherwise.

See Also

• readFileContentsTypeToFile

writeFileWrapper

public boolean writeFileWrapper(NSFileWrapper wrapper)

Discussion

Writes the serialized contents of the file wrapper wrapper to the receiver and declares the data to be of type FileContentsPboardType and also of a type appropriate for the file’s extension, if it has one. If wrapper does not have a preferred filename, this method throws an exception. Returns true if it could successfully write the data from wrapper to the receiver and false otherwise.

Constants

NSPasteboard defines the following named pasteboards:

NSPasteboard defines the following common pasteboard data types:

Delegate Methods

pasteboardChangedOwner

Notifies a prior owner of the sender pasteboard (and owners of representations on the pasteboard) that the pasteboard has changed owners.

public abstract void pasteboardChangedOwner(NSPasteboard sender)

Discussion

This method is optional and need only be implemented by pasteboard owners that need to know when they have lost ownership. The owner is not able to read the contents of the pasteboard when responding to this method. The owner should be prepared to receive this method at any time, even from within the declareTypes method used to declare ownership.

See Also

• changeCount

pasteboardProvideDataForType

Implemented by the owner (previously declared in a declareTypes message) to provide promised data.

public abstract void pasteboardProvideDataForType(NSPasteboard sender, String type)

Discussion

The owner receives a pasteboardProvideDataForType message from the sender pasteboard when the data is required for a paste operation; type gives the type of data being requested. The requested data should be written to sender using the setDataForType, setPropertyListForType, or setStringForType methods.

pasteboardProvideDataForType messages may also be sent to the owner when the application is shut down through Application's terminate method. This is the method that’s invoked in response to a Quit command. Thus the user can copy something to the pasteboard, quit the application, and still paste the data that was copied.

A pasteboardProvideDataForType message is sent only if type data has not already been supplied. Instead of writing all data types when the cut or copy operation is done, an application can choose to implement this method to provide the data for certain types only when they’re requested.

If an application writes data to the NSPasteboard in the richest, and therefore most preferred, type at the time of a cut or copy operation, its pasteboardProvideDataForType method can simply read that data from the pasteboard, convert it to the requested type, and write it back to the pasteboard as the new type.

---