sproutcore 1.4.5-java → 1.5.0-java

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

@@ -0,0 +1,138 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+
+/**
+  @namespace
+  NavigationBuilder is an implementation of the Builder protocol. It implements
+  buildIn/Out (though these only relay to buildIn/OutNavigation, so feel free to
+  override if needed; the navigation builders will still be accessible).
+  
+  Building in and out animates the view in and out to and from the left and right.
+*/
+SC.NavigationBuilder = {
+
+  /**
+    Walk like a duck.
+    
+    @type Boolean
+    @default YES
+    @constant
+  */
+  isNavigationBuilder: YES,
+  
+  /**
+    The transitions to be used for navigation; these are mixed in to the existing
+    transitions hash if one exists, or become the transitions hash otherwise.
+    
+    If NO, it uses the (hard-coded) defaults.
+    
+    @type Boolean
+    @default NO
+  */
+  navigationTransitions: NO,
+  
+  initMixin: function() {
+    // force integrate SC.Animatable
+    var animatable = SC.Animatable;
+    if (animatable && !this.isAnimatable) {
+      // okay, let's mix it in!
+      this.mixin(animatable);
+    } else if (!animatable) { 
+      // check that we actually have SC.Animatable
+      SC.Logger.error(
+        "SC.NavigationView and SC.NavigationBuilder require SC.Animatable " + 
+        "to perform animations, but it is not present. Please ensure your app or framework " +
+        "references it."
+      );
+    }
+    
+    var navigationTransitions = this.get("navigationTransitions");
+    if (!navigationTransitions && SC.Animatable) {
+      navigationTransitions = {
+        // these being identical helps us.
+        left: { duration: 0.25, timing: SC.Animatable.TRANSITION_EASE_IN_OUT, action: "navigationBuildDidFinish" },
+        transform: { duration: 0.25, timing: SC.Animatable.TRANSITION_EASE_IN_OUT, action: "navigationBuildDidFinish" }
+      };
+    }
+    
+    // mix in transitions (a base set will have been added by SC.Animatable alrady)
+    if (SC.Animatable) SC.mixin(this.transitions, navigationTransitions);
+  },
+  
+  /** @private
+    Determines metrics of the view. This may be adapted to work with non-CSS transforms in future...
+  */
+  metrics: function() {
+    var f = this.computeFrameWithParentFrame();
+    return f;
+  },
+  
+  /** @private
+    Applies the supplied CSS transform.
+  */
+  transform: function(pos) {
+    if (SC.platform.supportsCSS3DTransforms) {
+      this.adjust("transform", "translate3d(" + pos + "px,0px,0px)");
+    } else {
+      this.adjust("transform", "translate(" + pos + "px,0px)");
+    }
+  },
+  
+  buildInNavigation: function() {
+    // set initial state
+    var metrics = this.metrics();
+    this.disableAnimation();
+    this.transform(this.get("buildDirection") === SC.TO_LEFT ? metrics.width : -metrics.width);
+    this.enableAnimation();
+    
+    // now, (delayed) call transform to go to the correct spot
+    this.invokeLater("transform", 10, 0);
+  },
+  
+  buildOutNavigation: function() {
+    // we already have an initial state
+    var metrics = this.metrics();
+    this.transform(this.get("buildDirection") === SC.TO_LEFT ? -metrics.width : metrics.width);
+  },
+  
+  /**
+    You may override this. If you do, call buildInNavigation to call the original functionality.
+    You may need to override navigationBuildDidFinish as well if you call buildInNavigation.
+  */
+  buildIn: function() {
+    this.buildInNavigation();
+  },
+  
+  /**
+    You may override this. If you do, call buildOutNavigation to call the original functionality.
+    You may need to override navigationBuildDidFinish as well if you call buildOutNavigation.
+  */
+  buildOut: function() {
+    this.buildOutNavigation();
+  },
+  
+  /**
+    This ensures that the view has a CSS transform set, even if it is added without build in, etc.
+  */
+  resetBuild: function() {
+    this.transform(0);
+  },
+  
+  /**
+    Called when the transitions finish.
+  */
+  navigationBuildDidFinish: function() {
+    if (this.isBuildingIn) {
+      this.buildInDidFinish();
+    } else if (this.isBuildingOut) {
+      this.buildOutDidFinish();
+    }
+  }
+  
+} ;
+

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

@@ -1,11 +1,14 @@
-// ========================================================================
-// SproutCore -- JavaScript Application Framework
-// Copyright ©2006-2011, Strobe Inc. and contributors.
-// Portions copyright ©2008 Apple Inc.  All rights reserved.
-// ========================================================================
+// ==========================================================================
+// 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)
+// ==========================================================================
+
 
 /**
   @namespace
+  @deprecated
 
   Any views you implement that are scrollable should include this mixin to
   provide basic support for scrolling actions.  You can also override any 
@@ -16,35 +19,42 @@
   info.
   
   Note that isScrollable must always be true.
-
 */
 SC.Scrollable = {
   
 //@if(debug)
   initMixin: function() {
-    console.warn("SC.Scrollable is deprecated and will be removed in a future version of SproutCore.  Consider pulling the mixin into your own app if you want to keep using it.");
+    SC.Logger.warn("SC.Scrollable is deprecated and will be removed in a future version of SproutCore.  Consider pulling the mixin into your own app if you want to keep using it.");
   },
 //@endif 
 
   /** Informs the view system that the receiver is scrollable.
-  
+
     Must always be true.
+
+    @property {Boolean}
+    @default YES
+    @constant
   */
   isScrollable: true,
-  
+
   /** 
     Amount to scroll one vertical line.
   
-    Used by the default implementation of scrollDownLine() and scrollUpLine().  Defaults
-    to 20px.
+    Used by the default implementation of scrollDownLine() and scrollUpLine().
+    
+    @property {Number}
+    @default 20
   */
   verticalLineScroll: 20,
   
   /**
     Amount to scroll one horizontal line.
   
-    Used by the default implementation of scrollLeftLine() and scrollRightLine(). Defaults
-    to 20px.
+    Used by the default implementation of scrollLeftLine() and scrollRightLine().
+    
+    @property {Number}
+    @default 20
   */
   horizontalLineScroll: 20,
   
@@ -55,7 +65,7 @@ SC.Scrollable = {
     current innerFrame height.
   */
   verticalPageScroll: function() {
-    return this.get('innerFrame').height ;
+    return this.get('innerFrame').height;
   }.property('innerFrame'),
   
   /**
@@ -65,31 +75,33 @@ SC.Scrollable = {
     to current innerFrame width.
   */
   horizontalPageScroll: function() {
-    return this.get('innerFrame').width ;  
+    return this.get('innerFrame').width ;
   }.property('innerFrame'),
   
   /**
-    Returns true if the receiver has enough vertical content to require 
+    Returns true if the receiver has enough vertical content to require
     scrolling.
     
-    If you do not want to allow vertical scrolling, override this to be false 
+    If you do not want to allow vertical scrolling, override this to be false
     and set the appropriate CSS.
     
+    @field {Boolean}
   */
   hasVerticalScroller: function() {
-    return this.get('scrollFrame').height > this.get('innerFrame').height ;
+    return this.get('scrollFrame').height > this.get('innerFrame').height;
   }.property('scrollFrame'),
   
   /**
-    Returns true if the receiver has enough horizontal content to require 
+    Returns true if the receiver has enough horizontal content to require
     scrolling.
     
-    If you do not want to allow horizontal scrolling, override this to be 
+    If you do not want to allow horizontal scrolling, override this to be
     false and set the appropriate CSS.
     
+    @field {Boolean}
   */
   hasHorizontalScroller: function() {
-    return this.get('scrollFrame').width > this.get('innerFrame').width ;
+    return this.get('scrollFrame').width > this.get('innerFrame').width;
   }.property('scrollFrame'),
 
   /**
@@ -119,9 +131,12 @@ SC.Scrollable = {
 
   /**
     Scrolls the receiver to the specified x,y coordinate
+    
+    @param {Number} x
+    @param {Number} y
   */
   scrollTo: function(x,y) {
-    this.set('scrollFrame', { x: 0-x, y: 0-y }) ;  
+    this.set('scrollFrame', { x: 0-x, y: 0-y });
   },
   
   /**
@@ -129,10 +144,9 @@ SC.Scrollable = {
     
     Frame must be relative to the receiver's offsetParent.
     
-    @param {SC.ClassicView} view the view you want to make visible
+    @param {SC.View} view the view you want to make visible
   */
   scrollToVisible: function(view) {
-
     // get frames and convert them to proper offsets
     var f = this.get('innerFrame') ;
     var sf = this.get('scrollFrame') ;

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

@@ -1,29 +1,37 @@
 // ==========================================================================
 // 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)
 // ==========================================================================
 
 sc_require('panes/panel');
 sc_require('views/button');
-/** 
-  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.
-*/
+
 /** 
   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';
 
@@ -32,122 +40,196 @@ 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).  Just
-  pass these titles of these buttons to enable them or null to disable then.
+  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 pass a delegate object as the last parameter.  This
-  delegate's 'alertPaneDidDismiss()' method will be called when the pane
+  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("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  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'):
+  Show an AlertPane with a customized OK title (title will be 'Try Again') and
+  custom action:
   
-  {{{
-    SC.AlertPane.warn("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  Try again in a few minutes.", "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;
-        }
-      },
-      
-      ...
-    });
+            case SC.BUTTON3_STATUS:
+              this.showMoreInfo();
+              break;
+          }
+        },
+        ...
+      });
+    
     
-    SC.AlertPane.warn("Could not load calendar", "Your internet connection may be unavailable or our servers may be down.  Try again in a few minutes.", "Try Again", "Cancel", "More Info...", 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.",
+        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
+          }
+        ]
+      });
+  
+  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
 */
-SC.AlertPane = SC.PanelPane.extend({
-  
-  classNames: 'sc-alert',
-  
+SC.AlertPane = SC.PanelPane.extend(
+/** @scope SC.AlertPane.prototype */{
+
   /**
-    The delegate to notify when the pane is dismissed.  If you set a 
-    delegate, it should respond to the method:
+    @type Array
+    @default ['sc-alert']
+    @see SC.View#classNames
+  */
+  classNames: ['sc-alert'],
+
+  /**
+    The WAI-ARIA role for alert pane.
+    
+    @type String
+    @default 'alertdialog'
+    @constant
+  */
+  ariaRole: 'alertdialog',
+
+  /**
+    If defined, the delegate is notified when the pane is dismissed. If you have 
+    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 on of SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_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: "",
 
   /**
-    An optional detailed decription.  Use this string to provide further 
+    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
     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 ;
@@ -157,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 ;
@@ -174,33 +264,38 @@ SC.AlertPane = SC.PanelPane.extend({
   }.property('caption').cacheable(),
   
   /**
-    The button view for the button 1 (OK).
+    The button view for button 1 (OK).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
-  buttonOne: SC.outlet('contentView.childViews.1.childViews.1'),
-
+  button1: SC.outlet('contentView.childViews.1.childViews.1'),
+    
   /**
     The button view for the button 2 (Cancel).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
-  buttonTwo: SC.outlet('contentView.childViews.1.childViews.0'),
-
+  button2: SC.outlet('contentView.childViews.1.childViews.0'),
+    
   /**
     The button view for the button 3 (Extra).
     
-    @property {SC.ButtonView}
+    @type SC.ButtonView
   */
-  buttonThree: SC.outlet('contentView.childViews.2.childViews.0'),
-
+  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 */
@@ -214,15 +309,16 @@ SC.AlertPane = SC.PanelPane.extend({
       SC.View.extend(SC.StaticLayout, {
         classNames: ['info'],
 
+        /** @private */
         render: function(context, firstTime) {
           var pane = this.get('pane');
-          var blank = SC.BLANK_IMAGE_URL ;
           if(pane.get('icon') == 'blank') context.addClass('plain');
-          context.push('<img src="'+blank+'" class="icon '+pane.get('icon')+'" />');
+          context.push('<img src="'+SC.BLANK_IMAGE_URL+'" class="icon '+pane.get('icon')+'" />');
           context.begin('h1').attr('class', 'header').text(pane.get('message') || '').end();
           context.push(pane.get('displayDescription') || '');
           context.push(pane.get('displayCaption') || '');
           context.push('<div class="separator"></div>');
+
         }
       }),
 
@@ -230,35 +326,34 @@ SC.AlertPane = SC.PanelPane.extend({
         layout: { bottom: 13, height: 24, right: 18, width: 466 },
         childViews: ['cancelButton', 'okButton'],
         classNames: ['text-align-right'],
-        cancelButton : SC.ButtonView.extend({
-            useStaticLayout: YES,
-            actionKey: SC.BUTTON2_STATUS,
-            localize: YES,
-            titleMinWidth: 64,
-            layout: { right: 5, height: 'auto', width: 'auto', bottom: 0 },
-            theme: 'capsule',
-            title: "Cancel", 
-            isCancel: YES,
-            action: "dismiss",
-            isVisible: NO
-          }),
-
-        okButton : SC.ButtonView.extend({
-            useStaticLayout: YES,
-            actionKey: SC.BUTTON1_STATUS,
-            localize: YES,
-            titleMinWidth: 64,
-            layout: { left: 0, height: 'auto', width: 'auto', bottom: 0 },
-            theme: 'capsule',
-            title: "OK", 
-            isDefault: YES,
-            action: "dismiss"
-          })
+        
+        cancelButton: SC.ButtonView.extend({
+          useStaticLayout: YES,
+          actionKey: SC.BUTTON2_STATUS,
+          localize: YES,
+          titleMinWidth: 64,
+          layout: { right: 5, height: 'auto', width: 'auto', bottom: 0 },
+          theme: 'capsule',
+          isCancel: YES,
+          action: "dismiss",
+          isVisible: NO
+        }),
+        
+        okButton: SC.ButtonView.extend({
+          useStaticLayout: YES,
+          actionKey: SC.BUTTON1_STATUS,
+          localize: YES,
+          titleMinWidth: 64,
+          layout: { left: 0, height: 'auto', width: 'auto', bottom: 0 },
+          theme: 'capsule',
+          isDefault: YES,
+          action: "dismiss",
+          isVisible: NO
+        })
       }),
       
       SC.View.extend({
         layout: { bottom: 13, height: 24, left: 18, width: 150 },
-        isVisible: NO,
         childViews: [
           SC.ButtonView.extend({
             useStaticLayout: YES,
@@ -267,7 +362,6 @@ SC.AlertPane = SC.PanelPane.extend({
             titleMinWidth: 64,
             layout: { left: 0, height: 'auto', width: 'auto', bottom: 0 },
             theme: 'capsule',
-            title: "Extra", 
             action: "dismiss",
             isVisible: NO
           })]
@@ -275,14 +369,40 @@ SC.AlertPane = SC.PanelPane.extend({
   }),
 
   /**
-    Action triggered whenever any button is pressed.  Notifies any delegate
-    and then hides the alert pane.
+    Action triggered whenever any button is pressed. Also the hides the 
+    alertpane itself.
+    
+    This will trigger the following chain of events:
+    1. If a delegate was given, and it has alertPaneDidDismiss it will be called
+    2. Otherwise it will look for the action of the button and call:
+       a) The action function reference if one was given
+       b) The action method on the target if one was given
+       c) If both a and b are missing, call the action on the rootResponder
+    
+    @param {SC.View} sender - the button view that was clicked
   */
   dismiss: function(sender) {
-    var del = this.delegate;
+    var del = this.delegate,
+        rootResponder, action, target;
+    
     if (del && del.alertPaneDidDismiss) {
       del.alertPaneDidDismiss(this, sender.get('actionKey'));
     }
+    else if(action = (sender && sender.get('customAction'))) {
+      if(SC.typeOf(action)===SC.T_FUNCTION) {
+        action.call(action);
+      }
+      else if(target = sender.get('target')) {
+        target.tryToPerform(action);
+      }
+      else {
+        rootResponder = this.getPath('pane.rootResponder');
+        if(rootResponder) {
+          rootResponder.sendAction(action, del, this);
+        }
+      }
+    }
+    
     this.remove(); // hide alert
   },
   
@@ -294,117 +414,175 @@ SC.AlertPane = SC.PanelPane.extend({
     var v = this.getPath('contentView.childViews.0');
     if (v) v.displayDidChange(); // re-render message
   }.observes('icon', 'message', 'displayDescription', 'displayCaption')
-});
 
-/** @private
-  internal method normalizes arguments for processing by helper methods.
-*/
-SC.AlertPane._normalizeArguments = function(args) {
-  args = SC.A(args); // convert to real array
-  var len = args.length, delegate = args[len-1];
-  if (SC.typeOf(delegate) !== SC.T_STRING) {
-    args[len-1] = null;
-  } else delegate = null ;
-  args[7] = delegate ;
-  return args ;
-};
+});
 
-/**
-  Displays a new alert pane according to the passed parameters.  Every 
-  parameter except for the message is optional.  You can always pass the 
-  delegate as the last parameter and it will be used, even if you omit items
-  in between.
-  
-  If you need to pass other parameters but you want to omit some others 
-  in between, pass null and the related UI item will be hidden
-  
-  Note that if you pass an icon, it should be 48 x 48 in size.
-  
-  @param {String} message the primary message
-  @param {String} description an optional detailed description
-  @param {String} caption an optional detailed fine print caption
-  @param {String} button1Title optional unlocalized title for button 1 (OK)
-  @param {String} button2Title optional unlocalized title for button 2 (Cancel)
-  @param {String} button3Title optional unlocalized title for button 3 (extra)
-  @param {String} iconUrl optional URL or class name for icon.
-  @param {Object} delegate optional delegate to notify when pane is dismissed
-  @returns {SC.AlertPane} new alert pane
-*/
-SC.AlertPane.show = function(message, description, caption, button1Title, button2Title, button3Title, iconUrl, delegate) {
-  
-  // get the delegate and normalize the rest of the params
-  var args = this._normalizeArguments(arguments);
-  
-  // create basic AlertPane
-  var ret = this.create({
-    message: args[0] || '',
-    description: args[1] || null,
-    caption: args[2] || null,
-    icon: args[6] || 'sc-icon-alert-48',
-    delegate: args[7]
-  });
-  
-  // customize buttons as needed
-  var buttonKeys = 'buttonOne buttonTwo buttonThree'.w(), button, title;
-  for(var idx=0;idx<3;idx++) {
-    button = ret.get(buttonKeys[idx]);
-    title = args[idx + 3];
-    if (title) {
-      button.set('title', title).set('isVisible', YES);
-      if(title=='?') button.set('titleMinWidth', 0);
-      if (idx==2) {
-        var button_wrapper = ret.get('buttonThreeWrapper');
-        button_wrapper.set('isVisible', YES);
-      }
+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
+        });
+    
+    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
+    args = SC.AlertPane._argumentsCall.apply(this, arguments);
+    
+    var pane = this.create(args), 
+        idx = 0, 
+        buttons = args.buttons,
+        buttonView, title, action, target;
+    
+    if(buttons) {
+      buttons.forEach(function(button) {
+        idx++;
+        buttonView = pane.get('button%@'.fmt(idx));
+        
+        title = button.title;
+        action = button.action;
+        target = button.target;
+        
+        buttonView.set('title'.fmt(idx), title);
+        if(action) buttonView.set('customAction'.fmt(idx), action);
+        if(target) buttonView.set('target'.fmt(idx), target);
+        buttonView.set('isVisible', !!title);
+      });
     }
-  }
-  var show = ret.append() ; // make visible.
-  ret.adjust('height', ret.childViews[0].$().height()) ;
-  ret.updateLayout() ;
-  return show ;
-};
-
-/**
-  Displays a warning alert pane.  See SC.AlertPane.show() for complete details. 
+    else {
+      // if there are no buttons defined, just add the standard OK button
+      buttonView = pane.get('button1');
+      buttonView.set('title', "OK");
+      buttonView.set('isVisible', YES);
+    }
+    
+    var show = pane.append(); // make visible.
+    pane.adjust('height', pane.childViews[0].$().height());
+    pane.updateLayout();
+    return show;
+  },
   
-  @returns {SC.AlertPane} the pane
-*/
-SC.AlertPane.warn = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
-  var args = this._normalizeArguments(arguments);
-  args[6] = 'sc-icon-alert-48';
-  return this.show.apply(this, args);
-};
-
-
-/**
-  Displays a info alert pane.  See SC.AlertPane.show() for complete details. 
+  /**
+    Same as show() just that it uses sc-icon-alert-48 CSS classname
+    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
+    args = SC.AlertPane._argumentsCall.apply(this, arguments);
+    
+    args.icon = 'sc-icon-alert-48';
+    return this.show(args);
+  },
   
-  @returns {SC.AlertPane} the pane
-*/
-SC.AlertPane.info = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
-  var args = this._normalizeArguments(arguments);
-  args[6] = 'sc-icon-info-48';
-  return this.show.apply(this, args);
-};
-
-/**
-  Displays a error allert pane.  See SC.AlertPane.show() for complete details. 
+  /**
+    Same as show() just that it uses sc-icon-info-48 CSS classname
+    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
+    args = SC.AlertPane._argumentsCall.apply(this, arguments);
+    
+    args.icon = 'sc-icon-info-48';
+    return this.show(args);
+  },
   
-  @returns {SC.AlertPane} the pane
-*/
-SC.AlertPane.error = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
-  var args = this._normalizeArguments(arguments);
-  args[6] = 'sc-icon-error-48';
-  return this.show.apply(this, args);
-};
-
-/**
-  Displays a plain all-text allert pane w/o icon.  See SC.AlertPane.show() for complete details. 
+  /**
+    Same as show() just that it uses sc-icon-error-48 CSS classname
+    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
+    args = SC.AlertPane._argumentsCall.apply(this, arguments);
+    
+    args.icon = 'sc-icon-error-48';
+    return this.show(args);
+  },
   
-  @returns {SC.AlertPane} the pane
-*/
-SC.AlertPane.plain = function(message, description, caption, button1Title, button2Title, button3Title, delegate) {
-  var args = this._normalizeArguments(arguments);
-  args[6] = 'blank';
-  return this.show.apply(this, args);
-};
+  /**
+    Same as show() just that it uses blank CSS classname
+    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
+    args = SC.AlertPane._argumentsCall.apply(this, arguments);
+    
+    args.icon = 'blank';
+    return this.show(args);
+  },
+  
+  /** @private
+    Set properties to new structure for call that use the old arguments 
+    structure.
+    
+    Deprecated API but is preserved for now for backwards compatibility.
+    
+    @deprecated
+  */
+  _argumentsCall: function(args) {
+    var ret = args;
+    if(SC.typeOf(args)!==SC.T_HASH) {
+      //@if(debug)
+      SC.debug('SC.AlertPane has changed the signatures for show(), info(), warn(), error() and plain(). Please update accordingly.');
+      //@endif
+      var normalizedArgs = this._normalizeArguments(arguments);
+      
+      // now convert it to the new format for show()
+      ret = {
+        message: normalizedArgs[0],
+        description: normalizedArgs[1],
+        caption: normalizedArgs[2],
+        delegate: normalizedArgs[7],
+        icon: (normalizedArgs[6] || 'sc-icon-alert-48')
+      };
+      
+      // set buttons if there are any (and check if it's a string, since last
+      // argument could be the delegate object)
+      if(SC.typeOf(normalizedArgs[3])===SC.T_STRING || SC.typeOf(normalizedArgs[4])===SC.T_STRING || SC.typeOf(normalizedArgs[5])===SC.T_STRING) {
+        ret.buttons = [
+          { title: normalizedArgs[3] },
+          { title: normalizedArgs[4] },
+          { title: normalizedArgs[5] }
+        ];
+      }
+      
+    }
+    return ret;
+  },
+  
+  /** @private
+    internal method normalizes arguments for processing by helper methods.
+  */
+  _normalizeArguments: function(args) {
+    args = SC.A(args); // convert to real array
+    var len = args.length, delegate = args[len-1];
+    if (SC.typeOf(delegate) !== SC.T_STRING) {
+      args[len-1] = null;
+    } else delegate = null ;
+    args[7] = delegate ;
+    return args ;
+  }
+  
+});