NSPasteboardItem Class Reference

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

Overview

NSPasteboardItem is a generic class to represent an item on a pasteboard.

There are three main uses for an NSPasteboardItem object:

  1. Providing data on the pasteboard.

    You can create one or more pasteboard items, set data or data providers for types, and write to them pasteboard.

  2. Customizing data already on the pasteboard.

    As a delegate or subclass, you can retrieve the pasteboard items currently on the pasteboard, read the existing types and data and set new data and data providers for types as needed.

  3. Retrieving data from the pasteboard.

    You can retrieve pasteboard items from the pasteboard then read the data for types you’re interested in.

A pasteboard item can be associated with a single pasteboard. When you create an item, it can be written to any pasteboard. When you pass an item to a pasteboard in writeObjects:, that item becomes bound to the pasteboard it was written to. When you retrieve items from a pasteboard using pasteboardItems or readObjectsForClasses:options:, the returned items are associated with the messaged pasteboard. Passing an item that is already associated with a pasteboard into writeObjects: causes an exception to be raised.

Pasteboard items are intended to be used during a single pasteboard interaction, not held onto and used repeatedly. A pasteboard item is only valid until the owner of the pasteboard changes.

Tasks

Getting Types

Setting the Data Provider

Setting Values

Getting Values

Instance Methods

availableTypeFromArray:

Returns from a given array of types the the first type contained in the pasteboard item, according to the ordering of types.

- (NSString *)availableTypeFromArray:(NSArray *)types
Parameters
types

An array of strings representing UTIs, arranged in order of preference (most preferred as the 0th element in the array).

Return Value

The first (according to the sender's ordering of types) type in types contained in the pasteboard item, or nil if the receiver does not contain any types given in types.

Discussion

The method checks for UTI conformance of the requested types, preferring an exact match to conformance.

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

dataForType:

Returns the value for the specified type as an NSData object.

- (NSData *)dataForType:(NSString *)type
Parameters
type

A UTI type string.

Return Value

The value for the specified type as an NSData object.

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

propertyListForType:

Returns the value for the specified type as a property list.

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

A UTI type string.

Return Value

The value for the specified type as a property list.

Discussion

For more about property lists, see Property List Programming Guide.

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

setData:forType:

Sets the value for a specified type as an NSData object.

- (BOOL)setData:(NSData *)data forType:(NSString *)type
Parameters
data

An NSData object containing the value for the representation specified by type.

type

A UTI type string.

Return Value

YES if the value was set successfully, otherwise NO.

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

setDataProvider:forTypes:

Sets the data provider for the specified types.

- (BOOL)setDataProvider:(id <NSPasteboardItemDataProvider>)dataProvider forTypes:(NSArray *)types
Parameters
dataProvider

A pasteboard data provider.

types

An array of strings indicating the UTIs for the data representations dataProvider may provide.

Return Value

YES if the data provider was set successfully, otherwise NO.

Discussion

This method registers the data provider to be messaged to provide the data for any of the specified types when requested.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSPasteboardItem.h

setPropertyList:forType:

Sets the value for a specified type as a property list.

- (BOOL)setPropertyList:(id)propertyList forType:(NSString *)type
Parameters
propertyList

A property list object containing the value for the representation specified by type.

For about property lists, see Property List Programming Guide.

type

A UTI type string.

Return Value

YES if the value was set successfully, otherwise NO.

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

setString:forType:

Sets the value for a specified type as a string.

- (BOOL)setString:(NSString *)string forType:(NSString *)type
Parameters
string

A string for the representation specified by type.

type

A UTI type string.

Return Value

YES if the value was set successfully, otherwise NO.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSPasteboardItem.h

stringForType:

Returns the value for the specified type as a string.

- (NSString *)stringForType:(NSString *)type
Parameters
type

A UTI type string.

Return Value

The value for the specified type as a string.

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

types

Returns an array of UTI strings of the data types supported by the receiver.

- (NSArray *)types
Return Value

An array of UTI strings of the data types supported by the receiver.

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