RasterMouse.startDrag( event [, value [, data [, mouseListener [, disableIECapture]]]] )

Starts a drag operation. This method must be called within mousedown event handler.

This method starts either a drag or mousemove operation. If a mousemove type of operation is desired, a custom mouseListener must be specified. The mouseListener will have the following signature:
function myMouseMoveListener( rasterMouseEvent )
    // ...
Once the mousemove operation starts, the mouseListener function is called each time the mouse moves until the user release the mouse button, or RasterMouse.cancelDrag() is invoked. The argument sent to the mouseListener function is of type RasterMouseEvent.

If a mouseListener is not specified, a drag operation is started. As the mouse moves over the RasterControl objects, their respective drop handlers (if any) are fired. Note the RasterControl.setDropHandler() method is used to specify a drop handler function for any user-defined custom control.

At any time during a mouse move or drag operation, the RasterMouse.cancelDrag() can be invoked to stop the operation. Note that RasterMouse.cancelDrag() is automatically invoked if the end-user press the ESC key.

The disableIECapture is a IE-only feature. This argument is defaulted to false, unless explicitly changed. Mouse "capture" enables IE to keep firing all mousemove and mouseup events even if the mouse goes outside the browser window. This is the default mode used by startDrag. However, there are instances where "capture" is not desired. In mouse capture mode, the mouse pointer is fixed at the time the mouse capture operation starts, preventing IE from updating the mouse pointer when moving over elements using CSS cursor styles. If CSS cursor "hover styles" are important, set disableIECapture to true. Note that in non-capture mode, drag and mouse move operations are cancelled if the mouse leaves the browser window. This prevents drag and mouse move operation from "sticking" in cases where the user leaves the window, release the mouse button, and enters back.


Name Type   Description
event object Event object received in the mousedown or click event.
value any optional Value being dragged. This property is used to store the value you wish to pass along to other controls in a drag and drop operation: anything from a simple int or string to a complex object. Set to null if not needed.
data object optional Free-format data structure used to store meta data needed during a mousemove operation. For example, if you are dragging a circle inside a rectangle, you can pre-compute the min/max values the circle is allow to move without going outside the rectangle and save them in the data property. Then, all that your mousemove event has to do is validate against the values stored in the RasterMouseEvent.data property, rather than recomputing these values in each event occurence. This object persists for the duration of the drag operation. Set to null if not needed.
mouseListener function optional User-defined handler to be notified of mouse move events. Set to null if not needed.
disableIECapture boolean optional set to true to disable IE mouse capture. In IE, when the mouse is not captured the mouse stop responding once it goes out of the browser window.


Type Description
object The RasterMouseEvent resulting from starting a drag operation. This is the same object that will be passed along to other drop and mouse listeners. You may use this object to initialize the RasterMouseEvent.context if desired.

See Also

Home Examples Download License
Copyright © 2010-2017 Edwin R. López