Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.desktop 
NativeDragManager 
Packageflash.desktop
Classpublic class NativeDragManager
InheritanceNativeDragManager Inheritance 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.

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.

See also



Public Properties
 PropertyDefined By
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  AIR-only dragInitiator : InteractiveObject
[static] [read-only] The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation.
NativeDragManager
  AIR-only dropAction : String
[static] The drag action specified by the drop target.
NativeDragManager
  AIR-only isDragging : Boolean
[static] [read-only] Reports whether a drag operation is currently in progress.
NativeDragManager
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
Public Methods
 MethodDefined By
  
[static] Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.
NativeDragManager
  
AIR-only doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void
[static] Starts a drag-and-drop operation.
NativeDragManager
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
Property Detail
AIR-only 

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
AIR-only 

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

See also

AIR-only 

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
Method Detail

AIR-only 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

AIR-only 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.

See also