Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 handleÐrich 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.

Getting Data in Different Formats 

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

Referring to a Pasteboard by Name 

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

Writing Data 

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

Determining Types 

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

Reading Data 

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

Methods Implemented by the Owner 

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