RasterMouse.startDrag( event [, value [, data [, mouseListener [, disableIECapture]]]] )
Starts a drag operation. This method must be called within mousedownevent 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.
Parameters
| 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. |
Returns
| 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. |