Dragging

From Emitrom

Back to Index

---

Contents 1 Drag related attributes 1.1 draggable 1.2 dragConstraint 1.3 dragBounds 2 DragConstraintEnforcer 3 Drag Events 4 DragContext

Drag related attributes

Shapes and Groups have the following attributes that allow them to be dragged and that control how they can be dragged.

draggable

Whether the node can be dragged. Default: false.

dragConstraint

Whether the node can only be dragged horizontally (HORIZONTAL), vertically (VERTICAL) or in both directions (NONE). Default: NONE.

DragConstraint Javadoc Drag Constraints demo Slider demo

dragBounds

Restricts the node's location to a rectangular region. Default: null (no restrictions.)

Slider demo DragBounds Javadoc

Example:

Circle c = new Circle(20);
c.setDraggable(true);
c.setDragConstraint(DragContraint.HORIZONTAL);
c.setDragBounds(new DragBounds(x1, y1, x2, y2));

DragConstraintEnforcer

If you need more exotic drag behavior, you can override the getDragContraints method (in Shape or Group) and return your own DragConstraintEnforcer. The default DragConstraintEnforcer enforces the rules defined by the dragBounds and dragConstraint attributes.

DragConstraintEnforcer must implement two methods:

• void startDrag(DragContext dragContext)
• void adjust(Point2D dxy)

startDrag is called when the drag operation starts. It receives the DragContext which contains all the info you may need. adjust is called after every drag move event. It receives the difference between the location where the drag started (i.e. initial mouse click or touch event) and the current location as a Point2D with (dx,dy) in "local coordinates". To restrict the node's movement, simply adjust (dx,dy) of the specified Point2D. (See DragContext below for details.)

See Custom Drag Constraints demo for some examples, e.g. snapping to a grid, restricting the location to a set of fixed points and restricting the location to a circular region.

Note that the API related to dragging is still in flux. We intend to add setDragConstraints (so that you don't have to override getDragConstraints), add more drag constraint primitives and make them serializable. We may also refactor the dragBounds and dragConstraint properties and integrate them with this mechanism.

DragConstraintEnforcer Javadoc Custom Drag Constraints demo

Drag Events

To listen for drag events, register one or more drag event handlers on a Node:

• addNodeDragStartHandler - receives NodeDragStartEvent
• addNodeDragMoveHandler - receives NodeDragMoveEvent
• addNodeDragEndHandler - receives NodeDragEndEvent

The drag events contain drag related information via the DragContext.

Draggable Shapes demo Mouse Event demo

DragContext

The DragContext maintains information during a Drag operation of a Node.

Some values are defined in "global coordinates" (a.k.a. "canvas coordinates" or "viewport coordinates"), e.g. the raw canvas event (x,y) values are defined in pixels relative to the top-left corner of the canvas.

On the other hand, "local coordinates" are specific to a node's parent. E.g. the X,Y location of a node is defined relative to the top-left corner of the parent node.

To convert between local and global coordinates, you'd need to concatenate the Transform of the nodes ancestors, all the way down to the parent node (see DragContext.getLocalToGlobal). Converting from global to local coordinates requires the inverse of that Transform (see DragContext.getGlobalToLocal.)

Function	Meaning
getDragStartX getDragStartY	Returns the (x,y) coordinates at the start of the drag operation (in global/canvas coordinates.)
getEventX getEventY	Returns the (x,y) of the last drag move (in global/canvas coordinates.)
getDx getDy	Returns (dx,dy) between dragStart coordinates and current event coordinates (i.e. (eventX - dragstartX, eventY - dragStartY) in global/canvas coordinates.)
getGlobalToLocal	Returns the Transform that can be used to convert global/canvas coordinates to local coordinates (i.e. within the context of the node's parent.) This is the inverse of the localToGlobal transform.
getLocalToGlobal	Returns the Transform that can be used to convert local coordinates (i.e. within the context of the node's parent) to global/canvas coordinates. This is the inverse of the globalToLocal transform.
getLocalAdjusted	Returns (dx,dy) in local coordinates, adjusted by the DragConstraintEnforcer.
getNode	Returns the node being dragged as an IPrimitive.
getDragConstraints	Returns the DragConstraintEnforcer that adjusts the node location during a drag operation.

DragContext Javadoc