flash.desktop

# NativeDragManager - AS3

Package | flash.desktop
Class | public class NativeDragManager
Inheritance | NativeDragManager Object

Runtime Versions: | AIR 1.0

The NativeDragManager class coordinates drag-and-drop operations. With the native drag-and-drop API, you can allow a user to drag data between an AIR application and the native operating system, between two applications, or between components within a single application.

The following kinds of data can be transferred:

- Bitmaps
- Files
- Text
- URL strings
- Serialized objects
- Object references (valid only within the originating application)

Note: all NativeDragManager members are static. An instance of this class does not need to be created.

A drag-and-drop operation is a user interface gesture that begins with the user clicking a visible item and dragging it elsewhere. During the drag gesture, interactive objects on the display list dispatch native drag events as the gesture moves across the AIR application window. Handlers for these events can call the methods of the NativeDragManager class to indicate whether a dragged item can be dropped on an object. In response, the NativeDragManager changes the mouse pointer to provide feedback to the user.

AIR profile support: This feature is not supported on AIR for TV devices. Also, it is not supported on all mobile devices. You can test for support at run time using the `NativeDragManager.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

Drag actions

Drag-and-drop gestures are typically used for three types of operations, called actions. Since the meaning of these actions depends on the application context, the runtime does not enforce any particular behavior with respect to actions. However, properly implementing the actions improves the user experience with your application.

The possible actions are:

- Copy — A copy of the data is made, leaving the original untouched. (When dragging objects within an application, care should be taken to copy the original object itself rather than the reference to that object.)
- Move — The data is moved from its original context into the context defined by the drop target, such as when moving an item from one list to another.
- Link — A reference or shortcut to the original data is created, leaving the item in its original context.

The allowed actions can be set for a drag gesture by supplying an `allowedActions` parameter in the `NativeDragManager.doDrag()` call that starts the drag operation. If no `allowedActions` parameter is provided, all of the actions are allowed. Potential drag targets can check which actions are allowed by using the `allowedActions` property of a NativeDragEvent object, and should not accept a drop that allows only incompatible actions (this is not enforced by the runtime, however).

If a drop target only implements a single action, the object can set the `dropAction` property of the NativeDragManager in the handlers for both the `nativeDragEnter` and `nativeDragOver` events. Setting the property before the drop, allows the drag manager to update the mouse pointer to indicate the supported action and also prevents a user from choosing an incompatible action using modifier keys. If the specified action is not one of the allowed actions, then a drop is not allowed, even if the target calls the `acceptDrop()` method.

When accepting a drop, a potential drop target should specify the action chosen by setting the `NativeDragManager.dropAction` property in response to the `nativeDragDrop` event. This action is reported back to the initiating display object in the `nativeDragComplete` event. If no action is set by a drop target, then a default action is chosen from the allowed actions in this order of precedence: copy, move, link. The initiating object is responsible for updating its internal state in response to the chosen action.

String constants for the action names are defined in the NativeDragActions class.

Sequence of events

A drag gesture is begun by calling the `NativeDragManager.doDrag()` method within a `mouseDown` or `mouseMove` event handler and proceeds through the following event sequence in response to user actions:

- `nativeDragStart` event — When `NativeDragManager.doDrag()` is called, the interactive object passed as a paramter to the method becomes the initiator object and dispatches a `nativeDragStart` event.
- `nativeDragUpdate` event — While the drag is in progress, the initiator object continually dispatches `nativeDragUpdate` events.
- `nativeDragEnter`, `nativeDragOver` events — When a drag gesture passes over an interactive object, that object dispatches a `nativeDragEnter` event. While the drag gesture remains over the interactive object, it continually dispatches `nativeDragOver` events. In response to either of these events, an object that serves as a potential drop target should check the properties of the event object to decide whether it can accept the drop. If the data format and allowed actions are appropriate, then the event handler for these events must call `NativeDragManager.acceptDrop()`, passing in a reference to the display object to serve as the drag target (typically the object that dispatched the `nativeDragEnter` or `nativeDragOver` event). The user can then drop the dragged item onto the target.
- `nativeDragExit` event — When a drag gesture passes out of an interactive object, the object dispatches a `nativeDragExit` event. If the object had been designated as the drag target by an earlier call to the `NativeDragManager.acceptDrop()` method, that call is no longer valid and `acceptDrop()` must be called again if the gesture re-enters the interactive object.
- `nativeDragDrop` event — The target display object dispatches a `nativeDragDrop` event when the user releases the mouse button over the object. The handler for this event can access the data in the `transferable` property of the event object and should set the `NativeDragManager.dropAction` property to signal which action should be taken by the initiator object.
- `nativeDragComplete` — When the user releases the mouse button at the end of a drag gesture, the initiator object dispatches a `nativeDragComplete` event (whether or not the drop itself was consumated). The handler for this event can check the `dropAction` property of the event object to determine what, if any, modification should be made to its internal data state, such as removing a dragged-out item from a list. If `dropAction` is `NativeDragActions.NONE`, then the dragged item was not dropped on an eligible target.

Gestures between applications

When a drag gesture enters an AIR application window from a non-AIR application, there is no initiator object to dispatch the `nativeDragStart` or `nativeDragComplete` event. The events dispatched during the gesture will otherwise follow the same pattern as that of a gesture starting and ending within the same AIR application.

When a drag gesture leaves an AIR application window, there is no target object to dispatch `nativeDragEnter`, `nativeDragOver`, or `nativeDragDrop` events. The initiator object still dispatches a `nativeDragComplete` event, which reports the drag action set by the native operating system (or `none`, if the drop was not accepted).

When a drag gesture moves from one AIR application to another, the initiator and target display objects dispatch events within their separate applications as usual.

Transfering information

The data transfered during a drag-and-drop gesture is contained in a Clipboard object. This data object is added to the drag operation with the `NativeDragManager.doDrag()` method that starts the drag gesture. Potential drop targets can access the Clipboard object through the `clipboard` property of the native drag event object. Once a drag operation has started, the Clipboard object can only be accessed in the event handler of a NativeDragEvent. Any other attempt to access the object generates a run-time error.

Security considerations

The security sandboxes of the initiator and potential target objects determine how the the data being dragged can be accessed. If both objects are in the same sandbox, then the data can be accessed from any NativeDragEvent object. However, if the initiator and target objects are in different sandboxes, the data can only be accessed in the target sandbox within the event handler for the `nativeDragDrop` event. Other native drag event handlers can still still access the Clipboard object referenced in the event `clipboard` property to determine which data formats are available, but calling the `clipboard.getData()` method generates a security error.

More examples

Drag and drop in AIR

Related API Elements

flash.events.NativeDragEvent
flash.desktop.NativeDragActions
flash.desktop.NativeDragOptions
flash.desktop.Clipboard

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | dragInitiator : InteractiveObject [static] [read-only] The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation. | NativeDragManager
|  | dropAction : String [static] The drag action specified by the drop target. | NativeDragManager
|  | isDragging : Boolean [static] [read-only] Reports whether a drag operation is currently in progress. | NativeDragManager
|  | isSupported : Boolean [static] [read-only] The isSupported property is set to true if the NativeDragManager class is supported on the current platform, otherwise it is set to false. | NativeDragManager

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | acceptDragDrop(target:InteractiveObject):void [static] Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event. | NativeDragManager
|  | doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void [static] Starts a drag-and-drop operation. | NativeDragManager
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### dragInitiator

property

`dragInitiator:InteractiveObject` [read-only]

Runtime Versions: | AIR 1.0

The interactive object passed to the `NativeDragManager.doDrag()` call that initiated the drag operation.

Implementation
`public static function get dragInitiator():InteractiveObject`

### dropAction

property

`dropAction:String`

Runtime Versions: | AIR 1.0

The drag action specified by the drop target.

The `dropAction` property should be set in the handler for the `nativeDragDrop` event. If `dropAction` is not set before the `nativeDragComplete`, the NativeDragManager sets the value with the first allowed action from the list: copy, move, or link (in that order).

Implementation
`public static function get dropAction():String`
`public static function set dropAction(value:String):void`

Related API Elements

flash.desktop.NativeDragActions

### isDragging

property

`isDragging:Boolean` [read-only]

Runtime Versions: | AIR 1.0

Reports whether a drag operation is currently in progress.

Implementation
`public static function get isDragging():Boolean`

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

The `isSupported` property is set to `true` if the NativeDragManager class is supported on the current platform, otherwise it is set to `false`.

Implementation
`public static function get isSupported():Boolean`
Method Detail

### acceptDragDrop

()
method

`public static function acceptDragDrop(target:InteractiveObject):void`

Runtime Versions: | AIR 1.0

Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.

This method should be called only when there is a `nativeDragDrop` handler on the specified target object that can handle at least one of the data formats in the dragged item and at least one of the allowed actions.

This function can be called only within a `nativeDragEnter` or `nativeDragOver` event handler.

Parameters

| `target:InteractiveObject`

### doDrag

()
method

`public static function doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void`

Runtime Versions: | AIR 1.0

Starts a drag-and-drop operation.

To start a drag operation:

1. Create a new Clipboard object.
2. Add the data to be transferred in one or more formats.
3. Optionally, create a BitmapData object to serve as a proxy image during the drag.
4. Optionally, create a NativeDragOptions object to restrict the actions allowed in this operation. (If the `allowedActions` parameter is left `null`, all actions are allowed.)
5. Call `NativeDragManager.doDrag()`.

The initiator object dispatches a `nativeDragStart` event after this method is called, `nativeDragStart` events while the drag is in progress, and a `nativeDragComplete` event when the user releases the mouse button to end the drag gesture. The handler for the `nativeDragComplete` event can check the `dropAction` property of the event to determine whether the drag-and-drop operation was successfully completed. If `dropAction` is `NativeDragActions.NONE`, then the dragged item was not dropped on an eligible target.

This method can be called only from within a `mouseDown` or `mouseMove` event handler. (If called in response to a `mouseMove` event, the mouse button must also be down.)

Parameters

| `dragInitiator:InteractiveObject` — Typically the object from which the drag gesture began. Receives the `nativeDragStart` and `nativeDragComplete` events.
| `clipboard:Clipboard` — The container object for data being dragged.
| `dragImage:BitmapData` (default = `null`)`` — An optional proxy image displayed under the mouse pointer during the drag gesture. If `null`, no image is displayed.
| `offset:Point` (default = `null`)`` — The offset between the mouse hotspot and the top left corner of the drag image. Negative coordinates move the image up and to the left in relation to the hotspot. If `null`, the top left corner of the drag image is positioned at the mouse hotspot.
| `allowedActions:NativeDragOptions` (default = `null`)`` — Restricts the drag-and-drop actions allowed for this operation. If `null`, all actions are allowed.

Related API Elements

flash.desktop.NativeDragActions

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00