examples/ux/statusbar/StatusBar.js

   1 /*!
   2  * Ext JS Library 3.2.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   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         this.doLayout();
 212     },
 213
 214     /**
 215      * Sets the status {@link #text} and/or {@link #iconCls}. Also supports automatically clearing the
 216      * status that was set after a specified interval.
 217      * @param {Object/String} config A config object specifying what status to set, or a string assumed
 218      * to be the status text (and all other options are defaulted as explained below). A config
 219      * object containing any or all of the following properties can be passed:<ul>
 220      * <li><tt>text</tt> {String} : (optional) The status text to display.  If not specified, any current
 221      * status text will remain unchanged.</li>
 222      * <li><tt>iconCls</tt> {String} : (optional) The CSS class used to customize the status icon (see
 223      * {@link #iconCls} for details). If not specified, any current iconCls will remain unchanged.</li>
 224      * <li><tt>clear</tt> {Boolean/Number/Object} : (optional) Allows you to set an internal callback that will
 225      * automatically clear the status text and iconCls after a specified amount of time has passed. If clear is not
 226      * specified, the new status will not be auto-cleared and will stay until updated again or cleared using
 227      * {@link #clearStatus}. If <tt>true</tt> is passed, the status will be cleared using {@link #autoClear},
 228      * {@link #defaultText} and {@link #defaultIconCls} via a fade out animation. If a numeric value is passed,
 229      * it will be used as the callback interval (in milliseconds), overriding the {@link #autoClear} value.
 230      * All other options will be defaulted as with the boolean option.  To customize any other options,
 231      * you can pass an object in the format:<ul>
 232      *    <li><tt>wait</tt> {Number} : (optional) The number of milliseconds to wait before clearing
 233      *    (defaults to {@link #autoClear}).</li>
 234      *    <li><tt>anim</tt> {Number} : (optional) False to clear the status immediately once the callback
 235      *    executes (defaults to true which fades the status out).</li>
 236      *    <li><tt>useDefaults</tt> {Number} : (optional) False to completely clear the status text and iconCls
 237      *    (defaults to true which uses {@link #defaultText} and {@link #defaultIconCls}).</li>
 238      * </ul></li></ul>
 239      * Example usage:<pre><code>
 240 // Simple call to update the text
 241 statusBar.setStatus('New status');
 242
 243 // Set the status and icon, auto-clearing with default options:
 244 statusBar.setStatus({
 245     text: 'New status',
 246     iconCls: 'x-status-custom',
 247     clear: true
 248 });
 249
 250 // Auto-clear with custom options:
 251 statusBar.setStatus({
 252     text: 'New status',
 253     iconCls: 'x-status-custom',
 254     clear: {
 255         wait: 8000,
 256         anim: false,
 257         useDefaults: false
 258     }
 259 });
 260 </code></pre>
 261      * @return {Ext.ux.StatusBar} this
 262      */
 263     setStatus : function(o){
 264         o = o || {};
 265
 266         if(typeof o == 'string'){
 267             o = {text:o};
 268         }
 269         if(o.text !== undefined){
 270             this.setText(o.text);
 271         }
 272         if(o.iconCls !== undefined){
 273             this.setIcon(o.iconCls);
 274         }
 275
 276         if(o.clear){
 277             var c = o.clear,
 278                 wait = this.autoClear,
 279                 defaults = {useDefaults: true, anim: true};
 280
 281             if(typeof c == 'object'){
 282                 c = Ext.applyIf(c, defaults);
 283                 if(c.wait){
 284                     wait = c.wait;
 285                 }
 286             }else if(typeof c == 'number'){
 287                 wait = c;
 288                 c = defaults;
 289             }else if(typeof c == 'boolean'){
 290                 c = defaults;
 291             }
 292
 293             c.threadId = this.activeThreadId;
 294             this.clearStatus.defer(wait, this, [c]);
 295         }
 296         return this;
 297     },
 298
 299     /**
 300      * Clears the status {@link #text} and {@link #iconCls}. Also supports clearing via an optional fade out animation.
 301      * @param {Object} config (optional) A config object containing any or all of the following properties.  If this
 302      * object is not specified the status will be cleared using the defaults below:<ul>
 303      * <li><tt>anim</tt> {Boolean} : (optional) True to clear the status by fading out the status element (defaults
 304      * to false which clears immediately).</li>
 305      * <li><tt>useDefaults</tt> {Boolean} : (optional) True to reset the text and icon using {@link #defaultText} and
 306      * {@link #defaultIconCls} (defaults to false which sets the text to '' and removes any existing icon class).</li>
 307      * </ul>
 308      * @return {Ext.ux.StatusBar} this
 309      */
 310     clearStatus : function(o){
 311         o = o || {};
 312
 313         if(o.threadId && o.threadId !== this.activeThreadId){
 314             // this means the current call was made internally, but a newer
 315             // thread has set a message since this call was deferred.  Since
 316             // we don't want to overwrite a newer message just ignore.
 317             return this;
 318         }
 319
 320         var text = o.useDefaults ? this.defaultText : this.emptyText,
 321             iconCls = o.useDefaults ? (this.defaultIconCls ? this.defaultIconCls : '') : '';
 322
 323         if(o.anim){
 324             // animate the statusEl Ext.Element
 325             this.statusEl.el.fadeOut({
 326                 remove: false,
 327                 useDisplay: true,
 328                 scope: this,
 329                 callback: function(){
 330                     this.setStatus({
 331                             text: text,
 332                             iconCls: iconCls
 333                         });
 334
 335                     this.statusEl.el.show();
 336                 }
 337             });
 338         }else{
 339             // hide/show the el to avoid jumpy text or icon
 340             this.statusEl.hide();
 341                 this.setStatus({
 342                     text: text,
 343                     iconCls: iconCls
 344                 });
 345             this.statusEl.show();
 346         }
 347         return this;
 348     },
 349
 350     /**
 351      * Convenience method for setting the status text directly.  For more flexible options see {@link #setStatus}.
 352      * @param {String} text (optional) The text to set (defaults to '')
 353      * @return {Ext.ux.StatusBar} this
 354      */
 355     setText : function(text){
 356         this.activeThreadId++;
 357         this.text = text || '';
 358         if(this.rendered){
 359             this.statusEl.setText(this.text);
 360         }
 361         return this;
 362     },
 363
 364     /**
 365      * Returns the current status text.
 366      * @return {String} The status text
 367      */
 368     getText : function(){
 369         return this.text;
 370     },
 371
 372     /**
 373      * Convenience method for setting the status icon directly.  For more flexible options see {@link #setStatus}.
 374      * See {@link #iconCls} for complete details about customizing the icon.
 375      * @param {String} iconCls (optional) The icon class to set (defaults to '', and any current icon class is removed)
 376      * @return {Ext.ux.StatusBar} this
 377      */
 378     setIcon : function(cls){
 379         this.activeThreadId++;
 380         cls = cls || '';
 381
 382         if(this.rendered){
 383                 if(this.currIconCls){
 384                     this.statusEl.removeClass(this.currIconCls);
 385                     this.currIconCls = null;
 386                 }
 387                 if(cls.length > 0){
 388                     this.statusEl.addClass(cls);
 389                     this.currIconCls = cls;
 390                 }
 391         }else{
 392             this.currIconCls = cls;
 393         }
 394         return this;
 395     },
 396
 397     /**
 398      * Convenience method for setting the status text and icon to special values that are pre-configured to indicate
 399      * a "busy" state, usually for loading or processing activities.
 400      * @param {Object/String} config (optional) A config object in the same format supported by {@link #setStatus}, or a
 401      * string to use as the status text (in which case all other options for setStatus will be defaulted).  Use the
 402      * <tt>text</tt> and/or <tt>iconCls</tt> properties on the config to override the default {@link #busyText}
 403      * and {@link #busyIconCls} settings. If the config argument is not specified, {@link #busyText} and
 404      * {@link #busyIconCls} will be used in conjunction with all of the default options for {@link #setStatus}.
 405      * @return {Ext.ux.StatusBar} this
 406      */
 407     showBusy : function(o){
 408         if(typeof o == 'string'){
 409             o = {text:o};
 410         }
 411         o = Ext.applyIf(o || {}, {
 412             text: this.busyText,
 413             iconCls: this.busyIconCls
 414         });
 415         return this.setStatus(o);
 416     }
 417 });
 418 Ext.reg('statusbar', Ext.ux.StatusBar);