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

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

@@ -21,7 +21,6 @@
   be surrounded by two other views.
 
   @extends SC.View
-
   @author Charles Jolley
   @author Lawrence Pit
   @author Erich Ocean
@@ -30,20 +29,28 @@
 SC.SplitDividerView = SC.View.extend(
 /** @scope SC.SplitDividerView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-split-divider-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-split-divider-view'],
   
   /** @private */
 
+  /** @private */
   mouseDown: function(evt) {
     var splitView = this.get('splitView');
     return (splitView) ? splitView.mouseDownInThumbView(evt, this) : sc_super();
   },
   
+  /** @private */
   doubleClick: function(evt) {
     var splitView = this.get('splitView');
     return (splitView) ? splitView.doubleClickInThumbView(evt, this) : sc_super();
   },
   
+  /** @private */
   touchStart: function(evt){
     return this.mouseDown(evt);
   }

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

@@ -16,7 +16,7 @@ sc_require('views/collection') ;
   collections with complex displays and variable heights such as comments or
   small notification queues.
   
-  h2. Static Layout
+  ## Static Layout
   
   This view makes no attempt to size or position your child views.  It assumes
   you are using StaticLayout for your child views.  If you don't enable static
@@ -29,20 +29,30 @@ sc_require('views/collection') ;
   @extends SC.CollectionView
   @since SproutCore 0.9
 */
-SC.StackedView = SC.CollectionView.extend( 
-/** SC.StackedView.prototype */ {
+SC.StackedView = SC.CollectionView.extend(
+/** @scope SC.StackedView.prototype */ {
   
+  /**
+    @type Array
+    @default ['sc-stacked-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-stacked-view'],
   
   /** 
     Default layout for a stacked view will fill the parent view but auto-
     adjust the height of the view.
+    
+    @type Hash
+    @default `{ top: 0, left: 0, right: 0, height: 1 }`
+    @see SC.View#layout
   */
   layout: { top: 0, left: 0, right: 0, height: 1 },
   
   /**
     Return full range of its indexes for nowShowing
     
+    @param {Rect} rect
     @returns {SC.IndexSet} full range of indexes
   */
   computeNowShowing: function(rect) {
@@ -74,6 +84,7 @@ SC.StackedView = SC.CollectionView.extend(
     return this;
   },
   
+  /** @private */
   _updateHeight: function() {
     
     var childViews = this.get('childViews'),

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

@@ -26,13 +26,24 @@
   @since SproutCore 1.2
   @author Tom Dale
 */
+SC.StaticContentView = SC.View.extend(SC.StaticLayout,
+/** @scope SC.StaticContentView.prototype */ {
 
-SC.StaticContentView = SC.View.extend(SC.StaticLayout, {
-/** @scope SC.StaticContentView.prototype */
+  /**
+    @type Array
+    @default ['sc-static-content-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-static-content-view'],
 
+  /**
+    @type Array
+    @default ['content']
+    @see SC.View#displayProperties
+  */
   displayProperties: ['content'],
 
+
   // ..........................................................
   // PROPERTIES
   //
@@ -42,6 +53,7 @@ SC.StaticContentView = SC.View.extend(SC.StaticLayout, {
     the DOM, so ensure that any user-generated content has been escaped.
 
     @type String
+    @default null
   */
   content: null,
 
@@ -121,11 +133,13 @@ SC.StaticContentView = SC.View.extend(SC.StaticLayout, {
     }
   },
   
+  /** @private */
   touchStart: function(evt){
     evt.allowDefault();
     return YES;
   },
   
+  /** @private */
   touchEnd: function(evt){
     evt.allowDefault();
     return YES;

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

@@ -7,8 +7,25 @@
 
 sc_require('views/segmented');
 
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.TOP_LOCATION = 'top';
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.TOP_TOOLBAR_LOCATION = 'top-toolbar';
+
+/**
+  @static
+  @type String
+  @constant
+*/
 SC.BOTTOM_LOCATION = 'bottom';
 
 /** 
@@ -24,8 +41,18 @@ SC.BOTTOM_LOCATION = 'bottom';
 SC.TabView = SC.View.extend(
 /** @scope SC.TabView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-tab-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-tab-view'],
   
+  /**
+    @type Array
+    @default ['nowShowing']
+    @see SC.View#displayProperties
+  */
   displayProperties: ['nowShowing'],
 
   // ..........................................................
@@ -34,27 +61,85 @@ SC.TabView = SC.View.extend(
 
  /** 
     Set nowShowing with the page you want to display.
+    
+    @type String
+    @default null
   */
   nowShowing: null,
   
+  /**
+    @type Array
+    @default []
+  */
   items: [],
   
+  /**
+    @type Boolean
+    @default YES
+  */
   isEnabled: YES,
   
+  /**
+    @type String
+    @default null
+  */
   itemTitleKey: null,
+  
+  /**
+    @type String
+    @default null
+  */
   itemValueKey: null,
+  
+  /**
+    @type String
+    @default null
+  */
   itemIsEnabledKey: null,
+  
+  /**
+    @type String
+    @default null
+  */
   itemIconKey: null,
+  
+  /**
+    @type String
+    @default null
+  */
   itemWidthKey: null,
+  
+  /**
+    @type String
+    @default null
+  */
   itemToolTipKey: null,
+  
+  /**
+    @type Number
+    @default SC.REGULAR_BUTTON_HEIGHT
+  */
   tabHeight: SC.REGULAR_BUTTON_HEIGHT,
   
+  /**
+    Possible values:
+    
+      - SC.TOP_LOCATION
+      - SC.TOP_TOOLBAR_LOCATION
+      - SC.BOTTOM_LOCATION
+    
+    @type String
+    @default SC.TOP_LOCATION
+  */
   tabLocation: SC.TOP_LOCATION,
   
   /** 
     If set, then the tab location will be automatically saved in the user
     defaults.  Browsers that support localStorage will automatically store
     this information locally.
+    
+    @type String
+    @default null
   */
   userDefaultKey: null,
   
@@ -64,6 +149,7 @@ SC.TabView = SC.View.extend(
   // 
   
   // forward important changes on to child views
+  /** @private */
   _tab_nowShowingDidChange: function() {
     var v = this.get('nowShowing');
     this.get('containerView').set('nowShowing',v);
@@ -71,6 +157,7 @@ SC.TabView = SC.View.extend(
     return this ;
   }.observes('nowShowing'),
 
+  /** @private */
   _tab_saveUserDefault: function() {
     // if user default is set, save also
     var v = this.get('nowShowing');
@@ -80,6 +167,7 @@ SC.TabView = SC.View.extend(
     }
   }.observes('nowShowing'),
   
+  /** @private */
   _tab_itemsDidChange: function() {
     this.get('segmentedView').set('items', this.get('items'));
     return this ;    
@@ -93,6 +181,7 @@ SC.TabView = SC.View.extend(
     this._tab_nowShowingDidChange()._tab_itemsDidChange();
   },
 
+  /** @private */
   awake: function() {
     sc_super();  
     var defaultKey = this.get('userDefaultKey');
@@ -104,6 +193,7 @@ SC.TabView = SC.View.extend(
 
   },
   
+  /** @private */
   createChildViews: function() {
     var childViews  = [], view, containerView, layout,
         tabLocation = this.get('tabLocation'),
@@ -151,6 +241,7 @@ SC.TabView = SC.View.extend(
         this.invokeOnce(this.updateLayerIfNeeded) ;
       }.observes('value'),
 
+      /** @private */
       init: function() {
         // before we setup the rest of the view, copy key config properties 
         // from the owner view...
@@ -177,9 +268,17 @@ SC.TabView = SC.View.extend(
     The containerView managed by this tab view.  Note that TabView uses a 
     custom container view.  You can access this view but you cannot change 
     it.
+    
+    @type SC.View
+    @default SC.ContainerView
+    @readOnly
   */
   containerView: SC.ContainerView.extend({ renderDelegateName: 'wellRenderDelegate' }),
   
+  /**
+    @type SC.View
+    @default SC.SegmentedView
+  */
   segmentedView: SC.SegmentedView
   
 }) ;

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

@@ -24,12 +24,22 @@
 SC.ThumbView = SC.View.extend(
 /** @scope SC.ThumbView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-thumb-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-thumb-view'],
   
   /**
     Enable this thumb view to control its parent split view.
+    
+    @type Boolean
+    @default YES
   */
   isEnabled: YES,
+  
+  /** @private */
   isEnabledBindingDefault: SC.Binding.bool(),
   
   /** @private */
@@ -39,6 +49,7 @@ SC.ThumbView = SC.View.extend(
     return sc_super() ;
   },
   
+  /** @private */
   mouseDown: function(evt) {
     if (!this.get('isEnabled')) return NO ;
     
@@ -46,8 +57,9 @@ SC.ThumbView = SC.View.extend(
     return (splitView) ? splitView.mouseDownInThumbView(evt, this) : sc_super();
   },
   
+  /** @private */
   touchStart: function(evt) {
     return this.mouseDown(evt);
   }
-    
+
 });

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

@@ -7,31 +7,61 @@
 
 /**
   Layout properties needed to anchor a view to the top.
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ top: 0 }`
 */
 SC.ANCHOR_TOP = { top: 0 };
 
 /**
   Layout properties needed to anchor a view to the left.
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ left: 0 }`
 */
 SC.ANCHOR_LEFT = { left: 0 };
 
 /*
   Layout properties to anchor a view to the top left
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ top: 0, left: 0 }`
 */
 SC.ANCHOR_TOP_LEFT = { top: 0, left: 0 };
 
 /**
   Layout properties to anchoe view to the bottom.
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ bottom: 0 }`
 */
 SC.ANCHOR_BOTTOM = { bottom: 0 };
 
 /**
   Layout properties to anchor a view to the right.
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ right: 0 }`
 */
 SC.ANCHOR_RIGHT = { right: 0 } ;
 
 /**
   Layout properties to anchor a view to the bottom right.
+  
+  @static
+  @constant
+  @type Hash
+  @default `{ top: 0, right: 0 }`
 */
 SC.ANCHOR_BOTTOM_RIGHT = { bottom: 0, right: 0 };
 
@@ -41,7 +71,7 @@ SC.ANCHOR_BOTTOM_RIGHT = { bottom: 0, right: 0 };
   your main toolbar buttons.
 
   You can also override the layout property yourself or simply set the
-  anchorLocation to SC.ANCHOR_TOP or SC.ANCHOR_BOTTOM.  This will configure
+  anchorLocation to `SC.ANCHOR_TOP` or `SC.ANCHOR_BOTTOM`.  This will configure
   the layout of your toolbar automatically when it is created.
 
   @extends SC.View
@@ -50,19 +80,41 @@ SC.ANCHOR_BOTTOM_RIGHT = { bottom: 0, right: 0 };
 SC.ToolbarView = SC.View.extend(
 /** @scope SC.ToolbarView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-toolbar-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-toolbar-view'],
 
   /**
-    The WAI-ARIA role for toolbar view. This property's value should not be
-    changed.
+    The WAI-ARIA role for toolbar view.
 
-    @property {String}
+    @type String
+    @default 'toolbar'
+    @readOnly
   */
   ariaRole: 'toolbar',
 
+  /**
+    @type String
+    @default 'toolbarRenderDelegate'
+  */
+  renderDelegateName: 'toolbarRenderDelegate',
+
   /**
     Default anchor location.  This will be applied automatically to the
-    toolbar layout if you set it.
+    toolbar layout if you set it. Possible values:
+    
+      - SC.ANCHOR_TOP
+      - SC.ANCHOR_LEFT
+      - SC.ANCHOR_TOP_LEFT
+      - SC.ANCHOR_BOTTOM
+      - SC.ANCHOR_RIGHT
+      - SC.ANCHOR_BOTTOM_RIGHT
+    
+    @type String
+    @default null
   */
   anchorLocation: null,
 
@@ -80,9 +132,7 @@ SC.ToolbarView = SC.View.extend(
       this.layout = SC.merge(this.layout, this.anchorLocation);
     }
     sc_super();
-  },
-
-  renderDelegateName: 'toolbarRenderDelegate'
+  }
 
 });
 

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

@@ -4,6 +4,7 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 /** @class
 
   Used to display an iframe. The source, (specified by the value property) of 
@@ -14,21 +15,36 @@
   @extends SC.Control
   @since SproutCore 1.0
 */
-SC.WebView = SC.View.extend(SC.Control, {
-/** @scope SC.WebView.prototype */
+SC.WebView = SC.View.extend(SC.Control,
+/** @scope SC.WebView.prototype */ {
+
+  /**
+    @type Array
+    @default ['sc-web-view']
+    @see SC.View#classNames
+  */
   classNames: 'sc-web-view',
+  
+  /**
+    @type Array
+    @default ['value', 'shouldAutoResize']
+    @see SC.View#displayProperties
+  */
   displayProperties: ['value', 'shouldAutoResize'],
 
   /**
-  The content of the iframe can be bigger than the size specifed when creating
-  the view. If you want the view to be auto-resized to the dimensions of the 
-  iframe, then set the value of this property to YES.
-  The web view can be auto resized only if the contents are from the same
-  domain as the parent domain.
-  @property{Boolean}
+    The content of the iframe can be bigger than the size specifed when creating
+    the view. If you want the view to be auto-resized to the dimensions of the 
+    iframe, then set the value of this property to YES.
+    The web view can be auto resized only if the contents are from the same
+    domain as the parent domain.
+
+    @type Boolean
+    @default NO
   */
   shouldAutoResize: NO,
 
+  /** @private */
   render: function(context, firstTime) {
     var src = this.get('value');
     if (firstTime) {
@@ -42,7 +58,7 @@ SC.WebView = SC.View.extend(SC.Control, {
     }
   },
 
-  /**
+  /** @private
   Called when the layer gets created. 
   */
   didCreateLayer: function() {
@@ -52,14 +68,13 @@ SC.WebView = SC.View.extend(SC.Control, {
   },
 
 
-  /** 
-  Called when iframe onload event is fired.
-  1. Resizes the view to fit the contents of the iframe using the 
-  scroll width and scroll height of the contents of the iframe
+  /**  @private
+    Called when iframe onload event is fired.
+    1. Resizes the view to fit the contents of the iframe using the 
+    scroll width and scroll height of the contents of the iframe
   
-  The iframe contents can be accessed only when the src is from the same
-  domain as the parent document
-  @returns {void}
+    The iframe contents can be accessed only when the src is from the same
+    domain as the parent document
   */
   iframeDidLoad: function() {
     //fit the iframe to size of the contents.
@@ -75,13 +90,14 @@ SC.WebView = SC.View.extend(SC.Control, {
           //TODO: try out document flows other than top to bottom.
           if (!SC.browser.isIE){
             this.$().width(docElement.scrollWidth);
-            this.$().height(docElement.scrollHeight);          
+            this.$().height(docElement.scrollHeight);
           } else {
             this.$().width(docElement.scrollWidth + 12);
-            this.$().height(docElement.scrollHeight + 5);          
+            this.$().height(docElement.scrollHeight + 5);
           }
         }
       }
     }
   }
+
 });

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

@@ -5,8 +5,13 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-// Constants
-SC.WELL_CONTAINER_PADDING=15;
+/**
+  @static
+  @constant
+  @type Number
+  @default 15
+*/
+SC.WELL_CONTAINER_PADDING = 15;
 
 /** @class
 
@@ -22,22 +27,34 @@ SC.WELL_CONTAINER_PADDING=15;
 SC.WellView = SC.ContainerView.extend(
 /** @scope SC.WellView.prototype */ {
   
+  /**
+    @type Array
+    @default ['sc-well-view']
+    @see SC.View#classNames
+  */
   classNames: 'sc-well-view',
   
   /**
     Layout for the content of the container view.
-    @property {Object}
+    @type Hash
   */
   contentLayout: {
-    top:SC.WELL_CONTAINER_PADDING, bottom:SC.WELL_CONTAINER_PADDING,
-    left:SC.WELL_CONTAINER_PADDING, right:SC.WELL_CONTAINER_PADDING},
-  
+    top: SC.WELL_CONTAINER_PADDING,
+    bottom: SC.WELL_CONTAINER_PADDING,
+    left: SC.WELL_CONTAINER_PADDING,
+    right: SC.WELL_CONTAINER_PADDING
+  },
   
   /**
+    @type String
+    @default 'wellRenderDelegate'
+  */
+  renderDelegateName: 'wellRenderDelegate',
+  
+  /** @private
      Overrides createChildViews and replaces the layout of the contentView
      with the one in contentLayout.
    */
-  
   createChildViews: function() {
     // if contentView is defined, then create the content
     var view = this.get('contentView') ;
@@ -48,8 +65,7 @@ SC.WellView = SC.ContainerView.extend(
     } 
   },
 
-  renderDelegateName: 'wellRenderDelegate',
-  /**
+  /** @private
      Invoked whenever the content property changes.  This method will simply
      call replaceContent and set the contentLayout in the new contentView.