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

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

@@ -5,6 +5,10 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
+require("views/workspace");
+require("views/toolbar");
+
+
 /** @class
   Master/Detail view is a simple view which manages a master view and a detail view.
   This is not all that different from a SplitView, except that, for the moment (this
@@ -25,18 +29,33 @@
   
   @since SproutCore 1.2
 */
-require("views/workspace");
-require("views/toolbar");
+SC.MasterDetailView = SC.View.extend(
+/** @scope SC.MasterDetailView.prototype */ {
 
-SC.VERTICAL_ORIENTATION = "vertical";
-SC.HORIZONTAL_ORIENTATION = "horizontal";
-
-SC.MasterDetailView = SC.View.extend({
+  /**
+    @type Array
+    @default ['sc-master-detail-view']
+    @see SC.View#classNames
+  */
   classNames: ["sc-master-detail-view"],
   
+  /**
+    @type String
+    @default 'masterDetailRenderDelegate'
+  */
+  renderDelegateName: 'masterDetailRenderDelegate',
+  
+  
+  // ..........................................................
+  // Properties
+  // 
+  
   /**
     The master view. For your development pleasure, it defaults to a
     WorkspaceView with a top toolbar.
+    
+    @type SC.View
+    @default SC.WorkspaceView
   */
   masterView: SC.WorkspaceView.extend({
     topToolbar: SC.ToolbarView.extend({
@@ -48,6 +67,9 @@ SC.MasterDetailView = SC.View.extend({
     The detail view. For your development experience, it defaults to holding
     a top toolbar view with a button that closes/shows master. Come take a peek at
     the code to see what it looks like--it is so simple.
+    
+    @type SC.View
+    @default SC.WorkspaceView
   */
   detailView: SC.WorkspaceView.extend({
     topToolbar: SC.ToolbarView.extend({
@@ -70,6 +92,10 @@ SC.MasterDetailView = SC.View.extend({
     browser. Your purpose in overriding it is either to disable it from automatically
     disappearing on iPad and other touch devices, or force it to appear when a desktop
     browser changes.
+    
+    @field
+    @type Boolean
+    @default NO
   */
   autoHideMaster: function() {
     if (SC.platform.touch) return YES;
@@ -77,13 +103,19 @@ SC.MasterDetailView = SC.View.extend({
   }.property().cacheable(),
   
   /**
-    The width of the master view.
+    @type Number
     @default 250
   */
   masterWidth: 250,
   
   /**
     A property (computed) that says whether the master view is hidden.
+    
+    @field
+    @type Boolean
+    @default NO
+    @observes autoHideMaster
+    @observes orientation
   */
   masterIsHidden: function() {
     if (!this.get("autoHideMaster")) return NO;
@@ -92,10 +124,17 @@ SC.MasterDetailView = SC.View.extend({
   }.property("autoHideMaster", "orientation"),
   
   /**
-    Tracks the orientation of the view.
+    Tracks the orientation of the view. Possible values:
+    
+      - SC.VERTICAL_ORIENTATION
+      - SC.HORIZONTAL_ORIENTATION
+    
+    @type String
+    @default SC.VERTICAL_ORIENTATION
   */
   orientation: SC.VERTICAL_ORIENTATION,
   
+  /** @private */
   _scmd_frameDidChange: function() {
     var f = this.get("frame"), ret;
     if (f.width > f.height) ret = SC.HORIZONTAL_ORIENTATION;
@@ -104,8 +143,7 @@ SC.MasterDetailView = SC.View.extend({
     this.setIfChanged('orientation', ret);
   }.observes('frame'),
   
-  // have to calculate the initial orientation when added to parent at
-  // startup (frame doesn't invalidate in this case)
+  /** @private */
   init: function() {
     sc_super();
     this._scmd_frameDidChange();
@@ -114,8 +152,9 @@ SC.MasterDetailView = SC.View.extend({
   
   /**
     If the master is hidden, this toggles the master picker pane.
-    
     Of course, since pickers are modal, this actually only needs to handle showing.
+    
+    @param {SC.View} view The view to anchor the picker to
   */
   toggleMasterPicker: function(view) {
     if (!this.get("masterIsHidden")) return;
@@ -126,6 +165,9 @@ SC.MasterDetailView = SC.View.extend({
     }
   },
   
+  /**
+    @param {SC.View} view The view to anchor the picker to
+  */
   showMasterPicker: function(view) {
     if (this._picker && this._picker.get("isVisibleInWindow")) return;
     if (!this._picker) {
@@ -145,33 +187,46 @@ SC.MasterDetailView = SC.View.extend({
     }
   },
   
-  showPicker: function(p, view) {
-    p.popup(view, SC.PICKER_POINTER, [3, 0, 1, 2, 3], [9, -9, -18, 18]);
+  /**
+    @param {SC.PickerPane} picker The picker to popup
+    @param {SC.View} view The view to anchor the picker to
+  */
+  showPicker: function(picker, view) {
+    picker.popup(view, SC.PICKER_POINTER, [3, 0, 1, 2, 3], [9, -9, -18, 18]);
   },
   
-  hidePicker: function(p) {
-    p.remove();
+  /**
+    @param {SC.PickerPane} picker The picker to popup
+  */
+  hidePicker: function(picker) {
+    picker.remove();
   },
   
   /**
     The picker pane class from which to create a picker pane.
     
     This defaults to one with a special theme.
+    
+    @type SC.PickerPane
+    @default SC.PickerPane
   */
   pickerPane: SC.PickerPane.extend({
     layout: { width: 250, height: 480 },
     themeName: 'popover'
   }),
   
-  /// INTERNAL CODE. HERE, THERE BE MONSTERS!
-  _picker: null,
-  pointerDistanceFromEdge: 46,
   
+  // ..........................................................
+  // Internal Support
+  // 
   
-  renderDelegateName: 'masterDetailRenderDelegate',
+  /** @private */
+  _picker: null,
   
-  /**
-    @private
+  /** @private */
+  pointerDistanceFromEdge: 46,
+  
+  /** @private
     Updates masterIsHidden in child views.
   */
   _scmd_masterIsHiddenDidChange: function() {
@@ -180,8 +235,7 @@ SC.MasterDetailView = SC.View.extend({
     this.get("detailView").set("masterIsHidden", mih);
   }.observes("masterIsHidden"),
   
-  /**
-    @private
+  /** @private
     When the frame changes, we don't need to do anything. We use smart positioning.
     However, if the orientation were to change, well, then we might need to do something.
   */
@@ -189,15 +243,15 @@ SC.MasterDetailView = SC.View.extend({
     this.invokeOnce("_scmd_tile");
   }.observes("orientation"),
   
-  /**
+  /** @private
     Observes properties which require retiling.
   */
   _scmd_retileProperties: function() {
     this.invokeOnce("_scmd_tile");
   }.observes("masterIsHidden", "masterWidth"),
   
-  /**
-    Creates the child views. Specifically, instantiates master and detail views.
+  /** @private
+    Instantiates master and detail views.
   */
   createChildViews: function() {
     var master = this.get("masterView");
@@ -210,9 +264,10 @@ SC.MasterDetailView = SC.View.extend({
     this.invokeOnce("_scmd_tile");
   },
   
+  /** @private */
   _masterIsDrawn: NO, // whether the master is in the view
-  /**
-    @private
+  
+  /** @private
     Tiles the views as necessary.
   */
   _scmd_tile: function() {
@@ -254,4 +309,5 @@ SC.MasterDetailView = SC.View.extend({
       detail.set('layout', { left: 0, right: 0, top: 0, bottom: 0 });
     }
   }
+
 });

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

@@ -4,6 +4,7 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 sc_require('views/button') ;
 sc_require('views/separator') ;
 
@@ -16,26 +17,41 @@ sc_require('views/separator') ;
   @since SproutCore 1.0
 */
 SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
-/** @scope SC.MenuItemView.prototype */{
+/** @scope SC.MenuItemView.prototype */ {
+
+  /**
+    @type Array
+    @default ['sc-menu-item']
+    @see SC.View#classNames
+  */
+  classNames: ['sc-menu-item'],
 
+  /**
+    @type Array
+    @default ['title', 'isEnabled', 'isSeparator']
+    @see SC.View#displayProperties
+  */
   displayProperties: ['title', 'isEnabled', 'isSeparator'],
 
-  classNames: ['sc-menu-item'],
 
   /**
-    The WAI-ARIA role for menu items. This property's value should not be
-    changed.
+    The WAI-ARIA role for menu items.
 
-    @property {String}
+    @type String
+    @default 'menuitem'
+    @readOnly
   */
   ariaRole: 'menuitem',
 
+  /**
+    @type Boolean
+    @default YES
+  */
   escapeHTML: YES,
 
   /**
-    @private
-    @property
-    @type {Boolean}
+    @type Boolean
+    @default YES
   */
   acceptsFirstResponder: YES,
   
@@ -43,14 +59,17 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     IE only attribute to block bluring of other controls
 
     @type Boolean
+    @default YES
   */
   blocksIEDeactivate: YES,
 
   /**
-    Disable context menu.
+    @type Boolean
+    @default NO
   */
   isContextMenuEnabled: NO,
 
+
   // ..........................................................
   // KEY PROPERTIES
   //
@@ -59,22 +78,25 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     The content object the menu view will display.
 
     @type Object
+    @default null
   */
   content: null,
 
   /**
-    YES if this menu item represents a separator.
+    YES if this menu item represents a separator, NO otherwise.
 
-    @property {Boolean}
+    @field
+    @type Boolean
+    @observes content
   */
   isSeparator: function() {
     return this.getContentProperty('itemSeparatorKey') === YES;
   }.property('content').cacheable(),
 
   /**
-    Whether the menu item is enabled.
-
-    @property {Boolean}
+    @field
+    @type Boolean
+    @observes content.isEnabled
   */
   isEnabled: function() {
     return this.getContentProperty('itemIsEnabledKey') !== NO &&
@@ -84,7 +106,9 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   /**
     This menu item's submenu, if it exists.
 
-    @property {SC.MenuView}
+    @field
+    @type SC.MenuView
+    @observes content
   */
   subMenu: function() {
     var content = this.get('content'), menuItems, parentMenu;
@@ -115,23 +139,21 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   }.property('content').cacheable(),
 
   /**
-    Whether or not this menu item has a submenu.
-
-    @property {Boolean}
+    @type Boolean
+    @default NO
+    @observes subMenu
   */
   hasSubMenu: function() {
     return !!this.get('subMenu');
   }.property('subMenu').cacheable(),
 
-  /**
-    @private
-  */
+  /** @private */
   init: function() {
     sc_super();
     this.contentDidChange();
   },
 
-  /**
+  /** @private
     Fills the passed html-array with strings that can be joined to form the
     innerHTML of the receiver element.  Also populates an array of classNames
     to set on the outer element.
@@ -192,7 +214,7 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     context = context.end();
   },
 
-  /**
+  /** @private
    Generates the image used to represent the image icon. override this to
    return your own custom HTML
 
@@ -215,7 +237,7 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     context.begin('img').addClass('image').addClass(className).attr('src', url).end() ;
   },
 
-  /**
+  /** @private
    Generates the label used to represent the menu item. override this to
    return your own custom HTML
 
@@ -231,19 +253,18 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     context.push("<span class='value ellipsis'>"+label+"</span>") ;
   },
 
-  /**
+  /** @private
    Generates the string used to represent the branch arrow. override this to
    return your own custom HTML
 
    @param {SC.RenderContext} context the render context
    @returns {void}
   */
-
   renderBranch: function(context) {
     context.push('<span class="has-branch"></span>') ;
   },
 
-  /**
+  /** @private
    Generates the string used to represent the short cut keys. override this to
    return your own custom HTML
 
@@ -258,9 +279,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   /**
     This method will check whether the current Menu Item is still
     selected and then create a submenu accordignly.
-
-    @param {}
-    @returns void
   */
   showSubMenu: function() {
     var subMenu = this.get('subMenu') ;
@@ -272,6 +290,13 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     this._subMenuTimer = null;
   },
 
+  /**
+    The title from the content property.
+    
+    @field
+    @type String
+    @observes content.title
+  */
   title: function() {
     var ret = this.getContentProperty('itemTitleKey'),
         localize = this.getPath('parentMenu.localize');
@@ -281,6 +306,7 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     return ret||'';
   }.property('content.title').cacheable(),
 
+  /** @private */
   getContentProperty: function(property) {
     var content = this.get('content'),
         menu = this.get('parentMenu');
@@ -290,10 +316,12 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     }
   },
 
+
   //..........................................
   // Mouse Events Handling
   //
 
+  /** @private */
   mouseUp: function(evt) {
     // SproutCore's event system will deliver the mouseUp event to the view
     // that got the mouseDown event, but for menus we want to track the mouse,
@@ -349,9 +377,8 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     return YES;
   },
 
-  /**
+  /** @private
     Actually sends the action of the menu item to the target.
-    @private
   */
   sendAction: function() {
     var action = this.getContentProperty('itemActionKey'),
@@ -387,15 +414,13 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
 
   },
 
-  /**
+  /** @private
     Toggles the focus class name on the menu item layer to quickly flash the
     highlight. This indicates to the user that a selection has been made.
 
     This is initially called by performAction(). flashHighlight then keeps
     track of how many flashes have occurred, and calls itself until a maximum
     has been reached.
-
-    @private
   */
   flashHighlight: function() {
     var flashCounter = this._flashCounter, layer = this.$();
@@ -442,8 +467,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
 
   /** @private
     Set the focus based on whether the current menu item is selected or not.
-
-    @returns Boolean
   */
   mouseExited: function(evt) {
     var parentMenu, timer;
@@ -470,23 +493,28 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
     return YES ;
   },
 
+  /** @private */
   touchStart: function(evt){
     this.mouseEntered(evt);
     return YES;
   },
 
+  /** @private */
   touchEnd: function(evt){
     return this.mouseUp(evt);
   },
 
+  /** @private */
   touchEntered: function(evt){
     return this.mouseEntered(evt);
   },
 
+  /** @private */
   touchExited: function(evt){
     return this.mouseExited(evt);
   },
 
+  /** @private */
   checkMouseLocation: function() {
     var subMenu = this.get('subMenu'), parentMenu = this.get('parentMenu'),
         currentMenuItem, previousMenuItem;
@@ -507,8 +535,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
 
   /** @private
     Call the moveUp function on the parent Menu
-
-    @returns Boolean
   */
   moveUp: function(sender,evt) {
     var menu = this.get('parentMenu') ;
@@ -520,8 +546,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
 
   /** @private
     Call the moveDown function on the parent Menu
-
-    @returns Boolean
   */
   moveDown: function(sender,evt) {
     var menu = this.get('parentMenu') ;
@@ -533,8 +557,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
 
   /** @private
     Call the function to create a branch
-
-    @returns Boolean
   */
   moveRight: function(sender,evt) {
     this.showSubMenu() ;
@@ -595,8 +617,6 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   /**
     Close the parent Menu and remove the focus of the current Selected
     Menu Item
-
-    @returns void
   */
   closeParent: function() {
     this.$().removeClass('focus') ;
@@ -616,9 +636,7 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   // CONTENT OBSERVING
   //
 
-  /**
-    @private
-
+  /** @private
     Add an observer to ensure that we invalidate our cached properties
     whenever the content object’s associated property changes.
   */
@@ -641,9 +659,7 @@ SC.MenuItemView = SC.View.extend(SC.ContentDisplay,
   }.observes('content'),
 
 
-  /**
-    @private
-
+  /** @private
     Invalidate our cached property whenever the content object’s associated
     property changes.
   */