Inherits from: NSObject
Package: com.apple.yellow.application
generalPasteboard | |
pasteboardWithName |
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 an NSString from a pasteboard. |
setStringForType | Writes an NSString to a pasteboard. |
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.
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:
Pasteboard | Description |
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 Copy Font and Paste Font commands that my be implemented in a text editor. |
Ruler pasteboard | 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. |
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 another search. |
Drag pasteboard | The pasteboard that stores data to be moved 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. Data in a private pasteboard may then be shared by passing its name between applications.
The NSPasteboard class makes sure there's never more than one object for each named pasteboard on the computer. 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.
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 different applications as possible can use it.
Filtering services transform the data from one representation to another. Typically, these services aren't invoked until data is read from a pasteboard.
Data types are identified by NSString objects containing the full type name. These global variables identify the string objects for the standard pasteboard types:
Type | Description |
NSColorPboardType |
NSColor data |
NSFileContentsPboardType |
A representation of a file's contents |
NSFilenamesPboardType |
NSString designating one or more file names |
NSFontPboardType |
Font and character information |
NSPostScriptPboardType |
Encapsulated PostScript code (EPS) |
NSRulerPboardType |
Paragraph formatting information |
NSRTFPboardType |
Rich Text Format (RTF) |
NSRTFDPboardType |
RTFD formatted file contents |
NSSelectionPboardType |
Describes a selection for use with data linking |
NSStringPboardType |
NSString data |
NSTabularTextPboardType |
NSString containing tab-separated fields of text |
NSTIFFPboardType |
Tag Image File Format (TIFF) |
Typically, data is written to the pasteboard using setData:forType: and read using dataForType:. Some of these types can only be written with certain methods. For instance, NSFilenamesPboardType's form is an array of NSStrings and requires special handling. Use these methods to write these types:
Type | Writing Method | Reading Method |
NSColorPboardType |
NSColor class methods | NSColor class methods |
NSFileContentsPboardType |
writeFileContents: | readFileContentsType:toFile: |
NSFilenamesPboardType |
setPropertyList:forType: | propertyListForType: |
NSStringPboardType |
setString:forType: | stringForType: |
You don't have to write the data (using setDataForType) in all types that you've declared for the pasteboard: This avoids unneeded conversions. If data is requested from a pasteboard in a format that's not present, the owner of the pasteboard receives a pasteboard:provideDataForType: message notifying it that it needs to supply the data in that format. It then supplies data in the requested type by invoking one of the setDataForType, setStringForType, or setPropertyListForType methods on the pasteboard.
The class methods pasteboardByFilteringData, pasteboardByFilteringFile, and pasteboardByFilteringTypesInPasteboard return a pasteboard with data that is filtered into all types derivable from the current types using available filter services. (For more information on filter services see /NextLibrary/Documentation/NextDev/TasksAndConcepts/ProgrammingTopics/Services.rtf.) The pasteboards returned by these methods are autoreleased instances of NSPasteboard.
Types other than those listed above can also be used. For example, your application may keep data in a private format that's richer than any of the existing types. That format can also be used as a pasteboard type.
The NSRTFDPboardType is used for the contents of an RTFD file package (a directory containing an RTF text file and one or many EPS and TIFF image files). There are several ways to work with RTFD data. If you have an NSFileWrapper object that represents an RTFD file wrapper, you can send it the serializedRepresentation method to return the RTFD data and write that to the pasteboard.
In addition to NSFileWrapper, classes such as NSAttributedString and NSText can return RTFD data.
The change count is a computer-wide variable that increments every time the contents of the pasteboard changes (a new owner is declared). An independent change count is maintained for each named pasteboard. By examining the change count, an application can determine whether the current data in the pasteboard is the same as the data it last received.
The changeCount, addTypes, and declareTypes methods return the change count. A types or availableTypeFromArray message should be sent by the pasteboard before reading data so the change count is valid.
Except where errors are specifically mentioned in the method descriptions, any communications error with the pasteboard server throws an exception.
- 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:
- pasteboard:provideDataForType:
public NSPasteboard()
public static NSPasteboard generalPasteboard()
public static NSPasteboard pasteboardByFilteringData(NSData data, String type)
No filter service is invoked until the data is actually requested, so invoking this method is reasonably inexpensive.
public static NSPasteboard pasteboardByFilteringFile(String filename)
public static NSPasteboard pasteboardByFilteringTypesInPasteboard(NSPasteboard pasteboard)
This method returns pasteboard if pasteboard was returned by one of the pasteboardByFiltering... methods, so a pasteboard can't 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 will 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.
public static NSPasteboard pasteboardWithName(String name)
NSGeneralPboard
NSFontPboard
NSRulerPboard
NSFindPboard
NSDragPboard
Other names can be assigned to create private pasteboards for other purposes.
public static NSPasteboard pasteboardWithUniqueName()
public static NSArray typesFilterableTo(String type)
public int addTypes(NSArray newTypes, Object newOwner)
Returns the new change count, or 0 in case of an error.
See Also: changeCount
public String availableTypeFromArray(NSArray types)
A types or availableTypeFromArray: message should be sent before reading any data from the NSPasteboard.
public int changeCount()
See Also: declareTypes
public NSData dataForType(String dataType)
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:owner: message) since
they were last checked with the types method.
It also returns null
if the pasteboard
server can't 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. All other errors throw
an exception.
If null
is
returned, the application should put up a panel informing the user that
it was unable to carry out the paste operation.
The NSData object this method returns is autoreleased.
public int declareTypes(NSArray newTypes, Object newOwner)
newTypes is an array of NSStrings that name 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).
newOwner 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's required for a paste operation. If you wait, the owner will receive a pasteboard:provideDataForType: message requesting the data in a particular type when it's 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.
newOwner can
be null
if data is provided for all
types immediately. Otherwise, the owner should be an object that
won't 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 pasteboard's new change count.
See Also: setStringForType, addTypes, changeCount
public String name()
See Also: pasteboardWithName
public Object propertyListForType(String dataType)
A property list is an object of NSArray, NSData, NSDictionary, or NSString objects-or any combination thereof.
A types or availableTypeFromArray message should be sent before invoking propertyListForType.
This method invokes dataForType.
See Also: setPropertyListForType
public String readFileContentsTypeToFile(String type, String filename)
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 filename's extension
(as returned by the NSCreateFileContentsPboardType
function)
is substituted. If data matching type isn't
found on the NSPasteboard, data of type NSFileContentsPboardType
is requested. Returns the name of the file the data was actually
written to.
See Also: writeFileContents
public NSFileWrapper readFileWrapper()
null
.public void releaseGlobally()
- (void)releaseGlobally
After this method is invoked, no other application will be able to use the named pasteboard. A temporary, privately named pasteboard can be released this way when it's no longer needed, but a standard pasteboard should never be released globally.
public boolean setDataForType(NSData data, String dataType)
Returns true if the data is successfully written or false if ownership of the pasteboard has changed. Any other error throws an exception.
See Also: setPropertyListForType, setStringForType
public boolean setPropertyListForType(Object propertyList, String dataType)
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 an exception.
See Also: setStringForType
public boolean setStringForType(String string, String dataType)
This method invokes setPropertyListForType 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 an exception.
See Also: setDataForType, setStringForType
public String stringForType(String dataType)
This method invokes propertyListForType to obtain the string.
public NSArray types()
Returns an array of the types declared for the current contents of the NSPasteboard. The array is an array of NSStrings holding the type names. Types are listed in the order they were declared.
A types or availableTypeFromArray message should be sent before reading any data from the NSPasteboard.
See Also: declareTypes, dataForType
public boolean writeFileContents(String filename)
NSCreateFileContentsPboardType
function
when passed the files extension), if it has one. Returns true if
the data from filename was successfully written to the pasteboard
and false otherwise.See Also: readFileContentsTypeToFile
public boolean writeFileWrapper(NSFileWrapper wrapper)
NSCreateFileContentsPboardType
function
when passed 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 NSPasteboard; returns false, otherwise.Methods Implemented by the Owner
- (void)pasteboardChangedOwner:(NSPasteboard
*)sender
See Also: changeCount
- (void)pasteboard:(NSPasteboard
*)sender
provideDataForType:(NSString *)type
pasteboard:provideDataForType: 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 pasteboard:provideDataForType: message is sent only if type data hasn't 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 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.