Next Page > Hide TOC

NSPasteboard Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Declared in
NSPasteboard.h
Companion guides
Related sample code

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.

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

Tasks

Creating and Releasing a Pasteboard

Getting a Pasteboard’s Name

Writing Data

Reading Data

Determining Types

Noticing Changed Ownership

Class Methods

generalPasteboard

Returns the general NSPasteboard object.

+ (NSPasteboard *)generalPasteboard

Return Value

The general pasteboard.

Discussion

Invokes pasteboardWithName: to obtain the pasteboard.

Availability
Related Sample Code
Declared In
NSPasteboard.h

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.

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

Availability
Declared In
NSPasteboard.h

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.

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

Availability
Declared In
NSPasteboard.h

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.

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

Availability
Declared In
NSPasteboard.h

pasteboardWithName:

Returns the pasteboard with the specified name.

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

Availability
Related Sample Code
Declared In
NSPasteboard.h

pasteboardWithUniqueName

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

+ (NSPasteboard *)pasteboardWithUniqueName

Return Value

The new pasteboard object.

Discussion

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

Availability
Declared In
NSPasteboard.h

typesFilterableTo:

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

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

Availability
Declared In
NSPasteboard.h

Instance Methods

addTypes:owner:

Updates the list of declared data types in the receiver

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

Return Value

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

Discussion

This method lets you declare additional types of data to 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.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

availableTypeFromArray:

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

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

Availability
Related Sample Code
Declared In
NSPasteboard.h

changeCount

Returns the receiver’s change count.

- (NSInteger)changeCount

Return Value

The change count of the receiver.

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.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

dataForType:

Returns the data for the specified type.

- (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, 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 a 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.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

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.

- (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 valid for as long as the data is promised on the pasteboard.

Return Value

The receiver's new change count.

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:owner: message essentially changes the contents of the receiver: It invalidates the current contents of the receiver and increments its change count.

You can write the data immediately after declaring the types or wait until it is required for a paste operation. If you wait, the object in the newOwner parameter receives a pasteboard:provideDataForType: 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.

A newOwner must remain valid for as long as the data is promised on the pasteboard. Once an object has provided all of the types it has declared it is no longer needed by the pasteboard—conceptually the “owner” owns the promises to provide data for declared types. See also pasteboardChangedOwner:.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

name

Returns the receiver’s name.

- (NSString *)name

Return Value

The name of the receiver.

Availability
See Also
Declared In
NSPasteboard.h

propertyListForType:

Returns a property list object for the specified type.

- (id)propertyListForType:(NSString *)dataType

Parameters
dataType

The pasteboard data type containing the property-list data.

Return Value

The property-list object. This object consists of NSArray, NSData, NSDictionary, or NSString objects—or any combination thereof

Discussion

This method invokes the dataForType: method.

Special Considerations

You must send types or availableTypeFromArray: before invoking propertyListForType:.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

readFileContentsType:toFile:

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

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

Availability
See Also
Declared In
NSPasteboard.h

readFileWrapper

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

- (NSFileWrapper *)readFileWrapper

Return Value

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

Availability
Declared In
NSPasteboard.h

releaseGlobally

Releases the receiver’s resources in the pasteboard server.

- (void)releaseGlobally

Discussion

Because a pasteboard object is an autoreleased instance of NSPasteboard, it is not released by this method, and its retain count is not changed.

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.

Availability
Declared In
NSPasteboard.h

setData:forType:

Writes data of the specified type to the pasteboard server.

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

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

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

setPropertyList:forType:

Writes the specified property list to the pasteboard server.

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

YES if the data was written successfully, otherwise NO 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.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

setString:forType:

Writes the specified string to the pasteboard server.

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

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

Discussion

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

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

stringForType:

Returns the string for the specified type.

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

Parameters
dataType

The pasteboard data type to read.

Return Value

A string containing the pasteboard data, or nil if the data could not be read.

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.

Special Considerations

You must send types or availableTypeFromArray: before invoking stringForType:.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

types

Returns an array of the receiver’s supported data types.

- (NSArray *)types

Return Value

An array of NSString objects containing the types of data declared for the current contents of the receiver. The returned types are listed in the order they were declared.

Discussion

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.

Availability
See Also
Related Sample Code
Declared In
NSPasteboard.h

writeFileContents:

Writes the contents of the specified file to the pasteboard.

- (BOOL)writeFileContents:(NSString *)filename

Parameters
filename

The name of the file to write to the pasteboard.

Return Value

YES if the data was successfully written, otherwise NO.

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.

Availability
See Also
Declared In
NSPasteboard.h

writeFileWrapper:

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

- (BOOL)writeFileWrapper:(NSFileWrapper *)wrapper

Parameters
wrapper

The file wrapper to write to the pasteboard.

Return Value

YES if the data was successfully written, otherwise NO.

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.

Availability
Declared In
NSPasteboard.h

Delegate Methods

pasteboard:provideDataForType:

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

- (void)pasteboard:(NSPasteboard *)sender provideDataForType:(NSString *)type

Parameters
sender

The pasteboard that requires the specified data for a paste operation.

type

The type of data the owner object must provide.

Discussion

The requested data should be written to sender using the setData:forType:, setPropertyList:forType:, or setString:forType: method. The pasteboard:provideDataForType: messages may also be sent to the owner when the application is shut down through an application’s terminate: method. This is the method that is 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 pasteboard:provideDataForType: message is sent only if the specified type of data has not already been supplied to the pasteboard. 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 are requested.

If an application writes data to the pasteboard in the richest, and therefore most preferred, type at the time of a cut or copy operation, its pasteboard:provideDataForType: 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.

Availability
Declared In
NSPasteboard.h

pasteboardChangedOwner:

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

- (void)pasteboardChangedOwner:(NSPasteboard *)sender

Parameters
sender

The pasteboard object whose owner changed.

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:owner: method used to declare ownership.

Once an owner has provided all of its data for declared types, it will not receive a pasteboardChangedOwner: message. If, therefore, you are maintaining an object just for the purpose of providing data lazily, rather than relying solely on receipt of a pasteboardChangedOwner: message you need to keep track of what types were promised and what types have been provided. When all the types have been provided, you may release the owner. See also declareTypes:owner:.

Availability
See Also
Declared In
NSPasteboard.h

Constants

Pasteboard Names

The NSPasteboard class defines the following named pasteboards.

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

Constants
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 Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

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 Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

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 Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

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 Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

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

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

Declared In
AppKit/NSPasteboard.h

NSPasteboard Types for Standard Data

The NSPasteboard class uses the following common pasteboard data types.

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

NSColor data.

To write a color to a pasteboard you use writeToPasteboard: (NSColor); to get a color from a pasteboard you use colorFromPasteboard: (NSColor).

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSFileContentsPboardType

A representation of a file’s contents.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSFilenamesPboardType

An array of NSString objects designating one or more filenames.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSFontPboardType

Font and character information.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSHTMLPboardType

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

Available in Mac OS X v10.1 and later.

Declared in NSPasteboard.h.

NSPDFPboardType

PDF data.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSPICTPboardType

QuickDraw picture data.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSPostScriptPboardType

Encapsulated PostScript (EPS) code.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSRulerPboardType

Paragraph formatting information.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSRTFPboardType

Rich Text Format (RTF) data.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSRTFDPboardType

RTFD formatted file contents

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSStringPboardType

NSString data.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSTabularTextPboardType

An NSString object containing tab-separated fields of text.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSTIFFPboardType

Tag Image File Format (TIFF) data.

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSURLPboardType

NSURL data for one file or resource.

To write an URL to a pasteboard you use writeToPasteboard: (NSURL); to get an URL from a pasteboard you use URLFromPasteboard: (NSURL).

Available in Mac OS X v10.0 and later.

Declared in NSPasteboard.h.

NSVCardPboardType

VCard data

Available in Mac OS X v10.2 and later.

Declared in NSPasteboard.h.

NSFilesPromisePboardType

Promised files.

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

Available in Mac OS X v10.2 and later.

Declared in NSPasteboard.h.

NSInkTextPboardType

Ink text data.

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

Available in Mac OS X v10.4 and later.

Declared in NSPasteboard.h.

NSMultipleTextSelectionPboardType

Multiple text selection.

Available in Mac OS X v10.5 and later.

Declared in NSPasteboard.h.

Discussion

See also NSSoundPboardType (NSSound).

Declared In
AppKit/NSPasteboard.h

Next Page > Hide TOC


© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.