Class

UIPasteboard

An object that helps a user share data from one place to another within your app, and from your app to other apps.

Overview

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.

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 UIPasteboardNameGeneral constant; you can use it for any type of data. Obtain the general pasteboard by using the generalPasteboard class method.

You can create named pasteboards with the class methods pasteboardWithName:create: and pasteboardWithUniqueName 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 pasteboardTypes 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.

Topics

Getting and Removing Pasteboards

generalPasteboard

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

pasteboardWithName:create:

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

pasteboardWithUniqueName

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

removePasteboardWithName:

Invalidates the designated app pasteboard.

Getting and Setting Pasteboard Attributes

name

The name of the pasteboard.

persistent

A Boolean value that indicates whether the pasteboard is persistent.

Deprecated
changeCount

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

Determining Types of Single Pasteboard Items

pasteboardTypes

Returns the types of the first item on the pasteboard.

containsPasteboardTypes:

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

Getting and Setting Single Pasteboard Items

dataForPasteboardType:

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

valueForPasteboardType:

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

setData:forPasteboardType:

Puts data in the pasteboard for the specified representation type.

setValue:forPasteboardType:

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

Determining the Types of Multiple Pasteboard Items

numberOfItems

Returns the number of items in the pasteboard

pasteboardTypesForItemSet:

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

itemSetWithPasteboardTypes:

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

containsPasteboardTypes:inItemSet:

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

Getting and Setting Multiple Pasteboard Items

items

The pasteboard items on the pasteboard.

dataForPasteboardType:inItemSet:

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

valuesForPasteboardType:inItemSet:

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

addItems:

Appends pasteboard items to the current contents of the pasteboard.

setItems:options:

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

string

The string value of the first pasteboard item.

strings

An array of strings in all pasteboard items.

image

The image object of the first pasteboard item.

images

An array of image objects in all pasteboard items.

URL

The URL object of the first pasteboard item.

URLs

An array of URL objects in all pasteboard items.

color

The color object of the first pasteboard item.

colors

An array of color objects in all pasteboard items.

Checking for Data Types on a Pasteboard

hasColors

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

hasImages

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

hasStrings

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

hasURLs

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

UIPasteboardChangedNotification

Posted by a pasteboard object when its contents change.

UIPasteboardRemovedNotification

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

Instance Properties

itemProviders

An array of item providers for the pasteboard.

Beta

Instance Methods

setItemProviders:localOnly:expirationDate:

Sets and configures an explicit array of item providers for the pasteboard.

Beta
setObjects:

Sets an array of item providers for the pasteboard, based on a specified array of objects.

Beta
setObjects:localOnly:expirationDate:

Sets and configures an array of item providers for the pasteboard, based on a specified array of objects.

Beta

Relationships

Inherits From

See Also

Pasteboard

UIPasteConfiguration

A paste configuration for use by responder objects to declare their ability to accept specific data types for pasting and for drag-and-drop activities.

Beta

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software