3 * Copyright(c) 2006-2009 Ext JS, LLC
5 * http://www.extjs.com/license
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>
17 bbar: new Ext.ux.StatusBar({
20 // defaults to use when the status is cleared:
21 defaultText: 'Default status text',
22 defaultIconCls: 'default-icon',
24 // values to set initially:
26 iconCls: 'ready-icon',
28 // any standard Toolbar items:
35 // Update the status bar later in code:
36 var sb = Ext.getCmp('my-status');
40 clear: true // auto-clear after a set interval
43 // Set the status bar to show that something is processing:
48 sb.clearStatus(); // once completeed
50 * @extends Ext.Toolbar
52 * Creates a new StatusBar
53 * @param {Object/Array} config A config object
55 Ext.ux.StatusBar = Ext.extend(Ext.Toolbar, {
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:
64 // Create a left-aligned status bar containing a button,
65 // separator and text item that will be right-aligned (default):
69 bbar: new Ext.ux.StatusBar({
70 defaultText: 'Default status text',
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:
84 bbar: new Ext.ux.StatusBar({
85 defaultText: 'Default status text',
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 '').
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 '').
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>
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>
118 .x-statusbar .x-status-custom {
120 background: transparent url(images/custom-icon.gif) no-repeat 3px 2px;
123 // Setting a default icon:
124 var sb = new Ext.ux.StatusBar({
125 defaultIconCls: 'x-status-custom'
128 // Changing the icon:
131 iconCls: 'x-status-custom'
138 * The base class applied to the containing element for this component on render (defaults to 'x-statusbar')
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>.
148 busyIconCls : 'x-status-busy',
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>.
156 busyText : 'Loading...',
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.
171 * @cfg {String} emptyText
172 * The text string to use if no text has been set. Defaults to
173 * <tt>' '</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
180 emptyText : ' ',
186 initComponent : function(){
187 if(this.statusAlign=='right'){
188 this.cls += ' x-status-right';
190 Ext.ux.StatusBar.superclass.initComponent.call(this);
194 afterRender : function(){
195 Ext.ux.StatusBar.superclass.afterRender.call(this);
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 || ''
206 this.add(this.statusEl);
208 this.insert(0, this.statusEl);
209 this.insert(1, '->');
212 // this.statusEl = td.createChild({
213 // cls: 'x-status-text ' + (this.iconCls || this.defaultIconCls || ''),
214 // html: this.text || this.defaultText || ''
216 // this.statusEl.unselectable();
218 // this.spacerEl = td.insertSibling({
220 // style: 'width:100%',
221 // cn: [{cls:'ytb-spacer'}]
222 // }, right ? 'before' : 'after');
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>
250 * Example usage:<pre><code>
251 // Simple call to update the text
252 statusBar.setStatus('New status');
254 // Set the status and icon, auto-clearing with default options:
255 statusBar.setStatus({
257 iconCls: 'x-status-custom',
261 // Auto-clear with custom options:
262 statusBar.setStatus({
264 iconCls: 'x-status-custom',
272 * @return {Ext.ux.StatusBar} this
274 setStatus : function(o){
277 if(typeof o == 'string'){
280 if(o.text !== undefined){
281 this.setText(o.text);
283 if(o.iconCls !== undefined){
284 this.setIcon(o.iconCls);
289 wait = this.autoClear,
290 defaults = {useDefaults: true, anim: true};
292 if(typeof c == 'object'){
293 c = Ext.applyIf(c, defaults);
297 }else if(typeof c == 'number'){
300 }else if(typeof c == 'boolean'){
304 c.threadId = this.activeThreadId;
305 this.clearStatus.defer(wait, this, [c]);
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>
319 * @return {Ext.ux.StatusBar} this
321 clearStatus : function(o){
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.
331 var text = o.useDefaults ? this.defaultText : this.emptyText,
332 iconCls = o.useDefaults ? (this.defaultIconCls ? this.defaultIconCls : '') : '';
335 // animate the statusEl Ext.Element
336 this.statusEl.el.fadeOut({
340 callback: function(){
346 this.statusEl.el.show();
350 // hide/show the el to avoid jumpy text or icon
351 this.statusEl.hide();
356 this.statusEl.show();
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
366 setText : function(text){
367 this.activeThreadId++;
368 this.text = text || '';
370 this.statusEl.setText(this.text);
376 * Returns the current status text.
377 * @return {String} The status text
379 getText : function(){
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
389 setIcon : function(cls){
390 this.activeThreadId++;
394 if(this.currIconCls){
395 this.statusEl.removeClass(this.currIconCls);
396 this.currIconCls = null;
399 this.statusEl.addClass(cls);
400 this.currIconCls = cls;
403 this.currIconCls = cls;
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
418 showBusy : function(o){
419 if(typeof o == 'string'){
422 o = Ext.applyIf(o || {}, {
424 iconCls: this.busyIconCls
426 return this.setStatus(o);
429 Ext.reg('statusbar', Ext.ux.StatusBar);