- Working with Uniform Type Identifiers
- Accessing the System Pasteboard
- Recipe: Passively Updating the Pasteboard
- Recipe: Enabling Document File Sharing
- Recipe: Monitoring the Documents Folder
- The Document Interaction Controller
- Recipe: Checking for the Open Menu
- Declaring Document Support
- Recipe: Implementing Document Support
- Exported Type Declarations
- Creating URL-Based Services
- Recipe: Adding Custom Settings Bundles-Or Not
Accessing the System Pasteboard
Pasteboards, also known as clipboards on some systems, provide a central OS feature for sharing data across applications. Users can copy data to the pasteboard in one application, switch tasks, and then paste that data into another application. Cut/copy/paste features are similar to those found in most operating systems. Users can also copy and paste within a single application, when switching between text fields or views.
The UIPasteboard class offers access to a shared device pasteboard and its contents. This snippet returns the general system pasteboard, which is appropriate for most general copy/paste use:
UIPasteboard *pb = [UIPasteboard generalPasteboard];
In addition to the general shared system pasteboard, the iPhone offers both application-specific pasteboards to better ensure data privacy, which do not extend beyond the application itself, and custom-named pasteboards that can be used across applications, but only with applications that know and utilize the pasteboard name key. Create app-specific pasteboards using pasteboardWithUniqueName, which returns an application pasteboard object that persists until the application quits.
Create custom pasteboards using pasteboardWithName:create:, which returns a pasteboard with the specified name. Use reverse-DNS naming for the pasteboard (e.g., com.sadun.shared-application-pasteboard). The create parameter specifies whether the system should create the pasteboard if it does not yet exist. This kind of pasteboard can persist beyond a single application run; set the persistent property to YES after creation. Use removePasteboardWithName: to destroy a pasteboard and free up the resources used by it.
Pasteboards can store one or more entries at a time. Each has an associated type, using the UTI to specify what kind of data is stored. For example, you might find public.text (and more specifically public.utf8-plain-text) to store text data, public.url for URL address, and public.jpeg for image data. These are among many other common data types used on iOS. The dictionary that stores the type and the data is called an item, and you can retrieve an array of all available items via the pasteboard’s items property.
Query a pasteboard for its available types by sending it the pasteboardTypes message. This returns an array of types currently stored on the pasteboard.
NSArray *types = [pb pasteboardTypes];
You can set data on the pasteboard and associate a type by passing an NSData object and a UTI that describes a type the data conforms to. Alternatively, for property list objects (i.e., string, date, array, dictionary, number, or URL), set an NSValue via setValue:forPasteboardType:. These property list objects are stored internally somewhat differently than their raw-data cousins, giving rise to the method differentiation.
[[UIPasteboard generalPasteboard] setData;theData forPasteboardType:theUTI];
Storing Common Types
Pasteboards are further specialized for several data types, which represent the most commonly used pasteboard items. These are colors (not a property list “value” object), images (also not a property list “value” object), strings, and URLs. The UIPasteboard class provides specialized getters and setters to make it easier to handle these items. You can treat each of these as properties of the pasteboard, so you can set and retrieve them using dot notation. What’s more each property has a plural form, allowing you to access those items as arrays of objects.
Pasteboard properties greatly simplify using the system pasteboard for the most common use-cases. The property accessors include
- string—Set or retrieve the first string on the pasteboard
- strings—Set or retrieve an array of all strings on the pasteboard
- image—Set or retrieve the first image on the pasteboard
- images—Set or retrieve an array of all images on the pasteboard
- URL—Set or retrieve the first URL on the pasteboard
- URLs—Set or retrieve an array of all URLs on the pasteboard
- color—Set or retrieve the first color on the pasteboard
- colors—Set or retrieve an array of all colors on the pasteboard
When using one of the four special classes, simply use the associated property to retrieve data from the pasteboard. Otherwise you can fetch data using the dataForPasteboardType: method. This method returns the data from the first item whose type matches the UTI sent as a parameter. Any other matching items in the pasteboard are ignored.
Should you need to retrieve all matching data, recover an itemSetWithPasteboardTypes: and then iterate through the set to retrieve each dictionary. Recover the data type for each item from the single dictionary key and the data from its value.
As mentioned, UIPasteboard offers two approaches for pasting to the pasteboard depending on whether the information being pasted is a property list object or raw data. Use setValueForPasteboardType: for property list objects, which include strings, dates, numbers, dictionaries, arrays, and URLs. For general data, use setData:forPasteboardType:.
When pasteboards are changed, they issue a UIPasteboardChangedNotification, which you can listen into via a default NSNotificationCenter observer. You can also watch custom pasteboards and listen for their removal via UIPasteboardRemovedNotification.