sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

data/lib/frameworks/sproutcore/frameworks/desktop/protocols/drag_data_source.js

@@ -7,7 +7,6 @@
 
 require('system/drag') ;
 
-
 /**
   @namespace
 
@@ -17,24 +16,28 @@ require('system/drag') ;
 */
 SC.DragDataSource = {
 
-  /** @property
+  /**
     Implement this property as an array of data types you want to support
     for drag operations.
+
+    @type Array
+    @default []
   */
   dragDataTypes: [],
 
   /**
     Implement this method to return the data in the format passed.  Return
     null if the requested data type cannot be generated.
-  
+    
     @param {SC.Drag} drag The Drag instance managing this drag.
     @param {Object} dataType The proposed dataType to return.  This will 
       always be one of the data types declared in dragDataTypes.
     
     @returns The data object for the specified type
   */
-  dragDataForType: function(drag, dataType) { return null; }
-  
-};
+  dragDataForType: function(drag, dataType) {
+    return null;
+  }
 
+};
 

data/lib/frameworks/sproutcore/frameworks/desktop/protocols/drag_source.js

@@ -5,16 +5,14 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-
 require('system/drag') ;
 
 /**
-  @mixin
+  @namespace
 
   The DragSource 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 = {
 
@@ -23,29 +21,32 @@ SC.DragSource = {
     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.
-  
+    
+    The default implementation returns SC.DRAG_NONE
+    
     @param {SC.View} dropTarget The proposed target of the drop.
     @param {SC.Drag} drag The SC.Drag instance managing this drag.
-  
   */
-  dragSourceOperationMaskFor: function(drag, dropTarget) { return SC.DRAG_NONE ; },
+  dragSourceOperationMaskFor: function(drag, dropTarget) {
+    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.
     
-    @returns {Boolean}
+    @type Boolean
+    @default NO
   */
   ignoreModifierKeysWhileDragging: NO,
     
-  /**  
+  /**
     This method is called when the drag begins. You can use this to do any
     visual highlighting to indicate that the receiver is the source of the 
     drag.
-  
+    
     @param {SC.Drag} drag The Drag instance managing this drag.
-  
     @param {Point} loc The point in *window* coordinates where the drag 
       began.  You can use convertOffsetFromView() to convert this to local 
       coordinates.
@@ -55,29 +56,24 @@ SC.DragSource = {
   /**
     This method is called whenever the drag image is moved.  This is
     similar to the dragUpdated() method called on drop targets.
-
+    
     @param {SC.Drag} drag The Drag instance managing this drag.
-
     @param {Point} loc  The point in *window* coordinates where the drag 
       mouse is.  You can use convertOffsetFromView() to convert this to local 
       coordinates.
   */
   dragDidMove: function(drag, loc) {},
   
-  /**  
+  /**
     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.
-  
+    
     @param {SC.Drag} drag The drag instance managing the drag.
-  
-    @param {Point} loc The point in WINDOW coordinates where the drag 
-      ended. 
-  
-    @param {DragOp} op The drag operation that was performed. One of 
+    @param {Point} loc The point in WINDOW coordinates where the drag
+      ended.
+    @param {DragOp} op The drag operation that was performed. One of
       SC.DRAG_COPY, SC.DRAG_MOVE, SC.DRAG_LINK, or SC.DRAG_NONE.
-  
   */
   dragDidEnd: function(drag, loc, op) {}
-  
-} ;
 
+};

data/lib/frameworks/sproutcore/frameworks/desktop/protocols/drop_target.js

@@ -5,7 +5,6 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-
 require('system/drag');
 
 /**
@@ -19,18 +18,18 @@ require('system/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
+      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 
@@ -47,6 +46,10 @@ SC.DropTarget = {
     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.
+    
+    @type Boolean
+    @default YES
+    @constant
   */  
   isDropTarget: YES,
 
@@ -58,7 +61,7 @@ SC.DropTarget = {
     The default implementation does nothing.
     
     @param {SC.Drag} drag The current drag object.
-    @param {SC.Event}   evt  The most recent mouse move event.  Use to get location 
+    @param {SC.Event} evt The most recent mouse move event.  Use to get location 
   */
   dragStarted: function(drag, evt) {},
   
@@ -134,10 +137,13 @@ SC.DropTarget = {
     @param {SC.Drag} drag The current drag object
     @param {SC.Event} evt The most recent mouse move event.  Use to get 
       location 
+    
     @returns {DragOps} A mask of all the drag operations allowed or 
       SC.DRAG_NONE
   */
-  computeDragOperations: function(drag, evt) { return SC.DRAG_NONE; },
+  computeDragOperations: function(drag, evt) {
+    return SC.DRAG_NONE;
+  },
   
   /**
     Called when the user releases the mouse.
@@ -154,7 +160,9 @@ SC.DropTarget = {
     
     @return {Boolean} YES if operation is OK, NO to cancel.
   */  
-  acceptDragOperation: function(drag, op) { return YES; },
+  acceptDragOperation: function(drag, op) {
+    return YES;
+  },
   
   /**
     Called to actually perform the drag operation.
@@ -172,6 +180,8 @@ SC.DropTarget = {
     
     @return {DragOp} Drag Operation actually performed
   */
-  performDragOperation: function(drag, op) { return SC.DRAG_NONE; }
+  performDragOperation: function(drag, op) {
+    return SC.DRAG_NONE;
+  }
   
 };

data/lib/frameworks/sproutcore/frameworks/desktop/system/drag.js

@@ -6,14 +6,45 @@
 // ==========================================================================
 
 
-SC.DRAG_LINK = 0x0004; SC.DRAG_COPY = 0x0001; SC.DRAG_MOVE = 0x0002;
-SC.DRAG_NONE = 0x0000; SC.DRAG_ANY = 0x000F; SC.DRAG_DATA = 0x0008; // includes SC.DRAG_REORDER
+/**
+  @static
+*/
+SC.DRAG_LINK = 0x0004;
+
+/**
+  @static
+*/
+SC.DRAG_COPY = 0x0001;
+
+/**
+  @static
+*/
+SC.DRAG_MOVE = 0x0002;
+
+/**
+  @static
+*/
+SC.DRAG_NONE = 0x0000;
+
+/**
+  @static
+*/
+SC.DRAG_ANY = 0x000F;
+
+/**
+  @static
+*/
+SC.DRAG_DATA = 0x0008; // includes SC.DRAG_REORDER
+
+/**
+  @static
+*/
 SC.DRAG_AUTOSCROLL_ZONE_THICKNESS = 20;
 
-// Add draggable and scrollable support to SC.View
 SC.View.reopen(
   /** @scope SC.View.prototype */ {
 
+  /** @private */
   init: function(original) {
     original();
 
@@ -24,6 +55,7 @@ SC.View.reopen(
     if (this.get('isScrollable')) { SC.Drag.addScrollableView(this) ; }
   }.enhance(),
 
+  /** @private */
   destroy: function(original) {
     // unregister for drags
     if (this.get('isDropTarget')) { SC.Drag.removeDropTarget(this) ; }
@@ -43,45 +75,45 @@ SC.View.reopen(
   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:  
+  specified in a hash. Pass the ones you need to get the drag you want:
   
-  - *event: (req)* The mouse event/touch that triggered the drag.  This will be used
-    to position the element.
+    - *event: (req)* The mouse event/touch 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.
+    - *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: *  Optional view that will be used as the source image for the
-    drag. The drag operation will clone the DOM elements for this view and
-    parent them under the drag pane, which has the class name 'sc-ghost-view'.
-    The drag view is not moved from its original location during a drag.
-    If the dragView is not provided, the source is used as dragView.
+    - *dragView:*  Optional view that will be used as the source image for the
+      drag. The drag operation will clone the DOM elements for this view and
+      parent them under the drag pane, which has the class name 'sc-ghost-view'.
+      The drag view is not moved from its original location during a drag.
+      If the dragView is not provided, the source is used as dragView.
   
-  - *ghost:  YES | NO*  If NO, the drag view image will show, but the source 
-    dragView will not be hidden.  Set to YES to make it appear that the 
-    dragView itself is being dragged around.
+    - *ghost:  YES | NO*  If NO, the drag view image will show, but the source 
+      dragView will not be hidden.  Set to YES to make it appear that the 
+      dragView itself is being dragged around.
   
-  - *slideBack: YES | NO*  If YES and the drag operation is cancelled, the 
-    dragView will slide back to its source origin.
+    - *slideBack: YES | NO*  If YES and 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.
+    - *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 be used instead.
+    - *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 be used instead.
   
-  - *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.
+    - *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.
+    - *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
 */
@@ -115,7 +147,7 @@ SC.Drag = SC.Object.extend(
   ghostActsLikeCursor: NO,
   
   /**  
-    The view that was used as the source of the ghostView.  
+    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 
@@ -190,7 +222,7 @@ SC.Drag = SC.Object.extend(
     on your dragEntered() and prepareForDragOperation() methods to determine 
     if you can handle any of the data types offered up by the drag source.
     
-    @property {Array} available data types
+    @type Array
   */
   dataTypes: function() {
     // first try to use the data source.
@@ -217,7 +249,7 @@ SC.Drag = SC.Object.extend(
   /**
     Checks for a named data type in the drag.
     
-    @param dataType {String} the data type
+    @param {String} dataType the data type
     @returns {Boolean} YES if data type is present in dataTypes array.
   */
   hasDataType: function(dataType) {
@@ -406,6 +438,7 @@ SC.Drag = SC.Object.extend(
   // PRIVATE PROPERTIES AND METHODS
   //
 
+  /** @private */
   touchStart: function(evt) {
     return YES;
   },
@@ -539,6 +572,7 @@ SC.Drag = SC.Object.extend(
     this._dragInProgress = NO ; // required by autoscroll (invoked by a timer)
   },
 
+  /** @private */
   touchEnd: function(evt){
     this.mouseUp(evt);
   },
@@ -594,16 +628,15 @@ SC.Drag = SC.Object.extend(
     loc.y -= this.ghostOffset.y ;
     var gV = this.ghostView;
     if(gV) {
-      gV.adjust({ top: loc.y, left: loc.x }) ;   
+      gV.adjust({ top: loc.y, left: loc.x }) ;
       gV.invokeOnce('updateLayout') ;
     }
   },
   
-  /**
+  /** @private
     YES if the ghostView has been manually hidden.
     
-    @private 
-    @type {Boolean}
+    @type Boolean
     @default NO
   */
   _ghostViewHidden: NO,
@@ -946,7 +979,7 @@ SC.Drag.mixin(
     @param {SC.View} target a view implementing the SC.DropTarget protocol
   */
   addDropTarget: function(target) {
-    this._dropTargets[SC.guidFor(target)] = target ;
+    this._dropTargets[SC.guidFor(target)] = target;
   },
   
   /**
@@ -958,7 +991,7 @@ SC.Drag.mixin(
     @param {SC.View} target A previously registered drop target
   */
   removeDropTarget: function(target) {
-    delete this._dropTargets[SC.guidFor(target)] ;
+    delete this._dropTargets[SC.guidFor(target)];
   },
   
   /**
@@ -968,7 +1001,7 @@ SC.Drag.mixin(
     @param {SC.View} target The view that should be auto-scrolled
   */
   addScrollableView: function(target) {
-    this._scrollableViews[SC.guidFor(target)] = target ;  
+    this._scrollableViews[SC.guidFor(target)] = target;
   },
   
   /**
@@ -978,7 +1011,7 @@ SC.Drag.mixin(
     @param {SC.View} target A previously registered scrollable view
   */
   removeScrollableView: function(target) {
-    delete this._scrollableViews[SC.guidFor(target)] ;  
+    delete this._scrollableViews[SC.guidFor(target)];
   }
   
 });

data/lib/frameworks/sproutcore/frameworks/desktop/system/undo_manager.js

@@ -5,8 +5,9 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-
-require('core');
+/*
+  TODO More docs for this class
+*/
 
 /**
   @class
@@ -15,7 +16,7 @@ require('core');
   do is to make sure that you register a function with this manager to undo
   every change you make.  You can then invoke the undo/redo methods to do it.
   
-  h4. USING THE UNDOMANAGER
+  ## Using SC.UndoManager
   
   Typically you create an undo manager inside on of your controllers.  Then,
   whenever you are about to perform an action on your model object, all you
@@ -25,29 +26,28 @@ require('core');
   Besure the undo function you register also saves undo functions.  This makes
   redo possible.
   
-  More docs TBD.
-  
   @extends SC.Object
 */
 SC.UndoManager = SC.Object.extend(
-/** @scope SC.UndoManager.prototype */
-{
+/** @scope SC.UndoManager.prototype */ {
 
   /** 
-    (Property) Name of the next undo action name.  
-  
     Use this property to build your Undo menu name.
     
+    @field
+    @type String
+    @default null
   */
   undoActionName: function() { 
     return this.undoStack ? this.undoStack.name : null ;
   }.property('undoStack'),
   
   /** 
-    (Property) Name of the next return action name.  
-  
     Use this property to build your Redo menu name.
     
+    @field
+    @type String
+    @default null
   */
   redoActionName: function() { 
     return this.redoStack ? this.redoStack.name : null ;
@@ -57,43 +57,57 @@ SC.UndoManager = SC.Object.extend(
     True if there is an undo action on the stack.
     
     Use to validate your menu item.
+    
+    @field
+    @type Boolean
+    @default NO
   */
   canUndo: function() { 
-    return this.undoStack != null; 
+    // instead of this.undoStack !== null && this.undoStack !== undefined
+    return this.undoStack != null;
   }.property('undoStack'),
   
   /** 
-    True if there is an redo action on the stack.
+    True if there is an redo action on the stack. Use to validate your menu item.
     
-    Use to validate your menu item.
+    @field
+    @type Boolean
+    @default NO
   */
   canRedo: function() { 
+    // instead of this.redoStack !== null && this.redoStack !== undefined
     return this.redoStack != null; 
   }.property('redoStack'),
   
-  /**  
-    Tries to undo the last action.  
-  
-    Returns true if succeeded.  Fails if an undo group is currently open.
+  /**
+    Tries to undo the last action. Fails if an undo group is currently open.
+    
+    @returns {Boolean} YES if suceeded, NO otherwise.
   */
-  undo: function() { this._undoOrRedo('undoStack','isUndoing'); },
-  
-  /**  
-    Tries to redo the last action.  
+  undo: function() {
+    this._undoOrRedo('undoStack','isUndoing');
+  },
   
-    Returns true if succeeded.  Fails if an undo group is currently open.
+  /**
+    Tries to redo the last action. Fails if a redo group is currently open.
+    
+    @returns {Boolean} YES if suceeded, NO otherwise.
   */
-  redo: function() { this._undoOrRedo('redoStack','isRedoing'); },
+  redo: function() {
+    this._undoOrRedo('redoStack','isRedoing');
+  },
   
   /**
-    True if the manager is currently undoing events. 
+    @type Boolean
+    @default NO
   */
-  isUndoing: false, 
+  isUndoing: NO,
   
   /**
-    True if the manager is currently redoing events.
+    @type Boolean
+    @default NO
   */
-  isRedoing: false, 
+  isRedoing: NO, 
   
   /** @private */
   groupingLevel: 0,
@@ -126,6 +140,8 @@ SC.UndoManager = SC.Object.extend(
     
     When you are finished performing the action, balance this with a call to
     endUndoGroup().
+    
+    @param {String} name
   */
   beginUndoGroup: function(name) {
     // is a group already active? Just increment the counter.
@@ -141,7 +157,12 @@ SC.UndoManager = SC.Object.extend(
     }
   },
  
-  /** end the undo group.  see beginUndoGroup() */
+  /**
+    @throws {Error} If there is no active group
+    
+    @param {String} name
+    @see beginUndoGroup()
+  */
   endUndoGroup: function(name) {
     // if more than one groups are active, just decrement the counter.
     if (!this._activeGroup) raise("endUndoGroup() called outside group.") ;
@@ -156,9 +177,13 @@ SC.UndoManager = SC.Object.extend(
   },
 
   /**
-    Change the name of the current undo group.  
-  
+    Change the name of the current undo group.
+    
     Normally you don't want to do this as it will effect the whole group.
+    
+    @param {String} name
+    
+    @throws {Error} If there is no active group
   */
   setActionName: function(name) {
     if (!this._activeGroup) raise("setActionName() called outside group.") ;
@@ -168,8 +193,18 @@ SC.UndoManager = SC.Object.extend(
   // --------------------------------
   // PRIVATE
   //
-  _activeGroup: null, undoStack: null, redoStack: null, 
-  _undoOrRedo: function(stack,state) {
+  
+  /** @private */
+  _activeGroup: null,
+  
+  /** @private */
+  undoStack: null,
+  
+  /** @private */
+  redoStack: null, 
+  
+  /** @private */
+  _undoOrRedo: function(stack, state) {
     if (this._activeGroup) return false ;
     if (this.get(stack) == null) return true; // noting to do.