NSDraggingItem Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.7 and later. |
| Declared in | NSDraggingItem.h |
Overview
The NSDraggingItem class encompasses a single dragged item within an NSDraggingSession instance.
See NSDraggingSession Class Reference for more information
NSDraggingItem objects have extremely limited lifetimes. Do not retain these items as changing outside of the prescribed lifetimes have no impact on the drag.
When the NSDraggingSession method beginDraggingSessionWithItems:event:source: is called, the dragging items passed to the method are consumed immediately and are not retained. Any further changes to the dragging item associated with the returned NSDraggingSession must be done via the enumeration method enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock:. When enumerating, NSDraggingItem instances are created right before being given to the enumeration Block. After returning from the Block, the NSDraggingItem instance is no longer valid.
Tasks
Initializing a Dragging Item
Dragging Frame
Drag Image Components
-
imageComponentsproperty -
imageComponentsProviderproperty -
itemproperty
Properties
draggingFrame
Returns the frame of the dragging item.
Discussion
The dragging frame provides the spatial relationship between NSDraggingItem instances when the dragging formation is set to NSDraggingFormationNone.
The exact coordinate space of this rectangle is dependent on where it is used. The view that initiated the drag using beginDraggingSessionWithItems:event:source: or the view your pass to the NSDraggingSession instance implantation of enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock:.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.himageComponents
Returns an array of dragging image components that are used to create receiver’s the drag image. (read-only)
Discussion
An array of NSDraggingImageComponent instances that are used to create the drag image.
The array contains copies of the components. Changes made to these copies are not reflected in the drag. If needed, the imageComponentsProvider block is called to generate the image components.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.himageComponentsProvider
An array of Blocks that provide the dragging image components.
Discussion
The dragging image is the composite of an array of NSDraggingImageComponent objects.
The dragging image components are not set directly. Instead, a Block is used to generate the components and the Block will be called if necessary.
The block may be set to nil, meaning that this drag item has no image. Generally, only dragging destinations do this, and only if there is at least one valid item in the drop, and the receiver is not that object.
The components are composited in painting order. That is, each component in the array is painted on top of the previous components in the array.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.hitem
Returns the pasteboard reader or writer object dependent on the context of where this dragging item is used . (read-only)
Discussion
When you create an NSDraggingItem instance, item is the pasteboardWriter passed to initWithPasteboardWriter:.
However, when enumerating dragging items using the NSDraggingSession method enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: or the NSDraggingInfo method enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock:, item is not the original pasteboard reader or writer instance. It is an instance of one of the classes provided to the enumeration method’s classArray parameter.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.hInstance Methods
initWithPasteboardWriter:
Initializes and returns a dragging item using the specified content.
Parameters
- pasteboardWriter
The object that provides the dragging content. The object must implement the
NSPasteboardWritingprotocol.
Return Value
An initialized NSDraggingItem instance with the specified dragging content.
Discussion
When the developer creates an NSDraggingItem instance , it is for use with the view method beginDraggingSessionWithItems:event:source: During the invocation of that method, the pasteboardWriter is placed onto the dragging pasteboard for the NSDraggingSession that contains the dragging item instance.
The designated initializer.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.hsetDraggingFrame:contents:
Sets the item’s dragging frame and contents.
Parameters
- frame
The item content frame in the same coordinate space that the
draggingFrame.- contents
The item contents to display when dragging. Typically this is an
NSImage, but aCGImageRefwill also work.
Discussion
Alternate single image component setter.
This method simplifies modifying the components of an NSDraggingItem when there is only one component.
This is a convenience method. This method sets the draggingFrame and creates a single NSDraggingImageComponent instance with one image corresponding to the NSDraggingImageComponentIconKey key. You should only use this method under the following conditions: the drag image for this item is composed of a single image., or there are a reasonable number of dragging item instances being created or enumerated.
If your application requires the dragging of hundreds of items this method would create a instance for each item when it is called. Compare this to the imageComponentsProvider block which is much faster to define and allows the Application Kit to create only a subset of the items using imageComponentsProvider.
This method will set the draggingFrame and imageComponents properties.
Availability
- Available in OS X v10.7 and later.
Declared In
NSDraggingItem.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-06)