sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/desktop/views/scene.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -13,7 +13,7 @@
   optionally choose the kind of animation used to transition the two scenes 
   as well if supported on the web browser.
   
-  h1. Using The View
+  # Using SC.SceneView
   
   To setup the scene view, you should define the 'scenes' property with an 
   array of scene names.  These will be the properties on the scene view that
@@ -26,11 +26,11 @@
   is visible on screen.  Otherwise, it will simply make the new scene view 
   the current content view and that's it.
 
-  @extends SC.View
+  @extends SC.ContainerView
   @since SproutCore 1.0
 */
 SC.SceneView = SC.ContainerView.extend(
-  /** @scope SC.SceneView.prototype */ {
+/** @scope SC.SceneView.prototype */ {
 
   /**
     Array of scene names.  Scenes will slide on and off screen in the order
@@ -38,10 +38,8 @@ SC.SceneView = SC.ContainerView.extend(
     2 to a scene at index 1, the scenes will animation backwards.  If you
     shift to a scene at index 3, the scenes will animate forwards.
     
-    The default scenes defined are 'master' and 'detail'.  You can replace or 
-    augment this array as you like.
-    
-    @property {Array}
+    @type Array
+    @default ['master', 'detail']
   */
   scenes: ['master', 'detail'],
 
@@ -50,21 +48,26 @@ SC.SceneView = SC.ContainerView.extend(
     scene view to transition to the new scene.  If you set this property to 
     null, an empty string, or a non-existant scene, then the scene will appear
     empty.
+    
+    @type String
+    @default null
   */
   nowShowing: null,
   
   /**
     Speed of transition.  Should be expressed in msec.
+    
+    @type Number
+    @default 200
   */
   transitionDuration: 200,
   
+  /** @private */
   _state: 'NO_VIEW', // no view
 
   /** @private
-  
     Whenever called to change the content, save the nowShowing state and 
     then animate in by adjusting the layout.
-    
   */
   replaceContent: function(content) {
     if (content && this._state===this.READY) this.animateScene(content);
@@ -73,7 +76,6 @@ SC.SceneView = SC.ContainerView.extend(
   },
 
   /** @private
-  
     Invoked whenever we just need to swap the scenes without playing an
     animation.
   */
@@ -102,7 +104,6 @@ SC.SceneView = SC.ContainerView.extend(
   },
 
   /** @private
-  
     Invoked whenever we need to animate in the new scene.
   */
   animateScene: function(newContent) {
@@ -143,7 +144,8 @@ SC.SceneView = SC.ContainerView.extend(
     this.tick();
   },
 
-  /** @private - called while the animation runs.  Compute the new layout for
+  /** @private
+    Called while the animation runs.  Compute the new layout for
     the left and right views based on the portion completed.  When we finish
     call replaceScene().
   */
@@ -192,13 +194,18 @@ SC.SceneView = SC.ContainerView.extend(
   },
   
 
-  // states for view animation
+  /** @private */
   NO_VIEW: 'NO_VIEW',
+  
+  /** @private */
   ANIMATING: 'ANIMATING',
+  
+  /** @private */
   READY: 'READY',
 
-  /** @private - standard layout assigned to views at rest */
+  /** @private
+    Standard layout assigned to views at rest
+  */
   STANDARD_LAYOUT: { top: 0, left: 0, bottom: 0, right: 0 }
-  
-  
+
 });

data/lib/frameworks/sproutcore/frameworks/desktop/views/scroll.js

@@ -1,58 +1,101 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
 sc_require('views/scroller');
-sc_require('mixins/border');
 
+/**
+  @static
+  @type Number
+  @default 0.95
+*/
 SC.NORMAL_SCROLL_DECELERATION = 0.95;
+
+/**
+  @static
+  @type Number
+  @default 0.85
+*/
 SC.FAST_SCROLL_DECELERATION = 0.85;
 
 /** @class
-
   Implements a complete scroll view.  This class uses a manual implementation
   of scrollers in order to properly support clipping frames.
   
   Important Events:
   
-  - contentView frame size changes (to autoshow/hide scrollbar - adjust scrollbar size)
-  - horizontalScrollOffset change
-  - verticalScrollOffsetChanges
-  - scroll wheel events
+    - contentView frame size changes (to autoshow/hide scrollbar - adjust scrollbar size)
+    - horizontalScrollOffset change
+    - verticalScrollOffsetChanges
+    - scroll wheel events
   
   @extends SC.View
   @since SproutCore 1.0
 */
-SC.ScrollView = SC.View.extend(SC.Border, {
-  /** @scope SC.ScrollView.prototype */
+SC.ScrollView = SC.View.extend({
+/** @scope SC.ScrollView.prototype */
+
+  /**
+    @type Array
+    @default ['sc-scroll-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-scroll-view'],
-  
+
   // ..........................................................
   // PROPERTIES
   // 
   
+  /**
+    Walk like a duck
+    
+    @type Boolean
+    @default YES
+    @readOnly
+  */
   isScrollable: YES,
   
   /** 
     The content view you want the scroll view to manage. This will be assigned to the contentView of the clipView also.
+    
+    @type SC.View
+    @default null
   */
   contentView: null,
   
   /**
-    The horizontal alignment for non-filling content inside of the ScrollView.
+    The horizontal alignment for non-filling content inside of the ScrollView. Possible values:
+    
+      - SC.ALIGN_LEFT
+      - SC.ALIGN_RIGHT
+      - SC.ALIGN_CENTER
+    
+    @type String
+    @default SC.ALIGN_LEFT
   */
   horizontalAlign: SC.ALIGN_LEFT,
   
   /**
-    The vertical alignment for non-filling content inside of the ScrollView.
+    The vertical alignment for non-filling content inside of the ScrollView. Possible values:
+    
+      - SC.ALIGN_TOP
+      - SC.ALIGN_BOTTOM
+      - SC.ALIGN_MIDDLE
+    
+    @type String
+    @default SC.ALIGN_TOP
   */
   verticalAlign: SC.ALIGN_TOP,
 
   /**
     The current horizontal scroll offset. Changing this value will update both the contentView and the horizontal scroller, if there is one.
+    
+    @field
+    @type Number
+    @default 0
   */
   horizontalScrollOffset: function(key, value) {
     if (value !== undefined) {
@@ -66,6 +109,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   
   /**
     The current vertical scroll offset.  Changing this value will update both the contentView and the vertical scroller, if there is one.
+    
+    @field
+    @type Number
+    @default 0
   */
   verticalScrollOffset: function(key, value) {
     if (value !== undefined) {
@@ -77,8 +124,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     return this._scroll_verticalScrollOffset||0;
   }.property().cacheable(),
   
-  /**
-    @private
+  /** @private
     Calculates the maximum offset given content and container sizes, and the
     alignment.
   */
@@ -102,8 +148,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
-  /**
-    @private
+  /** @private
     Calculates the minimum offset given content and container sizes, and the
     alignment.
   */
@@ -131,18 +176,18 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     size and the size of the scroll view.  If horizontal scrolling is 
     disabled, this will always return 0.
     
-    @property {Number}
+    @field
+    @type Number
+    @default 0
   */
   maximumHorizontalScrollOffset: function() {
-    var view = this.get('contentView'),
-        contentWidth = 0, calculatedWidth = 0;
-        
-    if (view && view.get('frame')) contentWidth = view.get('frame').width;
-    if (view) calculatedWidth = view.calculatedWidth || 0;
+    var view = this.get('contentView') ;
+    var contentWidth = view ? view.get('frame').width : 0,
+        calculatedWidth = view ? view.get('calculatedWidth') : 0;
     
     // The following code checks if there is a calculatedWidth (collections)
     // to avoid looking at the incorrect value calculated by frame.
-    if(view && view.calculatedWidth && view.calculatedWidth!==0){
+    if (calculatedWidth) {
       contentWidth = view.calculatedWidth; 
     }
     contentWidth *= this._scale;
@@ -160,19 +205,19 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     size and the size of the scroll view.  If vertical scrolling is disabled,
     this will always return 0 (or whatever alignment dictates).
     
-    @property {Number}
+    @field
+    @type Number
+    @default 0
   */
   maximumVerticalScrollOffset: function() {
     var view = this.get('contentView'),
-        contentHeight = 0, calculatedHeight = 0;
-        
-    if (view && view.get('frame')) contentHeight = view.get('frame').height;
-    if (view) calculatedHeight = view.calculatedHeight || 0;
+        contentHeight = (view && view.get('frame')) ? view.get('frame').height : 0,
+        calculatedHeight = view ? view.get('calculatedHeight') : 0;
     
     // The following code checks if there is a calculatedWidth (collections)
     // to avoid looking at the incorrect value calculated by frame.
-    if(view && view.calculatedHeight && view.calculatedHeight!==0){
-      contentHeight = view.calculatedHeight; 
+    if(calculatedHeight){
+      contentHeight = calculatedHeight; 
     }
     contentHeight *= this._scale;
     
@@ -190,16 +235,18 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     size and the size of the scroll view.  If horizontal scrolling is 
     disabled, this will always return 0 (or whatever alignment dictates).
     
-    @property {Number}
+    @field
+    @type Number
+    @default 0
   */
   minimumHorizontalScrollOffset: function() {
     var view = this.get('contentView') ;
-    var contentWidth = view ? view.get('frame').width : 0 ;
-    
+    var contentWidth = view ? view.get('frame').width : 0,
+        calculatedWidth = view ? view.get('calculatedWidth') : 0;
     // The following code checks if there is a calculatedWidth (collections)
     // to avoid looking at the incorrect value calculated by frame.
-    if(view && view.calculatedWidth && view.calculatedWidth!==0){
-      contentWidth = view.calculatedWidth; 
+    if(calculatedWidth){
+      contentWidth = calculatedWidth; 
     }
     contentWidth *= this._scale;
     
@@ -216,15 +263,18 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     size and the size of the scroll view.  If vertical scrolling is disabled,
     this will always return 0 (or whatever alignment dictates).
     
-    @property {Number}
+    @field
+    @type Number
+    @default 0
   */
   minimumVerticalScrollOffset: function() {
     var view = this.get('contentView') ;
-    var contentHeight = (view && view.get('frame')) ? view.get('frame').height : 0 ;
+    var contentHeight = (view && view.get('frame')) ? view.get('frame').height : 0,
+        calculatedHeight = view ? view.get('calculatedHeight') : 0;
     
     // The following code checks if there is a calculatedWidth (collections)
     // to avoid looking at the incorrect value calculated by frame.
-    if(view && view.calculatedHeight && view.calculatedHeight!==0){
+    if(calculatedHeight){
       contentHeight = view.calculatedHeight; 
     }
     contentHeight *= this._scale;
@@ -238,12 +288,13 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   }.property(),
   
   
-  
   /** 
     Amount to scroll one vertical line.
   
-    Used by the default implementation of scrollDownLine() and scrollUpLine().  
-    Defaults to 20px.
+    Used by the default implementation of scrollDownLine() and scrollUpLine().
+    
+    @type Number
+    @default 20
   */
   verticalLineScroll: 20,
   
@@ -251,30 +302,43 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Amount to scroll one horizontal line.
   
     Used by the default implementation of scrollLeftLine() and 
-    scrollRightLine(). Defaults to 20px.
+    scrollRightLine().
+    
+    @type Number
+    @default 20
   */
   horizontalLineScroll: 20,
   
   /**
     Amount to scroll one vertical page.
     
-    Used by the default implementation of scrollUpPage() and scrollDownPage(). 
-    Defaults to current frame height.
+    Used by the default implementation of scrollUpPage() and scrollDownPage().
+    
+    @field
+    @type Number
+    @default value of frame.height
+    @observes frame
   */
   verticalPageScroll: function() {
-    return this.get('frame').height ;
+    return this.get('frame').height;
   }.property('frame'),
   
   /**
     Amount to scroll one horizontal page.
     
     Used by the default implementation of scrollLeftPage() and 
-    scrollRightPage().  Defaults to current innerFrame width.
+    scrollRightPage().
+    
+    @field
+    @type Number
+    @default value of frame.width
+    @observes frame
   */
   horizontalPageScroll: function() {
-    return this.get('frame').width ;  
+    return this.get('frame').width;
   }.property('frame'),
-    
+  
+  
   // ..........................................................
   // SCROLLERS
   // 
@@ -283,7 +347,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     YES if the view should maintain a horizontal scroller.   This property 
     must be set when the view is created.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   hasHorizontalScroller: YES,
   
@@ -292,7 +357,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     instance when the ScrollView is created unless hasHorizontalScroller is 
     NO.
     
-    @property {SC.View}
+    @type SC.View
+    @default SC.ScrollerView
   */
   horizontalScrollerView: SC.ScrollerView,
   
@@ -300,6 +366,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     The horizontal scroller view for touch. This will be replaced with a view
     instance when touch is enabled when the ScrollView is created unless 
     hasHorizontalScroller is NO.
+    
+    @type SC.View
+    @default SC.TouchScrollerView
   */
   horizontalTouchScrollerView: SC.TouchScrollerView,
   
@@ -310,7 +379,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     hasHorizontalScroller to NO to avoid creating a scroller view in the 
     first place.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isHorizontalScrollerVisible: YES,
 
@@ -318,7 +388,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Returns YES if the view both has a horizontal scroller, the scroller is
     visible.
     
-    @property {Boolean}
+    @field
+    @type Boolean
+    @default YES
   */
   canScrollHorizontal: function() {
     return !!(this.get('hasHorizontalScroller') && 
@@ -329,7 +401,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   /**
     If YES, the horizontal scroller will autohide if the contentView is
     smaller than the visible area.  You must set hasHorizontalScroller to YES 
-    for this property to have any effect.  
+    for this property to have any effect.
+    
+    @type Boolean
+    @default YES
   */
   autohidesHorizontalScroller: YES,
   
@@ -337,7 +412,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     YES if the view shuld maintain a vertical scroller.   This property must 
     be set when the view is created.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   hasVerticalScroller: YES,
   
@@ -345,13 +421,17 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     The vertical scroller view class. This will be replaced with a view 
     instance when the ScrollView is created unless hasVerticalScroller is NO.
     
-    @property {SC.View}
+    @type SC.View
+    @default SC.ScrollerView
   */
   verticalScrollerView: SC.ScrollerView,
   
   /**
     The vertical touch scroller view class. This will be replaced with a view
     instance when the ScrollView is created.
+    
+    @type SC.View
+    @default SC.TouchScrollerView
   */
   verticalTouchScrollerView: SC.TouchScrollerView,
   
@@ -362,7 +442,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     hasVerticalScroller to NO to avoid creating a scroller view in the first 
     place.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isVerticalScrollerVisible: YES,
 
@@ -370,7 +451,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Returns YES if the view both has a horizontal scroller, the scroller is
     visible.
     
-    @property {Boolean}
+    @field
+    @type Boolean
+    @default YES
   */
   canScrollVertical: function() {
     return !!(this.get('hasVerticalScroller') && 
@@ -381,7 +464,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   /**
     If YES, the vertical scroller will autohide if the contentView is
     smaller than the visible area.  You must set hasVerticalScroller to YES 
-    for this property to have any effect.  
+    for this property to have any effect.
+    
+    @type Boolean
+    @default YES
   */
   autohidesVerticalScroller: YES,
   
@@ -389,7 +475,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Use this property to set the 'bottom' offset of your vertical scroller, 
     to make room for a thumb view or other accessory view. Default is 0.
     
-    @property {Number}
+    @type Number
+    @default 0
   */
   verticalScrollerBottom: 0,
   
@@ -399,8 +486,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     This ensures that the container frame will not resize to accomodate the
     vertical scroller, hence overlaying the scroller on top of 
     the container.
-  
-    @property {Boolean}
+    
+    @field
+    @type Boolean
+    @default NO
   */
   verticalOverlay: function() {
     if (SC.platform.touch) return YES;
@@ -414,7 +503,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     horizontal scroller, hence overlaying the scroller on top of 
     the container
     
-    @property {Boolean}
+    @field
+    @type Boolean
+    @default NO
   */
   horizontalOverlay: function() {
     if (SC.platform.touch) return YES;
@@ -432,6 +523,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     “float on top” of the content view.
     
     Example: { top: -1, bottom: -1, right: 0 }
+    
+    @type Hash
+    @default null
   */
   verticalScrollerLayout: null,
   
@@ -445,6 +539,9 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     “float on top” of the content view.
     
     Example: { left: 0, bottom: 0, right: 0 }
+    
+    @type Hash
+    @default null
   */
   horizontalScrollerLayout: null,
   
@@ -456,11 +553,11 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     The container view that will contain your main content view.  You can 
     replace this property with your own custom subclass if you prefer.
     
-    @type {SC.ContainerView}
+    @type SC.ContainerView
+    @default SC.ConainerView
   */
-  containerView: SC.ContainerView.extend({
-
-  }),
+  containerView: SC.ContainerView.extend({}),
+  
   
   // ..........................................................
   // METHODS
@@ -479,8 +576,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     direction.  You can also optionally pass a Hash for the first parameter 
     with x and y coordinates.
     
-    @param x {Number} the x scroll location
-    @param y {Number} the y scroll location
+    @param {Number} x the x scroll location
+    @param {Number} y the y scroll location
     @returns {SC.ScrollView} receiver
   */
   scrollTo: function(x,y) {
@@ -490,12 +587,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
     
     if (!SC.none(x)) {
-      x = Math.max(this.get('minimumHorizontalScrollOffset'),Math.min(this.get('maximumHorizontalScrollOffset'), x)) ;
       this.set('horizontalScrollOffset', x) ;
     }
     
     if (!SC.none(y)) {
-      y = Math.max(this.get('minimumVerticalScrollOffset'),Math.min(this.get('maximumVerticalScrollOffset'), y)) ;
       this.set('verticalScrollOffset', y) ;
     }
     
@@ -511,8 +606,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     direction.  You can also optionally pass a Hash for the first parameter 
     with x and y coordinates.
     
-    @param x {Number} change in the x direction (or hash)
-    @param y {Number} change in the y direction
+    @param {Number} x change in the x direction (or hash)
+    @param {Number} y change in the y direction
     @returns {SC.ScrollView} receiver
   */
   scrollBy: function(x , y) {
@@ -557,7 +652,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   
   /**
     Scroll to the supplied rectangle.
-    @param {rect} Rectangle to scroll to.
+    @param {Rect} rect Rectangle to scroll to.
     @returns {Boolean} YES if scroll position was changed.
   */
   scrollToRect: function(rect) {
@@ -589,7 +684,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Scrolls the receiver down one or more lines if allowed.  If number of
     lines is not specified, scrolls one line.
     
-    @param lines {Number} options number of lines
+    @param {Number} lines number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollDownLine: function(lines) {
@@ -601,7 +696,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Scrolls the receiver up one or more lines if allowed.  If number of
     lines is not specified, scrolls one line.
     
-    @param lines {Number} options number of lines
+    @param {Number} lines number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollUpLine: function(lines) {
@@ -613,7 +708,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Scrolls the receiver right one or more lines if allowed.  If number of
     lines is not specified, scrolls one line.
     
-    @param lines {Number} options number of lines
+    @param {Number} lines number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollRightLine: function(lines) {
@@ -625,7 +720,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     Scrolls the receiver left one or more lines if allowed.  If number of
     lines is not specified, scrolls one line.
     
-    @param lines {Number} options number of lines
+    @param {Number} lines number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollLeftLine: function(lines) {
@@ -639,7 +734,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     the verticalPageScroll value.  By default this is the size of the current
     scrollable area.
     
-    @param pages {Number} options number of pages
+    @param {Number} pages number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollDownPage: function(pages) {
@@ -653,7 +748,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     the verticalPageScroll value.  By default this is the size of the current
     scrollable area.
     
-    @param pages {Number} options number of pages
+    @param {Number} pages number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollUpPage: function(pages) {
@@ -667,7 +762,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     the verticalPageScroll value.  By default this is the size of the current
     scrollable area.
     
-    @param pages {Number} options number of pages
+    @param {Number} pages number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollRightPage: function(pages) {
@@ -681,7 +776,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     the verticalPageScroll value.  By default this is the size of the current
     scrollable area.
     
-    @param pages {Number} options number of pages
+    @param {Number} pages number of lines
     @returns {SC.ScrollView} receiver
   */
   scrollLeftPage: function(pages) {
@@ -689,7 +784,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     return this.scrollBy(0-(this.get('horizontalPageScroll')*pages), null) ;
   },
   
-  /**
+  /** @private
     Adjusts the layout for the various internal views.  This method is called
     once when the scroll view is first configured and then anytime a scroller
     is shown or hidden.  You can call this method yourself as well to retile.
@@ -761,13 +856,15 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   // SCROLL WHEEL SUPPORT
   // 
   
-  /** @private */ _scroll_wheelDeltaX: 0,
-  /** @private */ _scroll_wheelDeltaY: 0,
+  /** @private */
+  _scroll_wheelDeltaX: 0,
+  
+  /** @private */
+  _scroll_wheelDeltaY: 0,
   
-  // save adjustment and then invoke the actual scroll code later.  This will
-  // keep the view feeling smooth.
+  /** @private */
   mouseWheel: function(evt) {
-    var deltaAdjust = (SC.browser.safari && SC.browser.version > 533.0) ? 120 : 1;
+    var deltaAdjust = (SC.browser.webkit && SC.browser.version > 533.0) ? 120 : 1;
     
     this._scroll_wheelDeltaX += evt.wheelDeltaX / deltaAdjust;
     this._scroll_wheelDeltaY += evt.wheelDeltaY / deltaAdjust;
@@ -798,13 +895,22 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   
   /**
     Determines whether scaling is allowed.
+    
+    @type Boolean
+    @default NO
   */
   canScale: NO,
   
-  /**
+  /** @private
     The current scale.
   */
   _scale: 1.0,
+  
+  /**
+    @field
+    @type Number
+    @default 1.0
+  */
   scale: function(key, value) {
     if (value !== undefined) {
       this._scale = Math.min(Math.max(this.get("minimumScale"), value), this.get("maximumScale"));
@@ -814,21 +920,32 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   
   /**
     The minimum scale.
+    
+    @type Number
+    @default 0.25
   */
   minimumScale: 0.25,
   
   /**
     The maximum scale.
+    
+    @type Number
+    @default 2.0
   */
   maximumScale: 2.0,
   
   /**
     Whether to automatically determine the scale range based on the size of the content.
+    
+    @type Boolean
+    @default NO
   */
   autoScaleRange: NO,
   
+  /** @private */
   _scale_css: "",
   
+  /** @private */
   updateScale: function(scale) {
     var contentView = this.get("contentView");
     if (!contentView) return;
@@ -841,35 +958,53 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
-  /*..............................................
-    TOUCH SUPPORT
+  
+  // ..........................................................
+  // Touch Support
+  // 
+  
+  /**
+    @type Boolean
+    @default YES
+    @readOnly
   */
   acceptsMultitouch: YES,
   
   /**
     The scroll deceleration rate.
+    
+    @type Number
+    @default SC.NORMAL_SCROLL_DECELERATION
   */
   decelerationRate: SC.NORMAL_SCROLL_DECELERATION,
   
   /**
     If YES, bouncing will always be enabled in the horizontal direction, even if the content
-    is smaller or the same size as the view. NO by default.
+    is smaller or the same size as the view.
+    
+    @type Boolean
+    @default NO
   */
   alwaysBounceHorizontal: NO,
   
   /**
     If NO, bouncing will not be enabled in the vertical direction when the content is smaller
-    or the same size as the scroll view. YES by default.
+    or the same size as the scroll view.
+    
+    @type Boolean
+    @default YES
   */
   alwaysBounceVertical: YES,
   
   /**
     Whether to delay touches from passing through to the content.
+    
+    @type Boolean
+    @default YES
   */
   delaysContentTouches: YES,
   
-  /**
-    @private
+  /** @private
     If the view supports it, this 
   */
   _touchScrollDidChange: function() {
@@ -890,6 +1025,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
+  /** @private */
   _touchScrollDidStart: function() {
     if (this.get("contentView").touchScrollDidStart) {
       this.get("contentView").touchScrollDidStart(this._scroll_horizontalScrollOffset, this._scroll_verticalScrollOffset);
@@ -904,6 +1040,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
+  /** @private */
   _touchScrollDidEnd: function() {
     if (this.get("contentView").touchScrollDidEnd) {
       this.get("contentView").touchScrollDidEnd(this._scroll_horizontalScrollOffset, this._scroll_verticalScrollOffset);
@@ -919,20 +1056,27 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
+  /** @private */
   _applyCSSTransforms: function(layer) {
     var transform = "";
     this.updateScale(this._scale);
     transform += 'translate3d('+ -this._scroll_horizontalScrollOffset +'px, '+ -Math.round(this._scroll_verticalScrollOffset)+'px,0) ';
     transform += this._scale_css;
-    layer.style.webkitTransform = transform;
-    layer.style.webkitTransformOrigin = "top left";
+    if (layer) {
+      layer.style.webkitTransform = transform;
+      layer.style.webkitTransformOrigin = "top left";
+    }
   },
   
+  /** @private */
   captureTouch: function(touch) {
     return YES;
   },
   
+  /** @private */
   touchGeneration: 0,
+  
+  /** @private */
   touchStart: function(touch) {
     var generation = ++this.touchGeneration;
     if (!this.tracking && this.get("delaysContentTouches")) {
@@ -946,6 +1090,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     return YES;
   },
 
+  /** @private */
   beginTouchesInContent: function(gen) {
     if (gen !== this.touchGeneration) return;
     
@@ -967,7 +1112,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
 
-  /**
+  /** @private
     Initializes the start state of the gesture.
 
     We keep information about the initial location of the touch so we can
@@ -1011,16 +1156,19 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     var globalFrame = this.convertFrameToView(this.get("frame"), null),
         positionInContentX = (horizontalScrollOffset + (avg.x - globalFrame.x)) / this._scale,
         positionInContentY = (verticalScrollOffset + (avg.y - globalFrame.y)) / this._scale;
-    
+
     this.touch = {
       startTime: touch.timeStamp,
       notCalculated: YES,
       
       enableScrolling: { 
         x: contentWidth * this._scale > containerWidth || this.get("alwaysBounceHorizontal"), 
-        y: contentHeight * this._scale > containerHeight || this.get("alwaysBounceVertical") }, // TODO: get from class properties
+        y: contentHeight * this._scale > containerHeight || this.get("alwaysBounceVertical") 
+      },
       scrolling: { x: NO, y: NO },
       
+      enableBouncing: SC.platform.bounceOnScroll,
+      
       // offsets and velocities
       startClipOffset: { x: startClipOffsetX, y: startClipOffsetY },
       lastScrollOffset: { x: horizontalScrollOffset, y: verticalScrollOffset },
@@ -1034,7 +1182,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       
       startScale: this._scale,
       startDistance: avg.d,
-      canScale: this.get("canScale"),
+      canScale: this.get("canScale") && SC.platform.pinchToZoom,
       minimumScale: this.get("minimumScale"),
       maximumScale: this.get("maximumScale"),
       
@@ -1079,6 +1227,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
+  /** @private */
   _adjustForEdgeResistance: function(offset, minOffset, maxOffset, resistanceCoefficient, asymptote) {
     var distanceFromEdge;
     
@@ -1098,11 +1247,13 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     return Math.min(Math.max(minOffset, offset), maxOffset) + distanceFromEdge;
   },
   
+  /** @private */
   touchesDragged: function(evt, touches) {
     var avg = evt.averagedTouchesForView(this);
     this.updateTouchScroll(avg.x, avg.y, avg.d, evt.timeStamp);
   },
   
+  /** @private */
   updateTouchScroll: function(touchX, touchY, distance, timeStamp) {
     // get some vars
     var touch = this.touch,
@@ -1160,7 +1311,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       if (deltaY > touch.scrollLock && !touch.scrolling.x) touch.enableScrolling.x = NO;
     }
     
-    // handle scaling
+    // handle scaling through pinch gesture
     if (touch.canScale) {
       
       var startDistance = touch.startDistance, dd = distance - startDistance;
@@ -1180,30 +1331,46 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       }
     }
     
-
+    // these do exactly what they sound like. So, this comment is just to
+    // block off the code a bit
+    // In english, these calculate the minimum X/Y offsets
     minOffsetX = this.minimumScrollOffset(touch.contentSize.width * this._scale, touch.containerSize.width, this.get("horizontalAlign"));
     minOffsetY = this.minimumScrollOffset(touch.contentSize.height * this._scale, touch.containerSize.height, this.get("verticalAlign"));
     
+    // and now, maximum...
     maxOffsetX = this.maximumScrollOffset(touch.contentSize.width * this._scale, touch.containerSize.width, this.get("horizontalAlign"));
     maxOffsetY = this.maximumScrollOffset(touch.contentSize.height * this._scale, touch.containerSize.height, this.get("verticalAlign"));
     
+    
+    // So, the following is the completely written out algebra:
     // (offsetY + touchYInFrame) / this._scale = touch.startTouchOffsetInContent.y
     // offsetY + touchYInFrame = touch.startTouchOffsetInContent.y * this._scale;
     // offsetY = touch.startTouchOffset * this._scale - touchYInFrame
+    
+    // and the result applied:
     offsetX = touch.startTouchOffsetInContent.x * this._scale - touchXInFrame;
     offsetY = touch.startTouchOffsetInContent.y * this._scale - touchYInFrame;
     
     
-    // update immediately, without consulting anyone else.
-    offsetX = this._adjustForEdgeResistance(offsetX, minOffsetX, maxOffsetX, touch.resistanceCoefficient, touch.resistanceAsymptote);
-    offsetY = this._adjustForEdgeResistance(offsetY, minOffsetY, maxOffsetY, touch.resistanceCoefficient, touch.resistanceAsymptote);
+    // we need to adjust for edge resistance, or, if bouncing is disabled, just stop flat.
+    if (touch.enableBouncing) {
+      offsetX = this._adjustForEdgeResistance(offsetX, minOffsetX, maxOffsetX, touch.resistanceCoefficient, touch.resistanceAsymptote);
+      offsetY = this._adjustForEdgeResistance(offsetY, minOffsetY, maxOffsetY, touch.resistanceCoefficient, touch.resistanceAsymptote);
+    } else {
+      offsetX = Math.max(minOffsetX, Math.min(maxOffsetX, offsetX));
+      offsetY = Math.max(minOffsetY, Math.min(maxOffsetY, offsetY));
+    }
     
+    // and now, _if_ scrolling is enabled, set the new coordinates
     if (touch.scrolling.x) this._scroll_horizontalScrollOffset = offsetX;
     if (touch.scrolling.y) this._scroll_verticalScrollOffset = offsetY;
     
+    // and apply the CSS transforms.
     this._applyCSSTransforms(touch.layer);
     this._touchScrollDidChange();
     
+    
+    // now we must prepare for momentum scrolling by calculating the momentum.
     if (timeStamp - touch.lastEventTime >= 1 || touch.notCalculated) {
       touch.notCalculated = NO;
       var horizontalOffset = this._scroll_horizontalScrollOffset;
@@ -1217,6 +1384,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
 
+  /** @private */
   touchEnd: function(touch) {
     var touchStatus = this.touch,
         avg = touch.averagedTouchesForView(this);
@@ -1263,6 +1431,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
   
+  /** @private */
   touchCancelled: function(touch) {
     var touchStatus = this.touch,
         avg = touch.averagedTouchesForView(this);
@@ -1285,6 +1454,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
 
+  /** @private */
   startDecelerationAnimation: function(evt) {
     var touch = this.touch;
     touch.decelerationVelocity = {
@@ -1295,8 +1465,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     this.decelerateAnimation();
   },
   
-  /**
-    @private
+  /** @private
     Does bounce calculations, adjusting velocity.
     
     Bouncing is fun. Functions that handle it should have fun names,
@@ -1334,6 +1503,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     return velocity;
   },
 
+  /** @private */
   decelerateAnimation: function() {
     // get a bunch of properties. They are named well, so not much explanation of what they are...
     // However, note maxOffsetX/Y takes into account the scale;
@@ -1354,6 +1524,11 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     
     var de = touch.decelerationFromEdge, ac = touch.accelerationToEdge;
     
+    // under a few circumstances, we may want to force a valid X/Y position.
+    // For instance, if bouncing is disabled, or if position was okay before
+    // adjusting scale.
+    var forceValidXPosition = !touch.enableBouncing, forceValidYPosition = !touch.enableBouncing;
+    
     // determine if position was okay before adjusting scale (which we do, in
     // a lovely, animated way, for the scaled out/in too far bounce-back).
     // if the position was okay, then we are going to make sure that we keep the
@@ -1361,8 +1536,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     //
     // Position OKness, here, referring to if the position is valid (within
     // minimum and maximum scroll offsets)
-    var validXPosition = newX >= minOffsetX && newX <= maxOffsetX;
-    var validYPosition = newY >= minOffsetY && newY <= maxOffsetY;
+    if (newX >= minOffsetX && newX <= maxOffsetX) forceValidXPosition = YES;
+    if (newY >= minOffsetY && newY <= maxOffsetY) forceValidYPosition = YES;
     
     // We are going to change scale in a moment, but the position should stay the
     // same, if possible (unless it would be more jarring, as described above, in
@@ -1410,15 +1585,21 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     maxOffsetY = this.maximumScrollOffset(touch.contentSize.height * this._scale, touch.containerSize.height, this.get("verticalAlign"));
     
     // see if scaling messed up the X position (but ignore if 'tweren't right to begin with).
-    if (validXPosition && (newX < minOffsetX || newX > maxOffsetX)) {
+    if (forceValidXPosition && (newX < minOffsetX || newX > maxOffsetX)) {
       // Correct the position
       newX = Math.max(minOffsetX, Math.min(newX, maxOffsetX));
+      
+      // also, make the velocity be ZERO; it is obviously not needed...
+      touch.decelerationVelocity.x = 0;
     }
     
     // now the y
-    if (validYPosition && (newY < minOffsetY || newY > maxOffsetY)) {
+    if (forceValidYPosition && (newY < minOffsetY || newY > maxOffsetY)) {
       // again, correct it...
       newY = Math.max(minOffsetY, Math.min(newY, maxOffsetY));
+      
+      // also, make the velocity be ZERO; it is obviously not needed...
+      touch.decelerationVelocity.y = 0;
     }
     
     
@@ -1428,9 +1609,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     
     this._applyCSSTransforms(touch.layer); // <- Does what it sounds like.
 
-    SC.RunLoop.begin();
     this._touchScrollDidChange();
-    SC.RunLoop.end();
     
     // Now we have to adjust the velocities. The velocities are simple x and y numbers that
     // get added to the scroll X/Y positions each frame.
@@ -1460,15 +1639,11 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     // as well.
     var absXVelocity = Math.abs(touch.decelerationVelocity.x);
     var absYVelocity = Math.abs(touch.decelerationVelocity.y);
-    if (absYVelocity < 0.01 && absXVelocity < 0.01 && Math.abs(sv) < 0.01) {
+    if (absYVelocity < 0.05 && absXVelocity < 0.05 && Math.abs(sv) < 0.05) {
       // we can reset the timeout, as it will no longer be required, and we don't want to re-cancel it later.
       touch.timeout = null;
       this.touch = null;
       
-      // we aren't in a run loop right now (see below, where we trigger the timer)
-      // so, we must start one.
-      SC.RunLoop.begin();
-      
       // trigger scroll end
       this._touchScrollDidEnd();
       
@@ -1480,8 +1655,6 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       this.set("horizontalScrollOffset", this._scroll_horizontalScrollOffset);
       this.endPropertyChanges();
       
-      // and now we're done, so just end the run loop and return.
-      SC.RunLoop.end();
       return;
     }
     
@@ -1493,7 +1666,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     var self = this;
     touch.lastEventTime = Date.now();
     this.touch.timeout = setTimeout(function(){
-      self.decelerateAnimation();
+      SC.run(self.decelerateAnimation(), self);
     }, 10);
   },
   
@@ -1551,6 +1724,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     this.tile() ; // set up initial tiling
   },
   
+  /** @private */
   init: function() {
     sc_super();
     
@@ -1561,13 +1735,17 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     var contentView = this._scroll_contentView ;
 
     if (contentView) {
-      contentView.addObserver('frame', this, this.contentViewFrameDidChange) ;
+      contentView.addObserver('frame', this, this.contentViewFrameDidChange);
+      contentView.addObserver('calculatedWidth', this, this.contentViewFrameDidChange);
+      contentView.addObserver('calculatedHeight', this, this.contentViewFrameDidChange);
     }
 
     if (this.get('isVisibleInWindow')) this._scsv_registerAutoscroll() ;
   },
   
-  /** @private Registers/deregisters view with SC.Drag for autoscrolling */
+  /** @private
+    Registers/deregisters view with SC.Drag for autoscrolling
+  */
   _scsv_registerAutoscroll: function() {
     if (this.get('isVisibleInWindow')) SC.Drag.addScrollableView(this);
     else SC.Drag.removeScrollableView(this);
@@ -1587,6 +1765,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       
       // stop observing old content view
       if (oldView) {
+        oldView.removeObserver('calculatedWidth', this, this.contentViewFrameDidChange);
+        oldView.removeObserver('calculatedHeight', this, this.contentViewFrameDidChange);
         oldView.removeObserver('frame', this, frameObserver);
         oldView.removeObserver('layer', this, layerObserver);
       }
@@ -1595,6 +1775,8 @@ SC.ScrollView = SC.View.extend(SC.Border, {
       this._scroll_contentView = newView;
       if (newView) {
         newView.addObserver('frame', this, frameObserver);
+        newView.addObserver('calculatedWidth', this, this.contentViewFrameDidChange);
+        newView.addObserver('calculatedHeight', this, this.contentViewFrameDidChange);
         newView.addObserver('layer', this, layerObserver);
       }
       
@@ -1613,12 +1795,19 @@ SC.ScrollView = SC.View.extend(SC.Border, {
   */
   render: function(context, firstTime) {
     this.invokeLast(this.adjustElementScroll);
+
     if (firstTime) {
       context.push('<div class="corner"></div>');
     }
     return sc_super();
   },
 
+  /** @private */
+  oldMaxHOffset: 0,
+  
+  /** @private */
+  oldMaxVOffset: 0,
+
   /** @private
     Invoked whenever the contentView's frame changes.  This will update the 
     scroller maxmimum and optionally update the scroller visibility if the
@@ -1627,18 +1816,24 @@ SC.ScrollView = SC.View.extend(SC.Border, {
 
     @param {Boolean} force (optional)  Re-calculate everything even if the contentView’s frame didn’t change size
   */
-
-  oldMaxHOffset: 0,
-  oldMaxVOffset: 0,
-
   contentViewFrameDidChange: function(force) {
     var view   = this.get('contentView'), 
         f      = (view) ? view.get('frame') : null,
         scale  = this._scale,
-        width  = (f) ? f.width  * scale : 0,
-        height = (f) ? f.height * scale : 0,
-        dim, dimWidth, dimHeight;
-    
+        width  = 0,
+        height = 0,
+        dim, dimWidth, dimHeight, calculatedWidth, calculatedHeight;
+
+    // If no view has been set yet, or it doesn't have a frame,
+    // we can avoid doing any work.
+    if (!view || !f) { return; }
+
+    width = view.get('calculatedWidth') || f.width || 0;
+    height = view.get('calculatedHeight') || f.height || 0;
+
+    width *= scale;
+    height *= scale;
+
     // cache out scroll settings...
     if (!force && (width === this._scroll_contentWidth) && (height === this._scroll_contentHeight)) return ;
     this._scroll_contentWidth  = width;
@@ -1742,14 +1937,12 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     // This gives views that use incremental rendering a chance to render
     // newly-appearing elements before they come into view.
     if (content) {
-      SC.RunLoop.begin();
-      content._viewFrameDidChange();
-      SC.RunLoop.end();
-
       // Use accelerated drawing if the browser supports it
       if (SC.platform.touch) {
         this._applyCSSTransforms(content.get('layer'));
       }
+
+      if (content._viewFrameDidChange) { content._viewFrameDidChange(); }
     }
 
     if (container && !SC.platform.touch) {
@@ -1769,6 +1962,7 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
 
+  /** @private */
   forceDimensionsRecalculation: function (forceWidth, forceHeight, vOffSet, hOffSet) {
     var oldScrollHOffset = hOffSet;
     var oldScrollVOffset = vOffSet;
@@ -1784,7 +1978,10 @@ SC.ScrollView = SC.View.extend(SC.Border, {
     }
   },
 
+  /** @private */
   _scroll_verticalScrollOffset: 0,
+  
+  /** @private */
   _scroll_horizontalScrollOffset: 0
   
 });