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
Related sample code

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

Properties

draggingFrame

Returns the frame of the dragging item.

@property NSRect draggingFrame
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.
Related Sample Code
Declared In
NSDraggingItem.h

imageComponents

Returns an array of dragging image components that are used to create receiver’s the drag image. (read-only)

@property(copy, readonly) NSArray *imageComponents
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.h

imageComponentsProvider

An array of Blocks that provide the dragging image components.

@property(copy) NSArray *(^imageComponentsProvider)(void)
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.
Related Sample Code
Declared In
NSDraggingItem.h

item

Returns the pasteboard reader or writer object dependent on the context of where this dragging item is used . (read-only)

@property(retain, readonly) id item
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.h

Instance Methods

initWithPasteboardWriter:

Initializes and returns a dragging item using the specified content.

- (id)initWithPasteboardWriter:(id < NSPasteboardWriting >)pasteboardWriter
Parameters
pasteboardWriter

The object that provides the dragging content. The object must implement the NSPasteboardWriting protocol.

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.h

setDraggingFrame:contents:

Sets the item’s dragging frame and contents.

- (void)setDraggingFrame:(NSRect)frame contents:(id)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 a CGImageRef will 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.
Related Sample Code
Declared In
NSDraggingItem.h