source/widgets/StatusBar.js

   1 /*\r
   2  * Ext JS Library 2.2.1\r
   3  * Copyright(c) 2006-2009, Ext JS, LLC.\r
   4  * licensing@extjs.com\r
   5  * \r
   6  * http://extjs.com/license\r
   7  */\r
   8 \r
   9 /**\r
  10  * @class Ext.StatusBar\r
  11  * <p>Basic status bar component that can be used as the bottom toolbar of any {@link Ext.Panel}.  In addition to\r
  12  * supporting the standard {@link Ext.Toolbar} interface for adding buttons, menus and other items, the StatusBar\r
  13  * provides a greedy status element that can be aligned to either side and has convenient methods for setting the\r
  14  * status text and icon.  You can also indicate that something is processing using the {@link #showBusy} method.</p>\r
  15  * <p><b>Note:</b> Although StatusBar supports xtype:'statusbar', at this time Ext.Toolbar (the base class) does\r
  16  * not support xtype.  For this reason, if you are adding Toolbar items into the StatusBar you must declare it\r
  17  * using the "new StatusBar()" syntax for the items to render correctly.</p> \r
  18  * <pre><code>\r
  19 new Ext.Panel({\r
  20     title: 'StatusBar',\r
  21     // etc.\r
  22     bbar: new Ext.StatusBar({\r
  23         id: 'my-status',\r
  24         \r
  25         // defaults to use when the status is cleared:\r
  26         defaultText: 'Default status text',\r
  27         defaultIconCls: 'default-icon',\r
  28         \r
  29         // values to set initially:\r
  30         text: 'Ready',\r
  31         iconCls: 'ready-icon',\r
  32         \r
  33         // any standard Toolbar items:\r
  34         items: [{\r
  35             text: 'A Button'\r
  36         }, '-', 'Plain Text']\r
  37     })\r
  38 });\r
  39 \r
  40 // Update the status bar later in code:\r
  41 var sb = Ext.getCmp('my-status');\r
  42 sb.setStatus({\r
  43     text: 'OK',\r
  44     iconCls: 'ok-icon',\r
  45     clear: true // auto-clear after a set interval\r
  46 });\r
  47 \r
  48 // Set the status bar to show that something is processing:\r
  49 sb.showBusy();\r
  50 \r
  51 // processing....\r
  52  \r
  53 sb.clearStatus(); // once completeed\r
  54 </code></pre>\r
  55  * @extends Ext.Toolbar\r
  56  * @constructor\r
  57  * Creates a new StatusBar\r
  58  * @param {Object/Array} config A config object\r
  59  */\r
  60 Ext.StatusBar = Ext.extend(Ext.Toolbar, {\r
  61     /**\r
  62      * @cfg {String} statusAlign\r
  63      * The alignment of the status element within the overall StatusBar layout.  When the StatusBar is rendered,\r
  64      * it creates an internal div containing the status text and icon.  Any additional Toolbar items added in the\r
  65      * StatusBar's {@link #items} config, or added via {@link #add} or any of the supported add* methods, will be\r
  66      * rendered, in added order, to the opposite side.  The status element is greedy, so it will automatically\r
  67      * expand to take up all sapce left over by any other items.  Example usage:\r
  68      * <pre><code>\r
  69 // Create a left-aligned status bar containing a button,\r
  70 // separator and text item that will be right-aligned (default):\r
  71 new Ext.Panel({\r
  72     title: 'StatusBar',\r
  73     // etc.\r
  74     bbar: new Ext.StatusBar({\r
  75         defaultText: 'Default status text',\r
  76         id: 'status-id',\r
  77         items: [{\r
  78             text: 'A Button'\r
  79         }, '-', 'Plain Text']\r
  80     })\r
  81 });\r
  82 \r
  83 // By adding the statusAlign config, this will create the\r
  84 // exact same toolbar, except the status and toolbar item\r
  85 // layout will be reversed from the previous example:\r
  86 new Ext.Panel({\r
  87     title: 'StatusBar',\r
  88     // etc.\r
  89     bbar: new Ext.StatusBar({\r
  90         defaultText: 'Default status text',\r
  91         id: 'status-id',\r
  92         statusAlign: 'right',\r
  93         items: [{\r
  94             text: 'A Button'\r
  95         }, '-', 'Plain Text']\r
  96     })\r
  97 });\r
  98 </code></pre>\r
  99      */\r
 100     /**\r
 101      * @cfg {String} defaultText\r
 102      * The default {@link #text} value.  This will be used anytime the status bar is cleared with the \r
 103      * <tt>useDefaults:true</tt> option (defaults to '').\r
 104      */\r
 105     /**\r
 106      * @cfg {String} defaultIconCls\r
 107      * The default {@link #iconCls} value (see the iconCls docs for additional details about customizing the icon).  \r
 108      * This will be used anytime the status bar is cleared with the <tt>useDefaults:true</tt> option (defaults to '').\r
 109      */\r
 110     /**\r
 111      * @cfg {String} text\r
 112      * A string that will be rendered into the status element as the status message (defaults to '');\r
 113      */\r
 114     /**\r
 115      * @cfg {String} iconCls\r
 116      * A CSS class that will be applied to the status element and is expected to provide a background image that will\r
 117      * serve as the status bar icon (defaults to '').  The class is applied directly to the div that also contains the\r
 118      * status text, so the rule should provide the appropriate padding on the div to make room for the image. \r
 119      * Example usage:<pre><code>\r
 120 // Example CSS rule:\r
 121 .x-statusbar .x-status-custom {\r
 122     padding-left: 25px;\r
 123     background: transparent url(images/custom-icon.gif) no-repeat 3px 3px;\r
 124 }\r
 125 \r
 126 // Initializing the status bar:\r
 127 var sb = new Ext.StatusBar({\r
 128     defaultIconCls: 'x-status-custom'\r
 129 });\r
 130 \r
 131 // Setting it in code:\r
 132 sb.setStatus({\r
 133     text: 'New status',\r
 134     iconCls: 'x-status-custom'\r
 135 });\r
 136 </code></pre>\r
 137      */\r
 138     \r
 139     /**\r
 140      * @cfg {String} cls\r
 141      * The base class applied to the containing element for this component on render (defaults to 'x-statusbar')\r
 142      */\r
 143     cls : 'x-statusbar',\r
 144     /**\r
 145      * @cfg {String} busyIconCls\r
 146      * The default {@link #iconCls} applied when calling {@link #showBusy} (defaults to 'x-status-busy'). It can be\r
 147      * overridden at any time by passing the <tt>iconCls</tt> argument into <tt>showBusy</tt>. See the \r
 148      * iconCls docs for additional details about customizing the icon.\r
 149      */\r
 150     busyIconCls : 'x-status-busy',\r
 151     /**\r
 152      * @cfg {String} busyText\r
 153      * The default {@link #text} applied when calling {@link #showBusy} (defaults to 'Loading...'). It can be\r
 154      * overridden at any time by passing the <tt>text</tt> argument into <tt>showBusy</tt>.\r
 155      */\r
 156     busyText : 'Loading...',\r
 157     /**\r
 158      * @cfg {Number} autoClear\r
 159      * The number of milliseconds to wait after setting the status via {@link #setStatus} before automatically\r
 160      * clearing the status text and icon (defaults to 5000).  Note that this only applies when passing the \r
 161      * <tt>clear</tt> argument to setStatus since that is the only way to defer clearing the status.  This can\r
 162      * be overridden by specifying a different <tt>wait</tt> value in setStatus. Calls to {@link #clearStatus} \r
 163      * always clear the status bar immediately and ignore this value.\r
 164      */\r
 165     autoClear : 5000,\r
 166     \r
 167     // private\r
 168     activeThreadId : 0,\r
 169     \r
 170     // private\r
 171     initComponent : function(){\r
 172         if(this.statusAlign=='right'){\r
 173             this.cls += ' x-status-right';\r
 174         }\r
 175         Ext.StatusBar.superclass.initComponent.call(this);\r
 176     },\r
 177     \r
 178     // private\r
 179     afterRender : function(){\r
 180         Ext.StatusBar.superclass.afterRender.call(this);\r
 181         \r
 182         var right = this.statusAlign=='right',\r
 183             td = Ext.get(this.nextBlock());\r
 184         \r
 185         if(right){\r
 186             this.tr.appendChild(td.dom);\r
 187         }else{\r
 188             td.insertBefore(this.tr.firstChild);\r
 189         }\r
 190         \r
 191         this.statusEl = td.createChild({\r
 192             cls: 'x-status-text ' + (this.iconCls || this.defaultIconCls || ''),\r
 193             html: this.text || this.defaultText || ''\r
 194         });\r
 195         this.statusEl.unselectable();\r
 196         \r
 197         this.spacerEl = td.insertSibling({\r
 198             tag: 'td',\r
 199             style: 'width:100%',\r
 200             cn: [{cls:'ytb-spacer'}]\r
 201         }, right ? 'before' : 'after');\r
 202     },\r
 203 \r
 204     /**\r
 205      * Sets the status {@link #text} and/or {@link #iconCls}. Also supports automatically clearing the \r
 206      * status that was set after a specified interval.\r
 207      * @param {Object/String} config A config object specifying what status to set, or a string assumed \r
 208      * to be the status text (and all other options are defaulted as explained below). A config\r
 209      * object containing any or all of the following properties can be passed:<ul>\r
 210      * <li><tt>text</tt> {String} : (optional) The status text to display.  If not specified, any current \r
 211      * status text will remain unchanged.</li>\r
 212      * <li><tt>iconCls</tt> {String} : (optional) The CSS class used to customize the status icon (see \r
 213      * {@link #iconCls} for details). If not specified, any current iconCls will remain unchanged.</li>\r
 214      * <li><tt>clear</tt> {Boolean/Number/Object} : (optional) Allows you to set an internal callback that will \r
 215      * automatically clear the status text and iconCls after a specified amount of time has passed. If clear is not \r
 216      * specified, the new status will not be auto-cleared and will stay until updated again or cleared using \r
 217      * {@link #clearStatus}. If <tt>true</tt> is passed, the status will be cleared using {@link #autoClear}, \r
 218      * {@link #defaultText} and {@link #defaultIconCls} via a fade out animation. If a numeric value is passed, \r
 219      * it will be used as the callback interval (in milliseconds), overriding the {@link #autoClear} value. \r
 220      * All other options will be defaulted as with the boolean option.  To customize any other options, \r
 221      * you can pass an object in the format:<ul>\r
 222      *    <li><tt>wait</tt> {Number} : (optional) The number of milliseconds to wait before clearing \r
 223      *    (defaults to {@link #autoClear}).</li>\r
 224      *    <li><tt>anim</tt> {Number} : (optional) False to clear the status immediately once the callback \r
 225      *    executes (defaults to true which fades the status out).</li>\r
 226      *    <li><tt>useDefaults</tt> {Number} : (optional) False to completely clear the status text and iconCls\r
 227      *    (defaults to true which uses {@link #defaultText} and {@link #defaultIconCls}).</li>\r
 228      * </ul></li></ul>\r
 229      * Example usage:<pre><code>\r
 230 // Simple call to update the text\r
 231 statusBar.setStatus('New status');\r
 232 \r
 233 // Set the status and icon, auto-clearing with default options:\r
 234 statusBar.setStatus({\r
 235     text: 'New status',\r
 236     iconCls: 'x-status-custom',\r
 237     clear: true\r
 238 });\r
 239 \r
 240 // Auto-clear with custom options:\r
 241 statusBar.setStatus({\r
 242     text: 'New status',\r
 243     iconCls: 'x-status-custom',\r
 244     clear: {\r
 245         wait: 8000,\r
 246         anim: false,\r
 247         useDefaults: false\r
 248     }\r
 249 });\r
 250 </code></pre>\r
 251      * @return {Ext.StatusBar} this\r
 252      */\r
 253     setStatus : function(o){\r
 254         o = o || {};\r
 255         \r
 256         if(typeof o == 'string'){\r
 257             o = {text:o};\r
 258         }\r
 259         if(o.text !== undefined){\r
 260             this.setText(o.text);\r
 261         }\r
 262         if(o.iconCls !== undefined){\r
 263             this.setIcon(o.iconCls);\r
 264         }\r
 265         \r
 266         if(o.clear){\r
 267             var c = o.clear,\r
 268                 wait = this.autoClear,\r
 269                 defaults = {useDefaults: true, anim: true};\r
 270             \r
 271             if(typeof c == 'object'){\r
 272                 c = Ext.applyIf(c, defaults);\r
 273                 if(c.wait){\r
 274                     wait = c.wait;\r
 275                 }\r
 276             }else if(typeof c == 'number'){\r
 277                 wait = c;\r
 278                 c = defaults;\r
 279             }else if(typeof c == 'boolean'){\r
 280                 c = defaults;\r
 281             }\r
 282             \r
 283             c.threadId = this.activeThreadId;\r
 284             this.clearStatus.defer(wait, this, [c]);\r
 285         }\r
 286         return this;\r
 287     },\r
 288      \r
 289     /**\r
 290      * Clears the status {@link #text} and {@link #iconCls}. Also supports clearing via an optional fade out animation.\r
 291      * @param {Object} config (optional) A config object containing any or all of the following properties.  If this \r
 292      * object is not specified the status will be cleared using the defaults below:<ul>\r
 293      * <li><tt>anim</tt> {Boolean} : (optional) True to clear the status by fading out the status element (defaults\r
 294      * to false which clears immediately).</li>\r
 295      * <li><tt>useDefaults</tt> {Boolean} : (optional) True to reset the text and icon using {@link #defaultText} and \r
 296      * {@link #defaultIconCls} (defaults to false which sets the text to '' and removes any existing icon class).</li>\r
 297      * </ul>\r
 298      * @return {Ext.StatusBar} this\r
 299      */\r
 300     clearStatus : function(o){\r
 301         o = o || {};\r
 302         \r
 303         if(o.threadId && o.threadId !== this.activeThreadId){\r
 304             // this means the current call was made internally, but a newer\r
 305             // thread has set a message since this call was deferred.  Since\r
 306             // we don't want to overwrite a newer message just ignore.\r
 307             return this;\r
 308         }\r
 309         \r
 310         var text = o.useDefaults ? this.defaultText : '',\r
 311             iconCls = o.useDefaults ? (this.defaultIconCls ? this.defaultIconCls : '') : '';\r
 312             \r
 313         if(o.anim){\r
 314             this.statusEl.fadeOut({\r
 315                 remove: false,\r
 316                 useDisplay: true,\r
 317                 scope: this,\r
 318                 callback: function(){\r
 319                     this.setStatus({\r
 320                             text: text, \r
 321                             iconCls: iconCls\r
 322                         });\r
 323                     this.statusEl.show();\r
 324                 }\r
 325             });\r
 326         }else{\r
 327             // hide/show the el to avoid jumpy text or icon\r
 328             this.statusEl.hide();\r
 329                 this.setStatus({\r
 330                     text: text,\r
 331                     iconCls: iconCls\r
 332                 });\r
 333             this.statusEl.show();\r
 334         }\r
 335         return this;\r
 336     },\r
 337     \r
 338     /**\r
 339      * Convenience method for setting the status text directly.  For more flexible options see {@link #setStatus}.\r
 340      * @param {String} text (optional) The text to set (defaults to '')\r
 341      * @return {Ext.StatusBar} this\r
 342      */\r
 343     setText : function(text){\r
 344         this.activeThreadId++;\r
 345         this.text = text || '';\r
 346         if(this.rendered){\r
 347             this.statusEl.update(this.text);\r
 348         }\r
 349         return this;\r
 350     },\r
 351     \r
 352     /**\r
 353      * Returns the current status text.\r
 354      * @return {String} The status text\r
 355      */\r
 356     getText : function(){\r
 357         return this.text;\r
 358     },\r
 359 \r
 360     /**\r
 361      * Convenience method for setting the status icon directly.  For more flexible options see {@link #setStatus}.\r
 362      * See {@link #iconCls} for complete details about customizing the icon.\r
 363      * @param {String} iconCls (optional) The icon class to set (defaults to '', and any current icon class is removed)\r
 364      * @return {Ext.StatusBar} this\r
 365      */\r
 366     setIcon : function(cls){\r
 367         this.activeThreadId++;\r
 368         cls = cls || '';\r
 369         \r
 370         if(this.rendered){\r
 371                 if(this.currIconCls){\r
 372                     this.statusEl.removeClass(this.currIconCls);\r
 373                     this.currIconCls = null;\r
 374                 }\r
 375                 if(cls.length > 0){\r
 376                     this.statusEl.addClass(cls);\r
 377                     this.currIconCls = cls;\r
 378                 }\r
 379         }else{\r
 380             this.currIconCls = cls;\r
 381         }\r
 382         return this;\r
 383     },\r
 384     \r
 385     /**\r
 386      * Convenience method for setting the status text and icon to special values that are pre-configured to indicate\r
 387      * a "busy" state, usually for loading or processing activities.\r
 388      * @param {Object/String} config (optional) A config object in the same format supported by {@link #setStatus}, or a\r
 389      * string to use as the status text (in which case all other options for setStatus will be defaulted).  Use the \r
 390      * <tt>text</tt> and/or <tt>iconCls</tt> properties on the config to override the default {@link #busyText} \r
 391      * and {@link #busyIconCls} settings. If the config argument is not specified, {@link #busyText} and \r
 392      * {@link #busyIconCls} will be used in conjunction with all of the default options for {@link #setStatus}.\r
 393      * @return {Ext.StatusBar} this\r
 394      */\r
 395     showBusy : function(o){\r
 396         if(typeof o == 'string'){\r
 397             o = {text:o};\r
 398         }\r
 399         o = Ext.applyIf(o || {}, {\r
 400             text: this.busyText,\r
 401             iconCls: this.busyIconCls\r
 402         });\r
 403         return this.setStatus(o);\r
 404     }\r
 405 });\r
 406 Ext.reg('statusbar', Ext.StatusBar);\r