UIPasteboard Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.0 and later.
Declared in
UIPasteboard.h
Related sample code

Overview

The UIPasteboard class enables an app to share data within the app and with another app. To share data with any other app, you can use system-wide pasteboards; to share data with another app that has the same team ID as your app, you can use app-specific pasteboards.

Typically, an object in the app writes data to a pasteboard when the user requests a copy or cut operation on a selection in the user interface. Another object in the same or different app then reads that data from the pasteboard and presents it to the user at a new location; this usually happens when the user requests a paste operation.

A pasteboard is a named region of memory where data can be shared. There are two system pasteboards: the General pasteboard (UIPasteboardNameGeneral) and the Find pasteboard (UIPasteboardNameFind. You can use the General pasteboard for copy-paste operations involving any kind of data; the Find pasteboard, which is used in search operations, holds the most recent string value in the search bar. Apps can also create pasteboards for their own use or for use by other apps that have the same team ID. A pasteboard must be identified by a unique name. You may also mark an app-specific pasteboard as persistent, so that it continues to exist past the termination of the app and past system reboots. System pasteboards are persistent by default.

When you write an object to a pasteboard, it is stored as a pasteboard item. A pasteboard item is one or more key-value pairs where the key is a string that identifies the representation type of the value. Having multiple representation types per pasteboard item makes it more possible for one app to share data with another app without having to know specific capabilities of that app. For example, the source app could write the same image to the pasteboard in PNG, JPEG, and GIF data formats. If the receiving app can only handle GIF images, it can still obtain the pasteboard data.

A Uniform Type Identifier (UTI) is frequently used for a representation type (sometimes called a pasteboard type). For example, you could use kUTTypeJPEG (a constant for public.jpeg) as a representation type for JPEG data. Apps are free to use any string to name a representation type; however, for app-specific data types, it is recommended that you use reverse-DNS notation to ensure the uniqueness of the type (for example, com.myCompany.myApp.myType).

UIPasteboard provides methods for reading and writing single pasteboard items at a time as well as multiple pasteboard items. The data written and read can be in two general forms. If the data to be written can be represented by an object—such as NSString, NSArray, NSDictionary, NSDate, NSNumber, UIImage, or NSURL—use a method such as setValue:forPasteboardType: to write it to the pasteboard. If the data is binary, use the setData:forPasteboardType: methoc to write it to the pasteboard. The class also provides convenience methods for writing and reading strings, images, URLs, and colors to and from single or multiple pasteboard items.

Although UIPasteboard is central to copy-paste operations, several other UIKit classes and protocols are used in these operations as well:

An app that implements copy-paste usually has to handle the management and presentation of selections in its user interface. It must also coordinate the addition and removal of items via paste and cut operations with its data model.

Tasks

Getting and Removing Pasteboards

Getting and Setting Pasteboard Attributes

Determining Types of Single Pasteboard Items

Getting and Setting Single Pasteboard Items

Determining the Types of Multiple Pasteboard Items

Getting and Setting Multiple Pasteboard Items

Getting and Setting Pasteboard Items of Standard Data Types

Properties

changeCount

The number of times the pasteboard’s contents have changed. (read-only)

@property(readonly, nonatomic) NSInteger changeCount
Discussion

Whenever the contents of a pasteboard changes—specifically, when pasteboard items are added, modified, or removed—UIPasteboard increments the value of this property. After it increments the change count, UIPasteboard posts the notifications named UIPasteboardChangedNotification (for additions and modifications) and UIPasteboardRemovedNotification (for removals). These notifications include (in the userInfo dictionary) the types of the pasteboard items added or removed. Because UIPasteboard waits until the end of the current event loop before incrementing the change count, notifications can be batched. The class also updates the change count when an app reactivates and another app has changed the pasteboard contents. When users restart a device, the change count is reset to zero.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

color

The color object of the first pasteboard item.

@property(nonatomic, copy) UIColor *color
Discussion

The value stored in this property is a UIColor object. The associated array of representation types is UIPasteboardTypeListColor. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

colors

An array of color objects in all pasteboard items.

@property(nonatomic, copy) NSArray *colors
Discussion

The value stored in this property is an array of UIColor objects. The associated array of representation types is UIPasteboardTypeListColor. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

image

The image object of the first pasteboard item.

@property(nonatomic, copy) UIImage *image
Discussion

The value stored in this property is a UIImage object. The associated array of representation types is UIPasteboardTypeListImage, which includes types kUTTypePNG and kUTTypeJPEG. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

images

An array of image objects in all pasteboard items.

@property(nonatomic, copy) NSArray *images
Discussion

The value stored in this property is an array of UIImage objects. The associated array of representation types is UIPasteboardTypeListImage, which includes types kUTTypePNG and kUTTypeJPEG. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

items

The pasteboard items on the pasteboard.

@property(nonatomic,copy) NSArray *items
Discussion

The value of the property is an array of dictionaries. Each dictionary represents a pasteboard item, with the key being the representation type and the value the object associated with that type. Setting this property replaces all of the current pasteboard items.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

name

The name of the pasteboard. (read-only)

@property(readonly, nonatomic) NSString *name
Discussion

Names of app pasteboard objects should be unique across installed apps. If the object is a system pasteboard, this property returns one of the constants described in “Pasteboard Names.”

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

numberOfItems

Returns the number of items in the pasteboard (read-only)

@property(readonly, nonatomic) NSInteger numberOfItems
Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

persistent

A Boolean value that indicates whether the pasteboard is persistent.

@property(getter=isPersistent, nonatomic) BOOL persistent
Discussion

When a pasteboard is persistent, it continues to exist past app terminations and across system reboots. App pasteboards that are not persistent only last until the owning (creating) app quits. System pasteboards are persistent. App pasteboards by default are not persistent. A persistent app pasteboard is removed when the app that created it is uninstalled.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

string

The string value of the first pasteboard item.

@property(nonatomic, copy) NSString *string
Discussion

The value stored in this property is an NSString object. The associated array of representation types is UIPasteboardTypeListString, which includes type kUTTypeUTF8PlainText. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

strings

An array of strings in all pasteboard items.

@property(nonatomic, copy) NSArray *strings
Discussion

The value stored in this property is an array of NSString objects. The associated array of representation types is UIPasteboardTypeListString, which includes type kUTTypeUTF8PlainText.Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

URL

The URL object of the first pasteboard item.

@property(nonatomic, copy) NSURL *URL
Discussion

The value stored in this property is an NSURL object. The associated array of representation types is UIPasteboardTypeListURL, which includes type kUTTypeURL. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

URLs

An array of URL objects in all pasteboard items.

@property(nonatomic, copy) NSArray *URLs
Discussion

The value stored in this property is an array of NSURL objects. The associated array of representation types is UIPasteboardTypeListURL, which includes type kUTTypeURL. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

Class Methods

generalPasteboard

Returns the general pasteboard, which is used for general copy-paste operations

+ (UIPasteboard *)generalPasteboard
Return Value

A shared system pasteboard object with the name of UIPasteboardNameGeneral.

Discussion

You may use the general pasteboard for copying and pasting text, images, URLs, colors, and other data within an app or between apps. The general pasteboard is persistent across device restarts and app uninstalls.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
UIPasteboard.h

pasteboardWithName:create:

Returns a pasteboard identified by name, optionally creating it if it doesn’t exist.

+ (UIPasteboard *)pasteboardWithName:(NSString *)pasteboardName create:(BOOL)create
Parameters
pasteboardName

A string or string constant that identifies (or should identify) the pasteboard. Specify nil if you want UIPasteboard to create a pasteboard with a unique name.

create

A Boolean value that indicates whether the pasteboard should be created if it doesn’t already exist. Specify NO for system pasteboards or if you want an existing app pasteboard.

Return Value

A pasteboard object that can be used for transferring data within an app or between apps that have the same team ID.

Discussion

You call this method to obtain the UIPasteboardNameFind pasteboard and to create custom app pasteboards. (You may also use it to obtain the general pasteboard, but generalPasteboard exists for that purpose.) App pasteboards returned by this method are not persistent, existing only until the app quits. To make them persistent, set the persistent property to YES.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

pasteboardWithUniqueName

Returns an app pasteboard identified by a unique system-generated name.

+ (UIPasteboard *)pasteboardWithUniqueName
Return Value

An app pasteboard object with a unique name.

Discussion

Obtain the value of the name property to discover the name of the returned pasteboard. App pasteboards returned by this method are not persistent, existing only until the app quits. To make them persistent, set the persistent property to YES. Calling this method is equivalent to calling pasteboardWithName:create: with the first parameter set to nil and the second set to YES.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

removePasteboardWithName:

Invalidates the designated app pasteboard.

+ (void)removePasteboardWithName:(NSString *)pasteboardName
Parameters
pasteboardName

The name of the pasteboard to be invalidated.

Discussion

Invalidation of an app pasteboard frees up all resources used by it. Once a pasteboard is invalidated, you cannot use the it; UIPasteboard ignores any calls to it. The method has no effect if called with the name of a system pasteboard.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

Instance Methods

addItems:

Appends pasteboard items to the current contents of the pasteboard.

- (void)addItems:(NSArray *)items
Parameters
items

An array of dictionaries. Each dictionary represents a pasteboard item, with the key being the representation type and the value being the object associated with that type.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIPasteboard.h

containsPasteboardTypes:

Returns whether the pasteboard holds data of the specified representation type.

- (BOOL)containsPasteboardTypes:(NSArray *)pasteboardTypes
Parameters
pasteboardTypes

An array of strings. Each string should identify a representation of the pasteboard item that the pasteboard reader can handle. These string are frequently UTIs. See the class description for more information about pasteboard item types.

Return Value

YES if the pasteboard item holds data of the indicated representation type, otherwise NO.

Discussion

This method works on the first item in the pasteboard. If there are other items, it ignores them. You can use this method when enabling or disabling the Paste menu command.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

containsPasteboardTypes:inItemSet:

Returns whether the specified pasteboard items contain data of the given representation types.

- (BOOL)containsPasteboardTypes:(NSArray *)pasteboardTypes inItemSet:(NSIndexSet *)itemSet
Parameters
pasteboardTypes

An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.

itemSet

An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Return Value

YES if the pasteboard items identified by itemSet have data corresponding to the representation types specified by pasteboardTypes; otherwise, returns NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

dataForPasteboardType:

Returns the data in the pasteboard for the given representation type.

- (NSData *)dataForPasteboardType:(NSString *)pasteboardType
Parameters
pasteboardType

A string identifying a representation type of a pasteboard item.

Return Value

A data object or nil if there is no data in the pasteboard of the given type.

Discussion

The returned object often holds raw (binary) data, such as image data. This method works on the first item in the pasteboard. If there are other items, it ignores them.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

dataForPasteboardType:inItemSet:

Returns the data objects in the indicated pasteboard items that have the given representation type.

- (NSArray *)dataForPasteboardType:(NSString *)pasteboardType inItemSet:(NSIndexSet *)itemSet
Parameters
pasteboardType

A string identifying a representation type. Typically this is a UTI.

itemSet

An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Return Value

An array of NSData objects or, if a requested pasteboard item has no data of the the type indicated by pasteboardType, a NSNull object.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

itemSetWithPasteboardTypes:

Returns an index set identifying pasteboard items having the specified representation types.

- (NSIndexSet *)itemSetWithPasteboardTypes:(NSArray *)pasteboardTypes
Parameters
pasteboardTypes

An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.

Return Value

An index set with each integer positionally identifying a pasteboard item that has one of the representation types specified in pasteboardTypes.

Discussion

You can pass the index set returned in this method in a call to dataForPasteboardType:inItemSet: or valuesForPasteboardType:inItemSet: to get the data in the indicated pasteboard items.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

PasteboardType:

Returns an object in the pasteboard for the given representation type.

- (id)valueForPasteboardType:(NSString *)pasteboardType
Parameters
pasteboardType

A string identifying a representation type of a pasteboard item.

Return Value

An object that is an instance of the appropriate class based on pasteboardType or an NSData object containing “raw” data.

Discussion

This method attempts to return an object that is of a class type appropriate to the representation type, which typically is a UTI. For example, if the representation type is kUTTypePlainText (public.plain-text), the method returns an NSString object. If the method can’t determine the class type from the representation type, it returns the object as a generic object, such as an NSString, NSArray, NSDictionary, NSDate, NSNumber, NSURL, UIImage, or NSData object. This method works on the first item in the pasteboard. If there are other items, it ignores them.

pasteboardTypes

Returns the types of the first item on the pasteboard.

- (NSArray *)pasteboardTypes
Return Value

An array of strings indicating the representation types of the first item on the pasteboard.

Discussion

A type is frequently, but not necessarily, a UTI (Uniform Type Identifier). It identifies a representation of the data on the pasteboard. For example, a pasteboard item could hold image data under public.png and public.tiff representations. Apps can define their own types for custom data such as com.mycompany.myapp.mytype; however, in this case, only those apps that know of the type could understand the data written to the pasteboard.

With this method, you can determine if the pasteboard holds data of a particular representation type by a line of code such as this:

BOOL pngOnPasteboard = [[pasteboard pasteboardTypes] containsObject:@"public.png"];
Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

pasteboardTypesForItemSet:

Returns an array of representation types for each specified pasteboard item.

- (NSArray *)pasteboardTypesForItemSet:(NSIndexSet *)itemSet
Parameters
itemSet

An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Return Value

An array of arrays, with each inner array holding the representation types for a particular pasteboard item.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

setData:forPasteboardType:

Puts data in the pasteboard for the specified representation type.

- (void)setData:(NSData *)data forPasteboardType:(NSString *)pasteboardType
Parameters
data

The data object to be written to the pasteboard.

pasteboardType

A string identifying the representation type of the pasteboard item. This is typically a UTI.

Discussion

Use this method to put raw data on the pasteboard. For example, you could archive a graph of model objects and pass the resulting NSData object to a related app via a pasteboard using a custom pasteboard type. (To put objects—such as NSString, NSArray, NSDictionary, NSDate, NSNumber, UIImage, or NSURL objects—on the pasteboard, use the setValue:forPasteboardType: method.) This method writes data for the first item in the pasteboard. Calling this method replaces any items currently in the pasteboard.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

setValue:forPasteboardType:

Puts an object in the pasteboard for the specified representation type.

- (void)setValue:(id)value forPasteboardType:(NSString *)pasteboardType
Parameters
value

The object to be written to the pasteboard.

pasteboardType

A string identifying the representation type of the pasteboard item. If the type is a UTI, it must be compatible with the class of value; otherwise, nothing is written to the pasteboard.

Discussion

Use this method to put an object—such as an NSString, NSArray, NSDictionary, NSDate, NSNumber, UIImage, or NSURL object—on the pasteboard. (For images, you can also use the image or images properties; for all other data, such as raw binary data, use the setData:forPasteboardType: method.) This method writes the object as the first item in the pasteboard. Calling this method replaces any items currently in the pasteboard.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

valuesForPasteboardType:inItemSet:

Returns the objects in the indicated pasteboard items that have the given representation type.

- (NSArray *)valuesForPasteboardType:(NSString *)pasteboardType inItemSet:(NSIndexSet *)itemSet
Parameters
pasteboardType

A string identifying a representation type. Typically this is a UTI.

itemSet

An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Return Value

An array of objects that have the type indicated by pasteboardType; or—if the pasteboard type is custom or unknown—an array of NSData objects.

Discussion

Returned objects are of one of the following classes, depending on the pasteboard item’s representation type: NSString, NSArray, NSDictionary, NSDate, NSNumber, NSURL, or UIImage.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIPasteboard.h

Constants

Pasteboard Names

Names identifying the system pasteboards.

UIKIT_EXTERN NSString *const UIPasteboardNameGeneral;
UIKIT_EXTERN NSString *const UIPasteboardNameFind;
Constants
UIPasteboardNameGeneral

The name identifying the General pasteboard, which is used for general copy-cut-paste operations.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

UIPasteboardNameFind

The name identifying the Find pasteboard, which is used in search operations. In such operations, the most recent search string in the search bar is put in the Find pasteboard.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

Discussion

You can access both system pasteboards by calling the class method pasteboardWithName:create:, specifying one of these constants as the first argument. You may also access the general pasteboard by calling the generalPasteboard class method. Both system pasteboards are persistent across device restarts, app uninstalls, and restores.

Declared In
UIPasteboard.h

Data Type Extensions

Pasteboard-item representation types for a given object value.

UIKIT_EXTERN NSArray *UIPasteboardTypeListString;
UIKIT_EXTERN NSArray *UIPasteboardTypeListURL;
UIKIT_EXTERN NSArray *UIPasteboardTypeListImage;
UIKIT_EXTERN NSArray *UIPasteboardTypeListColor;
Constants
UIPasteboardTypeListString

An array of pasteboard-item representation types for strings, including kUTTypeUTF8PlainText and kUTTypeText. Related properties are string and strings.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

UIPasteboardTypeListURL

An array of pasteboard-item representation types for URLs, including kUTTypeURL. Related properties are URL and URLs.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

UIPasteboardTypeListImage

An array of pasteboard-item representation types for images, including kUTTypePNG and kUTTypeJPEG. Related properties are image and images.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

UIPasteboardTypeListColor

An array of pasteboard-item representation types for colors. Related properties are color and colors.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

Declared In
UIPasteboard.h

UserInfo Dictionary Keys

You use the following keys to access the representation types of pasteboard items that have been added to or removed from a pasteboard.

UIKIT_EXTERN NSString *const UIPasteboardChangedTypesAddedKey;
UIKIT_EXTERN NSString *const UIPasteboardChangedTypesRemovedKey;
Constants
UIPasteboardChangedTypesAddedKey

With the notification named UIPasteboardChangedNotification, use this key to access the added representation types. These types are stored as an array in the notification’s userInfo dictionary.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

UIPasteboardChangedTypesRemovedKey

With the notification named UIPasteboardChangedNotification, use this key to access the removed representation types. These types are stored as an array in the notification’s userInfo dictionary.

Available in iOS 3.0 and later.

Declared in UIPasteboard.h.

Declared In
UIPasteboard.h

Notifications

UIPasteboardChangedNotification

Posted by a pasteboard object when its contents change. This happens at the same time the pasteboard’s change count (changeCount property) is incremented. Changes include the addition, removal, and modification of pasteboard items. The userInfo dictionary may contain the representation types of pasteboard items that have been added to or removed from the pasteboard. See “UserInfo Dictionary Keys” for the keys used to access these representation types. If pasteboard items have been modified but not added or removed, the userInfo dictionary is nil.
Availability
Declared In
UIPasteboard.h

UIPasteboardRemovedNotification

Posted by a pasteboard object just before an app removes it. The removal class method is removePasteboardWithName:. There is no userInfo dictionary.
Availability
Declared In
UIPasteboard.h