examples/docs/source/StatusBar.html

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