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
- SC.DropTargetProtocol.isDropTarget
Class Methods
- acceptDragOperation(drag, op)
- computeDragOperations(drag, evt, op)
- dragEnded(drag, evt)
- dragEntered(drag, evt)
- dragExited(drag, evt)
- dragStarted(drag, evt)
- dragUpdated(drag, evt)
- performDragOperation(drag, op)
Field Detail
SC.DropTargetProtocol.isDropTarget BooleanMust 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
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.
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
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.
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
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.
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.
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.
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