sproutcore 1.10.3.1 → 1.11.0.rc1

data/lib/frameworks/sproutcore/frameworks/designer/designers/object_designer.js

@@ -270,10 +270,14 @@ SC.ObjectDesigner.mixin({
     needed.
   */
   didCreateObject: function(object, attrs) {
+    // GATEKEEP: If this isn't a design, bail.
+    if (!object.constructor.isDesign) return;
+
     // add designer if page is in design mode
-    var page = object.get('page'), design = object.constructor;
-    
-    if (design.isDesign && page && page.get('needsDesigner')) {
+    var page = object.get('page'),
+        design = object.constructor;
+
+    if (page && page.get('needsDesigner')) {
       
       // find the designer class
       var cur = design, origDesign = design;

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/collection_row_delegate.js

@@ -6,92 +6,173 @@
 // ==========================================================================
 
 
-/** 
+/**
   @namespace
-  
-  `CollectionRowDelegate`s are consulted by `SC.ListView` and `SC.TableView` to
-  control the height of rows, including specifying custom heights for
-  specific rows.
-  
-  You can implement a custom row height in one of two ways.
+
+  `CollectionRowDelegate`s are consulted by collection views, such as `SC.ListView`
+  that lay out items in vertical or horizontal rows, in order to determine the
+  height or width of each row.
 */
 SC.CollectionRowDelegate = {
 
   /**
     Walk like a duck.
-  
+
     @type Boolean
-    @default YES
+    @default true
   */
-  isCollectionRowDelegate: YES,
-  
-  /**
+  isCollectionRowDelegate: true,
+
+  /** @deprecated Version 1.11. Please use the `rowSize` property instead.
     Size of an item without spacing or padding.
-    Unless you implement some custom row height
-    support, this row height will be used for all items.
-    
+    Unless you implement custom row height or widths upport, this row height will be used for all items.
+
     @type Number
-    @default 18
+    @default 24
   */
-  itemHeight: 24,
-  
+  itemHeight: null,
+
+  /**
+    The height or width of a row before padding depending on whether the
+    collection is laid out vertically or horizontally.
+
+    Unless you implement custom row size support, this value will be used for
+    all rows.
+
+    @type Number
+    @default 24
+  */
+  // This is a computed property in order to provide backwards compatibility for itemHeight.
+  // When itemHeight is removed completely, this can become a simple `24` value.
+  rowSize: function (key, value) {
+    var itemHeight = this.get('itemHeight'),
+      ret = 24;
+
+    // Backwards compatibility support
+    if (!SC.none(itemHeight)) {
+      //@if(debug)
+      SC.warn('Developer Warning: The itemHeight property of SC.CollectionRowDelegate has been renamed to rowSize.');
+      //@endif
+
+      return itemHeight;
+    }
+
+    if (!SC.none(value)) { ret = value; }
+
+    return ret;
+  }.property('itemHeight').cacheable(),
+
   /**
-    This inserts empty space between rows that you can use for borders.
-    
+    The amount of space to leave between each row.
+
+    This is useful when you need to leave space for borders.
+
     @type Number
     @default 0
   */
   rowSpacing: 0,
-  
+
   /**
+    Padding space added to the top and bottom of each row when laid out vertically,
+    or to the left and right when laid out horizontally.
+
     This is useful if you are using a custom item view that needs to be padded.
-    This value is added to the top and bottom of the `itemHeight`.
-    
+
     @type Number
     @default 0
   */
   rowPadding: 0,
-  
-  /**
-    Total row height used for calculation. Equal to `itemHeight + (2 * rowPadding)`.
-    
+
+  /** @deprecated Version 1.11. Please use a combination of rowSize and rowPadding to specify the total height or width of each row.
+    Total row size used for calculation. Equal to `rowSize + (2 * rowPadding)`.
+
     @type Number
   */
-  rowHeight: function(key, value) {
-    var rowPadding = this.get('rowPadding');
-    var itemHeight = this.get('itemHeight');
+  rowHeight: function (key, value) {
+    var rowPadding = this.get('rowPadding'),
+      rowSize = this.get('rowSize');
 
     if (value !== undefined) {
-      this.set('itemHeight', value-rowPadding*2);
+      this.set('rowSize', value - rowPadding * 2);
       return value;
     }
 
-    return itemHeight + rowPadding * 2;
-  }.property('itemHeight', 'rowPadding'),
+    return rowSize + rowPadding * 2;
+  }.property('rowSize', 'rowPadding'),
 
-  /**
+  /** @private - Returns the total row size based on rowSize and rowPadding for convenience. */
+  _sc_totalRowSize: function () {
+    // Backwards compatibility in case the rowHeight property is set directly.
+    return this.get('rowHeight');
+  }.property('rowHeight'),
+
+  /** @deprecated Version 1.11. Please use the `customRowSizeIndexes` property instead.
     Index set of rows that should have a custom row height. If you need
     certain rows to have a custom row height, then set this property to a
     non-null value.  Otherwise leave it blank to disable custom row heights.
-    
+
     @type SC.IndexSet
   */
   customRowHeightIndexes: null,
-  
+
   /**
-    Called for each index in the `customRowHeightIndexes` set to get the
+    Index set of rows that should have a custom row height. If you need
+    certain rows to have a custom row height, then set this property to a
+    non-null value.  Otherwise leave it blank to disable custom row heights.
+
+    @type SC.IndexSet
+  */
+  // This is a computed property in order to provide backwards compatibility for customRowHeightIndexes.
+  // When customRowHeightIndexes is removed completely, this can become a simple `null` value.
+  customRowSizeIndexes: function (key, value) {
+    var customRowHeightIndexes = this.get('customRowHeightIndexes'),
+      ret = null;
+
+    // Backwards compatibility support.
+    if (!SC.none(customRowHeightIndexes)) {
+      //@if(debug)
+      SC.warn('Developer Warning: The customRowHeightIndexes property of SC.CollectionRowDelegate has been renamed to customRowSizeIndexes.');
+      //@endif
+
+      return customRowHeightIndexes;
+    }
+
+    if (!SC.none(value)) { ret = value; }
+
+    return ret;
+  }.property('customRowHeightIndexes').cacheable(),
+
+  /** @deprecated Version 1.11. Please use the `contentIndexRowSize()` function instead.
+    Called for each index in the `customRowSizeIndexes` set to get the
     actual row height for the index.  This method should return the default
-    rowHeight if you don't want the row to have a custom height.
-    
-    The default implementation just returns the default rowHeight.
-    
+    rowSize if you don't want the row to have a custom height.
+
+    The default implementation just returns the default rowSize.
+
     @param {SC.CollectionView} view the calling view
     @param {Object} content the content array
-    @param {Number} contentIndex the index 
+    @param {Number} contentIndex the index
     @returns {Number} row height
   */
-  contentIndexRowHeight: function(view, content, contentIndex) {
-    return this.get('rowHeight');
+  contentIndexRowHeight: function (view, content, contentIndex) {
+    return this.get('_sc_totalRowSize');
+  },
+
+  /**
+    Called for each index in the `customRowSizeIndexes` set to get the
+    actual row size for the index.  This method should return the default
+    rowSize if you don't want the row to have a custom size.
+
+    The default implementation just returns the default rowSize plus rowPadding.
+
+    @param {SC.CollectionView} view the calling view
+    @param {Object} content the content array
+    @param {Number} contentIndex the index
+    @returns {Number} row size
+  */
+  contentIndexRowSize: function (view, content, contentIndex) {
+    // Backwards compatibility in case the contentIndexRowHeight function is overridden.
+    return this.contentIndexRowHeight(view, content, contentIndex);
   }
 
 };

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

@@ -41,7 +41,8 @@ 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
-  provide a better user experience than using the OS-level alert dialogs.
+  provide a substantially better user experience than using the OS-level alert
+  dialogs.
 
   ## Displaying an Alert Pane
 
@@ -51,27 +52,76 @@ SC.BUTTON3_STATUS = 'button3';
 
   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
-
-  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.
-
-  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.
+   - `warn({})` -- displays an alert pane with a warning icon to the left.
+   - `error()` -- displays an alert with an error icon.
+   - `info()` -- displays an alert with an info icon.
+   - `plain()` -- displays an alert with no icon.
+   - `show()` -- displays an alert with the icon class you specify.
+
+  Each method takes a single argument: a hash of options. These options include:
+
+  - `message` -- The alert's title message.
+  - `description` -- A longer description of the alert, displayed below the title
+    in a smaller font.
+  - `caption` -- A third layer of alert text, displayed below the description in
+    an even-smaller font.
+  - `icon` -- This is set for you automatically unless you call `show`. You may
+    specify any icon class you wish. The icon is displayed at the alert pane's
+    left.
+  - `themeName` -- A button theme that is applied to each button. The default is
+    `capsule`.
+  - `delegate` -- A delegate to be notified when the user reacts to your pane. See
+    "Responding to User Actions" below.
+  - `buttons` -- An array of up to three hashes used to customize the alert's buttons.
+    See "Customizing Buttons" below.
+
+  ## Responding to User Actions
+
+  Often, you may wish to be notified when the user has dismissed to your alert. You
+  have two options: you may specify a delegate in the options hash, or you may
+  customize each button with a target & action.
+
+  If you specify a delegate, it must implement a method with the following signature:
+  `alertPaneDidDismiss(pane, buttonKey)`. When the user dismisses your alert, this
+  method will be called with the pane instance and a key indicating which button was
+  pressed (one of either `SC.BUTTON1_STATUS`, `SC.BUTTON2_STATUS` or `SC.BUTTON3_STATUS`).
+
+  If you specify a target/action for a button (see "Customizing Buttons" below) and the
+  user dismisses the alert with that button, that action will be triggered. If you specify
+  a delegate but no target, the delegate will be used as the target. The action will
+  be called with the alert pane itself as the sender (first argument).
+
+  ## Customizing Buttons
+
+  SC.AlertPane allows you to specify up to three buttons, arranged from right to left (as
+  on Mac OS X). You can customize them by passing an array of up to three options hashes
+  on the `buttons` property. By default, the first, rightmost button is the default (i.e.
+  it is triggered when the user hits the enter key), and the second button is the "cancel"
+  button (triggered by the escape key).
+
+  If you don't specify any buttons, a single default "OK" button will appear.
+
+  You may customize the following button options:
+
+  - `title` -- The button text. Highly recommended unless you like empty buttons.
+  - `localize` -- Whether to localize the title.
+  - `toolTip` -- An extra hint to show when the user hovers the mouse over the button.
+    Make sure that the user can get along fine without this, as tooltips are hard to
+    discover and unavailable on touch devices!
+  - `isDefault` -- You may specify a different button than the first, rightmost button
+    to be the default (triggered by the enter key, and visually distinct in the default
+    Ace theme).
+  - `isCancel` -- You may specify a different button than the second, middle button
+    to be the cancel button (triggered by the escape key).
+  - `target` & `action` -- Supports the target/action pattern (see "Responding to User
+    Actions" above).
+
+  (You may also specify a layerId for the button if needed. As always, using custom
+  layerIds is dangerous and should be avoided unless you know what you're doing.)
 
   ## Examples
 
-  Show a simple AlertPane with an OK button:
+  Show a simple AlertPane with a warning (!) icon and an OK button:
 
       SC.AlertPane.warn({
         message: "Could not load calendar",
@@ -79,8 +129,7 @@ SC.BUTTON3_STATUS = 'button3';
         caption: "Try again in a few minutes."
       });
 
-  Show an AlertPane with a customized OK title (title will be 'Try Again') and
-  custom action:
+  Show an AlertPane with a customized OK button title (title will be 'Try Again'):
 
       SC.AlertPane.warn({
         message: "Could not load calendar",
@@ -91,9 +140,20 @@ SC.BUTTON3_STATUS = 'button3';
         ]
       });
 
-  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.
+  Show an AlertPane with fully customized buttons:
+
+      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.",
+        buttons: [
+          { title: "Try Again", toolTip: "Retry the connection", isDefault: true },
+          { title: "More Info...", toolTip: "Get more info" },
+          { title: "Cancel", toolTip: "Cancel the action", isCancel: true }
+        ]
+      });
+
+  Show an alert pane, using the delegate pattern to respond to how the user dismisses it.
 
       MyApp.calendarController = SC.Object.create({
         alertPaneDidDismiss: function(pane, status) {
@@ -101,11 +161,9 @@ SC.BUTTON3_STATUS = 'button3';
             case SC.BUTTON1_STATUS:
               this.tryAgain();
               break;
-
             case SC.BUTTON2_STATUS:
               // do nothing
               break;
-
             case SC.BUTTON3_STATUS:
               this.showMoreInfo();
               break;
@@ -114,7 +172,6 @@ SC.BUTTON3_STATUS = 'button3';
         ...
       });
 
-
       SC.AlertPane.warn({
         message: "Could not load calendar",
         description: "Your internet connection may be unavailable or our servers may be down.",
@@ -127,8 +184,8 @@ SC.BUTTON3_STATUS = 'button3';
         ]
       });
 
-  Instead of using the delegate pattern above, you can also specify a target
-  and an action, similar to SC.ButtonView.
+  Show an alert pane using the target/action pattern on each button to respond to how the user
+  dismisses it.
 
       SC.AlertPane.warn({
         message: "Could not load calendar",
@@ -136,18 +193,23 @@ SC.BUTTON3_STATUS = 'button3';
         caption: "Try again in a few minutes.",
         buttons: [
           {
-            title: "OK",
-            action: "didClickOK",
+            title: "Try Again",
+            action: "doTryAgain",
+            target: MyApp.calendarController
+          },
+          {
+            title: "Cancel",
+            action: "doCancel",
+            target: MyApp.calendarController
+          },
+          {
+            title: "More Info…",
+            action: "doGiveMoreInfo",
             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
-  action.
-
-
   @extends SC.PanelPane
   @since SproutCore 1.0
 */
@@ -430,32 +492,61 @@ SC.AlertPane.mixin(
     @param {Hash} args
     @return {SC.AlertPane} the pane shown
   */
-  show: function(args) {
+  show: function (args) {
     // normalize the arguments if this is a deprecated call
     args = SC.AlertPane._argumentsCall.apply(this, arguments);
 
     var pane = this.create(args),
-        idx = 0,
+        idx,
         buttons = args.buttons,
-        buttonView, title, action, target, themeName;
+        button, buttonView, layerId, title, toolTip, action, target, themeName,
+        isDefault, isCancel, hasDefault, hasCancel;
+
+    if (buttons) {
+      //@if(debug)
+      // Provide some developer support for more than three button hashes.
+      if (buttons.length > 3) {
+        SC.warn("Tried to show SC.AlertPane with %@ buttons. SC.AlertPane only supports up to three buttons.".fmt(buttons.length));
+      }
+      //@endif
+
+      // Determine if any button hash specifies isDefault/isCancel. If so, we need
+      // to override the button views' default settings.
+      hasDefault = !!buttons.findProperty('isDefault');
+      hasCancel = !!buttons.findProperty('isCancel');
 
-    if(buttons) {
-      buttons.forEach(function(button) {
-        idx++;
-        if(!button) return;
-        buttonView = pane.get('button%@'.fmt(idx));
+      for (idx = 0; idx < 3; idx++) {
+        button = buttons[idx];
+        if (!button) continue;
 
+        buttonView = pane.get('button%@'.fmt(idx + 1));
+
+        layerId = button.layerId;
         title = button.title;
+        localize = button.localize;
+        toolTip = button.toolTip;
         action = button.action;
         target = button.target;
         themeName = args.themeName || 'capsule';
 
-        buttonView.set('title'.fmt(idx), title);
-        if(action) buttonView.set('customAction'.fmt(idx), action);
-        if(target) buttonView.set('customTarget'.fmt(idx), target);
+        // If any button has the isDefault/isCancel flags set, we
+        // explicitly cast the button's flag to bool, ensuring that this
+        // overrides the default. Otherwise, we use undefined so we skip
+        // setting the property, ensuring the default value is used.
+        isDefault = hasDefault ? !!button.isDefault : undefined;
+        isCancel = hasCancel ? !!button.isCancel : undefined;
+
+        buttonView.set('title', title);
+        if (localize === YES) buttonView.set('localize', YES);
+        if (toolTip) buttonView.set('toolTip', toolTip);
+        if (action) buttonView.set('customAction', action);
+        if (target) buttonView.set('customTarget', target);
+        if (layerId !== undefined) { buttonView.set('layerId', layerId); }
+        if (isDefault !== undefined) { buttonView.set('isDefault', isDefault); }
+        if (isCancel !== undefined) { buttonView.set('isCancel', isCancel); }
         buttonView.set('isVisible', !!title);
         buttonView.set('themeName', themeName);
-      });
+      }
     } else {
       // if there are no buttons defined, just add the standard OK button
       buttonView = pane.get('button1');