sproutcore 0.9.0

data/frameworks/sproutcore/drag/drag.js

@@ -0,0 +1,549 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('Core') ;
+require('views/view') ;
+
+SC.DRAG_LINK = 0x0004; SC.DRAG_COPY = 0x0001; SC.DRAG_MOVE = 0x0002;
+SC.DRAG_NONE = 0x0000; SC.DRAG_ANY = 0x0007 ;
+
+/**
+
+  @class
+  
+  An instance of this object is created whenever a drag occurs.  The instance
+  manages the mouse events and coordinating with droppable targets until the
+  user releases the mouse button. 
+
+  To initiate a drag, you should call SC.Drag.start() with the options below
+  specified in a hash. Pass the ones you need to get the drag you want:  
+   
+  {{{
+   event: (req)
+     The mouse event that triggered the drag.  This will be used to 
+     position the element.
+  
+   source: (req)
+     The drag source object that should be consulted during the drag operations.
+     This is usually the container view that initiated the drag.
+  
+   dragView: (req)
+     This should point to a view that will be used as the source image for 
+     the drag. The drag operation will clone the DOM elements for this 
+     view and add the class name 'drag-image' to the outermost element.
+  
+   ghost:  YES | NO
+     if YES or not passed, then drag view image will show, but the source
+     dragView will not be hidden.  set to NO to make it appear that the
+     dragView itself is being dragged around.
+  
+   slideBack: YES | NO
+     If YES or not specified, then if the drag operation is cancelled, the
+     dragView will slide back to its source origin.
+  
+   origin:
+     If passed, this will be used as the origin point for the ghostView
+     when it slides back.  You normally do not need to pass this unless
+     the ghost view does not appear in the main UI.
+  
+   data:
+     Optional hash of data types and values.  You can use this to pass a
+     static set of data instead of providing a dataSource.  If you provide
+     a dataSource, it will override this.
+  
+   dataSource:
+     Optional object that will provide the data for the drag to be consumed
+     by the drop target.  If you do not pass this parameter or the data 
+     hash, then the source object will be used if it implements the
+     SC.DragDataSource protocol.
+  
+   anchorView:
+     if you pass this optional view, then the drag will only be allowed to
+     happen within this view.  The ghostView will actually be added as a
+     child of this view during the drag.  Normally the anchorView is the
+     window.
+   }}}
+   
+  @extends SC.Object
+*/
+SC.Drag = SC.Object.extend(
+/** @scope SC.Drag.prototype */
+{
+  /** [RO] The source object used to coordinate this drag. */  
+  source: null,
+
+  /**  The actual image being dragged around the screen.  
+  
+    This is created automatically from the dragView.
+  */
+  ghostView: null,
+
+  /**  
+    The view that was used as the source of the ghostView.  
+    
+    The drag view is not moved from its original location during a drag.
+    Instead, the DOM content of the view is cloned and managed by the 
+    ghostView.  If you want to visually indicate that the view is being 
+    movied, you may want to temporarily hide it during the drag.
+  */
+  dragView: null,
+  
+  /**  
+    If YES, the dragView is automatically hidden while dragging around the ghost.
+  */
+  ghost: YES,
+  
+  /**
+    If YES, then the ghostView will slide back to its original location if drag is cancelled.
+  */
+  slideBack: YES,
+  
+  /**  The original mouse down event. */
+  mouseDownEvent: null,
+
+  /**  
+    The origin to slide back to in the coordinate of the dragView's offsetParent.
+  */
+  ghostOffset: { x: 0, y: 0 },
+  
+  /**
+    The current location of the mouse pointer in window coordinates.  
+  
+    This is updated as long as the mouse button is pressed.
+  */
+  location: null,
+
+  // ..........................................
+  // DRAG DATA
+  //
+
+  /**
+    (Property) Data types supported by this drag operation.
+    
+    Returns an array of data types supported by the drag source.  This may 
+    be generated dynamically depending on the data source.
+
+    If you are implementing a drag source, you will need to provide these data
+    types so that drop targets can detect if they can accept your drag data.
+    
+    If you are implementing a drop target, you should inspect this property
+    on your dragEntered() and prepareForDragOperation() methods to determine 
+    if you can handle any of the data types offered up by the drag source.
+    
+    @returns {Array} available data types
+  */
+  dataTypes: function() {
+    
+    // first try to use the data source.
+    if (this.dataSource) return this.dataSource.get('dragDataTypes') ;
+    
+    // if that fails, get the keys from the data hash.
+    if (this.data) {
+      var ret = [];
+      for(var key in this._data) {
+        if (this.data.hasOwnProperty(key)) ret.push(key) ;
+      }
+      return key ;
+    }    
+    
+    // if that fails, then check to see if the source object is a dataSource.
+    var source = this.get('source') ;
+    if (source && source.dragDataTypes) return source.get('dragDataTypes') ;
+    
+    // no data types found. :(
+    return [] ; 
+  }.property(),
+  
+  /**
+    Retrieve the data for the specified dataType from the drag source.
+  
+    Drop targets can use this method during their performDragOperation() method
+    to retrieve the actual data provided by the drag data source.  This data
+    may be generated dynamically depending on the data source.
+    
+    @param {Object} dataType data type you want to retrieve.  Should be one of the values returned in the dataTypes property
+    
+    @returns {Object} The generated data.
+  */
+  dataForType: function(dataType) {
+    
+    // first try to use the data Source.
+    if (this.dataSource) {
+      return this.dataSource.dragDataForType(dataType, this) ;
+      
+    // then try to use the data hash.
+    } else if (this.data) {
+      return this.data[dataType];
+      
+    // if all else fails, check to see if the source object is a data source.
+    } else {
+      var source = this.get('source') ;
+      if (source && $type(source.dragDataForType) == T_FUNCTION) {
+        return source.dragDataForType(dataType, this) ;
+        
+      // no data source found. :(
+      } else return null ;
+    }
+  },
+  
+  /**
+    Optional object used to provide the data for the drag.
+
+    Drag source can designate a dataSource object to generate the data for 
+    a drag dynamically.  The data source can and often is the drag source 
+    object itself.  
+
+    Data Source objects must comply with the SC.DragDataSource interface.  If
+    you do not want to implement this interface, you can provide the data 
+    directly with the data property.
+
+    If you are implementing a drop target, use the dataTypes property and 
+    dataForTypes() method to access data instead of working directly with these
+    properties.
+    
+    @type {Object}
+  */
+  dataSource: null,
+
+  /**
+    Optional hash of data.  Used if no dataSource was provided.
+    
+    Drag sources can provide a hash of data when the drag begins instead of 
+    specifying an actual dataSource.  The data is stored in this property.
+    If you are implementing a drop target, use the dataTypes property and 
+    dataForTypes() method to access data instead of working directly with these
+    properties.
+    
+    @type {Object}
+  */
+  data: null,
+
+  // this will actually start the drag process.
+  startDrag: function() {
+    
+    // create the ghost view and position.
+    this._createGhostView() ;
+    
+    // compute the offset from the original mouse location.
+    var origin = this.dragView.convertFrameToView(this.dragView.get('origin'), null);
+    var pointer = Event.pointerLocation(this.event) ;
+    this.ghostOffset = { x: (pointer.x-origin.x), y: (pointer.y-origin.y) };
+
+    // position the ghost view.
+    this._positionGhostView(this.event) ;
+    
+    // notify window a drag is in process. mouseDragged notifications will
+    // go to the drag instead.
+    SC.window.dragDidStart(this) ;
+    
+    if (this.source && this.source.dragDidBegin) {
+      this.source.dragDidBegin(this, pointer) ;
+    }
+  },
+  
+  _lastLoc: {},
+
+  /**  
+    @private
+    
+    This method is called repeatedly during a mouse drag.  It updates the
+    position of the ghost image, then it looks for a current drop target and
+    notifies it.
+  */
+  mouseDragged: function(evt) {
+    // ignore duplicate calls.
+    var loc = Event.pointerLocation(evt) ;
+    if ((loc.x == this._lastLoc.x) && (loc.y == this._lastLoc.y)) return ;
+    this._lastLoc = loc ;
+    this.set('location', loc) ;
+    
+    this._positionGhostView(evt) ;
+    var last = this._lastTarget ;
+
+    // STEP 1: Determine the deepest drop target that allows an operation.
+    // if the drop target selected the last time this method was called differs
+    // from the deepest target found, then go up the chain until we either hit the
+    // last one or find one that will allow a drag operation
+    var target = this._findDropTarget(evt) ; // deepest drop target
+    var op = SC.DRAG_NONE ;
+    while (target && (target != last) && (op == SC.DRAG_NONE)) {
+      
+      // make sure the drag source will permit a drop operation on the named target.
+      // if source does not implement this callback, just assume a drop is allowed
+      // by the source.
+      if (target && this.source && this.source.dragSourceOperationMaskFor) {
+        op = this.source.dragSourceOperationMaskFor(target, this) ;
+      } else op = SC.DRAG_ANY ;
+
+      // now, let's see if the target will accept the drag.  If it does not respond
+      // to dragEntered, then assume NO drag opts.
+      if ((op != SC.DRAG_NONE) && target && target.dragEntered) {
+        op = op & target.dragEntered(this, evt) ;
+      } else op = SC.DRAG_NONE ;
+
+      console.log(SC.Drag.inspectOperation(op)) ;
+      
+      // if DRAG_NONE, then look for the next parent that is a drop zone.
+      if (op == SC.DRAG_NONE) target = this._findNextDropTarget(target) ;
+    }
+
+    // STEP 2: Refocus the drop target.
+    // If a new drop target was found then this part of the method will exit the
+    // last drag target and start the new one.
+    if (target != last) {
+
+      // if the new target does not match the last target, exit that target.
+      if (last && last.dragExited) last.dragExited(this, evt) ;
+
+      if (target && this.source && this.source.dragSourceOperationMaskFor) {
+        op = this.source.dragSourceOperationMaskFor(target, this) ;
+      } else op = SC.DRAG_ANY ;
+
+      // save new op and set target to null if op = DRAG_NONE
+      this.sourceDropOperations = op ;
+      
+      // now notify the new target, if there is one.  Save the allowed drop
+      // operations as the logical AND between the ops allowed by the source
+      // and target.
+      if (target && target.dragEntered) {
+        this.dropOperations = op & target.dragEntered(this, evt) ;
+      } else this.dropOperations = SC.DRAG_NONE ;
+
+      if (this.dropOperations == SC.DRAG_NONE) target = null ;
+    
+    // if nothing has changed, send dragUpdated
+    } else {
+      if (target && target.dragUpdated) target.dragUpdated(this, evt) ;
+    }
+     
+    // notify source that the drag moved.
+    if (this.source && this.source.dragDidMove) {
+      this.source.dragDidMove(this, loc) ;
+    }   
+    
+    this._lastTarget = target ;
+  },
+  
+  /**
+    @private
+    
+    Called when the mouse is released.  Performs any necessary cleanup and
+    executes the drop target protocol to try to complete the drag operation.
+  */
+  mouseUp: function(evt) {
+    var loc = Event.pointerLocation(evt) ;
+
+    // try to have the drop target perform the drop...
+    var target = this._lastTarget ;
+    var op = this.dropOperations;
+    
+    if (target && target.prepareForDragOperation(op, this)) {
+      op = target.performDragOperation(op, this) ;  
+    }
+    
+    // create cleanupFunc.  This function will be called at the end of this
+    // function or after the ghostView slides back to its origin.
+    var drag = this ;
+    var cleanupFunc = function() {
+      if (target) target.concludeDragOperation(op, this) ;  
+      drag._destroyGhostView() ;
+    };
+    
+    // notify drop target.
+    if (target && target.dragEnded) target.dragEnded(this, evt) ;
+    this._lastTarget = null ;
+    
+    // clean up ghost view.  if sldeBack is true, then do the animation.
+    if ((op == SC.DRAG_NONE) && this.get('slideBack')) {
+      var loc = this.dragView.convertFrameToView(this.dragView.get('origin'), null) ;
+      this._ghostView.transitionTo(1.0, 
+        "left: %@px; top: %@px".fmt(loc.x, loc.y), 
+        { duration: 200, onComplete: cleanupFunc }) ;
+        
+    } else cleanupFunc() ;
+    
+    // notify the source that everything has completed.
+    if (this.source && this.source.dragDidEnd) {
+      this.source.dragDidEnd(this, loc, op) ;
+    }
+    
+  },
+  
+  // ..........................................
+  // PRIVATE PROPERTIES AND METHODS
+  //
+  
+  // positions the ghost view underneath the mouse with the initial offset
+  // recorded by when the drag started.
+  _positionGhostView: function(evt) {
+    var loc = { x: Event.pointerX(evt), y: Event.pointerY(evt) } ;
+    loc.x -= this.ghostOffset.x ;
+    loc.y -= this.ghostOffset.y ;
+    this._ghostView.set('origin', loc) ;   
+  },
+  
+  // this will create the ghostView and add it to the main HTML document.
+  // it will also position it underneath the current mouse location.
+  _createGhostView: function() {
+    
+    // create the elements by cloning the dragView.
+    var el = this.dragView.rootElement.cloneNode(true) ;
+    
+    // create the ghost view instance add ghost class name.
+    this._ghostView = this._ghostViewClass.viewFor(el) ;
+    this._ghostView.owner = this ;
+    this._ghostView.addClassName('ghost') ;
+    this._ghostView.set('isPositioned', true) ; // make absolute position.
+    
+    // add to bottom of main document body and to window.
+    SC.window.appendChild(this._ghostView) ;
+  },
+
+  _destroyGhostView: function() {  
+    if (this._ghostView) {
+      this._ghostView.removeFromParent() ;
+      this._ghostView = null ; // this will allow the GC to collect it.
+    }
+  },
+  
+  _ghostView: null,
+  
+  // Return an array of drop targets, sorted with any nested drop targets
+  // at the top of the array.  The first time this method is called during
+  // a drag, it will reconstruct this array using the current set of 
+  // drop targets.  Afterwards it uses the cached set until the drop
+  // completes.
+  //
+  // This means that if you change the view hierarchy of your drop targets
+  // during a drag, it will probably be wrong.
+  _dropTargets: function() {
+    if (this._cachedDropTargets) return this._cachedDropTargets ;
+    var ret = [];
+    
+    // build array of drop targets
+    var dt = SC.Drag._dropTargets ;
+    for(var key in dt) {
+      if (!dt.hasOwnProperty(key)) continue ;
+      ret.push(dt[key]) ;      
+    }
+    
+    // now resort.  This custom function will sort nested drop targets
+    // at the start of the list.
+    ret = ret.sort(function(a,b) {
+      var view = a;
+      while((view = view.parentNode) && (view != SC.window)) {
+        if (b == view) return -1 ;
+      }
+      return 1; 
+    }) ;
+
+    this._cachedDropTargets = ret ;
+    
+    console.log('ret: %@'.fmt(ret.join(','))) ;
+    return ret ;
+  },
+  
+  // This will search through the drop targets, looking for one in the 
+  // target area.
+  _findDropTarget: function(evt) {
+    var dt = this._dropTargets() ;
+    var loc = { x: Event.pointerX(evt), y: Event.pointerY(evt) } ;
+
+    var ret = null ;
+    for(var idx=0;idx<dt.length;idx++) {
+      var t = dt[idx] ;
+      if(!t.get('isVisibleInWindow')) continue ;
+      
+      // get frame, converted to view.
+      var f = t.convertFrameToView(t.get('frame'), null) ;
+      
+      // check to see if loc is inside.  If so, then make this the drop
+      // target unless there is a drop target and the current one 
+      // is not deeper.
+      if (SC.pointInRect(loc, f)) return t;
+    } 
+    return null ;
+  },
+  
+  // Search the parent nodes of the target to find another view matching the drop
+  // target.  Returns null if no matching target is found.
+  _findNextDropTarget: function(target) {
+    while ((target = target.parentNode) && (target != SC.window)) {
+      if (SC.Drag._dropTargets[target._guid]) return target ;
+    }
+    return null ;
+  },
+  
+  _ghostViewClass: SC.View.extend({})   
+  
+}) ;
+
+SC.Drag.mixin(
+/** @scope SC.Drag */
+{
+  
+   
+  /**  
+   This is the method you use to initiate a new drag.  See class documentation 
+   for more info on the options taken by this method.
+   
+   @params {Hash} ops a hash of options.  See documentation above.
+   
+  */
+  start: function(ops) {
+    var ret = this.create(ops) ;
+    ret.startDrag() ;
+    return ret ;
+  },
+  
+  _dropTargets: {},
+  
+  /**
+    Register the view object as a drop target.
+    
+    This method is called automatically whenever a view is created with the
+    isDropTarget property set to YES.  You generally will not need to call it
+    yourself.
+  */
+  addDropTarget: function(target) {
+    this._dropTargets[target._guid] = target ;
+  },
+
+  /**
+    Remove a view from the list of drop targets.
+    
+    This method is called automatically whenever a view is removed from the 
+    hierarchy.  You generally will not need to call it yourself.
+  */
+  removeDropTarget: function(target) {
+    delete this._dropTargets[target._guid] ;
+  },
+
+  /**
+    Convenience method to turn a operation mask into a descriptive string.
+  */
+  inspectOperation: function(op) {
+    var ret = [] ;
+    if (op == SC.DRAG_NONE) {
+      ret = ['DRAG_NONE'];
+    } else if (op == SC.DRAG_ANY) {
+      ret = ['DRAG_ANY'] ;
+    } else {
+      if (op & SC.DRAG_LINK) {
+        ret.push('DRAG_LINK') ;
+      }
+
+      if (op & SC.DRAG_COPY) {
+        ret.push('DRAG_COPY') ;
+      }
+
+      if (op & SC.DRAG_MOVE) {
+        ret.push('DRAG_MOVE') ;
+      }
+    }
+    return ret.join('|') ;
+  }
+
+});

data/frameworks/sproutcore/drag/drag_data_source.js

@@ -0,0 +1,32 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('drag/drag') ;
+
+
+// This mixin can be used to implement a dynamic data source for a drag 
+// operation.  You can return a set of allowed data types and then the 
+// method will be used to actually get data in that format when requested.
+SC.DragDataSource = {
+
+  // Implement this property as an array of data types you want to support
+  // for drag operations.
+  dragDataTypes: [],
+
+  // Implement this method to return the data in the format passed.  Return
+  // null if the requested data type cannot be generated.
+  //
+  //  dataType:
+  //    The proposed dataType to return.  This will always be one of the
+  //    data types declared in dragDataTypes.
+  //
+  //  drag:
+  //    The Drag instance managing this drag.
+  //
+  dragDataForType: function(dataType, drag) { return null; }
+  
+};
+
+

data/frameworks/sproutcore/drag/drag_source.js

@@ -0,0 +1,64 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('drag/drag') ;
+
+// The DataSource protocol is used to dynamically generate multiple types of
+// data from a single object.  You must implement this protocol if you want to
+// provide the data for a drag event.
+SC.DragSource = {
+
+  // This method is called when the drag begins. You can use this to do any
+  // visual highlighting to indicate that the receive is the source of the 
+  // drag.
+  //
+  //  drag:
+  //    The Drag instance managing this drag.
+  //
+  //  atPoint:
+  //    The point in WINDOW coordinates where the drag began.  You can use
+  //    convertOffsetFromView() to convert this to local coordinates.
+  dragDidBegin: function(drag, atPoint) {},
+  
+  // This method is called when the drag ended. You can use this to do any
+  // cleanup.  The operation is the actual operation performed on the drag.
+  //
+  //  drag:
+  //    The SC.Drag instance managing the drag.
+  //
+  //  endPoint:
+  //    The point in WINDOW coordinates where the drag ended. 
+  //
+  //  operation: SC.DRAG_COPY | SC.DRAG_MOVE | SC.DRAG_LINK | SC.DRAG_NONE
+  //    The drag operation that was performed.
+  //
+  dragDidEnd: function(drag, endPoint, operation) {},
+  
+  // This method is called whenever the drag image is moved.  This is
+  // similar to the dragUpdated() method called on drop targets.
+  dragDidMove: function(drag, newPoint) {},
+  
+  // This method must be overridden for drag operations to be allowed. 
+  // Return a bitwise OR'd mask of the drag operations allowed on the
+  // specified target.  If you don't care about the target, just return a
+  // constant value.
+  //
+  //  dropTarget:
+  //    The proposed target of the drop.
+  //
+  //  drag:
+  //    The SC.Drag instance managing this drag.
+  //
+  dragSourceOperationMaskFor: function(dropTarget, drag) {
+    return SC.DRAG_NONE ;
+  },
+  
+  // If this property is set to NO or is not implemented, then the user may
+  // modify the drag operation by changing the modifier keys they have 
+  // pressed.
+  ignoreModifierKeysWhileDragging: NO
+    
+} ;
+