examples/ux/StatusBar.js

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