Basics of drag and drop in AIR

Drag-and-drop gesture stages

The drag-and-drop gesture has three stages:

Initiation

A user initiates a drag-and-drop operation by dragging from a component, or an item in a component, while holding down the mouse button. The component that is the source of the dragged item is typically designated as the drag initiator and dispatches nativeDragStart and nativeDragComplete events. An Adobe AIR application starts a drag operation by calling the NativeDragManager.doDrag() method in response to a mouseDown or mouseMove event.

If the drag operation is initiated from outside an AIR application, there is no initiator object to dispatch nativeDragStart or nativeDragComplete events.

Dragging

While holding down the mouse button, the user moves the mouse cursor to another component, application, or to the desktop. As long as the drag is underway, the initiator object dispatches nativeDragUpdate events. (However, this event is not dispatched in AIR for Linux.) When the user moves the mouse over a possible drop target in an AIR application, the drop target dispatches a nativeDragEnter event. The event handler can inspect the event object to determine whether the dragged data is available in a format that the target accepts and, if so, let the user drop the data onto it by calling the NativeDragManager.acceptDragDrop() method.

As long as the drag gesture remains over an interactive object, that object dispatches nativeDragOver events. When the drag gesture leaves the interactive object, it dispatches a nativeDragExit event.

Drop

The user releases the mouse over an eligible drop target. If the target is an AIR application or component, then the target object dispatches a nativeDragDrop event. The event handler can access the transferred data from the event object. If the target is outside AIR, the operating system or another application handles the drop. In both cases, the initiating object dispatches a nativeDragComplete event (if the drag started from within AIR).

The NativeDragManager class controls both drag-in and drag-out gestures. All the members of the NativeDragManager class are static, do not create an instance of this class.

The Clipboard object

Data that is dragged into or out of an application or component is contained in a Clipboard object. A single Clipboard object can make available different representations of the same information to increase the likelihood that another application can understand and use the data. For example, an image could be included as image data, a serialized Bitmap object, and as a file. Rendering of the data in a format can be deferred to a rendering function that is not called until the data is read.

Once a drag gesture has started, the Clipboard object can only be accessed from within an event handler for the nativeDragEnter , nativeDragOver , and nativeDragDrop events. After the drag gesture has ended, the Clipboard object cannot be read or reused.

An application object can be transferred as a reference and as a serialized object. References are only valid within the originating application. Serialized object transfers are valid between AIR applications, but can only be used with objects that remain valid when serialized and deserialized. Objects that are serialized are converted into the Action Message Format for ActionScript 3 (AMF3), a string-based data-transfer format.

Working with the Flex framework

In most cases, it is better to use the Adobe® Flex™ drag-and-drop API when building Flex applications. The Flex framework provides an equivalent feature set when a Flex application is run in AIR (it uses the AIR NativeDragManager internally). Flex also maintains a more limited feature set when an application or component is running within the more restrictive browser environment. AIR classes cannot be used in components or applications that run outside the AIR run-time environment.