iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIPasteboard Class Reference

Options
Deployment Target:

On This Page
Language:

UIPasteboard

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. More...

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.0 and later.
  • Returns the general pasteboard, which is used for general copy-paste operations

    Declaration

    Swift

    class func generalPasteboard() -> UIPasteboard

    Objective-C

    + (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init!(name pasteboardName: String!, create create: Bool) -> UIPasteboard

    Objective-C

    + (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 NOfalse 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 YEStrue.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func pasteboardWithUniqueName() -> UIPasteboard

    Objective-C

    + (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 YEStrue. Calling this method is equivalent to calling pasteboardWithName:create: with the first parameter set to nil and the second set to YEStrue.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Invalidates the designated app pasteboard.

    Declaration

    Swift

    class func removePasteboardWithName(_ pasteboardName: String)

    Objective-C

    + (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • name name Property

    The name of the pasteboard. (read-only)

    Declaration

    Swift

    var name: String { get }

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • A Boolean value that indicates whether the pasteboard is persistent.

    Declaration

    Swift

    var persistent: Bool

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var changeCount: Int { get }

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns the types of the first item on the pasteboard.

    Declaration

    Swift

    func pasteboardTypes() -> [AnyObject]!

    Objective-C

    - (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"];

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func containsPasteboardTypes(_ pasteboardTypes: [AnyObject]) -> Bool

    Objective-C

    - (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

    YEStrue if the pasteboard item holds data of the indicated representation type, otherwise NOfalse.

    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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func dataForPasteboardType(_ pasteboardType: String) -> NSData?

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func valueForPasteboardType(_ pasteboardType: String) -> AnyObject?

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Puts data in the pasteboard for the specified representation type.

    Declaration

    Swift

    func setData(_ data: NSData, forPasteboardType pasteboardType: String)

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setValue(_ value: AnyObject, forPasteboardType pasteboardType: String)

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • items items Property

    The pasteboard items on the pasteboard.

    Declaration

    Swift

    var items: [AnyObject]!

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    See Also

    – addItems:

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

    Declaration

    Swift

    func dataForPasteboardType(_ pasteboardType: String, inItemSet itemSet: NSIndexSet?) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func valuesForPasteboardType(_ pasteboardType: String, inItemSet itemSet: NSIndexSet?) -> [AnyObject]!

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Appends pasteboard items to the current contents of the pasteboard.

    Declaration

    Swift

    func addItems(_ items: [AnyObject])

    Objective-C

    - (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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    See Also

    items

  • string string Property

    The string value of the first pasteboard item.

    Declaration

    Swift

    var string: String?

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • strings strings Property

    An array of strings in all pasteboard items.

    Declaration

    Swift

    var strings: [AnyObject]?

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • image image Property

    The image object of the first pasteboard item.

    Declaration

    Swift

    @NSCopying var image: UIImage?

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • images images Property

    An array of image objects in all pasteboard items.

    Declaration

    Swift

    var images: [AnyObject]!

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • URL URL Property

    The URL object of the first pasteboard item.

    Declaration

    Swift

    @NSCopying var URL: NSURL?

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • URLs URLs Property

    An array of URL objects in all pasteboard items.

    Declaration

    Swift

    var URLs: [AnyObject]!

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • color color Property

    The color object of the first pasteboard item.

    Declaration

    Swift

    @NSCopying var color: UIColor?

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • colors colors Property

    An array of color objects in all pasteboard items.

    Declaration

    Swift

    var colors: [AnyObject]!

    Objective-C

    @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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Names identifying the system pasteboards.

    Declaration

    Swift

    let UIPasteboardNameGeneral: String let UIPasteboardNameFind: String

    Objective-C

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

    Constants

    • UIPasteboardNameGeneral

      UIPasteboardNameGeneral

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

      Available in iOS 3.0 and later.

    • UIPasteboardNameFind

      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.

    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.

  • Pasteboard-item representation types for a given object value.

    Declaration

    Swift

    var UIPasteboardTypeListString: NSArray! var UIPasteboardTypeListURL: NSArray! var UIPasteboardTypeListImage: NSArray! var UIPasteboardTypeListColor: NSArray!

    Objective-C

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

    Constants

    • UIPasteboardTypeListString

      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.

    • UIPasteboardTypeListURL

      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.

    • UIPasteboardTypeListImage

      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.

    • UIPasteboardTypeListColor

      UIPasteboardTypeListColor

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

      Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let UIPasteboardChangedTypesAddedKey: String let UIPasteboardChangedTypesRemovedKey: String

    Objective-C

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

    Constants

    • UIPasteboardChangedTypesAddedKey

      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.

    • UIPasteboardChangedTypesRemovedKey

      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.

  • 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.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Posted by a pasteboard object just before an app removes it. The removal class method is removePasteboardWithName:. There is no userInfo dictionary.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.