| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iOS 3.0 and later. |
| Companion guide | |
| Declared in | UIPasteboard.h |
The UIPasteboard class enables an application to share data within the application or with another application using system-wide or application-specific pasteboards.
Typically, an object in the application 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 application 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. Applications can also create pasteboards for their own use or for use by a family of related applications. Pasteboards must be identified by a unique names. You may also mark an application pasteboard as persistent, so that it continues to exist past the termination of the application 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 application to share data with another application without having to know specific capabilities of that application. For example, the source application could write the same image to the pasteboard in PNG, JPEG, and GIF data formats. If the receiving application 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. However, applications are free to use any string they want for a representation type; however, for application-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).
Note: For a discussion of Uniform Type Identifiers and a list of common ones, see Uniform Type Identifiers Overview.
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 is a property-list objects or can be converted to such an object, use a method such as setValue:forPasteboardType: to write it to the pasteboard. If the data is binary (say, image data) or can’t be converted to a property-list type, you would use the setData:forPasteboardType: to write it to the pasteboard. For UIPasteboard, the classes of the property-list objects are NSString, NSArray, NSDictionary, NSDate, NSNumber and NSURL. 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:
UIMenuController —Displays a menu with Copy, Cut, Paste, Select, and Select All commands above or below the selection.
UIResponder — Responders implement the canPerformAction:withSender: to enable or disable commands in the above-mentioned menu based on the current context.
UIResponderStandardEditActions — Responders implement methods declared in this informal protocol to handle the chosen menu commands (for example, copy: and paste:).
An application 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.
+ generalPasteboard
+ pasteboardWithName:create:
+ pasteboardWithUniqueName
+ removePasteboardWithName:
name property
persistent property
changeCount property
– dataForPasteboardType:
– valueForPasteboardType:
– setData:forPasteboardType:
– setValue:forPasteboardType:
numberOfItems property
– pasteboardTypesForItemSet:
– itemSetWithPasteboardTypes:
– containsPasteboardTypes:inItemSet:
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The number of times the pasteboard’s contents have changed. (read-only)
@property(readonly, nonatomic) NSInteger changeCount
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 application reactivates and another application has changed the pasteboard contents. When users restart a device, the change count is reset to zero.
UIPasteboard.hThe color object of the first pasteboard item.
@property(nonatomic, copy) UIColor *color
The value stored in this property is a UIColor object. The associated array of representation types is UIPasteboardTypeListColor, which includes type . 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.
UIPasteboard.hAn array of color objects in all pasteboard items.
@property(nonatomic, copy) NSArray *colors
The value stored in this property is an array of UIColor objects. The associated array of representation types is UIPasteboardTypeListColor, which includes type . 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.
UIPasteboard.hThe image object of the first pasteboard item.
@property(nonatomic, copy) UIImage *image
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.
UIPasteboard.hAn array of image objects in all pasteboard items.
@property(nonatomic, copy) NSArray *images
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.
UIPasteboard.hThe pasteboard items on the pasteboard.
@property(nonatomic,copy) NSArray *items
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 data object or property-list object associated with that type. Setting this property replaces all of the current pasteboard items.
UIPasteboard.hThe name of the pasteboard. (read-only)
@property(readonly, nonatomic) NSString *name
Names of application pasteboard objects should be unique across installed applications. If the object is a system pasteboard, this property returns one of the constants described in “Pasteboard Names.”
UIPasteboard.hReturns the number of items in the pasteboard (read-only)
@property(readonly, nonatomic) NSInteger numberOfItems
UIPasteboard.hA Boolean value that indicates whether the pasteboard is persistent.
@property(getter=isPersistent, nonatomic) BOOL persistent
When a pasteboard is persistent, it continues to exist past application terminations and across system reboots. Application pasteboards that are not persistent only last until the owning (creating) application quits. System pasteboards are persistent. Application pasteboards by default are not persistent. A persistent application pasteboard is removed when the application that created it is uninstalled.
UIPasteboard.hThe string value of the first pasteboard item.
@property(nonatomic, copy) NSString *string
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.
UIPasteboard.hAn array of strings in all pasteboard items.
@property(nonatomic, copy) NSArray *strings
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.
UIPasteboard.hThe URL object of the first pasteboard item.
@property(nonatomic, copy) NSURL *URL
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.
UIPasteboard.hAn array of URL objects in all pasteboard items.
@property(nonatomic, copy) NSArray *URLs
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.
UIPasteboard.hReturns the general pasteboard, which is used for general copy-paste operations
+ (UIPasteboard *)generalPasteboard
A shared system pasteboard object with the name of UIPasteboardNameGeneral.
You may use the general pasteboard for copying and pasting text, images, URLs, colors, and other data within an application or between applications. The general pasteboard is persistent across device restarts and application uninstalls.
UIPasteboard.hReturns a pasteboard identified by name, optionally creating it if it doesn’t exist.
+ (UIPasteboard *)pasteboardWithName:(NSString *)pasteboardNamecreate:(BOOL)create
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.
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 application pasteboard.
A pasteboard object that can be used for transferring data within and application or between applications.
You call this method to obtain the UIPasteboardNameFind pasteboard and to create custom application pasteboards. (You may also use it to obtain the general pasteboard, but generalPasteboard exists for that purpose.) If you create a pasteboard for your application, the name should a unique string to prevent possible name collisions with other applications’ pasteboards; for this, use of reverse DNS notation (for example, com.mycompany.myapp.pboard) is recommended. Application pasteboards returned by this method are not persistent, existing only until the application quits. To make them persistent, set the persistent property to YES.
UIPasteboard.hReturns an application pasteboard identified by a unique system-generated name.
+ (UIPasteboard *)pasteboardWithUniqueName
An application pasteboard object with a unique name.
Obtain the value of the name property to discover the name of the returned pasteboard. Application pasteboards returned by this method are not persistent, existing only until the application 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.
UIPasteboard.hInvalidates the designated application pasteboard.
+ (void)removePasteboardWithName:(NSString *)pasteboardName
The name of the pasteboard to be invalidated.
Invalidation of an application 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.
UIPasteboard.hAppends pasteboard items to the current contents of the pasteboard.
- (void)addItems:(NSArray *)items
An array of dictionaries. Each dictionary represents a pasteboard item, with the key being the representation type and the value the data object or property-list object associated with that type.
UIPasteboard.hReturns whether the pasteboard holds data of the specified representation type.
- (BOOL)containsPasteboardTypes:(NSArray *)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.
YES if the pasteboard item holds data of the indicated representation type, otherwise NO.
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.
UIPasteboard.hReturns whether the specified pasteboard items contain data of the given representation types.
- (BOOL)containsPasteboardTypes:(NSArray *)pasteboardTypes inItemSet:(NSIndexSet *)itemSet
An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.
An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.
YES if the pasteboard items identified by itemSet have data corresponding to the representation types specified by pasteboardTypes; otherwise, returns NO.
UIPasteboard.hReturns the data in the pasteboard for the given representation type.
- (NSData *)dataForPasteboardType:(NSString *)pasteboardType
A string identifying a representation type of a pasteboard item.
A data object or nil if there is no data in the pasteboard of the given type.
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.
UIPasteboard.hReturns the data objects in the indicated pasteboard items that have the given representation type.
- (NSArray *)dataForPasteboardType:(NSString *)pasteboardType inItemSet:(NSIndexSet *)itemSet
A string identifying a representation type. Typically this is a UTI.
An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.
An array of NSData objects or, if a requested pasteboard item has no data of the the type indicated by pasteboardType, a NSNull object.
UIPasteboard.hReturns an index set identifying pasteboard items having the specified representation types.
- (NSIndexSet *)itemSetWithPasteboardTypes:(NSArray *)pasteboardTypes
An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.
An index set with each integer positionally identifying a pasteboard item that has one of the representation types specified in pasteboardTypes.
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.
UIPasteboard.hReturns the types of the first item on the pasteboard.
- (NSArray *)pasteboardTypes
An array of strings indicating the representation types of the first item on the pasteboard.
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. Applications can define their own types for custom data such as com.mycompany.myapp.mytype; however, in this case, only those applications 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"]; |
UIPasteboard.hReturns an array of representation types for each specified pasteboard item.
- (NSArray *)pasteboardTypesForItemSet:(NSIndexSet *)itemSet
An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.
An array of arrays, with each inner array holding the representation types for a particular pasteboard item.
UIPasteboard.hPuts data in the pasteboard for the specified representation type.
- (void)setData:(NSData *)data forPasteboardType:(NSString *)pasteboardType
The data object to be written to the pasteboard.
A string identifying the representation type of the pasteboard item. This is typically a UTI.
Use this method to put data on the pasteboard when the data is not a standard property-list object—that is, an object of the NSString, NSArray, NSDictionary, NSDate, NSNumber, or NSURL class. (For property-list objects, use the setValue:forPasteboardType: method.) For example, you could archive a graph of model objects and pass the resulting NSData object to a related application via a pasteboard using a custom pasteboard type. This method writes data for the first item in the pasteboard. Calling this method replaces any items currently in the pasteboard.
UIPasteboard.hPuts a property-list object in the pasteboard for the specified representation type.
- (void)setValue:(id)value forPasteboardType:(NSString *)pasteboardType
The property-list object to be written to the pasteboard.
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.
Use this method to put an object on the pasteboard that is a standard property-list object—that is an object of the NSString, NSArray, NSDictionary, NSDate, NSNumber, or NSURL class. (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.
UIPasteboard.hReturns an object in the pasteboard for the given representation type.
- (id)valueForPasteboardType:(NSString *)pasteboardType
A string identifying a representation type of a pasteboard item.
An object that is an instance of the appropriate class based on pasteboardType, a property-list object, or a NSData object containing “raw” data.
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 cannot determine the class type from the representation type, it returns the object as a generic property-list object. Property-list objects include NSString, NSArray, NSDictionary, NSDate, or NSNumber objects, with NSURL objects also as a possibility. If the method cannot decode the value as a property-list object, it returns the pasteboard item as an NSData object. This method works on the first item in the pasteboard. If there are other items, it ignores them.
UIPasteboard.hReturns the property-list objects in the indicated pasteboard items that have the given representation type.
- (NSArray *)valuesForPasteboardType:(NSString *)pasteboardType inItemSet:(NSIndexSet *)itemSet
A string identifying a representation type. Typically this is a UTI.
An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.
An array of NSData objects or, if a requested pasteboard item has no data of the the type indicated by pasteboardType, a NSNull object.
Returned objects are of one of the following classes: NSString, NSArray, NSDictionary, NSDate, NSNumber, or NSURL.
UIPasteboard.hNames identifying the system pasteboards.
UIKIT_EXTERN NSString *const UIPasteboardNameGeneral; UIKIT_EXTERN NSString *const UIPasteboardNameFind;
UIPasteboardNameGeneralThe 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.
UIPasteboardNameFindThe 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.
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, application uninstalls, and restores.
UIPasteboard.hPasteboard-item representation types for a given object value.
UIKIT_EXTERN NSArray *UIPasteboardTypeListString; UIKIT_EXTERN NSArray *UIPasteboardTypeListURL; UIKIT_EXTERN NSArray *UIPasteboardTypeListImage; UIKIT_EXTERN NSArray *UIPasteboardTypeListColor;
UIPasteboardTypeListStringAn array of pasteboard-item representation types for strings, including kUTTypeUTF8PlainText. Related properties are string and strings.
Available in iOS 3.0 and later.
Declared in UIPasteboard.h.
UIPasteboardTypeListURLAn 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.
UIPasteboardTypeListImageAn 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.
UIPasteboardTypeListColorAn 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.
UIPasteboard.hYou 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;
UIPasteboardChangedTypesAddedKeyWith 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.
UIPasteboardChangedTypesRemovedKeyWith 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.
UIPasteboard.hPosted 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.
UIPasteboard.hPosted by a pasteboard object just before an application removes it. The removal class method is removePasteboardWithName:. There is no userInfo dictionary.
UIPasteboard.hLast updated: 2010-08-03