Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / MessageBox.html
index 64f332a..9e46abb 100644 (file)
@@ -1,11 +1,18 @@
-<html>\r
-<head>\r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.MessageBox"></div>/**
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <title>The source code</title>
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.3.1
+ * Copyright(c) 2006-2010 Sencha Inc.
+ * licensing@sencha.com
+ * http://www.sencha.com/license
+ */
+<div id="cls-Ext.MessageBox"></div>/**
  * @class Ext.MessageBox
  * <p>Utility class for generating different styles of message boxes.  The alias Ext.Msg can also be used.<p/>
  * <p>Note that the MessageBox is asynchronous.  Unlike a regular JavaScript <code>alert</code> (which will halt
@@ -37,12 +44,14 @@ Ext.Msg.show({
  * @singleton
  */
 Ext.MessageBox = function(){
-    var dlg, opt, mask, waitTimer;
-    var bodyEl, msgEl, textboxEl, textareaEl, progressBar, pp, iconEl, spacerEl;
-    var buttons, activeTextEl, bwidth, iconCls = '';
+    var dlg, opt, mask, waitTimer,
+        bodyEl, msgEl, textboxEl, textareaEl, progressBar, pp, iconEl, spacerEl,
+        buttons, activeTextEl, bwidth, bufferIcon = '', iconCls = '',
+        buttonNames = ['ok', 'yes', 'no', 'cancel'];
 
     // private
     var handleButton = function(button){
+        buttons[button].blur();
         if(dlg.isVisible()){
             dlg.hide();
             handleHide();
@@ -55,7 +64,7 @@ Ext.MessageBox = function(){
         if(opt && opt.cls){
             dlg.el.removeClass(opt.cls);
         }
-        progressBar.reset();
+        progressBar.reset();        
     };
 
     // private
@@ -71,26 +80,25 @@ Ext.MessageBox = function(){
 
     // private
     var updateButtons = function(b){
-        var width = 0;
+        var width = 0,
+            cfg;
         if(!b){
-            buttons['ok'].hide();
-            buttons['cancel'].hide();
-            buttons['yes'].hide();
-            buttons['no'].hide();
+            Ext.each(buttonNames, function(name){
+                buttons[name].hide();
+            });
             return width;
         }
         dlg.footer.dom.style.display = '';
-        for(var k in buttons){
-            if(typeof buttons[k] != 'function'){
-                if(b[k]){
-                    buttons[k].show();
-                    buttons[k].setText(typeof b[k] == 'string' ? b[k] : Ext.MessageBox.buttonText[k]);
-                    width += buttons[k].el.getWidth()+15;
-                }else{
-                    buttons[k].hide();
-                }
+        Ext.iterate(buttons, function(name, btn){
+            cfg = b[name];
+            if(cfg){
+                btn.show();
+                btn.setText(Ext.isString(cfg) ? cfg : Ext.MessageBox.buttonText[name]);
+                width += btn.getEl().getWidth() + 15;
+            }else{
+                btn.hide();
             }
-        }
+        });
         return width;
     };
 
@@ -101,6 +109,16 @@ Ext.MessageBox = function(){
          */
         getDialog : function(titleText){
            if(!dlg){
+                var btns = [];
+                
+                buttons = {};
+                Ext.each(buttonNames, function(name){
+                    btns.push(buttons[name] = new Ext.Button({
+                        text: this.buttonText[name],
+                        handler: handleButton.createCallback(name),
+                        hideMode: 'offsets'
+                    }));
+                }, this);
                 dlg = new Ext.Window({
                     autoCreate : true,
                     title:titleText,
@@ -112,7 +130,7 @@ Ext.MessageBox = function(){
                     stateful: false,
                     modal: true,
                     shim:true,
-                    buttonAlign:'center',
+                    buttonAlign:"center",
                     width:400,
                     height:100,
                     minHeight: 80,
@@ -121,20 +139,16 @@ Ext.MessageBox = function(){
                     closable:true,
                     close : function(){
                         if(opt && opt.buttons && opt.buttons.no && !opt.buttons.cancel){
-                            handleButton('no');
+                            handleButton("no");
                         }else{
-                            handleButton('cancel');
+                            handleButton("cancel");
                         }
-                    }
+                    },
+                    fbar: new Ext.Toolbar({
+                        items: btns,
+                        enableOverflow: false
+                    })
                 });
-                buttons = {};
-                var bt = this.buttonText;
-                //TODO: refactor this block into a buttons config to pass into the Window constructor
-                buttons['ok'] = dlg.addButton(bt['ok'], handleButton.createCallback('ok'));
-                buttons['yes'] = dlg.addButton(bt['yes'], handleButton.createCallback('yes'));
-                buttons['no'] = dlg.addButton(bt['no'], handleButton.createCallback('no'));
-                buttons['cancel'] = dlg.addButton(bt['cancel'], handleButton.createCallback('cancel'));
-                buttons['ok'].hideMode = buttons['yes'].hideMode = buttons['no'].hideMode = buttons['cancel'].hideMode = 'offsets';
                 dlg.render(document.body);
                 dlg.getEl().addClass('x-window-dlg');
                 mask = dlg.mask;
@@ -149,9 +163,9 @@ Ext.MessageBox = function(){
                 textboxEl.addKeyListener([10,13], function(){
                     if(dlg.isVisible() && opt && opt.buttons){
                         if(opt.buttons.ok){
-                            handleButton('ok');
+                            handleButton("ok");
                         }else if(opt.buttons.yes){
-                            handleButton('yes');
+                            handleButton("yes");
                         }
                     }
                 });
@@ -175,19 +189,17 @@ Ext.MessageBox = function(){
             if(!dlg.isVisible() && !opt.width){
                 dlg.setSize(this.maxWidth, 100); // resize first so content is never clipped from previous shows
             }
-            msgEl.update(text || '&#160;');
+            // Append a space here for sizing. In IE, for some reason, it wraps text incorrectly without one in some cases
+            msgEl.update(text ? text + ' ' : '&#160;');
 
-            var iw = iconCls != '' ? (iconEl.getWidth() + iconEl.getMargins('lr')) : 0;
-            var mw = msgEl.getWidth() + msgEl.getMargins('lr');
-            var fw = dlg.getFrameWidth('lr');
-            var bw = dlg.body.getFrameWidth('lr');
-            if (Ext.isIE && iw > 0){
-                //3 pixels get subtracted in the icon CSS for an IE margin issue,
-                //so we have to add it back here for the overall width to be consistent
-                iw += 3;
-            }
-            var w = Math.max(Math.min(opt.width || iw+mw+fw+bw, this.maxWidth),
-                        Math.max(opt.minWidth || this.minWidth, bwidth || 0));
+            var iw = iconCls != '' ? (iconEl.getWidth() + iconEl.getMargins('lr')) : 0,
+                mw = msgEl.getWidth() + msgEl.getMargins('lr'),
+                fw = dlg.getFrameWidth('lr'),
+                bw = dlg.body.getFrameWidth('lr'),
+                w;
+                
+            w = Math.max(Math.min(opt.width || iw+mw+fw+bw, opt.maxWidth || this.maxWidth),
+                    Math.max(opt.minWidth || this.minWidth, bwidth || 0));
 
             if(opt.prompt === true){
                 activeTextEl.setWidth(w-iw-fw-bw);
@@ -198,6 +210,7 @@ Ext.MessageBox = function(){
             if(Ext.isIE && w == bwidth){
                 w += 4; //Add offset when the content width is smaller than the buttons.    
             }
+            msgEl.update(text || '&#160;');
             dlg.setSize(w, 'auto').center();
             return this;
         },
@@ -259,6 +272,8 @@ Ext.MessageBox = function(){
          * progress and wait dialogs will ignore this property and always hide the close button as they can only
          * be closed programmatically.</div></li>
          * <li><b>cls</b> : String<div class="sub-desc">A custom CSS class to apply to the message box's container element</div></li>
+         * <li><b>defaultTextHeight</b> : Number<div class="sub-desc">The default height in pixels of the message box's multiline textarea
+         * if displayed (defaults to 75)</div></li>
          * <li><b>fn</b> : Function<div class="sub-desc">A callback function which is called when the dialog is dismissed either
          * by clicking on the configured buttons, or on the dialog close button, or by pressing
          * the return button to enter input.
@@ -286,15 +301,11 @@ Ext.MessageBox = function(){
          * displayed (defaults to true)</div></li>
          * <li><b>msg</b> : String<div class="sub-desc">A string that will replace the existing message box body text (defaults to the
          * XHTML-compliant non-breaking space character '&amp;#160;')</div></li>
-         * <li><a id="show-option-multiline"></a><b>multiline</b> : Boolean/Number<div class="sub-desc">
-         * If <code>prompt</code> is true, instead of prompting the user with a single line textbox,
-         * specify <code>multiline = true</code> to prompt the user with a multiline textarea
-         * using the <code>{@link #defaultTextHeight}</code> property, or specify a height in pixels
-         * to create the textarea (defaults to false creating a single-line textbox)</div></li>
+         * <li><a id="show-option-multiline"></a><b>multiline</b> : Boolean<div class="sub-desc">
+         * True to prompt the user to enter multi-line text (defaults to false)</div></li>
          * <li><b>progress</b> : Boolean<div class="sub-desc">True to display a progress bar (defaults to false)</div></li>
          * <li><b>progressText</b> : String<div class="sub-desc">The text to display inside the progress bar if progress = true (defaults to '')</div></li>
-         * <li><a id="show-option-prompt"></a><b>prompt</b> : Boolean<div class="sub-desc">
-         * True to prompt the user with a textbox or textarea (defaults to false)</div></li>
+         * <li><a id="show-option-prompt"></a><b>prompt</b> : Boolean<div class="sub-desc">True to prompt the user to enter single-line text (defaults to false)</div></li>
          * <li><b>proxyDrag</b> : Boolean<div class="sub-desc">True to display a lightweight proxy while dragging (defaults to false)</div></li>
          * <li><b>title</b> : String<div class="sub-desc">The title text</div></li>
          * <li><b>value</b> : String<div class="sub-desc">The string value to set into the active textbox element if displayed</div></li>
@@ -309,7 +320,7 @@ Ext.Msg.show({
    msg: 'Please enter your address:',
    width: 300,
    buttons: Ext.MessageBox.OKCANCEL,
-   multiline: true, // show a multiline textarea using the {@link #defaultTextHeight}
+   multiline: true,
    fn: saveAddress,
    animEl: 'addAddressBtn',
    icon: Ext.MessageBox.INFO
@@ -322,9 +333,9 @@ Ext.Msg.show({
                 this.hide();
             }
             opt = options;
-            var d = this.getDialog(opt.title || '&#160;');
+            var d = this.getDialog(opt.title || "&#160;");
 
-            d.setTitle(opt.title || '&#160;');
+            d.setTitle(opt.title || "&#160;");
             var allowClose = (opt.closable !== false && opt.progress !== true && opt.wait !== true);
             d.tools.close.setDisplayed(allowClose);
             activeTextEl = textboxEl;
@@ -333,8 +344,7 @@ Ext.Msg.show({
                 if(opt.multiline){
                     textboxEl.hide();
                     textareaEl.show();
-                    textareaEl.setHeight(typeof opt.multiline == 'number' ?
-                        opt.multiline : this.defaultTextHeight);
+                    textareaEl.setHeight(Ext.isNumber(opt.multiline) ? opt.multiline : this.defaultTextHeight);
                     activeTextEl = textareaEl;
                 }else{
                     textboxEl.show();
@@ -344,60 +354,60 @@ Ext.Msg.show({
                 textboxEl.hide();
                 textareaEl.hide();
             }
-            activeTextEl.dom.value = opt.value || '';
+            activeTextEl.dom.value = opt.value || "";
             if(opt.prompt){
                 d.focusEl = activeTextEl;
             }else{
                 var bs = opt.buttons;
                 var db = null;
                 if(bs && bs.ok){
-                    db = buttons['ok'];
+                    db = buttons["ok"];
                 }else if(bs && bs.yes){
-                    db = buttons['yes'];
+                    db = buttons["yes"];
                 }
                 if (db){
                     d.focusEl = db;
                 }
             }
-            if(opt.iconCls){
+            if(Ext.isDefined(opt.iconCls)){
               d.setIconClass(opt.iconCls);
             }
-            this.setIcon(opt.icon);
+            this.setIcon(Ext.isDefined(opt.icon) ? opt.icon : bufferIcon);
+            bwidth = updateButtons(opt.buttons);
+            progressBar.setVisible(opt.progress === true || opt.wait === true);
+            this.updateProgress(0, opt.progressText);
+            this.updateText(opt.msg);
             if(opt.cls){
                 d.el.addClass(opt.cls);
             }
             d.proxyDrag = opt.proxyDrag === true;
             d.modal = opt.modal !== false;
             d.mask = opt.modal !== false ? mask : false;
-            
-            d.on('show', function(){
-                //workaround for window internally enabling keymap in afterShow
-                d.keyMap.setDisabled(allowClose !== true);
-                d.doLayout();
-                this.setIcon(opt.icon);
-                bwidth = updateButtons(opt.buttons);
-                progressBar.setVisible(opt.progress === true || opt.wait === true);
-                this.updateProgress(0, opt.progressText);
-                this.updateText(opt.msg);
-                if(opt.wait === true){
-                    progressBar.wait(opt.waitConfig);
-                }
-
-            }, this, {single:true});
             if(!d.isVisible()){
                 // force it to the end of the z-index stack so it gets a cursor in FF
                 document.body.appendChild(dlg.el.dom);
                 d.setAnimateTarget(opt.animEl);
+                //workaround for window internally enabling keymap in afterShow
+                d.on('show', function(){
+                    if(allowClose === true){
+                        d.keyMap.enable();
+                    }else{
+                        d.keyMap.disable();
+                    }
+                }, this, {single:true});
                 d.show(opt.animEl);
             }
+            if(opt.wait === true){
+                progressBar.wait(opt.waitConfig);
+            }
             return this;
         },
 
         <div id="method-Ext.MessageBox-setIcon"></div>/**
          * Adds the specified icon to the dialog.  By default, the class 'ext-mb-icon' is applied for default
          * styling, and the class passed in is expected to supply the background image url. Pass in empty string ('')
-         * to clear any existing icon.  The following built-in icon classes are supported, but you can also pass
-         * in a custom class name:
+         * to clear any existing icon. This method must be called before the MessageBox is shown.
+         * The following built-in icon classes are supported, but you can also pass in a custom class name:
          * <pre>
 Ext.MessageBox.INFO
 Ext.MessageBox.WARNING
@@ -408,6 +418,11 @@ Ext.MessageBox.ERROR
          * @return {Ext.MessageBox} this
          */
         setIcon : function(icon){
+            if(!dlg){
+                bufferIcon = icon;
+                return;
+            }
+            bufferIcon = undefined;
             if(icon && icon != ''){
                 iconEl.removeClass('x-hidden');
                 iconEl.replaceClass(iconCls, icon);
@@ -474,7 +489,7 @@ Ext.MessageBox.ERROR
          * @param {String} title The title bar text
          * @param {String} msg The message box body text
          * @param {Function} fn (optional) The callback function invoked after the message box is closed
-         * @param {Object} scope (optional) The scope of the callback function
+         * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to the browser wnidow.
          * @return {Ext.MessageBox} this
          */
         alert : function(title, msg, fn, scope){
@@ -483,7 +498,8 @@ Ext.MessageBox.ERROR
                 msg : msg,
                 buttons: this.OK,
                 fn: fn,
-                scope : scope
+                scope : scope,
+                minWidth: this.minWidth
             });
             return this;
         },
@@ -496,7 +512,7 @@ Ext.MessageBox.ERROR
          * @param {String} title The title bar text
          * @param {String} msg The message box body text
          * @param {Function} fn (optional) The callback function invoked after the message box is closed
-         * @param {Object} scope (optional) The scope of the callback function
+         * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to the browser wnidow.
          * @return {Ext.MessageBox} this
          */
         confirm : function(title, msg, fn, scope){
@@ -506,7 +522,8 @@ Ext.MessageBox.ERROR
                 buttons: this.YESNO,
                 fn: fn,
                 scope : scope,
-                icon: this.QUESTION
+                icon: this.QUESTION,
+                minWidth: this.minWidth
             });
             return this;
         },
@@ -519,7 +536,7 @@ Ext.MessageBox.ERROR
          * @param {String} title The title bar text
          * @param {String} msg The message box body text
          * @param {Function} fn (optional) The callback function invoked after the message box is closed
-         * @param {Object} scope (optional) The scope of the callback function
+         * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to the browser wnidow.
          * @param {Boolean/Number} multiline (optional) True to create a multiline textbox using the defaultTextHeight
          * property, or the height in pixels to create the textbox (defaults to false / single-line)
          * @param {String} value (optional) Default value of the text input element (defaults to '')
@@ -531,7 +548,7 @@ Ext.MessageBox.ERROR
                 msg : msg,
                 buttons: this.OKCANCEL,
                 fn: fn,
-                minWidth:250,
+                minWidth: this.minPromptWidth,
                 scope : scope,
                 prompt:true,
                 multiline: multiline,
@@ -597,28 +614,34 @@ Ext.MessageBox.ERROR
          */
         maxWidth : 600,
         <div id="prop-Ext.MessageBox-minWidth"></div>/**
-         * The minimum width in pixels of the message box (defaults to 110)
+         * The minimum width in pixels of the message box (defaults to 100)
          * @type Number
          */
-        minWidth : 110,
+        minWidth : 100,
         <div id="prop-Ext.MessageBox-minProgressWidth"></div>/**
          * The minimum width in pixels of the message box if it is a progress-style dialog.  This is useful
-         * for setting a different minimum width than text-only dialogs may need (defaults to 250)
+         * for setting a different minimum width than text-only dialogs may need (defaults to 250).
          * @type Number
          */
         minProgressWidth : 250,
+        <div id="prop-Ext.MessageBox-minPromptWidth"></div>/**
+         * The minimum width in pixels of the message box if it is a prompt dialog.  This is useful
+         * for setting a different minimum width than text-only dialogs may need (defaults to 250).
+         * @type Number
+         */
+        minPromptWidth: 250,
         <div id="prop-Ext.MessageBox-buttonText"></div>/**
          * An object containing the default button text strings that can be overriden for localized language support.
          * Supported properties are: ok, cancel, yes and no.  Generally you should include a locale-specific
          * resource file for handling language support across the framework.
-         * Customize the default text like so: Ext.MessageBox.buttonText.yes = 'oui'; //french
+         * Customize the default text like so: Ext.MessageBox.buttonText.yes = "oui"; //french
          * @type Object
          */
         buttonText : {
-            ok : 'OK',
-            cancel : 'Cancel',
-            yes : 'Yes',
-            no : 'No'
+            ok : "OK",
+            cancel : "Cancel",
+            yes : "Yes",
+            no : "No"
         }
     };
 }();
@@ -626,6 +649,6 @@ Ext.MessageBox.ERROR
 <div id="prop-Ext.MessageBox-Msg"></div>/**
  * Shorthand for {@link Ext.MessageBox}
  */
-Ext.Msg = Ext.MessageBox;</pre>    \r
-</body>\r
+Ext.Msg = Ext.MessageBox;</pre>    
+</body>
 </html>
\ No newline at end of file