sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/desktop/views/menu_scroll.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)
 // ==========================================================================
 
@@ -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:
+    
+      - SC.LAYOUT_VERTICAL
+      - SC.LAYOUT_HORIZONTAL
     
-    @property
+    @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,16 +463,48 @@ 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();
+
+    var contentView = this.get('contentView') ;
+    if (!contentView) return NO; // nothing to do if no contentView.
+
+    // get the frame for the view - should work even for views with static
+    // layout, assuming it has been added to the screen.
+    var vf = view.get('frame');
+    if (!vf) return NO; // nothing to do
+
+    // convert view's frame to an offset from the contentView origin.  This
+    // will become the new scroll offset after some adjustment.
+    vf = contentView.convertFrameFromView(vf, view.get('parentView')) ;
+
+    var vscroll2 = this.get('verticalScrollerView2');
+    if (vscroll2 && vscroll2.get('isVisible')) {
+      vf.height += vscroll2.get('frame').height;
+    }
+
+    var vscroll = this.get('verticalScrollerView');
+    if (vscroll && vscroll.get('isVisible')) {
+      vf.top -= vscroll.get('frame').height;
+    }
+
+    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.
@@ -509,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

@@ -0,0 +1,261 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require("views/workspace");
+
+/**
+  @static
+  @type String
+  @constant
+*/
+SC.TO_LEFT = "TOLEFT";
+
+/**
+  @static
+  @type String
+  @constant
+*/
+SC.TO_RIGHT = "TORIGHT";
+
+
+/** @class
+
+  NavigationView is very loosely based on UINavigationController:
+  that is, it implements a push/pop based API. 
+  
+  NavigationView checks if the view is NavigationBuildable--that is, if it has 
+  
+  Views may specify a topToolbar or bottomToolbar property. These will become the
+  top or bottom toolbars of the NavigationView (which is, incidentally, a WorkspaceView).
+  
+  Of course, this process is animated...
+  
+  @author Alex Iskander
+  @extends SC.WorkspaceView
+  @since SproutCore 1.4
+*/
+SC.NavigationView = SC.WorkspaceView.extend(
+/** @scope SC.NavigationView.prototype */ {
+  
+  /** @private */
+  _views: null,
+  
+  /** @private */
+  _current: null,
+  
+  /**
+    @type SC.View
+    @default SC.View
+  */
+  navigationContentView: SC.View,
+  
+  /** @private */
+  init: function() {
+    sc_super();
+    this._views = [];
+  },
+  
+  /** @private */
+  createChildViews: function() {
+    sc_super();
+    
+    // get the content
+    var content = this.get("navigationContentView");
+    
+    // instantiate if needed
+    if (content.isClass) content = this.createChildView(content);
+    
+    // set internal values
+    this._defaultContent = this.navigationContentView = content;
+    
+    // append to the content view
+    this.contentView.appendChild(content);
+  },
+  
+  /** @private */
+  changeNavigationContent: function(view) {
+    var top = null, bottom = null;
+    
+    // find top and bottom toolbars if we are setting it to a view
+    if (view) {
+      top = view.get("topToolbar"); 
+      bottom = view.get("bottomToolbar");
+    }
+    
+    // instantiate top if needed
+    if (top && top.isClass) {
+      view.set("topToolbar", top = top.create());
+    }
+    
+    // and now bottom
+    if (bottom && bottom.isClass) {
+      view.set("bottomToolbar", bottom = bottom.create());
+    }
+    
+    
+    // batch property changes for efficiency
+    this.beginPropertyChanges();
+    
+    // update current, etc. etc.
+    this._current = view;
+    this.set("navigationContentView", view ? view : this._defaultContent);
+    
+    // set the top/bottom appropriately
+    this.set("topToolbar", top);
+    this.set("bottomToolbar", bottom);
+    
+    // and we are done
+    this.endPropertyChanges();
+  },
+  
+  /**
+    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;
+    
+    // add current view to the stack (if needed)
+    if (this._current) this._views.push(this._current);
+    
+    // update content now...
+    this.changeNavigationContent(view);
+  },
+  
+  /**
+    Pops the current view off the navigation view stack.
+  */
+  pop: function() {
+    this._currentDirection = SC.TO_RIGHT;
+    
+    // pop the view
+    var view = this._views.pop();
+    
+    // set new (old) content view
+    this.changeNavigationContent(view);
+  },
+  
+  /**
+    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;
+    var views = this._views,
+        idx = views.length - 1, 
+        view = views[idx];
+    
+    // loop back from end
+    while (view && view !== toView) {
+      this._views.pop();
+      idx--;
+      view = views[idx];
+    }
+    
+    // and change the content
+    this.changeNavigationContent(view);
+  },
+  
+  /** @private */
+  topToolbarDidChange: function() {
+    var active = this.activeTopToolbar, replacement = this.get("topToolbar");
+    
+    // if we have an active toolbar, set the build direction and build out
+    if (active) {
+      if (this._currentDirection !== null) {
+        active.set("buildDirection", this._currentDirection);
+        this.buildOutChild(active);
+      } else {
+        this.removeChild(active);
+      }
+    }
+    
+    // if we have a new toolbar, set the build direction and build in
+    if (replacement) {
+      if (this._currentDirection !== null) {
+        replacement.set("buildDirection", this._currentDirection);
+        this.buildInChild(replacement);
+      } else {
+        this.appendChild(replacement);
+      }
+    }
+    
+    // update, and queue retiling
+    this.activeTopToolbar = replacement;
+    this.invokeOnce("childDidChange");
+  }.observes("topToolbar"),
+  
+  /** @private */
+  bottomToolbarDidChange: function() {
+    var active = this.activeBottomToolbar, replacement = this.get("bottomToolbar");
+    
+    if (active) {
+      if (this._currentDirection !== null) {
+        active.set("buildDirection", this._currentDirection);
+        this.buildOutChild(active);
+      } else {
+        this.removeChild(active);
+      }
+    }
+    if (replacement) {
+      if (this._currentDirection !== null) {
+        replacement.set("buildDirection", this._currentDirection);
+        this.buildInChild(replacement);
+      } else {
+        this.appendChild(replacement);
+      }
+    }
+    
+    this.activeBottomToolbar = replacement;
+    this.invokeOnce("childDidChange");
+  }.observes("topToolbar"),
+  
+  /** @private */
+  contentViewDidChange: function() {
+    var active = this.activeNavigationContentView, replacement = this.get("navigationContentView");
+    
+    // mix in navigationbuilder if needed
+    if (!replacement.isNavigationBuilder) {
+      replacement.mixin(SC.NavigationBuilder);
+    }
+    
+    // tiling really needs to happen _before_ animation
+    // so, we set "pending" and queue tiling.
+    this._pendingBuildOut = active;
+    this._pendingBuildIn = replacement;
+    
+    this.activeNavigationContentView = replacement;
+    this.invokeOnce("childDidChange");
+  }.observes("navigationContentView"),
+  
+  /** @private */
+  childDidChange: function() {
+    var replacement = this._pendingBuildIn, active = this._pendingBuildOut;
+    if (active) {
+      if (this._currentDirection !== null) {
+        active.set("buildDirection", this._currentDirection);
+        this.contentView.buildOutChild(active);
+      } else {
+        this.contentView.removeChild(active);
+      }
+    }
+
+    this._scws_tile();
+    
+    if (replacement) {
+      if (this._currentDirection !== null) {
+        replacement.set("buildDirection", this._currentDirection);
+        this.contentView.buildInChild(replacement);
+      } else {
+        this.contentView.appendChild(replacement);
+      }
+    }
+  }
+  
+});