Class: UIPasteboard

Inherits:
NSObject show all

Overview

The UIPasteboard class enables an application to share data within the application or with another application using system-wide or application-specific pasteboards.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Integer) changeCount (readonly)

The number of times the pasteboard’s contents have changed. (read-only) 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.

Returns:

- (UIColor) color

The color object of the first pasteboard item. 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.

Returns:

- (Array) colors

An array of color objects in all pasteboard items. 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.

Returns:

- (UIImage) image

The image object of the first pasteboard item. 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.

Returns:

- (Array) images

An array of image objects in all pasteboard items. 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.

Returns:

- (Array) items

The pasteboard items on the pasteboard. 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.

Returns:

- (String) name (readonly)

The name of the pasteboard. (read-only) 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.”

Returns:

- (Integer) numberOfItems (readonly)

Returns the number of items in the pasteboard (read-only)

Returns:

- (Boolean) persistent

A Boolean value that indicates whether the pasteboard is 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.

Returns:

  • (Boolean)

- (String) string

The string value of the first pasteboard item. 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.

Returns:

- (Array) strings

An array of strings in all pasteboard items. 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.

Returns:

- (NSURL) URL

The URL object of the first pasteboard item. 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.

Returns:

- (Array) URLs

An array of URL objects in all pasteboard items. 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.

Returns:

Class Method Details

+ (UIPasteboard) generalPasteboard

Returns the general pasteboard, which is used for general copy-paste operations 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.

Returns:

  • (UIPasteboard) —

    A shared system pasteboard object with the name of UIPasteboardNameGeneral.

+ (UIPasteboard) pasteboardWithName(pasteboardName, create:create)

Returns a pasteboard identified by name, optionally creating it if it doesn’t exist. 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.

Parameters:

  • pasteboardName (String) —

    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 (Boolean) —

    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.

Returns:

  • (UIPasteboard) —

    A pasteboard object that can be used for transferring data within and application or between applications.

+ (UIPasteboard) pasteboardWithUniqueName

Returns an application pasteboard identified by a unique system-generated 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.

Returns:

  • (UIPasteboard) —

    An application pasteboard object with a unique name.

+ (Object) removePasteboardWithName(pasteboardName)

Invalidates the designated application pasteboard. 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.

Parameters:

  • pasteboardName (String) —

    The name of the pasteboard to be invalidated.

Returns:

Instance Method Details

- (Object) addItems(items)

Appends pasteboard items to the current contents of the pasteboard.

Parameters:

  • items (Array) —

    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.

Returns:

- (Boolean) containsPasteboardTypes(pasteboardTypes)

Returns whether the pasteboard holds data of the specified representation type. 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.

Parameters:

  • pasteboardTypes (Array) —

    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.

Returns:

  • (Boolean) —

    YES if the pasteboard item holds data of the indicated representation type, otherwise NO.

- (Boolean) containsPasteboardTypes(pasteboardTypes, inItemSet:itemSet)

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

Parameters:

  • pasteboardTypes (Array) —

    An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.

  • itemSet (NSIndexSet) —

    An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Returns:

  • (Boolean) —

    YES if the pasteboard items identified by itemSet have data corresponding to the representation types specified by pasteboardTypes; otherwise, returns NO.

- (NSData) dataForPasteboardType(pasteboardType)

Returns the data in the pasteboard for the given representation 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.

Parameters:

  • pasteboardType (String) —

    A string identifying a representation type of a pasteboard item.

Returns:

  • (NSData) —

    A data object or nil if there is no data in the pasteboard of the given type.

- (Array) dataForPasteboardType(pasteboardType, inItemSet:itemSet)

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

Parameters:

  • pasteboardType (String) —

    A string identifying a representation type. Typically this is a UTI.

  • itemSet (NSIndexSet) —

    An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Returns:

  • (Array) —

    An array of NSData objects or, if a requested pasteboard item has no data of the the type indicated by pasteboardType, a NSNull object.

- (NSIndexSet) itemSetWithPasteboardTypes(pasteboardTypes)

Returns an index set identifying pasteboard items having the specified representation types. 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.

Parameters:

  • pasteboardTypes (Array) —

    An array of strings, with each string identifying a representation type. Typically you use UTIs as pasteboard types.

Returns:

  • (NSIndexSet) —

    An index set with each integer positionally identifying a pasteboard item that has one of the representation types specified in pasteboardTypes.

- (Array) pasteboardTypes

Returns the 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:

Returns:

  • (Array) —

    An array of strings indicating the representation types of the first item on the pasteboard.

- (Array) pasteboardTypesForItemSet(itemSet)

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

Parameters:

  • itemSet (NSIndexSet) —

    An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Returns:

  • (Array) —

    An array of arrays, with each inner array holding the representation types for a particular pasteboard item.

- (Object) setData(data, forPasteboardType:pasteboardType)

Puts data in the pasteboard for the specified representation type. 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.

Parameters:

  • data (NSData) —

    The data object to be written to the pasteboard.

  • pasteboardType (String) —

    A string identifying the representation type of the pasteboard item. This is typically a UTI.

Returns:

- (Object) setValue(value, forPasteboardType:pasteboardType)

Puts a property-list object in the pasteboard for the specified representation type. 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.

Parameters:

  • value (Object) —

    The property-list object to be written to the pasteboard.

  • pasteboardType (String) —

    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.

Returns:

- (Object) valueForPasteboardType(pasteboardType)

Returns an object in the pasteboard for the given representation type. 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.

Parameters:

  • pasteboardType (String) —

    A string identifying a representation type of a pasteboard item.

Returns:

  • (Object) —

    An object that is an instance of the appropriate class based on pasteboardType, a property-list object, or a NSData object containing “raw” data.

- (Array) valuesForPasteboardType(pasteboardType, inItemSet:itemSet)

Returns the property-list objects in the indicated pasteboard items that have the given representation type. Returned objects are of one of the following classes: NSString, NSArray, NSDictionary, NSDate, NSNumber, or NSURL.

Parameters:

  • pasteboardType (String) —

    A string identifying a representation type. Typically this is a UTI.

  • itemSet (NSIndexSet) —

    An index set with each integer value identifying a pasteboard item positionally in the pasteboard. Pass in nil to request all pasteboard items.

Returns:

  • (Array) —

    An array of NSData objects or, if a requested pasteboard item has no data of the the type indicated by pasteboardType, a NSNull object.