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

data/lib/frameworks/sproutcore/frameworks/foundation/gestures/swipe.js

@@ -4,33 +4,119 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 sc_require("system/gesture");
 
+/*
+  TODO Document this class
+*/
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_HORIZONTAL = "X";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_VERTICAL = "Y";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_ANY = "XY";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_LEFT = "LEFT";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_RIGHT = "RIGHT";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_UP = "UP";
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.SWIPE_DOWN = "DOWN";
 
-SC.SwipeGesture = SC.Gesture.extend({
+/**
+  @class
+  @extends SC.Gesture
+*/
+SC.SwipeGesture = SC.Gesture.extend(
+/** @scope SC.SwipeGesture.prototype */ {
+
+  /**
+    @type String
+    @default "swipe"
+    @readOnly
+  */
   name: "swipe",
+
+  /**
+    @type Boolean
+    @default YES
+    @readOnly
+  */
   acceptsMultitouch: YES,
-  
+
+  /**
+    @type String
+    @default SC.SWIPE_HORIZONTAL
+  */
   direction: SC.SWIPE_HORIZONTAL,
 
   /**
     Will be populated with the current direction of the swipe once
     one has been determined.
+    
+    @type String
+    @default null
   */
   currentDirection: null,
 
+  /**
+    @type Number
+    @default 5
+  */
   startDistance: 5,
+
+  /**
+    @type Number
+    @default 40
+  */
   swipeDistance: 40,
   
-  tolerance: 0.5, // we accept .5 the distance in the other direction as a swipe
+  /**
+    Amount of distance in the other direction to consider it a swipe
+    
+    @type Number
+    @default 0.5
+  */
+  tolerance: 0.5,
   
+  /** @private */
   touchIsInGesture: function(touch, status) {
     // if we have not "flunked" the touch before, and it has moved 
     if (!status.flunked) {
@@ -67,6 +153,7 @@ SC.SwipeGesture = SC.Gesture.extend({
     return NO;
   },
   
+  /** @private */
   touchStart: function(touch) {
     var d = this.get("currentDirection"), 
         delta = touch["page" + d] - touch["start" + d],
@@ -79,6 +166,7 @@ SC.SwipeGesture = SC.Gesture.extend({
     return YES;
   },
   
+  /** @private */
   touchesDragged: function(evt, touches) {
     var touch = touches.firstObject();
     var d = this.get("currentDirection"), 
@@ -98,12 +186,13 @@ SC.SwipeGesture = SC.Gesture.extend({
       this.release(touch);
 
       var allTouches = touch.touchesForResponder(this);
-      if (!allTouches || allTouches.length == 0) this.cancel(touch, swipeDirection, delta);
+      if (!allTouches || allTouches.length === 0) this.cancel(touch, swipeDirection, delta);
     } else {
       this.change(touch, swipeDirection, delta);
     }
   },
   
+  /** @private */
   touchEnd: function(touch) {
     var d = this.get("currentDirection"), 
         o = (d === SC.SWIPE_HORIZONTAL ? "Y" : "X"),
@@ -136,6 +225,7 @@ SC.SwipeGesture = SC.Gesture.extend({
     }
   },
 
+  /** @private */
   cancel: function(){
     sc_super();
     this.set('currentDirection', null);

data/lib/frameworks/sproutcore/frameworks/foundation/gestures/tap.js

@@ -4,23 +4,57 @@
 // Author:    Peter Wagenet
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 sc_require("system/gesture");
 
-SC.TapGesture = SC.Gesture.extend({
+/**
+  @class
+  @extends SC.Gesture
+*/
+SC.TapGesture = SC.Gesture.extend(
+/** @scope SC.TapGesture.prototype */{
+
+  /**
+    @type String
+    @default "tap"
+    @readOnly
+  */
   name: "tap",
+
+  /**
+    @type Boolean
+    @default NO
+    @readOnly
+  */
   acceptsMultitouch: NO,
 
+  /** @private */
   _tapCount: null,
+  
+  /** @private */
   _candidateTouch: null,
+  
+  /** @private */
   _eventTimer: null,
 
+  /**
+    @type Number
+    @default 20
+  */
   tapWiggle: 10,
+
+  /**
+    @type Number
+    @default 200
+  */
   tapDelay: 200,
 
+  /** @private */
   touchIsInGesture: function(touch, status) {
     return !touch.tapFlunked;
   },
 
+  /** @private */
   touchStart: function(touch) {
     // We don't want events triggering during a touch, will be reset when touch is over if it's a candidate
     if (this._eventTimer) this._eventTimer.invalidate();
@@ -42,6 +76,7 @@ SC.TapGesture = SC.Gesture.extend({
     return YES;
   },
 
+  /** @private */
   touchesDragged: function(evt, touches) {
     var touch = touches[0];
 
@@ -58,6 +93,7 @@ SC.TapGesture = SC.Gesture.extend({
     if (tooManyTouches || touchMoved) this._cancelTap(touch);
   },
 
+  /** @private */
   touchEnd: function(touch){
     if (this._calculateDragDistance(touch) > this.get('tapWiggle') || Date.now() - this._candidateTouch.startTime > this.get('tapDelay') ) {
       // Touch moved too much or took too long
@@ -67,6 +103,7 @@ SC.TapGesture = SC.Gesture.extend({
     }
   },
 
+  /** @private */
   _addTap: function(touch){
     var self = this;
 
@@ -85,6 +122,7 @@ SC.TapGesture = SC.Gesture.extend({
 
   },
 
+  /** @private */
   _cancelTap: function(touch){
     // We don't set this on the touchStatus because the status is
     // linked to an individual view/gesture and we want this to be
@@ -101,6 +139,7 @@ SC.TapGesture = SC.Gesture.extend({
 
   },
 
+  /** @private */
   _triggerTap: function(touch){
     this.end(touch, this._tapCount);
 
@@ -109,6 +148,7 @@ SC.TapGesture = SC.Gesture.extend({
     this._eventTimer = null;
   },
 
+  /** @private */
   _calculateDragDistance: function(touch) {
     return Math.sqrt(Math.pow(touch.pageX - touch.startX, 2) + Math.pow(touch.pageY - touch.startY, 2));
   }

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/auto_mixin.js

@@ -14,6 +14,7 @@
   @since SproutCore 1.0
 */
 SC.AutoMixin = {
+
   /**
     The mixins to automatically mix in.
     @property
@@ -36,4 +37,5 @@ SC.AutoMixin = {
     v = v.create.apply(v, applyMixins);
     return v;
   }
+
 };

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/auto_resize.js

@@ -45,22 +45,25 @@ SC.AutoResize = {
     setting 'measuredSize' to the measured value (you can bind to measuredSize
     and update size manually).
 
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   shouldAutoResize: YES,
 
   /**
     If NO, prevents SC.AutoResize from doing anything at all.
 
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   shouldMeasureSize: YES,
 
   /**
     Determines if the view's width should be resized
-    on calculation. Default is YES.
+    on calculation.
 
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   shouldResizeWidth: YES,
 
@@ -69,7 +72,8 @@ SC.AutoResize = {
     on calculation. Default is NO to retain backwards
     compatibility.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   shouldResizeHeight: NO,
   
@@ -79,7 +83,7 @@ SC.AutoResize = {
     shouldAutoResize to NO, allows you to customize the 'sizing' part, using
     SC.AutoResize purely for its measuring code.
     
-    @property {Rect}
+    @type Rect
   */
   measuredSize: { width: 0, height: 0 },
 
@@ -108,14 +112,19 @@ SC.AutoResize = {
   /**
     If this property is provided, all views that share the same value for this property will be resized as a batch for increased performance.
 
-    @property {String}
+    @type String
   */
   batchResizeId: null,
 
+  /** @private */
   _scar_measurementPending: NO,
+  
+  /** @private */
   _scar_requestedBatchResizeId: null,
 
-  // if the batch id changed while a request is out, we have to fix it
+  /** @private
+    If the batch id changed while a request is out, we have to fix it
+  */
   _scar_batchResizeIdDidChange: function() {
     var batchResizeId = this.get('batchResizeId'),
     requestedBatchResizeId = this._scar_requestedBatchResizeId;
@@ -208,7 +217,7 @@ SC.AutoResize = {
   },
 
   /**
-    
+    @private
   */
   _scar_valueDidChange: function() {
     this.scheduleMeasurement();

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/collection_content.js

@@ -5,25 +5,27 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-
 /**
   Used for contentIndexDisclosureState().  Indicates open branch node.
   
-  @property {Number}
+  @type Number
+  @constant
 */
 SC.BRANCH_OPEN = 0x0011;
 
 /**
   Used for contentIndexDisclosureState().  Indicates closed branch node.
   
-  @property {Number}
+  @type Number
+  @constant
 */
 SC.BRANCH_CLOSED = 0x0012;
 
 /**
   Used for contentIndexDisclosureState().  Indicates leaf node.
   
-  @property {Number}
+  @type Number
+  @constant
 */
 SC.LEAF_NODE = 0x0020;
 
@@ -44,7 +46,7 @@ SC.CollectionContent = {
   /**
     Used to detect the mixin by SC.CollectionView
 
-    @property {Boolean}
+    @type Boolean
   */
   isCollectionContent: YES,
   

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/content_display.js

@@ -15,14 +15,12 @@
   method on your view. Your updateDisplay() method will then be called at the 
   end of the run loop.
   
-  h2. Example
+  ## Example
   
-  {{{
-    MyApp.MyViewClass = SC.View.extend(SC.ContentDisplay, { 
-      contentDisplayProperties: 'title isEnabled hasChildren'.w(),
-      ...
-    });
-  }}}
+      MyApp.MyViewClass = SC.View.extend(SC.ContentDisplay, { 
+        contentDisplayProperties: 'title isEnabled hasChildren'.w(),
+        ...
+      });
   
   @since SproutCore 1.0
 */
@@ -39,7 +37,8 @@ SC.ContentDisplay = {
     should trigger an update of the display for your view.  Changes to the
     content object will only invoke your display method once per runloop.
     
-    @property {Array}
+    @type Array
+    @default []
   */
   contentDisplayProperties: [],
 

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/content_value_support.js

@@ -5,27 +5,32 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-/*
-* @mixin
-*
-* This mixin allows a view to get its value from a content object based
-* on the value of its contentValueKey.
-*
-* {{{
-* myView = SC.View.create({
-*   content: {prop: "abc123"},
-*
-*   contentValueKey: 'prop'
-* });
-*
-* // myView.get('value') will be "abc123"
-* }}}
-*
-* This is useful if you have a nested record structure and want to have
-* it be reflected in a nested view structure. If your data structures
-* only have primitive values, consider using SC.Control instead.
+/**
+  @mixin
+
+  This mixin allows a view to get its value from a content object based
+  on the value of its contentValueKey.
+
+      myView = SC.View.create({
+        content: {prop: "abc123"},
+
+        contentValueKey: 'prop'
+      });
+
+      // myView.get('value') will be "abc123"
+
+  This is useful if you have a nested record structure and want to have
+  it be reflected in a nested view structure. If your data structures
+  only have primitive values, consider using SC.Control instead.
 */
 SC.ContentValueSupport = {
+
+  /**
+    Walk like a duck.
+
+    @type Boolean
+    @default YES
+  */
   hasContentValueSupport: YES,
 
   /** @private */
@@ -46,7 +51,8 @@ SC.ContentValueSupport = {
     set a content object and have the control display a single property
     of that control, then you should use the content property instead.
 
-    @property {Object}
+    @type Object
+    @default null
   */
   value: null,
   
@@ -66,7 +72,8 @@ SC.ContentValueSupport = {
     collection view, then it would be better to instead bind the value of
     the control directly to a controller property.
     
-    @property {SC.Object}
+    @type SC.Object
+    @default null
   */
   content: null,
   
@@ -76,7 +83,8 @@ SC.ContentValueSupport = {
     content object is first set.  If you have a displayDelegate, then
     you can also use the contentValueKey of the displayDelegate.
     
-    @property {String}
+    @type String
+    @default null
   */
   contentValueKey: null,
   
@@ -208,10 +216,12 @@ SC.ContentValueSupport = {
     
   }.observes('content'),
   
-  // since we always observe *, just call the update function
+  /** @private
+    Since we always observe *, just call the update function
+  */
   _control_contentValueKeyDidChange: function() {
     // notify that value did change.
     this.contentPropertyDidChange(this.get('content'), '*') ;
-  }.observes('contentValueKey'),
+  }.observes('contentValueKey')
 };
 

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/control.js

@@ -11,48 +11,57 @@ sc_require('mixins/content_value_support');
 /**
   Option for controls to automatically calculate their size (should be default 
   on controls that use renderers).
+  
+  @type String
+  @constant
 */
 SC.AUTO_CONTROL_SIZE = '__AUTO__';
 
 /** 
   Option for HUGE control size.
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.JUMBO_CONTROL_SIZE = 'sc-jumbo-size' ;
 
 /** 
   Option for HUGE control size.
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.HUGE_CONTROL_SIZE = 'sc-huge-size' ;
 
 /** 
   Option for large control size.
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.LARGE_CONTROL_SIZE = 'sc-large-size' ;
 
 /** 
   Option for standard control size.
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.REGULAR_CONTROL_SIZE = 'sc-regular-size' ;
 
 /** 
   Option for small control size.
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.SMALL_CONTROL_SIZE = 'sc-small-size' ;
 
 /** 
   Option for tiny control size
   
-  @property {String}
+  @type String
+  @constant
 */
 SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
 
@@ -64,7 +73,7 @@ SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
   functionality including showing a selected state, enabled state, focus
   state, etc.
   
-  h2. About Values and Content
+  ## About Values and Content
   
   Controls typically are used to represent a single value, such as a number,
   boolean or string.  The value a control is managing is typically stored in
@@ -98,7 +107,7 @@ SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
   properties you care about on the content object and update your view if 
   anything you care about has changed.
   
-  h2. Delegate Support
+  ## Delegate Support
   
   Controls can optionally get the contentDisplayProperty from a 
   displayDelegate, if it is set.  The displayDelegate is often used to 
@@ -107,16 +116,29 @@ SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
   collection view will be automatically set as its displayDelegate.
   
   @since SproutCore 1.0
+  @extends SC.ContentValueSupport
 */
-SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
+SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport),
+/** @scope SC.Control.prototype */{
   
+  /**
+    Walk like a duck
+    
+    @type Boolean
+    @default YES
+    @readOnly
+  */
   isControl: YES,
   
   /** 
-    The selected state of this control.  Possible options are YES, NO or 
-    SC.MIXED_STATE.
+    The selected state of this control. Possible values:
+    
+      - `YES`
+      - `NO`
+      - SC.MIXED_STATE.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isSelected: NO,
   
@@ -131,7 +153,8 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
     Changing this property value by default will cause the Control mixin to
     add/remove an 'active' class name to the root element.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isActive: NO,
   
@@ -146,7 +169,8 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
     automatically bind the value to the property key you name here on the 
     content object.
     
-    @property {String}
+    @type String
+    @default null
   */
   fieldKey: null,
   
@@ -157,7 +181,8 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
     in the error explanation.  If you do not set this property, then the 
     fieldKey or the class name will be used to generate a human readable name.
     
-    @property {String}
+    @type String
+    @default null
   */
   fieldLabel: null,
   
@@ -173,7 +198,10 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
     Try to localize using the string "ErrorLabel.{ClassName}". Return a 
     humanized form of the class name.
     
-    @property {String}
+    @field
+    @type String
+    @observes 'fieldLabel'
+    @observes 'fieldKey'
   */
   errorLabel: function() {
     var ret, fk, def ;
@@ -197,7 +225,8 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
     a height, performance will be impacted as it must be calculated; if you do
     this, a warning will be issued. If you don't care, use SC.CALCULATED_CONTROL_SIZE.
     
-    @property {String}
+    @type String
+    @default SC.REGULAR_CONTROL_SIZE
   */
   controlSize: SC.REGULAR_CONTROL_SIZE,
   
@@ -248,6 +277,7 @@ SC.Control = SC.mixin(SC.clone(SC.ContentValueSupport), {
         this.$input().attr('disabled', disabled);
       }
     }
-  },
+  }
+
 });