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

data/lib/frameworks/sproutcore/frameworks/desktop/panes/alert.js

@@ -10,16 +10,28 @@ sc_require('views/button');
 
 /** 
   Passed to delegate when alert pane is dismissed by pressing button 1
+  
+  @static
+  @type String
+  @default 'button1'
 */
 SC.BUTTON1_STATUS = 'button1';
 
 /** 
   Passed to delegate when alert pane is dismissed by pressing button 2
+  
+  @static
+  @type String
+  @default 'button2'
 */
 SC.BUTTON2_STATUS = 'button2';
 
 /** 
   Passed to delegate when alert pane is dismissed by pressing button 3
+  
+  @static
+  @type String
+  @default 'button3'
 */
 SC.BUTTON3_STATUS = 'button3';
 
@@ -28,116 +40,108 @@ SC.BUTTON3_STATUS = 'button3';
   
   Alert panes are a simple way to provide modal messaging that otherwise 
   blocks the user's interaction with your application.  Alert panes are 
-  useful for showing important error messages and confirmation dialogs.  They
+  useful for showing important error messages and confirmation dialogs. They
   provide a better user experience than using the OS-level alert dialogs.
   
-  h1. Displaying an Alert Pane
+  # Displaying an Alert Pane
   
-  The easiest way to display an alert pane is to use one of the various 
+  The easiest way to display an alert pane is to use one of the various
   class methods defined on SC.AlertPane, passing the message and an optional
-  detailed description and caption.  
+  detailed description and caption.
   
-  There are four variations of this method can you can invoke:  
+  There are four variations of this method can you can invoke:
   
-  - *warn()* - displays an alert pane with a warning icon to the left.
-  - *error()* - displays an alert with an error icon to the left
-  - *info()* - displays an alert with an info icon to the left
-  - *plain()* - displays an alert w/o any icon
-  - *show()* - displays an alert with a customizable icon to the left
+    - *warn()* - displays an alert pane with a warning icon to the left.
+    - *error()* - displays an alert with an error icon to the left
+    - *info()* - displays an alert with an info icon to the left
+    - *plain()* - displays an alert w/o any icon
+    - *show()* - displays an alert with a customizable icon to the left
   
   In addition to passing a message, description and caption, you can also customize
   the title of the button 1 (OK) and add an optional button 2 and 3 (Cancel or Extra).
   
-  button1 : 1st button from the right. default:OK
-  button2 : 2nd button from the right. Optional. Could be Cancel or 2nd action.
-  button3 : 1st button from the left. Optional. Could be Cancel or alternative option.
+    - button1 - 1st button from the right. default:OK
+    - button2 - 2nd button from the right. Optional. Could be Cancel or 2nd action.
+    - button3 - 1st button from the left. Optional. Could be Cancel or alternative option.
   
   Additionally, you can define a delegate object.  This delegate's 
   'alertPaneDidDismiss()' method will be called when the pane
   is dismissed, passing the pane instance and a key indicating which 
   button was pressed.
   
-  h1. Examples
+  # Examples
   
   Show a simple AlertPane with an OK button:
   
-  {{{
-    SC.AlertPane.warn({
-      message: "Could not load calendar",
-      description: "Your internet connection may be unavailable or our servers may be down.",
-      caption: "Try again in a few minutes."
-    });
-  }}}
+      SC.AlertPane.warn({
+        message: "Could not load calendar",
+        description: "Your internet connection may be unavailable or our servers may be down.",
+        caption: "Try again in a few minutes."
+      });
   
   Show an AlertPane with a customized OK title (title will be 'Try Again') and
   custom action:
   
-  {{{
-    SC.AlertPane.warn({
-      message: "Could not load calendar",
-      description: "Your internet connection may be unavailable or our servers may be down.",
-      caption: "Try again in a few minutes.",
-      buttons: [
-        { title: "Try Again" }
-      ]
-    });
-  }}}
+      SC.AlertPane.warn({
+        message: "Could not load calendar",
+        description: "Your internet connection may be unavailable or our servers may be down.",
+        caption: "Try again in a few minutes.",
+        buttons: [
+          { title: "Try Again" }
+        ]
+      });
   
   Show an AlertPane with a custom OK, a Cancel button and an Extra button, 
   each with custom titles.  Also, pass a delegate that will be invoked when
   the user's dismisses the dialog.
   
-  {{{
-    MyApp.calendarController = SC.Object.create({
-      alertPaneDidDismiss: function(pane, status) {
-        switch(status) {
-          case SC.BUTTON1_STATUS:
-            this.tryAgain();
-            break;
+      MyApp.calendarController = SC.Object.create({
+        alertPaneDidDismiss: function(pane, status) {
+          switch(status) {
+            case SC.BUTTON1_STATUS:
+              this.tryAgain();
+              break;
             
-          case SC.BUTTON2_STATUS:
-            // do nothing
-            break;
+            case SC.BUTTON2_STATUS:
+              // do nothing
+              break;
             
-          case SC.BUTTON3_STATUS:
-            this.showMoreInfo();
-            break;
-        }
-      },
-      ...
-    });
-    
-    
-    SC.AlertPane.warn({
-      message: "Could not load calendar",
-      description: "Your internet connection may be unavailable or our servers may be down.",
-      caption: "Try again in a few minutes.",
-      delegate: MyApp.calendarController,
-      buttons: [
-        { title: "Try Again" },
-        { title: "Cancel" },
-        { title: "More Info…" }
-      ]
-    });
-  }}}
+            case SC.BUTTON3_STATUS:
+              this.showMoreInfo();
+              break;
+          }
+        },
+        ...
+      });
+    
+    
+      SC.AlertPane.warn({
+        message: "Could not load calendar",
+        description: "Your internet connection may be unavailable or our servers may be down.",
+        caption: "Try again in a few minutes.",
+        delegate: MyApp.calendarController,
+        buttons: [
+          { title: "Try Again" },
+          { title: "Cancel" },
+          { title: "More Info…" }
+        ]
+      });
   
   Instead of using the delegate pattern above, you can also specify a target
   and an action, similar to SC.ButtonView.
   
-  {{{
-    SC.AlertPane.warn({
-      message: "Could not load calendar",
-      description: "Your internet connection may be unavailable or our servers may be down.",
-      caption: "Try again in a few minutes.",
-      buttons: [
-        { 
-          title: "OK", 
-          action: "didClickOK",
-          target: MyApp.calendarController
-        }
-      ]
-    });
-  }}}
+      SC.AlertPane.warn({
+        message: "Could not load calendar",
+        description: "Your internet connection may be unavailable or our servers may be down.",
+        caption: "Try again in a few minutes.",
+        buttons: [
+          { 
+            title: "OK", 
+            action: "didClickOK",
+            target: MyApp.calendarController
+          }
+        ]
+      });
   
   Also note that in addition to passing the action as a string of the method
   name that will be invoked, you can also give a function reference as the
@@ -147,15 +151,22 @@ SC.BUTTON3_STATUS = 'button3';
   @extends SC.PanelPane
   @since SproutCore 1.0
 */
-SC.AlertPane = SC.PanelPane.extend({
-
-  classNames: 'sc-alert',
+SC.AlertPane = SC.PanelPane.extend(
+/** @scope SC.AlertPane.prototype */{
 
   /**
-    The WAI-ARIA role for alert pane. This property's value should not be
-    changed.
+    @type Array
+    @default ['sc-alert']
+    @see SC.View#classNames
+  */
+  classNames: ['sc-alert'],
 
-    @property {String}
+  /**
+    The WAI-ARIA role for alert pane.
+    
+    @type String
+    @default 'alertdialog'
+    @constant
   */
   ariaRole: 'alertdialog',
 
@@ -164,49 +175,61 @@ SC.AlertPane = SC.PanelPane.extend({
     set specific button actions, they will be called on the delegate object
     
     The method to be called on your delegate will be:
-    {{{
-      alertPaneDidDismiss: function(pane, status)
-    }}}
+    
+        alertPaneDidDismiss: function(pane, status) {}
     
     The status will be one of SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_STATUS
     depending on which button was clicked.
     
-    @property {Object}
+    @type Object
+    @default null
   */
   delegate: null,
   
   /**
-    The icon URL or class name.  If you do not set this, an alert icon will
+    The icon URL or class name. If you do not set this, an alert icon will
     be shown instead.
     
-    @property {String}
+    @type String
+    @default 'sc-icon-alert-48'
   */
   icon: 'sc-icon-alert-48',
 
   /**
-    The primary message to display.  This message will appear in large bold
+    The primary message to display. This message will appear in large bold
     type at the top of the alert.
     
-    @property {String}
+    @type String
+    @default ""
   */
   message: "",
 
   /**
     The ARIA label for the alert is the message, by default.
+    
+    @field {String}
   */
   ariaLabel: function() {
     return this.get('message');
   }.property('message').cacheable(),
 
   /**
-    An optional detailed decription.  Use this string to provide further 
+    An optional detailed decription. Use this string to provide further
     explanation of the condition and, optionally, ways the user can resolve
     the problem.
     
-    @property {String}
+    @type String
+    @default ""
   */
   description: "",
   
+  /**
+    An escaped and formatted version of the description property.
+    
+    @field
+    @type String
+    @observes description
+  */
   displayDescription: function() {
     var desc = this.get('description');
     if (!desc || desc.length === 0) return desc ;
@@ -216,14 +239,22 @@ SC.AlertPane = SC.PanelPane.extend({
   }.property('description').cacheable(),
 
   /**
-    An optional detailed caption.  Use this string to provide further 
+    An optional detailed caption. Use this string to provide further
     fine print explanation of the condition and, optionally, ways the user can resolve
     the problem.
     
-    @property {String}
+    @type String
+    @default ""
   */
   caption: "",
   
+  /**
+    An escaped and formatted version of the caption property.
+    
+    @field
+    @type String
+    @observes caption
+  */
   displayCaption: function() {
     var caption = this.get('caption');
     if (!caption || caption.length === 0) return caption ;
@@ -235,31 +266,36 @@ SC.AlertPane = SC.PanelPane.extend({
   /**
     The button view for button 1 (OK).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
   button1: SC.outlet('contentView.childViews.1.childViews.1'),
     
   /**
     The button view for the button 2 (Cancel).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
   button2: SC.outlet('contentView.childViews.1.childViews.0'),
     
   /**
     The button view for the button 3 (Extra).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
   button3: SC.outlet('contentView.childViews.2.childViews.0'),
     
   /**
     The view for the button 3 (Extra) wrapper.
     
-    @property {SC.View}
+    @type SC.View
   */
   buttonThreeWrapper: SC.outlet('contentView.childViews.2'),
   
+  /**
+    @type Hash
+    @default { top : 0.3, centerX: 0, width: 500 }
+    @see SC.View#layout
+  */
   layout: { top : 0.3, centerX: 0, width: 500 },
 
   /** @private - internal view that is actually displayed */
@@ -273,6 +309,7 @@ SC.AlertPane = SC.PanelPane.extend({
       SC.View.extend(SC.StaticLayout, {
         classNames: ['info'],
 
+        /** @private */
         render: function(context, firstTime) {
           var pane = this.get('pane');
           if(pane.get('icon') == 'blank') context.addClass('plain');
@@ -380,24 +417,24 @@ SC.AlertPane = SC.PanelPane.extend({
 
 });
 
-SC.AlertPane.mixin({
+SC.AlertPane.mixin(
+/** @scope SC.AlertPane */{
   
   /**
     Show a dialog with a given set of hash attributes:
     
-    {{{
-      SC.AlertPane.show({
-        message: "Could not load calendar",
-        description: "Your internet connection may be unavailable or our servers may be down.",
-        caption: "Try again in a few minutes.",
-        delegate: MyApp.calendarController
-      });
-    }}}
+        SC.AlertPane.show({
+          message: "Could not load calendar",
+          description: "Your internet connection may be unavailable or our servers may be down.",
+          caption: "Try again in a few minutes.",
+          delegate: MyApp.calendarController
+        });
     
     See more examples for how to configure buttons and individual actions in the 
     documentation for the SC.AlertPane class.
     
     @param {Hash} args
+    @return {SC.AlertPane} the pane shown
   */
   show: function(args) {
     // normalize the arguments if this is a deprecated call
@@ -441,6 +478,7 @@ SC.AlertPane.mixin({
     as the dialog icon
     
     @param {Hash} args
+    @return {SC.AlertPane} the pane shown
   */
   warn: function(args) {
     // normalize the arguments if this is a deprecated call
@@ -455,6 +493,7 @@ SC.AlertPane.mixin({
     as the dialog icon
     
     @param {Hash} args
+    @return {SC.AlertPane} the pane shown
   */
   info: function(args) {
     // normalize the arguments if this is a deprecated call
@@ -469,6 +508,7 @@ SC.AlertPane.mixin({
     as the dialog icon
     
     @param {Hash} args
+    @return {SC.AlertPane} the pane shown
   */
   error: function(args) {
     // normalize the arguments if this is a deprecated call
@@ -483,6 +523,7 @@ SC.AlertPane.mixin({
     as the dialog icon
     
     @param {Hash} args
+    @return {SC.AlertPane} the pane shown
   */
   plain: function(args) {
     // normalize the arguments if this is a deprecated call

data/lib/frameworks/sproutcore/frameworks/desktop/panes/menu.js

@@ -4,6 +4,7 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 require('panes/picker');
 require('views/menu_item');
 
@@ -59,20 +60,26 @@ require('views/menu_item');
   @extends SC.PickerPane
   @since SproutCore 1.0
 */
-
 SC.MenuPane = SC.PickerPane.extend(
 /** @scope SC.MenuPane.prototype */ {
 
+  /**
+    @property {Array}
+    @default ['sc-menu']
+    @see SC.View#classNames
+  */
   classNames: ['sc-menu'],
 
   /**
-    The WAI-ARIA role for menu pane. This property's value should not be
-    changed.
+    The WAI-ARIA role for menu pane.
 
     @property {String}
+    @default 'menu'
+    @constant
   */
   ariaRole: 'menu',
 
+
   // ..........................................................
   // PROPERTIES
   //
@@ -83,7 +90,8 @@ SC.MenuPane = SC.PickerPane.extend(
     various itemKey properties to tell the menu how to extract the information
     it needs.
 
-    @type String
+    @property {Array}
+    @default []
   */
   items: [],
 
@@ -97,6 +105,7 @@ SC.MenuPane = SC.PickerPane.extend(
     Your theme can override the default values for each control size by specifying
     them in the `menuRenderDelegate`. For example:
 
+    {{{
         MyTheme.menuRenderDelegate = SC.BaseTheme.menuRenderDelegate.create({
           'sc-tiny-size': {
             itemHeight: 20,
@@ -105,10 +114,11 @@ SC.MenuPane = SC.PickerPane.extend(
             submenuOffsetX: 2
           }
         });
+    }}}
 
     Changing the controlSize once the menu is instantiated has no effect.
 
-    @type String
+    @property {String}
     @default SC.REGULAR_CONTROL_SIZE
   */
   controlSize: SC.REGULAR_CONTROL_SIZE,
@@ -122,7 +132,7 @@ SC.MenuPane = SC.PickerPane.extend(
     If you don't specify a value, the item height will be inferred from
     controlSize.
 
-    @type Number
+    @property {Number}
     @default itemHeight from theme if present, or 20.
   */
   itemHeight: SC.propertyFromRenderDelegate('itemHeight', 20),
@@ -136,16 +146,17 @@ SC.MenuPane = SC.PickerPane.extend(
     If you don't specify a value, the height of the separator menu items will
     be inferred from controlSize.
 
-    @type Number
+    @property {Number}
     @default itemSeparatorHeight from theme, or 9.
   */
   itemSeparatorHeight: SC.propertyFromRenderDelegate('itemSeparatorHeight', 9),
 
   /**
-    The height of the menu pane.  This is updated every time menuItemViews
+    The height of the menu pane. This is updated every time menuItemViews
     is recalculated.
 
-    @type Number
+    @property {Number}
+    @default 0
     @isReadOnly
   */
   menuHeight: 0,
@@ -160,7 +171,7 @@ SC.MenuPane = SC.PickerPane.extend(
     If you don't specify a value, the padding will be inferred from the
     controlSize.
 
-    @type Number
+    @property {Number}
     @default menuHeightPadding from theme, or 6
   */
   menuHeightPadding: SC.propertyFromRenderDelegate('menuHeightPadding', 6),
@@ -171,7 +182,7 @@ SC.MenuPane = SC.PickerPane.extend(
     If you don't specify a value, the padding will be inferred from the
     controlSize.
 
-    @type Number
+    @property {Number}
     @default submenuOffsetX from theme, or 2
   */
   submenuOffsetX: SC.propertyFromRenderDelegate('submenuOffsetX', 2),
@@ -182,7 +193,7 @@ SC.MenuPane = SC.PickerPane.extend(
     You can place an observer on this property to be notified when the user
     makes a selection.
 
-    @type SC.Object
+    @property {SC.Object}
     @default null
     @isReadOnly
   */
@@ -195,8 +206,8 @@ SC.MenuPane = SC.PickerPane.extend(
     set here for each item in the @items@ array. You may provide your own
     subclass for this property to display the customized content.
 
+    @property {SC.View}
     @default SC.MenuItemView
-    @type SC.View
   */
   exampleView: SC.MenuItemView,
 
@@ -216,6 +227,7 @@ SC.MenuPane = SC.PickerPane.extend(
     YES if this menu pane was generated by a parent SC.MenuPane.
 
     @type Boolean
+    @default NO
     @isReadOnly
   */
   isSubMenu: NO,
@@ -241,9 +253,13 @@ SC.MenuPane = SC.PickerPane.extend(
   
   /**
     Disable context menu.
+    
+    @property {Boolean}
+    @default NO
   */
   isContextMenuEnabled: NO,
 
+
   // ..........................................................
   // METHODS
   //
@@ -255,10 +271,9 @@ SC.MenuPane = SC.PickerPane.extend(
     anchor itself to the view, and intelligently reposition itself if the
     contents of the menu exceed the available space.
 
-    @param SC.View anchorViewOrElement the view or element to which the menu
+    @param {SC.View} anchorViewOrElement the view or element to which the menu
     should anchor.
-    @param preferMatrix The prefer matrix used to position the pane.
-    (optional)
+    @param {Array} (preferMatrix) The prefer matrix used to position the pane.
   */
   popup: function(anchorViewOrElement, preferMatrix) {
     var anchor;

data/lib/frameworks/sproutcore/frameworks/desktop/panes/modal.js

@@ -14,26 +14,30 @@
   panes.
   
   A modal pane is automatically appended when a pane with isModal set to
-  YES is made visible and removed when the same pane is hidden.  The only 
-  purpose of the ModalPane is to absorb mouse events so that they cannot 
-  filter through to the underlying content. 
+  YES is made visible and removed when the same pane is hidden.  The only
+  purpose of the ModalPane is to absorb mouse events so that they cannot
+  filter through to the underlying content.
   
   @extends SC.Pane
   @since SproutCore 1.0
 */
-SC.ModalPane = SC.Pane.extend({
+SC.ModalPane = SC.Pane.extend(
+/** @scope SC.ModalPane.prototype */{
   
+  /**
+    @type Array
+    @default ['sc-modal']
+    @see SC.View#classNames
+  */
   classNames: 'sc-modal',
   
-  /** @private cover the entire screen */
-  layout: { top: 0, left: 0, bottom: 0, right: 0 },
-
+  /** @private */
   _openPaneCount: 0,
   
-  /** 
+  /** @private
     Called by a pane just before it appends itself.   The modal pane can
     make itself visible first if needed.
-
+    
     @param {SC.Pane} pane the pane
     @returns {SC.ModalPane} receiver
   */
@@ -43,7 +47,7 @@ SC.ModalPane = SC.Pane.extend({
     return this ;    
   },
   
-  /**
+  /** @private
     Called by a pane just after it removes itself.  The modal pane can remove
     itself if needed.   Modal panes only remove themselves when an equal 
     number of paneWillAppend() and paneDidRemove() calls are received.
@@ -59,14 +63,13 @@ SC.ModalPane = SC.Pane.extend({
     }
   },
   
-  /** 
-    If owner pane implements modalPaneDidClick(), call it on mouse down.
-  */
+  /** @private */
   mouseDown: function(evt) {
     var owner = this.get('owner');
     if (owner && owner.modalPaneDidClick) owner.modalPaneDidClick(evt);
   },
   
+  /** @private */
   touchStart: function(evt) {
     this.mouseDown(evt);
   }