1 // ==========================================================================
  2 // Project:   SproutCore - JavaScript Application Framework
  3 // Copyright: ©2006-2011 Strobe Inc. and contributors.
  4 //            Portions ©2008-2011 Apple Inc. All rights reserved.
  5 // License:   Licensed under MIT license (see license.js)
  6 // ==========================================================================
  7 
  8 sc_require('system/drag') ;
  9 
 10 /** @namespace
 11   The `SC.DragSourceProtocol` protocol defines the properties and methods that you may implement in
 12   your drag source objects in order to access additional functionality of SproutCore's drag support.
 13 
 14   If you implement the `SC.DragSourceProtocol` protocol on your drag's source, it will receive a
 15   series of callbacks throughout the course of the drag, and be consulted about what operations to
 16   allow on a particular candidate drop target. Note that when you initiate a drag you must also
 17   provide an object implementing `SC.DragDataSourceProtocol`, which includes some *required*
 18   methods. A single object may serve as both the drag's source and its data source.
 19 
 20   *Note: Do not mix `SC.DragSourceProtocol` into your classes. As a protocol, it exists only for
 21   reference sake. You only need define any of the properties or methods listed below in order to use
 22   this protocol.*
 23 */
 24 SC.DragSourceProtocol = {
 25 
 26   /**
 27     Return a bitwise OR'd mask of the drag operations allowed on the
 28     specified target.  If you don't care about the target, just return a
 29     constant value. If a drag's source does not implement this method,
 30     it will assume that any drag operation (SC.DRAG_ANY) is allowed.
 31 
 32     @param {SC.Drag} drag The SC.Drag instance managing this drag.
 33     @param {SC.View} dropTarget The proposed target of the drop.
 34   */
 35   dragSourceOperationMaskFor: function(drag, dropTarget) {
 36     return SC.DRAG_ANY;
 37   },
 38 
 39   /**
 40     If this property is set to `NO` or is not implemented, then the user may
 41     modify the drag operation by changing the modifier keys they have
 42     pressed.
 43 
 44     @type Boolean
 45     @default NO
 46   */
 47   ignoreModifierKeysWhileDragging: NO,
 48 
 49   /**
 50     This method is called when the drag begins. You can use this to do any
 51     visual highlighting to indicate that the receiver is the source of the
 52     drag.
 53 
 54     @param {SC.Drag} drag The Drag instance managing this drag.
 55     @param {Point} loc The point in *window* coordinates where the drag
 56       began.  You can use convertOffsetFromView() to convert this to local
 57       coordinates.
 58   */
 59   dragDidBegin: function(drag, loc) {},
 60 
 61   /**
 62     This method is called whenever the drag image is moved.  This is
 63     similar to the `dragUpdated()` method called on drop targets.
 64 
 65     @param {SC.Drag} drag The Drag instance managing this drag.
 66     @param {Point} loc  The point in *window* coordinates where the drag
 67       mouse is.  You can use convertOffsetFromView() to convert this to local
 68       coordinates.
 69   */
 70   dragDidMove: function(drag, loc) {},
 71 
 72   /**
 73     This method is called if the drag ends and is successfully handled by a
 74     drop target (i.e. the drop target returns any operation other than
 75     SC.DRAG_NONE).
 76 
 77     @param {SC.Drag} drag The drag instance managing the drag.
 78     @param {Point} loc The point in WINDOW coordinates where the drag
 79       ended.
 80     @param {DragOp} op The drag operation that was performed. One of
 81       SC.DRAG_COPY, SC.DRAG_MOVE, or SC.DRAG_LINK.
 82   */
 83   dragDidSucceed: function(drag, loc, op) {},
 84 
 85   /**
 86     This method is called if the drag ends without being handled, or if a drop
 87     target handles it but returns SC.DRAG_NONE.
 88 
 89     @param {SC.Drag} drag The drag instance managing the drag.
 90     @param {Point} loc The point in WINDOW coordinates where the drag
 91       ended.
 92     @param {DragOp} op Provided for consistency. Always SC.DRAG_NONE.
 93   */
 94   dragDidCancel: function(drag, loc, op) {},
 95 
 96   /**
 97     This method is called when the drag ended, regardless of whether it succeeded
 98     or not. You can use this to do any cleanup.
 99 
100     @param {SC.Drag} drag The drag instance managing the drag.
101     @param {Point} loc The point in WINDOW coordinates where the drag
102       ended.
103     @param {DragOp} op The drag operation that was performed. One of
104       SC.DRAG_COPY, SC.DRAG_MOVE, SC.DRAG_LINK, or SC.DRAG_NONE.
105   */
106   dragDidEnd: function(drag, loc, op) {},
107 
108   /**
109     If a drag is canceled or not handled, and has its slideBack property set
110     to YES, then the drag's ghost view will slide back to its initial location.
111     dragDidEnd is called immediately upon mouseUp; dragSlideBackDidEnd is called
112     after the slide-back animation completes.
113 
114     @param {SC.Drag} drag The drag instance managing the drag.
115   */
116   dragSlideBackDidEnd: function(drag) {}
117 
118 };
119