Drag-and-Drop in Flex

Also check out the Flex Drag-and-Drop: The Definitive Tutorial to learn how to drag-and-drop in Flex, step by step.

Drag-and-drop lets you move components and transfer data in a Flex application via the mouse and ubiquitous "click-drag-drop" paradigm. All Flex components support drag-and-drop operations with the proper enablement.

Drag-and-Drop example

Overview of Drag-and-Drop

Drag-and-drop operations have three main stages: initiation, dragging, and dropping.

Initiation, Dragging, and Dropping

Initiation of a drag-and-drop operation occurs when a "drag-enabled" component is selected with the mouse and moved while holding down the mouse button. The component selected and dragged is called the drag initiator. A drag source object is created for holding data related to the drag session.

To learn how to "drag-enabled" a component, see the Making a Component Draggable section below.

Dragging occurs when the user, still holding down the mouse button, moves the drag initiator component around the application. While a component is being dragged Flex will display an image called a drag proxy.

Dropping is the action of releasing the drag initiator component over a drop target. A potential drop target can inspect the drag source and determine whether to allow (or accept) a drop.

To learn how to make a component a "drop target", see the Making a Component a Drop Target section below.

Drag Initiator, Source, Proxy, and Drop Target

The above descriptions of Initiation, Dragging, and Dropping introduce us to the following objects involved in drag and drop operations.

Drag Initiator - the drag-enabled component that started a drag-and-drop operation via a mouse click
Drag Source - an mx.core.DragSource object created to hold data about the drag initiator
Drag Proxy - an image or visual object (mx.core.IUIComponent) shown while an component is being dragged
Drop Target - a "drop-enabled" component that can allow or disallow the drop of a drag source

A simplified description: Click on a component (drag initiator), drag it around, then drop it on another component (drop target).

If you've got a basic understanding of the terminology of drag-and-drop in Flex, let's move on to the code (the good stuff).

Enabling Drag-and-Drop

Enabling drag-and-drop in your Flex application largely involves making components draggable and making components drop targets.

To do this we'll make use of events, specifically mouse events (flash.events.MouseEvent) and drag events (mx.events.DragEvent).

We'll also make use of the DragManager class.

Making a Component Draggable

Add listener for MouseEvent.MOUSE_DOWN
Determine drag initiator and hand-off to DragManager

To kick off a drag-n-drop, you'll need a MouseEvent for the component to be dragged.

   public function makeDraggable( component:IUIComponent ):void
   {
      // a mouseDown event will start the drag
      component.addEventListener( MouseEvent.MOUSE_DOWN, beginDrag );
   }
   
   public function beginDrag( mouseEvent:MouseEvent ):void
   {
      // the drag initiator is the object being dragged (target of the mouse event)
      var dragInitiator:IUIComponent = mouseEvent.currentTarget as IUIComponent;
      
      // the drag source contains data about what's being dragged
      var dragSource:DragSource = new DragSource();
      
      // ask the DragManger to begin the drag
      DragManager.doDrag( dragInitiator, dragSource, mouseEvent, null );
   }

Making a Component a Drop Target

To "drop-enable" a component you must add appropriate event listeners to it. Specifically a drop target should listen for at least the the DragEvent.DRAG_ENTER ("dragEnter") and DragEvent.DRAG_DROP ("dragDrop") events.

The code below shows a makeDroppable() function that make a component a drop target by listening for appropriate drag events.

   public function makeDroppable( component:IUIComponent ):void
   {
      // a dragEnter event occurs when a draggable is over a droppable
      component.addEventListener( DragEvent.DRAG_ENTER, allowDrop );
      
      // a dragDrop event occurs when a draggable is dropped
      component.addEventListener( DragEvent.DRAG_DROP, acceptDrop );
   }
   
   public function allowDrop( dragEvent:DragEvent ):void
   {
      // the drop target
      var dropTarget:IUIComponent = dragEvent.currentTarget as IUIComponent;
      
      // signal to the drop manager that this will accept the item
      DragManager.acceptDragDrop( dropTarget );
   }
   
   public function acceptDrop( dragEvent:DragEvent ):void
   {
      var dragSource:DragSource = dragEvent.dragSource;
      var dragInitiator:IUIComponent = dragEvent.dragInitiator;
      var dropTarget:Object = dragEvent.currentTarget;
      
      Alert.show( "Dragged ("+dragInitiator['label']+") to ("+dropTarget['label']+") and Dropped" );
   }

Drag-and-Drop Events (Reviewed)

Drag-and-drop implementation typically uses a combination of the following mouse events and drag events.

For a component to be a drag initiator it must have a listener for the MouseEvent.MOUSE_DOWN event to start a drag
For a component to be a drop target it must have a listener for the DragEvent.DRAG_ENTER event to determine if it will allow a drop
For a component to be a drop target it must have a listener for the DragEvent.DRAG_DROP event to accept a drop and take appropriate action
Optionally, a drop target may have a listener for the DragEvent.DRAG_EXIT event to "turn off" any visual effects triggered by the drag enter event

The DragEvent instance contains several important properties used to complete the drop.

DragEvent.dragSource - the drag source object
DragEvent.dragInitiator - the drag initiator component
DragEvent.currentTarget - the drop target component

Built-in Drag-and-Drop Support for List Controls and Containers

Some List controls (e.g. DataGrid, List, Menu, Tree) and Containers in Flex have built-in drag-and-drop support.

You can make these controls drag initiators by setting the dragEnabled property to true. Similarly, you can make these controls drop targets by setting the dropEnabled property to true. Flex lets you move items by dragging them from a drag-enabled control to a drop-enabled control, or copy them by dragging while pressing the Control key.

The below example shows how to easily setup two List controls for easy drag-and-drop between each other.

   <mx:List id="list1" width="150" height="200"
      dragEnabled="true" dropEnabled="true" dragMoveEnabled="true">
      <mx:dataProvider>
         <mx:Array>
            <mx:String>One</mx:String>
            <mx:String>Two</mx:String>
            <mx:String>Three</mx:String>
         </mx:Array>
      </mx:dataProvider>
   </mx:List>
   
   <mx:List id="list2" width="150" height="200"
      dragEnabled="true" dropEnabled="true" dragMoveEnabled="true">
   </mx:List>

The result is that you can drag items from list to list.

List controls with simple Drag-and-Drop support.

Setting Data in the Drag Source

TODO... addData(), addHandler(), dataForFormat(), hasHandler()

Drag and Drop Flex Example