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.DropTargetProtocol` protocol defines the properties and methods that you may implement 12 in your views in order to act as a drop target for a drag. 13 14 The general call sequence for all drop targets is (in pseudo-Ragel, regex format): 15 16 dragStarted 17 ( 18 computeDragOperations+ 19 ( 20 dragEntered 21 dragUpdated 22 ( computeDragOperations | dragUpdated )* 23 ( acceptDragOperation performDragOperation? )? // mouseUp 24 dragExited 25 )* 26 )* 27 dragEnded 28 29 Thus, every drop target will have its `dragStarted` and `dragEnded` methods called once during 30 every drag session. `computeDragOperations`, if called at all, may be called more than once before 31 the `dragEntered` method is called. Once `dragEntered` is called, you are guaranteed that both 32 `dragUpdated` and `dragExited` will be called at some point, followed by either `dragEnded` or 33 additional `computeDragOperation` calls. 34 35 *Note: Do not mix `SC.DropTargetProtocol` into your classes. As a protocol, it exists only for 36 reference sake. You only need define any of the properties or methods listed below in order to use 37 this protocol.* 38 */ 39 SC.DropTargetProtocol = { 40 41 /** 42 Must be true when your view is instantiated. 43 44 Drop targets must be specially registered in order to receive drop 45 events. SproutCore knows to register your view when this property 46 is true on view creation. 47 48 @type Boolean 49 @default YES 50 @constant 51 */ 52 isDropTarget: YES, 53 54 /** 55 Called when the drag is started, regardless of where or not your drop 56 target is current. You can use this to highlight your drop target 57 as "eligible". 58 59 The default implementation does nothing. 60 61 @param {SC.Drag} drag The current drag object. 62 @param {SC.Event} evt The most recent mouse move event. Use to get location 63 */ 64 dragStarted: function(drag, evt) {}, 65 66 /** 67 Called when the drag first enters the droppable area, if it returns a 68 drag operations other than `SC.DRAG_NONE`. 69 70 The default implementation does nothing. 71 72 @param drag {SC.Drag} The current drag object. 73 @param evt {SC.Event} The most recent mouse move event. Use to get location 74 */ 75 dragEntered: function(drag, evt) {}, 76 77 /** 78 Called periodically when a drag is over your droppable area. 79 80 Override this method this to update various elements of the drag state, 81 including the location of ghost view. You should use this method to 82 implement snapping. 83 84 This method will be called periodically, even if the user is not moving 85 the drag. If you perform expensive operations, be sure to check the 86 mouseLocation property of the drag to determine if you actually need to 87 update anything before doing your expensive work. 88 89 The default implementation does nothing. 90 91 @param {SC.Drag} drag The current drag object. 92 @param {SC.Event} evt The most recent mouse move event. Use to get location 93 */ 94 dragUpdated: function(drag, evt) {}, 95 96 /** 97 Called when the user exits your droppable area or the drag ends 98 and you were the last targeted droppable area. 99 100 Override this method to perform any clean up on your UI such as hiding 101 a special highlight state or removing insertion points. 102 103 The default implementation does nothing. 104 105 @param {SC.Drag} drag The current drag object 106 @param {SC.Event} evt The most recent mouse move event. Use to get location. 107 */ 108 dragExited: function(drag, evt) {}, 109 110 /** 111 Called on all drop targets when the drag ends. 112 113 For example, the user might have dragged the view off the screen and let 114 go or they might have hit escape. Override this method to perform any 115 final cleanup. This will be called instead of dragExited. 116 117 The default implementation does nothing. 118 119 @param {SC.Drag} drag The current drag object 120 @param {SC.Event} evt The most recent mouse move event. Use to get location. 121 */ 122 dragEnded: function(drag, evt) {}, 123 124 /** 125 Called when the drag needs to determine which drag operations are 126 valid in a given area. 127 128 Override this method to return an OR'd mask of the allowed drag 129 operations. If the user drags over a droppable area within another 130 droppable area, the drag will latch onto the deepest view that returns one 131 or more available operations. 132 133 The default implementation returns `SC.DRAG_NONE` 134 135 @param {SC.Drag} drag The current drag object 136 @param {SC.Event} evt The most recent mouse move event. Use to get 137 location 138 @param {DragOp} op The proposed drag operation. A drag constant 139 140 @returns {DragOps} A mask of all the drag operations allowed or 141 SC.DRAG_NONE 142 */ 143 computeDragOperations: function(drag, evt, op) { 144 return SC.DRAG_NONE; 145 }, 146 147 /** 148 Called when the user releases the mouse. 149 150 This method gives your drop target one last opportunity to choose to 151 accept the proposed drop operation. You might use this method to 152 perform fine-grained checks on the drop location, for example. 153 Return true to accept the drop operation. 154 155 The default implementation returns `YES`. 156 157 @param {SC.Drag} drag The drag instance managing this drag 158 @param {DragOp} op The proposed drag operation. A drag constant 159 160 @return {Boolean} YES if operation is OK, NO to cancel. 161 */ 162 acceptDragOperation: function(drag, op) { 163 return YES; 164 }, 165 166 /** 167 Called to actually perform the drag operation. 168 169 Override this method to actually perform the drag operation. This method 170 is only called if you returned `YES` in `acceptDragOperation()`. 171 172 Return the operation that was actually performed or `SC.DRAG_NONE` if the 173 operation was aborted. 174 175 The default implementation returns `SC.DRAG_NONE` 176 177 @param {SC.Drag} drag The drag instance managing this drag 178 @param {DragOp} op The proposed drag operation. A drag constant. 179 180 @return {DragOp} Drag Operation actually performed 181 */ 182 performDragOperation: function(drag, op) { 183 return SC.DRAG_NONE; 184 } 185 186 }; 187