NSPasteboardWriting Protocol Reference

Conforms to
Availability
Available in OS X v10.6 and later.
Declared in
NSPasteboard.h
Companion guides
Related sample code

Overview

The NSPasteboardWriting protocol specifies the interface for retrieving a representation of an object that can be written to a pasteboard. The Cocoa framework classes NSString, NSAttributedString, NSURL, NSColor, NSSound, NSImage, and NSPasteboardItem implement this protocol. You can make your custom class conform to this protocol so that you can write instances of the class to a pasteboard using the writeObjects: method of NSPasteboard.

Tasks

Required Methods

Property List for Type

Instance Methods

pasteboardPropertyListForType:

Returns a property list object to represent the receiver on a pasteboard as an object of a specified type. (required)

- (id)pasteboardPropertyListForType:(NSString *)type
Parameters
type

One of the types the receiver supports for writing (one of the UTIs returned by its implementation of writableTypesForPasteboard:).

Return Value

A property list object to represent the receiver on a pasteboard as an object of type type.

Discussion

The returned value will commonly be the NSData object for the specified data type. However, if this method returns either a string, or any other property-list type, the pasteboard will automatically convert these items to the correct data format required for the pasteboard.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSPasteboard.h

writableTypesForPasteboard:

Returns an array of UTI strings of data types the receiver can write to a given pasteboard. (required)

- (NSArray *)writableTypesForPasteboard:(NSPasteboard *)pasteboard
Parameters
pasteboard

A pasteboard.

You can use this argument to provide different options based on the pasteboard name, if you need to.

Return Value

An array of UTI strings of data types the receiver can write to pasteboard.

Discussion

By default, data for the first returned type is put onto the pasteboard immediately, with the remaining types being promised.

To change the default behavior, implement -writingOptionsForType:pasteboard: and return NSPasteboardWritingPromised to lazily provide data for types, return no option to provide the data for that type immediately. Use the pasteboard argument to provide different types based on the pasteboard name, if desired. Do not perform other pasteboard operations in the method implementation.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSPasteboard.h

writingOptionsForType:pasteboard:

Returns options for writing data of a specified type to a given pasteboard.

- (NSPasteboardWritingOptions)writingOptionsForType:(NSString *)type pasteboard:(NSPasteboard *)pasteboard
Parameters
type

One of the types the receiver supports for writing (one of the UTIs returned by its implementation of writableTypesForPasteboard:).

pasteboard

A pasteboard.

You can use this argument to provide different options based on the pasteboard name, if you need to.

Return Value

Options for writing data of type type to pasteboard. Return 0 for no options, or a value given in “Pasteboard Writing Options.”

Special Considerations

Do not perform other pasteboard operations in the method implementation.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSPasteboard.h

Constants

Pasteboard Writing Options

Constant to specify options for writing to a pasteboard, used by writingOptionsForType:pasteboard:.

enum {
   NSPasteboardWritingPromised = 1 << 9,
};
Constants
NSPasteboardWritingPromised

Data for a type with this option will be promised, not immediately written.

Available in OS X v10.6 and later.

Declared in NSPasteboard.h.

NSPasteboardWritingOptions

Type to specify options for writing to a pasteboard.

typedef NSUInteger NSPasteboardWritingOptions;
Discussion

For possible values, see “Pasteboard Writing Options.”

Availability
  • Available in OS X v10.6 and later.
Declared In
NSPasteboard.h