Protocol: SC.DropTargetProtocol

The SC.DropTargetProtocol protocol defines the properties and methods that you may implement in your views in order to act as a drop target for a drag.

The general call sequence for all drop targets is (in pseudo-Ragel, regex format):

dragStarted
(
  computeDragOperations+
  (
    dragEntered
    dragUpdated
    ( computeDragOperations | dragUpdated )*
    ( acceptDragOperation performDragOperation? )? // mouseUp
    dragExited
  )*
)*
dragEnded

Thus, every drop target will have its dragStarted and dragEnded methods called once during every drag session. computeDragOperations, if called at all, may be called more than once before the dragEntered method is called. Once dragEntered is called, you are guaranteed that both dragUpdated and dragExited will be called at some point, followed by either dragEnded or additional computeDragOperation calls. Note: Do not mix SC.DropTargetProtocol into your classes. As a protocol, it exists only for reference sake. You only need define any of the properties or methods listed below in order to use this protocol.*

Defined in: drop_target_protocol.js

Field Summary

Class Methods

Field Detail

SC.DropTargetProtocol.isDropTarget Boolean

Must be true when your view is instantiated.

Drop targets must be specially registered in order to receive drop events. SproutCore knows to register your view when this property is true on view creation.

Default value:
YES

Class Method Detail

acceptDragOperation(drag, op)

Called when the user releases the mouse.

This method gives your drop target one last opportunity to choose to accept the proposed drop operation. You might use this method to perform fine-grained checks on the drop location, for example. Return true to accept the drop operation.

The default implementation returns YES.

Parameters:
drag SC.Drag
The drag instance managing this drag
op DragOp
The proposed drag operation. A drag constant
Returns:
Boolean
YES if operation is OK, NO to cancel.
computeDragOperations(drag, evt, op)

Called when the drag needs to determine which drag operations are valid in a given area.

Override this method to return an OR'd mask of the allowed drag operations. If the user drags over a droppable area within another droppable area, the drag will latch onto the deepest view that returns one or more available operations.

The default implementation returns SC.DRAG_NONE

Parameters:
drag SC.Drag
The current drag object
evt SC.Event
The most recent mouse move event. Use to get location
op DragOp
The proposed drag operation. A drag constant
Returns:
DragOps

A mask of all the drag operations allowed or SC.DRAG_NONE

dragEnded(drag, evt)

Called on all drop targets when the drag ends.

For example, the user might have dragged the view off the screen and let go or they might have hit escape. Override this method to perform any final cleanup. This will be called instead of dragExited.

The default implementation does nothing.

Parameters:
drag SC.Drag
The current drag object
evt SC.Event
The most recent mouse move event. Use to get location.
dragEntered(drag, evt)

Called when the drag first enters the droppable area, if it returns a drag operations other than SC.DRAG_NONE.

The default implementation does nothing.

Parameters:
drag
{SC.Drag} The current drag object.
evt
{SC.Event} The most recent mouse move event. Use to get location
dragExited(drag, evt)

Called when the user exits your droppable area or the drag ends and you were the last targeted droppable area.

Override this method to perform any clean up on your UI such as hiding a special highlight state or removing insertion points.

The default implementation does nothing.

Parameters:
drag SC.Drag
The current drag object
evt SC.Event
The most recent mouse move event. Use to get location.
dragStarted(drag, evt)

Called when the drag is started, regardless of where or not your drop target is current. You can use this to highlight your drop target as "eligible".

The default implementation does nothing.

Parameters:
drag SC.Drag
The current drag object.
evt SC.Event
The most recent mouse move event. Use to get location
dragUpdated(drag, evt)

Called periodically when a drag is over your droppable area.

Override this method this to update various elements of the drag state, including the location of ghost view. You should use this method to implement snapping.

This method will be called periodically, even if the user is not moving the drag. If you perform expensive operations, be sure to check the mouseLocation property of the drag to determine if you actually need to update anything before doing your expensive work.

The default implementation does nothing.

Parameters:
drag SC.Drag
The current drag object.
evt SC.Event
The most recent mouse move event. Use to get location
performDragOperation(drag, op)

Called to actually perform the drag operation.

Override this method to actually perform the drag operation. This method is only called if you returned YES in acceptDragOperation().

Return the operation that was actually performed or SC.DRAG_NONE if the operation was aborted.

The default implementation returns SC.DRAG_NONE

Parameters:
drag SC.Drag
The drag instance managing this drag
op DragOp
The proposed drag operation. A drag constant.
Returns:
DragOp
Drag Operation actually performed
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)