/javascripts/lib/src/widgets/LoadMask.js

  1/*!
  2 * Ext JS Library 3.2.1
  3 * Copyright(c) 2006-2010 Ext JS, Inc.
  4 * licensing@extjs.com
  5 * http://www.extjs.com/license
  6 */
  7/**
  8 * @class Ext.LoadMask
  9 * A simple utility class for generically masking elements while loading data.  If the {@link #store}
 10 * config option is specified, the masking will be automatically synchronized with the store's loading
 11 * process and the mask element will be cached for reuse.  For all other elements, this mask will replace the
 12 * element's Updater load indicator and will be destroyed after the initial load.
 13 * <p>Example usage:</p>
 14 *<pre><code>
 15// Basic mask:
 16var myMask = new Ext.LoadMask(Ext.getBody(), {msg:"Please wait..."});
 17myMask.show();
 18</code></pre>
 19 * @constructor
 20 * Create a new LoadMask
 21 * @param {Mixed} el The element or DOM node, or its id
 22 * @param {Object} config The config object
 23 */
 24Ext.LoadMask = function(el, config){
 25    this.el = Ext.get(el);
 26    Ext.apply(this, config);
 27    if(this.store){
 28        this.store.on({
 29            scope: this,
 30            beforeload: this.onBeforeLoad,
 31            load: this.onLoad,
 32            exception: this.onLoad
 33        });
 34        this.removeMask = Ext.value(this.removeMask, false);
 35    }else{
 36        var um = this.el.getUpdater();
 37        um.showLoadIndicator = false; // disable the default indicator
 38        um.on({
 39            scope: this,
 40            beforeupdate: this.onBeforeLoad,
 41            update: this.onLoad,
 42            failure: this.onLoad
 43        });
 44        this.removeMask = Ext.value(this.removeMask, true);
 45    }
 46};
 47
 48Ext.LoadMask.prototype = {
 49    /**
 50     * @cfg {Ext.data.Store} store
 51     * Optional Store to which the mask is bound. The mask is displayed when a load request is issued, and
 52     * hidden on either load sucess, or load fail.
 53     */
 54    /**
 55     * @cfg {Boolean} removeMask
 56     * True to create a single-use mask that is automatically destroyed after loading (useful for page loads),
 57     * False to persist the mask element reference for multiple uses (e.g., for paged data widgets).  Defaults to false.
 58     */
 59    /**
 60     * @cfg {String} msg
 61     * The text to display in a centered loading message box (defaults to 'Loading...')
 62     */
 63    msg : 'Loading...',
 64    /**
 65     * @cfg {String} msgCls
 66     * The CSS class to apply to the loading message element (defaults to "x-mask-loading")
 67     */
 68    msgCls : 'x-mask-loading',
 69
 70    /**
 71     * Read-only. True if the mask is currently disabled so that it will not be displayed (defaults to false)
 72     * @type Boolean
 73     */
 74    disabled: false,
 75
 76    /**
 77     * Disables the mask to prevent it from being displayed
 78     */
 79    disable : function(){
 80       this.disabled = true;
 81    },
 82
 83    /**
 84     * Enables the mask so that it can be displayed
 85     */
 86    enable : function(){
 87        this.disabled = false;
 88    },
 89
 90    // private
 91    onLoad : function(){
 92        this.el.unmask(this.removeMask);
 93    },
 94
 95    // private
 96    onBeforeLoad : function(){
 97        if(!this.disabled){
 98            this.el.mask(this.msg, this.msgCls);
 99        }
100    },
101
102    /**
103     * Show this LoadMask over the configured Element.
104     */
105    show: function(){
106        this.onBeforeLoad();
107    },
108
109    /**
110     * Hide this LoadMask.
111     */
112    hide: function(){
113        this.onLoad();
114    },
115
116    // private
117    destroy : function(){
118        if(this.store){
119            this.store.un('beforeload', this.onBeforeLoad, this);
120            this.store.un('load', this.onLoad, this);
121            this.store.un('exception', this.onLoad, this);
122        }else{
123            var um = this.el.getUpdater();
124            um.un('beforeupdate', this.onBeforeLoad, this);
125            um.un('update', this.onLoad, this);
126            um.un('failure', this.onLoad, this);
127        }
128    }
129};