examples/ux/statusbar/StatusBar.js

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