docs/source/StatusBar.html

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