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

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

@@ -19,8 +19,14 @@ sc_require('views/scroll');
   @extends SC.ScrollerView
   @since SproutCore 1.0
 */
+SC.MenuScrollerView = SC.ScrollerView.extend(
+/** @scope SC.MenuScrollerView.prototype */ {
 
-SC.MenuScrollerView = SC.ScrollerView.extend({
+  /**
+    @type Array
+    @default ['sc-menu-scroller-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-menu-scroller-view'],
   
   // ..........................................................
@@ -28,7 +34,10 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
   // 
   
   /**
-   Used to set the scrolling direction of the scroller.
+    Used to set the scrolling direction of the scroller.
+    
+    @type Boolean
+    @default NO
   */
   scrollDown: NO,
   
@@ -36,7 +45,9 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     The scroller offset value.  This value will adjust between the minimum
     and maximum values that you set. Default is 0.
     
-    @property
+    @field
+    @type Number
+    @observes maximum
   */
   value: function(key, val) {
     if (val !== undefined) {
@@ -56,7 +67,8 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     
     When set less than the height of the scroller, the scroller is disabled.
     
-    @property {Number}
+    @type Number
+    @default 0
   */
   maximum: 0,
   
@@ -64,22 +76,30 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     YES if enable scrollbar, NO to disable it.  Scrollbars will automatically 
     disable if the maximum scroll width does not exceed their capacity.
     
-    @property
+    @type Boolean
+    @default YES
   */
   isEnabled: YES,
   
   /**
     Determine the layout direction.  Determines whether the scrollbar should 
     appear horizontal or vertical.  This must be set when the view is created.
-    Changing this once the view has been created will have no effect.
+    Changing this once the view has been created will have no effect. Possible
+    values:
     
-    @property
+      - SC.LAYOUT_VERTICAL
+      - SC.LAYOUT_HORIZONTAL
+    
+    @type String
+    @default SC.LAYOUT_VERTICAL
   */
   layoutDirection: SC.LAYOUT_VERTICAL,
   
   /** 
      Amount to scroll one vertical line.
-     Defaults to 20px.
+     
+     @type Number
+     @default 20
   */
   verticalLineScroll: 20,
 
@@ -87,16 +107,20 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     This function overrides the default function in SC.Scroller as 
     menus only have vertical scrolling.
     
-    @property {String}
+    @field
+    @type String
+    @default 'verticalScrollOffset'
   */
   ownerScrollValueKey: function() {
-    return 'verticalScrollOffset' ;  
+    return 'verticalScrollOffset';
   }.property('layoutDirection').cacheable(),
 
+
   // ..........................................................
   // INTERNAL SUPPORT
   //
 
+  /** @private */
   init: function() {
     // Set the scrollerThickness based on controlSize
     switch (this.get('controlSize')) {
@@ -120,6 +144,7 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     return sc_super();
   },
   
+  /** @private */
   render: function(context, firstTime) {
     context.addClass('sc-vertical') ;
     context.addClass(this.get('controlSize'));
@@ -130,6 +155,7 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     context.setClass('disabled', !this.get('isEnabled')) ;
   },
   
+  /** @private */
   didCreateLayer: function() {
     // var callback, amt, layer;
     // 
@@ -143,33 +169,32 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     // layer.scrollTop = amt ;
   },
   
+  /** @private */
   willDestroyLayer: function() {
     var callback = this._sc_scroller_scrollDidChange ;
     SC.Event.remove(this.$(), 'scroll', this, callback) ;
   },
   
+  /** @private */
   mouseEntered: function(evt) {
     this.set('isMouseOver', YES);
     this._invokeScrollOnMouseOver();
   },
   
+  /** @private */
   mouseExited: function(evt) {
     this.set('isMouseOver', NO);
   },
   
-  /** @private */
-  
   /**
-    This function overrides the default function in SC.Scroller. 
+    This function overrides the default function in SC.Scroller.
     SC.MenuScroller and SC.MenuScroll use valueBinding so this function is
     not neccesary.
   */
-  _sc_scroller_valueDidChange: function() {
-    
-  }.observes('value'),
+  _sc_scroller_valueDidChange: function() {}.observes('value'),
   
 
-  // after 50msec, fire event again
+  /** @private */
   _sc_scroller_armScrollTimer: function() {
     if (!this._sc_scrollTimer) {
       SC.RunLoop.begin() ;
@@ -179,6 +204,7 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     }
   },
   
+  /** @private */
   _sc_scroller_scrollDidChange: function() {
     var now = Date.now(), 
         last = this._sc_lastScroll, 
@@ -200,7 +226,7 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
   },
   
   
-  /**
+  /** @private
     Scroll the menu if it is is an up or down arrow. This is called by
     the function that simulates mouseOver.
   */
@@ -223,7 +249,8 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
     return YES;
   },
   
-  /**
+  /** @private
+    
     We use this function to simulate mouseOver. It checks for the flag 
     isMouseOver which is turned on when mouseEntered is called and turned off
     when mouseExited is called. 
@@ -238,12 +265,38 @@ SC.MenuScrollerView = SC.ScrollerView.extend({
 });
 
 /**
-  Default metrics for scroller size.
+  @static
+  @type Number
+  @default 18
 */
 SC.MenuScrollerView.REGULAR_SCROLLER_THICKNESS = 18;
+
+/**
+  @static
+  @type Number
+  @default 10
+*/
 SC.MenuScrollerView.TINY_SCROLLER_THICKNESS    = 10;
+
+/**
+  @static
+  @type Number
+  @default 14
+*/
 SC.MenuScrollerView.SMALL_SCROLLER_THICKNESS   = 14;
+
+/**
+  @static
+  @type Number
+  @default 23
+*/
 SC.MenuScrollerView.LARGE_SCROLLER_THICKNESS   = 23;
+
+/**
+  @static
+  @type Number
+  @default 26
+*/
 SC.MenuScrollerView.HUGE_SCROLLER_THICKNESS    = 26;
 
 
@@ -259,10 +312,17 @@ SC.MenuScrollerView.HUGE_SCROLLER_THICKNESS    = 26;
   @extends SC.ScrollView
   @since SproutCore 1.0
 */
-SC.MenuScrollView = SC.ScrollView.extend({
+SC.MenuScrollView = SC.ScrollView.extend(
+/** @scope SC.MenuScrollView.prototype */{
 
+  /**
+    @type Array
+    @default ['sc-menu-scroll-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-menu-scroll-view'],
   
+  
   // ..........................................................
   // PROPERTIES
   // 
@@ -273,7 +333,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     size and the size of the scroll view.  If horizontal scrolling is 
     disabled, this will always return 0.
     
-    @property {Number}
+    @type Number
+    @default 0
   */
   maximumHorizontalScrollOffset: 0,
     
@@ -286,7 +347,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     YES if the view should maintain a horizontal scroller.   This property 
     must be set when the view is created.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   hasHorizontalScroller: NO,
   
@@ -295,7 +357,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     instance when the ScrollView is created unless hasHorizontalScroller is 
     NO.
     
-    @property {SC.View}
+    @type SC.View
+    @default SC.MenuScrollerView
   */
   horizontalScrollerView: SC.MenuScrollerView,
   
@@ -306,7 +369,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     hasHorizontalScroller to NO to avoid creating a scroller view in the 
     first place.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isHorizontalScrollerVisible: NO,
 
@@ -314,14 +378,18 @@ SC.MenuScrollView = SC.ScrollView.extend({
     Returns YES if the view both has a horizontal scroller, the scroller is
     visible.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   canScrollHorizontal: NO,
    
   /**
     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 NO
   */
   autohidesHorizontalScroller: NO,
   
@@ -329,7 +397,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     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,
   
@@ -337,7 +406,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     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.MenuScrollerView
   */
   verticalScrollerView: SC.MenuScrollerView,
   verticalScrollerView2: SC.MenuScrollerView,
@@ -346,17 +416,24 @@ SC.MenuScrollView = SC.ScrollView.extend({
     YES if the vertical scroller should be visible.  For SC.MenuScroll the
     vertical scroller is always there we just hide the arrows to scroll.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isVerticalScrollerVisible: YES,
 
-  
+  /**
+    @type Boolean
+    @default YES
+  */
   canScrollVertical: YES,
 
   /**
     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,
   
@@ -364,7 +441,8 @@ SC.MenuScrollView = SC.ScrollView.extend({
     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,
   
@@ -375,6 +453,9 @@ SC.MenuScrollView = SC.ScrollView.extend({
 
   /**
     Control Size for Menu content: change verticalLineScroll
+    
+    @type String
+    @default SC.REGULAR_CONTROL_SIZE
   */
   controlSize: SC.REGULAR_CONTROL_SIZE,
   
@@ -382,13 +463,18 @@ SC.MenuScrollView = SC.ScrollView.extend({
     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.ContainerView
   */
   containerView: SC.ContainerView,
 
   // ..........................................................
   // METHODS
   //
+  
+  /**
+    @param {SC.View} view
+  */
   scrollToVisible: function(view) {
     // if no view is passed, do default
     if (arguments.length === 0) return sc_super();
@@ -418,7 +504,7 @@ SC.MenuScrollView = SC.ScrollView.extend({
     return this.scrollToRect(vf);
   },
 
-  /**
+  /** @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.
@@ -536,6 +622,7 @@ SC.MenuScrollView = SC.ScrollView.extend({
     this.tile() ; // set up initial tiling
   },
   
+  /** @private */
   init: function() {
     sc_super();
     

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

@@ -5,7 +5,22 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-SC.TO_LEFT = "TOLEFT"; SC.TO_RIGHT = "TORIGHT";
+sc_require("views/workspace");
+
+/**
+  @static
+  @type String
+  @constant
+*/
+SC.TO_LEFT = "TOLEFT";
+
+/**
+  @static
+  @type String
+  @constant
+*/
+SC.TO_RIGHT = "TORIGHT";
+
 
 /** @class
 
@@ -20,26 +35,31 @@ SC.TO_LEFT = "TOLEFT"; SC.TO_RIGHT = "TORIGHT";
   Of course, this process is animated...
   
   @author Alex Iskander
-  @since SproutCore Quilmes
+  @extends SC.WorkspaceView
+  @since SproutCore 1.4
 */
-
-sc_require("views/workspace");
-SC.NavigationView = SC.WorkspaceView.extend({
+SC.NavigationView = SC.WorkspaceView.extend(
+/** @scope SC.NavigationView.prototype */ {
+  
+  /** @private */
   _views: null,
+  
+  /** @private */
   _current: null,
-  navigationContentView: SC.View.extend(),
   
   /**
-    Initializes the NavigationView by creating the view stack.
+    @type SC.View
+    @default SC.View
   */
+  navigationContentView: SC.View,
+  
+  /** @private */
   init: function() {
     sc_super();
     this._views = [];
   },
   
-  /**
-    Creates the navigation content view and places it inside the content view.
-  */
+  /** @private */
   createChildViews: function() {
     sc_super();
     
@@ -56,10 +76,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
     this.contentView.appendChild(content);
   },
   
-  /**
-    @private
-    Changes the content of the navigation, updating toolbars, etc., as needed.
-  */
+  /** @private */
   changeNavigationContent: function(view) {
     var top = null, bottom = null;
     
@@ -97,6 +114,8 @@ SC.NavigationView = SC.WorkspaceView.extend({
   
   /**
     Pushes a view into the navigation view stack. The view may have topToolbar and bottomToolbar properties.
+    
+    @param {SC.View} view The view to display
   */
   push: function(view) {
     this._currentDirection = this._current ? SC.TO_LEFT : null;
@@ -109,7 +128,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
   },
   
   /**
-    Pops a view off the navigation view stack.
+    Pops the current view off the navigation view stack.
   */
   pop: function() {
     this._currentDirection = SC.TO_RIGHT;
@@ -123,6 +142,8 @@ SC.NavigationView = SC.WorkspaceView.extend({
   
   /**
     Pops to the specified view on the navigation view stack; the view you pass will become the current view.
+    
+    @param {SC.View} toView The view to display
   */
   popToView: function(toView) {
     this._currentDirection = SC.TO_RIGHT;
@@ -141,7 +162,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
     this.changeNavigationContent(view);
   },
   
-  
+  /** @private */
   topToolbarDidChange: function() {
     var active = this.activeTopToolbar, replacement = this.get("topToolbar");
     
@@ -170,6 +191,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
     this.invokeOnce("childDidChange");
   }.observes("topToolbar"),
   
+  /** @private */
   bottomToolbarDidChange: function() {
     var active = this.activeBottomToolbar, replacement = this.get("bottomToolbar");
     
@@ -194,6 +216,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
     this.invokeOnce("childDidChange");
   }.observes("topToolbar"),
   
+  /** @private */
   contentViewDidChange: function() {
     var active = this.activeNavigationContentView, replacement = this.get("navigationContentView");
     
@@ -211,6 +234,7 @@ SC.NavigationView = SC.WorkspaceView.extend({
     this.invokeOnce("childDidChange");
   }.observes("navigationContentView"),
   
+  /** @private */
   childDidChange: function() {
     var replacement = this._pendingBuildIn, active = this._pendingBuildOut;
     if (active) {

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

@@ -13,13 +13,13 @@ sc_require("views/toolbar");
   that handle, well, swiping. In short, they are neat.
   
   @extends SC.ToolbarView
+  @extends SC.Gesturable
   @since SproutCore 1.0
 */
-SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
-  gestures: ["swipeGesture"],
-  swipeGesture: SC.SwipeGesture,
+SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable,
+/** @scope SC.NavigationBarView.prototype */{
 
-  
+  /** @private */
   init: function() {
     sc_super();
     
@@ -31,13 +31,10 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     }
   },
 
-  /**
-    @private
-    Mixies in animatable and the navigation bar transitions.
-  */
+  /** @private */
   mixinAnimatable: function() {
     this.mixin(SC.Animatable);
-    this.transitions = this.navigationTransitions;    
+    this.transitions = this.navigationTransitions;
   },
   
   /**
@@ -56,10 +53,18 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     opacity: 1
   },
   
-  //
-  // GESTURE SUPPORT
-  //
+
+  // ..........................................................
+  // Gesture Support
+  // 
   
+  /** @private */
+  gestures: ["swipeGesture"],
+  
+  /** @private */
+  swipeGesture: SC.SwipeGesture,
+
+  /** @private */
   swipe: function(gesture, touch, direction) {
     var lookingFor = (direction === SC.SWIPE_LEFT) ? "isSwipeLeft" : "isSwipeRight",
         cv = this.get("childViews"), 
@@ -80,16 +85,17 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     
   },
   
-  //
-  // BUILD IN/OUT
-  //
   
-  // for various reasons, including the fact that mixing in init  is VERY BAD, we do this lazily.
+  // ..........................................................
+  // View Build Support
+  // 
+  
+  /** @private */
   resetBuild: function() {
     if (!this.isAnimatable) this.mixinAnimatable();
   },
   
-  // callback
+  /** @private */
   didFinishTransition: function() {
     if (this.isBuildingIn) {
       // and please continue
@@ -97,6 +103,7 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     } else if (this.isBuildingOut) this.buildOutDidFinish();
   },
   
+  /** @private */
   preBuildIn: function() {
     // first, fade this view out
     this.disableAnimation();
@@ -121,6 +128,7 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     }
   },
   
+  /** @private */
   buildIn: function() {
     // first, we do the precursor
     this.preBuildIn();
@@ -129,6 +137,7 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     this.invokeLater("startBuildIn", 10);
   },
   
+  /** @private */
   startBuildIn: function() {
     this.adjust("opacity", 1);
 
@@ -141,6 +150,7 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     }
   },
 
+  /** @private */
   buildOut: function() {
     this.adjust("opacity", 0);
     
@@ -153,7 +163,7 @@ SC.NavigationBarView = SC.ToolbarView.extend(SC.Gesturable, {
     }
   },
   
-  /* CHILD VIEWS */
+  /** @private */
   mixinNavigationChild: function(child) {
     if (child.isAnimatable) return;