Implement Drag and Drop in Your Web Apps - Part 2/Page 3

Implement Drag and Drop in Your Web Apps - Part 2 [con't]

Mouse Listeners

The final pieces of the dnd puzzle are the mouse listeners, where most of the complexity lies. Listing 6.13 lists the AbstractMouseDragger class, which blithely drags widgets around on an absolute panel.

Listing 6.13 com.gwtsolutions.components.client.ui.dnd.AbstractMouseDragger

package com.gwtsolutions.components.client.ui.dnd;
import com.google.gwt.user.client.DOM;
import com.google.gwt.user.client.ui.AbsolutePanel;
import com.google.gwt.user.client.ui.MouseListenerAdapter;
public abstract class AbstractMouseDragger extends
 MouseListenerAdapter {
 private int xoffset, yoffset;
 // Subclasses implement this method to override the
 // proposed left edge of the dragSource after a drag
 protected abstract int getNextLeft(int proposedLeft,
 DragSource ds);
 // Subclasses implement this method to override the
 // proposed top edge of the dragSource after a drag
 protected abstract int getNextTop(int proposedTop,
 DragSource ds);
 public void onMouseDown(DragSource ds, int x, int y) {
 xoffset = x;
 yoffset = y;
 // Enable event capturing, so that subsequent mouse
 // events are all sent directly to the ds's
 // DOM element
 DOM.setCapture(ds.getElement());
 // Tell the drag source that dragging has begun
 ds.setDragging(true);
 }
 public void onMouseMove(DragSource ds, int x, int y) {
 if (ds.isDragging()) {
 // If the drag source is being dragged, calculate
 // the proposed left and top, and give subclasses
 // a chance to adjust those values
 AbsolutePanel ap = (AbsolutePanel) ds.getParent();
 int proposedLeft = x + ap.getWidgetLeft(ds) - xoffset;
 int proposedRight = y + ap.getWidgetTop(ds) - yoffset;
 int nextLeft = getNextLeft(proposedLeft, ds);
 int nextRight = getNextTop(proposedRight, ds);
 // Set the drag source's position to the next
 // left and next right
 ap.setWidgetPosition(ds, nextLeft, nextRight);
 }
 }
 public void onMouseUp(DragSource ds, int x, int y) {
 // Tell the drag source that dragging is done and
 // release the capture of mouse events that was set
 // in onMouseDown()
 ds.setDragging(false);
 DOM.releaseCapture(ds.getElement());
 }
 protected int checkLeftBounds(int proposedLeft,
 DragSource dragSource) {
 // Adjust the left edge of the dragSource if it's outside
 // the bounds of it's parent panel
 AbsolutePanel panel =
 (AbsolutePanel) dragSource.getParent();
 int dragSourceWidth = dragSource.getOffsetWidth();
 int panelWidth = panel.getOffsetWidth();
 int nextLeft = proposedLeft;
 if (proposedLeft + dragSourceWidth > panelWidth)
 nextLeft = panelWidth - dragSourceWidth;
 nextLeft = nextLeft < 0 ? 0 : nextLeft;
 return nextLeft;
 }
 protected int checkTopBounds(
 // Adjust the top edge of the dragSource if it's outside
 // the bounds of it's parent panel
 int proposedTop, DragSource dragSource) {
 AbsolutePanel panel =
 (AbsolutePanel) dragSource.getParent();
 int dragSourceHeight = dragSource.getOffsetHeight();
 int panelHeight = panel.getOffsetHeight();
 int nextRight = proposedTop;
 if (proposedTop + dragSourceHeight > panelHeight)
 nextRight = panelHeight - dragSourceHeight;
 nextRight = nextRight < 0 ? 0 : nextRight;
 return nextRight;
 }
}

This class knows nothing about drag sources or drop targets; all it does is drag widgets. Most of the logic consists of basic math that calculates the next position of a widget and checks boundaries to make sure the widget does not escape its enclosing absolute panel.

The interesting parts of the class are the calls to DOM.setCapture() and DOM.releaseCapture(), in onMouseDown() and onMouseUp(), respectively. DOM.setCapture() captures all mouse events and makes them available only to the widget that it is passed until DOM.releaseCapture() is invoked, returning event handling to normal. That provides a significant boost to performance while a widget is being dragged, which gives us time to make sophisticated calculations, like those in the DragSourceListener class, listed in Listing 6.15.

One other interesting thing about the AbstractMouseDragger class: It's abstract because it defines two abstract methods that can be implemented by subclasses to plug in a different dragging algorithm. Those methods—getNextLeft() and getNextTop()—are passed proposed locations that follow the mouse and return final locations for the current mouse movement. Those methods can be implemented by subclasses for specialized dragging, such as dragging widgets only in the horizontal or vertical directions. One of those subclasses is the FollowsMouseDragger class, listed in Listing 6.14, which follows the mouse but restricts the widget being dragged to the bounds of its enclosing absolute panel by invoking the inherited methods checkLeftBounds() and checkTopBounds().

Listing 6.14 com.gwtsolutions.components.client.ui.dnd.FollowsMouseDragger

package com.gwtsolutions.components.client.ui.dnd;

The DragSourceListener class, which makes callbacks to drag sources and drop targets as a widget is dragged, is listed in Listing 6.15.

Listing 6.15 com.gwtsolutions.components.client.ui.dnd.DragSourceListener

package com.gwtsolutions.components.client.ui.dnd;
 import com.google.gwt.user.client.DOM;
 import com.google.gwt.user.client.Event;
 import com.google.gwt.user.client.EventPreview;
 import com.google.gwt.user.client.ui.AbsolutePanel;
 import com.google.gwt.user.client.ui.MouseListenerAdapter;
 import com.google.gwt.user.client.ui.Widget;
 import com.google.gwt.user.client.ui.WidgetCollection;
import com.gwtsolutions.components.client.ui.Point;
import java.util.Iterator;
public class DragSourceListener extends MouseListenerAdapter {
 private final Point[] dsCorners = new Point[4];
 private final WidgetCollection dropTargets =
 new WidgetCollection(null);
 // The following event preview prevents the browser
 // from reacting to mouse drags as the user drags
 // drag sources
 private static EventPreview preventDefaultMouseEvents =
 new EventPreview() {
 public boolean onEventPreview(Event event) {
 switch (DOM.eventGetType(event)) {
 case Event.ONMOUSEDOWN:
 case Event.ONMOUSEMOVE:
 DOM.eventPreventDefault(event);
 }
 return true;
 }
 };
 public void onMouseEnter(Widget sender) {
 // Prevent the browser from reacting to mouse
 // events once the cursor enters the drag source
 DOM.addEventPreview(preventDefaultMouseEvents);
 }
 public void onMouseLeave(Widget sender) {
 // Restore browser event handling when the cursor
 // leaves the drag source
 DOM.removeEventPreview(preventDefaultMouseEvents);
 }
 public void onMouseDown(Widget sender, int x, int y) {
 // All drag sources must have an AbsolutePanel for a
 // parent. This restriction is enforced in the
 // drag source's onLoad method
 AbsolutePanel parent = (AbsolutePanel)sender.getParent();
 Iterator widgetIterator = parent.iterator();
 // Iterate over the parent's widgets and put all
 // drop targets in the dropTargets widget collection
 // for future reference (see intersectsDropTarget(),
 // implemented below)
 while (widgetIterator.hasNext()) {
 Widget w = (Widget) widgetIterator.next();
 if (w instanceof DropTarget) {
 dropTargets.add(w);
 }
 }
 // Set the original location of the drag source in
 // case the drag source is dropped outside any drop
 // targets or is dropped on a drop target that rejects
 // the drag source
 DragSource ds = (DragSource) sender;
 ds.setOriginalLocation(new Point(parent.getWidgetLeft(ds),
 parent.getWidgetTop(ds)));
 // Notify the drag source that a drag has been
 // initiated
 ds.dragStarted();
 }
 public void onMouseMove(Widget sender, int x, int y) {
 DragSource ds = (DragSource) sender;
 if (!ds.isDragging()) {
 // Don't do anything if the drag source is
 // not being dragged
 return;
 }
 Widget dsWidget = ds.getWidget();
 DropTarget dt = intersectsDropTarget(dsWidget);
 // If the drag source intersects a drop target...
 if (dt != null) {
 // ...and if the drag source just entered
 // the drop target...
 if (ds.getEnclosingDropTarget() == null) {
 // ...set the enclosing drop target and
 // notify the drop target that the drag source
 // has entered
 ds.setEnclosingDropTarget(dt);
 dt.dragSourceEntered(ds);
 }
 }
 // If the drag source is not intersecting a drop
 // target...
 else {
 DropTarget enclosingDropTarget =
 ds.getEnclosingDropTarget();
 // ...and the drag source was inside a drop target
 // previously...
 if (enclosingDropTarget != null) {
 // ...set the enclosing drop target to null
 // and notify the drop target that the drag
 // source has exited
 ds.setEnclosingDropTarget(null);
 enclosingDropTarget.dragSourceExited(ds);
 }
 }
 }
 public void onMouseUp(Widget sender, int x, int y) {
 DragSource ds = (DragSource) sender;
 Widget dsWidget = ds.getWidget();
 if (!ds.isDragging()) {
 // If the drag source is not being dragged,
 // do nothing
 return;
 }
 DropTarget dt = intersectsDropTarget(dsWidget);
 if (dt != null) {
 // If the drag source intersects a drop target,
 // notify the drop target that the drag source
 // was dropped
 dt.dragSourceDropped(ds);
 }
 else {
 // If the drag source doesn't intersect a drop
 // target, notify the drag source that it was
 // dropped outside of any drop target
 ds.droppedOutsideDropTarget();
 }
 }
 private DropTarget intersectsDropTarget(Widget dsWidget) {
 // Iterate over the collection of drop targets in the
 // drag source's enclosing panel and see if the drag
 // source intersects any of those drop targets; if so,
 // return that drop target
 Iterator it = dropTargets.iterator();
 while (it.hasNext()) {
 DropTarget dt = (DropTarget) it.next();
 int dtLeft = dt.getAbsoluteLeft();
 int dtTop = dt.getAbsoluteTop();
 int dtWidth = dt.getOffsetWidth();
 int dtHeight = dt.getOffsetHeight();
 int dsLeft = dsWidget.getAbsoluteLeft();
 int dsTop = dsWidget.getAbsoluteTop();
 int dsWidth = dsWidget.getOffsetWidth();
 int dsHeight = dsWidget.getOffsetHeight();
 dsCorners[0] = new Point(dsLeft, dsTop);
 dsCorners[1] = new Point(dsLeft + dsWidth, dsTop);
 dsCorners[2] =
 new Point(dsLeft + dsWidth, dsTop + dsHeight);
 dsCorners[3] = new Point(dsLeft, dsTop + dsHeight);
 for (int i = 0; i < dsCorners.length; ++i) {
 int x = dsCorners[i].x;
 int y = dsCorners[i].y;
 if (x > dtLeft && x < dtLeft + dtWidth && y > dtTop
 && y < dtTop + dtHeight) {
 return dt;
 }
 }
 }
 return null;
 }
}

This is where most of the heavy lifting in the dnd module occurs. On a mouse down event, onMouseDown() finds all the drop targets in the drag source's enclosing absolute panel and stores them in an instance of WidgetCollection for further reference. That method also stores the drag source's location and invokes its startDragging method.

When the drag source is dragged, onMouseMove() checks to see if the drag source intersects one of the drop targets discovered in onMouseDown(); if so, it sets the drag source's enclosingDropTarget property and informs the drop target that a drag source has entered. If the drag source does not intersect a drop target but currently has an enclosing drop target, the listener informs the drop target that the drag source has exited and sets the drag source's enclosingDropTarget property to null.

When a drag source is dropped, either inside or outside a drop target, onMouseUp() informs both the drag source and drop target of the event.

Finally, notice that in onMouseEnter(), we call GWT's DOM.addEventPreview method to add an event preview to the top of the JavaScript event stack to prevent the browser from reacting to mouse drags. If we don't do that, then when a user drags an image, the browser will drag around an outline of the image as the user drags the mouse. It will not drag the image itself. Without that event preview, our drag and drop turns into mush (you might want to try removing the event preview and see the results for yourself). Subsequently, onMouseLeave() removes the event preview so that event handling returns to normal. See "Overriding a Pop-Up Panel's Default Event Handling Behavior" (page 211) for a more in-depth discussion of DOM.addEventPreview() and DOM.eventPreventDefault().

com.google.gwt.user.client.ui.Widget

getParent()
Returns the widget's parent widget. This method returns null for the root panel and for widgets whose DOM elements have not yet been added to the DOM tree.

One final detail of our drag-and-drop module: The DragSourceListener class uses instances of the Component module's Point class, which is listed in Listing 6.16.

Listing 6.16 com.gwtsolutions.components.client.ui.Point

Stuff We Covered in This Solution

GWT gives us all the tools we need to achieve drag and drop, and now that you have the code discussed in this solution, you don't have to do it yourself. With that code in hand, it's easy to use drag and drop in your own applications by developing the appropriate drag sources and drop targets, which can enclose any GWT widget, and then adding them to an absolute panel.

Apart from drag and drop itself, we've also explored some interesting corners of GWT, such as creating a GWT module to encapsulate reusable code, changing a widget's cursor, capturing and releasing events for a specific widget, and using event previews to inhibit the browser's reactions to events. That knowledge will come in handy as you create your own components, whether or not they are related to drag and drop.