Class

UIPasteboard

Use the UIPasteboard class to let a user to share data from one place to another within your app, and from your app to other apps. For sharing data with any other app, use the systemwide general pasteboard; for sharing data with another app from your team—that has the same team ID as the app to share from—use named pasteboards.

Overview

In typical usage, an object in your app writes data to a pasteboard when the user requests a copy, cut, or duplicate 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.

The General Pasteboard and Named Pasteboards

The systemwide general pasteboard is identified with the general constant; you can use it for any type of data. Obtain the general pasteboard by using the general() class method.

You can create named pasteboards with the class methods init(name:create:) and withUniqueName() for sharing data within your app and from your app to other apps that have the same Team ID.

Using Pasteboards

The UIPasteboard class provides methods for reading and writing individual pasteboard items, as well as methods for reading and writing multiple pasteboard items at once. See Getting and Setting Single Pasteboard Items and Getting and Setting Multiple Pasteboard Items .

The data to be written to a pasteboard can be in either of two forms:

The UIPasteboard class provides convenience methods for writing and reading strings, images, URLs, and colors to and from single or multiple pasteboard items, as described in Getting and Setting Pasteboard Items of Standard Data Types.

Starting in iOS 10, the UIPasteboard class provides properties for directly checking whether specific data types are present on a pasteboard, described in Checking for Data Types on a Pasteboard. Use these properties, rather than attempting to read pasteboard data, to avoid causing the system to needlessly attempt to fetch data before it is needed or when the data might not be present. For example, you can use the new hasStrings property to determine whether to present a string-data Paste option in the user interface, using code like this:

if UIPasteboard.generalPasteboard().hasStrings {
    // Enable string-related control...
}

Pasteboard Items and Representation Types

When you write an object to a pasteboard, the pasteboard stores it as a pasteboard item. A pasteboard item is one or more key-value pairs in which the key identifies the representation type (sometimes called a pasteboard type) of the value.

A Uniform Type Identifier (UTI) is frequently used as the key for a representation type. For example, you could use the kUTTypeJPEG UTI (a constant for public.jpeg) as a representation type key for JPEG data.

For a discussion of Uniform Type Identifiers (UTIs) and a list of common ones, see Uniform Type Identifiers Overview.

Your app is 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).

You can provide flexibility for data sharing by providing, during a Copy or Cut operation, multiple representation types for a pasteboard item. Various contexts within your app or other apps can then make use of an appropriate representation type. For example, when a user copies an image, your app could write multiple representation types, such as in the PNG, JPEG, and GIF data formats, to a pasteboard. If the original image was in PNG format but the receiving app can handle only GIF images, it can still use the pasteboard data.

For more about representation types, read the discussion for the types instance method.

Using Pasteboards With Other Objects

Although the UIPasteboard class is central to Copy, Paste, and Duplicate operations, you can employ protocols and instances of other UIKit classes 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:).

A typical app that implements copy, paste, and duplicate operations also manages and presents related selections in its user interface. In addition, your app must coordinate changes in pasteboard content with changes to its data model, as appropriate for your app.

Symbols

Getting and Removing Pasteboards

init?(name: UIPasteboardName, create: Bool)

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

class func withUniqueName()

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

class func remove(withName: UIPasteboardName)

Invalidates the designated app pasteboard.

Getting and Setting Pasteboard Attributes

var name: UIPasteboardName

The name of the pasteboard.

func setPersistent(Bool)

A Boolean value that indicates whether the pasteboard is persistent.

var changeCount: Int

The number of times the pasteboard’s contents have changed.

Determining Types of Single Pasteboard Items

var types: [String]

Returns the types of the first item on the pasteboard.

func contains(pasteboardTypes: [String])

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

Getting and Setting Single Pasteboard Items

func data(forPasteboardType: String)

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

func value(forPasteboardType: String)

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

func setData(Data, forPasteboardType: String)

Puts data in the pasteboard for the specified representation type.

func setValue(Any, forPasteboardType: String)

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

Determining the Types of Multiple Pasteboard Items

var numberOfItems: Int

Returns the number of items in the pasteboard

func types(forItemSet: IndexSet?)

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

func itemSet(withPasteboardTypes: [String])

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

func contains(pasteboardTypes: [String], inItemSet: IndexSet?)

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

Getting and Setting Multiple Pasteboard Items

var items: [[String : Any]]

The pasteboard items on the pasteboard.

func data(forPasteboardType: String, inItemSet: IndexSet?)

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

func values(forPasteboardType: String, inItemSet: IndexSet?)

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

func addItems([[String : Any]])

Appends pasteboard items to the current contents of the pasteboard.

func setItems([[String : Any]], options: [UIPasteboardOption : Any] = [:])

Adds an array of items to a pasteboard, and sets privacy options for all the items on the pasteboard.

Getting and Setting Pasteboard Items of Standard Data Types

var string: String?

The string value of the first pasteboard item.

var strings: [String]?

An array of strings in all pasteboard items.

var image: UIImage?

The image object of the first pasteboard item.

var images: [UIImage]?

An array of image objects in all pasteboard items.

var url: URL?

The URL object of the first pasteboard item.

var urls: [URL]?

An array of URL objects in all pasteboard items.

var color: UIColor?

The color object of the first pasteboard item.

var colors: [UIColor]?

An array of color objects in all pasteboard items.

Checking for Data Types on a Pasteboard

var hasColors: Bool

Returns a Boolean value indicating whether or not the colors property contains a nonempty array.

var hasImages: Bool

Returns a Boolean value indicating whether or not the images property contains a nonempty array.

var hasStrings: Bool

Returns a Boolean value indicating whether or not the strings property contains a nonempty array.

var hasURLs: Bool

Returns a Boolean value indicating whether or not the urls property contains a nonempty array.

Constants

Pasteboard Names

Names identifying the system pasteboards.

UIPasteboardOption

Options for describing pasteboard privacy. Use these options with the setItems(_:options:) method. Options that you set apply to all the items on a pasteboard.

Pasteboard Data Type Representations

Pasteboard-item representation types, as for a given object value.

UserInfo Dictionary Keys

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

Notifications

static let UIPasteboardChanged: NSNotification.Name

Posted by a pasteboard object when its contents change.

static let UIPasteboardRemoved: NSNotification.Name

Posted by a pasteboard object just before an app removes it.

Relationships

Inherits From

Conforms To