docs/source/StatusBar.html

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