NSPasteboard

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: AppKit/NSPasteboard.h

Class Description

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 and may paste, 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.

Named Pasteboards

Data in the pasteboard server is associated with a name that indicates how it's to be used. Each set of data and its associated name is, in effect, a separate pasteboard, distinct from the others. An application keeps a separate NSPasteboard object for each named pasteboard that it uses. There are five standard pasteboards in common use:

General pasteboard The pasteboard that's used for ordinary cut, copy, and paste operations. It holds the contents of the last selection that's been cut or copied.

Font pasteboard The pasteboard that holds font and character information and supports the Copy Font and Paste Font commands.

Ruler pasteboard The pasteboard that holds information about paragraph formats in support of the Copy Ruler and Paste Ruler commands.

Find pasteboard 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 the search.

Drag pasteboard The pasteboard that stores data to be manipulated as the result of a drag operation.

Each standard pasteboard is identified by a unique name (stored in global string objects):

NSGeneralPboard

NSFontPboard

NSRulerPboard

NSFindPboard

NSDragPboard

You can create private pasteboards by asking for an NSPasteboard object with any name other than those listed above. The name of a private pasteboard can be passed to other applications to allow them to share the data it holds.

The NSPasteboard class makes sure there's never more than one object for each named pasteboard. If you ask for a new object when one has already been created for the pasteboard with that name, the existing object will be returned to you.

Data Types

Data can be placed in the pasteboard server in more than one representation. For example, an image might be provided both in Tag Image File Format (TIFF) and as encapsulated PostScript code (EPS). Multiple representations give pasting applications the option of choosing which data type to use. In general, an application taking data from the pasteboard should choose the richest representation it can handlerich text over plain ASCII, for example. An application putting data in the pasteboard should promise to supply it in as many data types as possible, so that as many applications as possible can make use of it.

Data types are identified by string objects containing the full type name. These global variables identify the string objects for the standard pasteboard types:

Type Description

NSStringPboardType NSString data

NSPostScriptPboardType Encapsulated PostScript code (EPS)

NSTIFFPboardType Tag Image File Format (TIFF)

NSRTFPboardType Rich Text Format (RTF)

NSFilenamesPboardType ASCII text designating one or more file names

NSTabularTextPboardType Tab-separated fields of ASCII text

NSFontPboardType Font and character information

NSRulerPboardType Paragraph formatting information

NSFileContentsPboardType A representation of a file's contents

NSColorPboardType NSColor data

NSGeneralPboardType Describes a selection

NSDataLinkPboardType Defines a link between documents

Types other than those listed can also be used. For example, your application may keep data in a private format that's richer than any of the types listed above. That format can also be used as a pasteboard type.

Reading and Writing Data

Typically, data is written to the pasteboard using setData:forType: and read using dataForType:. However, data of the type NSFileContentsPboardType, representing the contents of a named file, must be written to the NSPasteboard object using writeFileContents: and copied from the object to a file using readFileContentsType:toFile:.

Errors

Except where errors are specifically mentioned in the method descriptions, any communications error with the pasteboard server raises an NSPasteboardCommunicationException exception.

Creating and Releasing an NSPasteboard Object

• + (NSPasteboard *)generalPasteboard Returns the general NSPasteboard.
• + (NSPasteboard *)pasteboardWithName:(NSString *)name Returns the NSPasteboard named name.
• + (NSPasteboard *)pasteboardWithUniqueName Returns a uniquely named NSPasteboard.
• - (void)releaseGlobally Releases the NSPasteboard and its resources in the pasteboard server.

• + (NSPasteboard *)pasteboardByFilteringData:(NSData *)data ofType:(NSString *)type Returns an NSPasteboard that contains data of all types filterable from data of type type.
• + (NSPasteboard *)pasteboardByFilteringFile:(NSString *)filename Returns an NSPasteboard that contains data of all types filterable from filename.
• + (NSPasteboard *)pasteboardByFilteringTypesInPasteboard:(NSPasteboard *)pboard Returns an NSPasteboard that contains data of all types filterable from pboard.
• + (NSArray *)typesFilterableTo:(NSString *)type Returns an array specifying all types type can be filtered to.

• - (NSString *)name Returns the NSPasteboard's name.

• - (int)addTypes:(NSArray *)newTypes Adds data types to the NSPasteboard and declares a new owner:(id)newOwner owner. Returns the new change count or 0 in case of error.
• - (int)declareTypes:(NSArray *)newTypes Sets the data types and owner of the NSPasteboard and owner:(id)newOwner returns the new change count.
• - (BOOL)setData:(NSData *)data Writes data of type dataType to the pasteboard server from forType:(NSString *)dataType data. Returns YES if the data is successfully written; otherwise returns NO.
• - (BOOL)setPropertyList:(id)propertyList Writes data of type dataType to the pasteboard server from forType:(NSString *)dataType propertyList. Returns YES if the data is successfully written; otherwise returns NO.
• - (BOOL)setString:(NSString *)string Writes data of type dataType to the pasteboard server from forType:(NSString *)dataType string. Returns YES if the data is successfully written; otherwise returns NO.
• - (BOOL)writeFileContents:(NSString *)filename Writes data from filename to the pasteboard server.

• - (NSString *)availableTypeFromArray:(NSArray *)types Returns first type in types that matches a type declared in the receiver.
• - (NSArray *)types Returns an array of the NSPasteboard's data types.

• - (int)changeCount Returns the NSPasteboard's change count.
• - (NSData *)dataForType:(NSString *)dataType Returns NSPasteboard data using the type specified by dataType.
• - (id)propertyListForType:(NSString *)dataType Returns a property list object using the type specified by dataType.
• - (NSString *)readFileContentsType:(NSString *)type toFile:(NSString *)filename Reads data of type type representing a file's contents from the NSPasteboard and writes it to filename. Returns the actual name of the file that was written.
• - (NSString *)stringForType:(NSString *)dataType Returns an NSString using the type specified by dataType.

• - (void)pasteboard:(NSPasteboard *)sender Implemented to write promised data to sender as type. provideDataForType:(NSString *)type
• - (void)pasteboardChangedOwner:(NSPasteboard *)sender Notifies prior owner that ownership changed.