Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / ColumnModel.html
index a7bd6f5..da438b7 100644 (file)
@@ -7,10 +7,10 @@
 </head>
 <body  onload="prettyPrint();">
     <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.2.1
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
+ * Ext JS Library 3.3.1
+ * Copyright(c) 2006-2010 Sencha Inc.
+ * licensing@sencha.com
+ * http://www.sencha.com/license
  */
 <div id="cls-Ext.grid.ColumnModel"></div>/**
  * @class Ext.grid.ColumnModel
@@ -103,24 +103,27 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * <tt><b>{@link #defaults}</b></tt> config property.
      */
     defaultWidth: 100,
+
     <div id="cfg-Ext.grid.ColumnModel-defaultSortable"></div>/**
      * @cfg {Boolean} defaultSortable (optional) Default sortable of columns which have no
      * sortable specified (defaults to <tt>false</tt>).  This property shall preferably be configured
      * through the <tt><b>{@link #defaults}</b></tt> config property.
      */
     defaultSortable: false,
+
     <div id="cfg-Ext.grid.ColumnModel-columns"></div>/**
      * @cfg {Array} columns An Array of object literals.  The config options defined by
      * <b>{@link Ext.grid.Column}</b> are the options which may appear in the object literal for each
      * individual column definition.
      */
+
     <div id="cfg-Ext.grid.ColumnModel-defaults"></div>/**
      * @cfg {Object} defaults Object literal which will be used to apply {@link Ext.grid.Column}
      * configuration options to all <tt><b>{@link #columns}</b></tt>.  Configuration options specified with
      * individual {@link Ext.grid.Column column} configs will supersede these <tt><b>{@link #defaults}</b></tt>.
      */
 
-    constructor : function(config){
+    constructor : function(config) {
         <div id="prop-Ext.grid.ColumnModel-config"></div>/**
             * An Array of {@link Ext.grid.Column Column definition} objects representing the configuration
             * of this ColumnModel.  See {@link Ext.grid.Column} for the configuration properties that may
@@ -128,12 +131,13 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
             * @property config
             * @type Array
             */
-           if(config.columns){
+           if (config.columns) {
                Ext.apply(this, config);
                this.setConfig(config.columns, true);
-           }else{
+           } else {
                this.setConfig(config, true);
            }
+           
            this.addEvents(
                <div id="event-Ext.grid.ColumnModel-widthchange"></div>/**
                 * @event widthchange
@@ -146,6 +150,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
                 * @param {Number} newWidth The new width
                 */
                "widthchange",
+               
                <div id="event-Ext.grid.ColumnModel-headerchange"></div>/**
                 * @event headerchange
                 * Fires when the text of a header changes.
@@ -154,6 +159,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
                 * @param {String} newText The new header text
                 */
                "headerchange",
+               
                <div id="event-Ext.grid.ColumnModel-hiddenchange"></div>/**
                 * @event hiddenchange
                 * Fires when a column is hidden or "unhidden".
@@ -162,6 +168,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
                 * @param {Boolean} hidden true if hidden, false otherwise
                 */
                "hiddenchange",
+               
                <div id="event-Ext.grid.ColumnModel-columnmoved"></div>/**
                 * @event columnmoved
                 * Fires when a column is moved.
@@ -170,6 +177,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
                 * @param {Number} newIndex
                 */
                "columnmoved",
+               
                <div id="event-Ext.grid.ColumnModel-configchange"></div>/**
                 * @event configchange
                 * Fires when the configuration is changed
@@ -177,6 +185,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
                 */
                "configchange"
            );
+           
            Ext.grid.ColumnModel.superclass.constructor.call(this);
     },
 
@@ -185,11 +194,11 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {Number} index The column index
      * @return {String} the id
      */
-    getColumnId : function(index){
+    getColumnId : function(index) {
         return this.config[index].id;
     },
 
-    getColumnAt : function(index){
+    getColumnAt : function(index) {
         return this.config[index];
     },
 
@@ -203,13 +212,16 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {Boolean} initial Specify <tt>true</tt> to bypass cleanup which deletes the <tt>totalWidth</tt>
      * and destroys existing editors.
      */
-    setConfig : function(config, initial){
+    setConfig : function(config, initial) {
         var i, c, len;
-        if(!initial){ // cleanup
+        
+        if (!initial) { // cleanup
             delete this.totalWidth;
-            for(i = 0, len = this.config.length; i < len; i++){
+            
+            for (i = 0, len = this.config.length; i < len; i++) {
                 c = this.config[i];
-                if(c.setEditor){
+                
+                if (c.setEditor) {
                     //check here, in case we have a special column like a CheckboxSelectionModel
                     c.setEditor(null);
                 }
@@ -225,20 +237,24 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
         this.config = config;
         this.lookup = {};
 
-        for(i = 0, len = config.length; i < len; i++){
+        for (i = 0, len = config.length; i < len; i++) {
             c = Ext.applyIf(config[i], this.defaults);
+            
             // if no id, create one using column's ordinal position
-            if(Ext.isEmpty(c.id)){
+            if (Ext.isEmpty(c.id)) {
                 c.id = i;
             }
-            if(!c.isColumn){
+            
+            if (!c.isColumn) {
                 var Cls = Ext.grid.Column.types[c.xtype || 'gridcolumn'];
                 c = new Cls(c);
                 config[i] = c;
             }
+            
             this.lookup[c.id] = c;
         }
-        if(!initial){
+        
+        if (!initial) {
             this.fireEvent('configchange', this);
         }
     },
@@ -248,7 +264,7 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {String} id The column id
      * @return {Object} the column
      */
-    getColumnById : function(id){
+    getColumnById : function(id) {
         return this.lookup[id];
     },
 
@@ -257,9 +273,9 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {String} id The column id
      * @return {Number} the index, or -1 if not found
      */
-    getIndexById : function(id){
-        for(var i = 0, len = this.config.length; i < len; i++){
-            if(this.config[i].id == id){
+    getIndexById : function(id) {
+        for (var i = 0, len = this.config.length; i < len; i++) {
+            if (this.config[i].id == id) {
                 return i;
             }
         }
@@ -271,10 +287,12 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {Number} oldIndex The index of the column to move.
      * @param {Number} newIndex The position at which to reinsert the coolumn.
      */
-    moveColumn : function(oldIndex, newIndex){
-        var c = this.config[oldIndex];
-        this.config.splice(oldIndex, 1);
-        this.config.splice(newIndex, 0, c);
+    moveColumn : function(oldIndex, newIndex) {
+        var config = this.config,
+            c      = config[oldIndex];
+            
+        config.splice(oldIndex, 1);
+        config.splice(newIndex, 0, c);
         this.dataMap = null;
         this.fireEvent("columnmoved", this, oldIndex, newIndex);
     },
@@ -284,17 +302,22 @@ Ext.grid.ColumnModel = Ext.extend(Ext.util.Observable, {
      * @param {Boolean} visibleOnly Optional. Pass as true to only include visible columns.
      * @return {Number}
      */
-    getColumnCount : function(visibleOnly){
-        if(visibleOnly === true){
-            var c = 0;
-            for(var i = 0, len = this.config.length; i < len; i++){
-                if(!this.isHidden(i)){
+    getColumnCount : function(visibleOnly) {
+        var length = this.config.length,
+            c = 0,
+            i;
+        
+        if (visibleOnly === true) {
+            for (i = 0; i < length; i++) {
+                if (!this.isHidden(i)) {
                     c++;
                 }
             }
+            
             return c;
         }
-        return this.config.length;
+        
+        return length;
     },
 
     <div id="method-Ext.grid.ColumnModel-getColumnsBy"></div>/**
@@ -312,15 +335,21 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * is executed. Defaults to this ColumnModel.
      * @return {Array} result
      */
-    getColumnsBy : function(fn, scope){
-        var r = [];
-        for(var i = 0, len = this.config.length; i < len; i++){
-            var c = this.config[i];
-            if(fn.call(scope||this, c, i) === true){
-                r[r.length] = c;
+    getColumnsBy : function(fn, scope) {
+        var config = this.config,
+            length = config.length,
+            result = [],
+            i, c;
+            
+        for (i = 0; i < length; i++){
+            c = config[i];
+            
+            if (fn.call(scope || this, c, i) === true) {
+                result[result.length] = c;
             }
         }
-        return r;
+        
+        return result;
     },
 
     <div id="method-Ext.grid.ColumnModel-isSortable"></div>/**
@@ -328,7 +357,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @return {Boolean}
      */
-    isSortable : function(col){
+    isSortable : function(col) {
         return !!this.config[col].sortable;
     },
 
@@ -337,7 +366,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @return {Boolean}
      */
-    isMenuDisabled : function(col){
+    isMenuDisabled : function(col) {
         return !!this.config[col].menuDisabled;
     },
 
@@ -346,14 +375,11 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index.
      * @return {Function} The function used to render the cell. See {@link #setRenderer}.
      */
-    getRenderer : function(col){
-        if(!this.config[col].renderer){
-            return Ext.grid.ColumnModel.defaultRenderer;
-        }
-        return this.config[col].renderer;
+    getRenderer : function(col) {
+        return this.config[col].renderer || Ext.grid.ColumnModel.defaultRenderer;
     },
 
-    getRendererScope : function(col){
+    getRendererScope : function(col) {
         return this.config[col].scope;
     },
 
@@ -374,7 +400,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * <li><b>colIndex</b> : Number<p class="sub-desc">Column index</p></li>
      * <li><b>store</b> : Ext.data.Store<p class="sub-desc">The {@link Ext.data.Store} object from which the Record was extracted.</p></li></ul>
      */
-    setRenderer : function(col, fn){
+    setRenderer : function(col, fn) {
         this.config[col].renderer = fn;
     },
 
@@ -383,8 +409,12 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @return {Number}
      */
-    getColumnWidth : function(col){
-        return this.config[col].width;
+    getColumnWidth : function(col) {
+        var width = this.config[col].width;
+        if(typeof width != 'number'){
+            width = this.defaultWidth;
+        }
+        return width;
     },
 
     <div id="method-Ext.grid.ColumnModel-setColumnWidth"></div>/**
@@ -394,10 +424,11 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Boolean} suppressEvent True to suppress firing the <code>{@link #widthchange}</code>
      * event. Defaults to false.
      */
-    setColumnWidth : function(col, width, suppressEvent){
+    setColumnWidth : function(col, width, suppressEvent) {
         this.config[col].width = width;
         this.totalWidth = null;
-        if(!suppressEvent){
+        
+        if (!suppressEvent) {
              this.fireEvent("widthchange", this, col, width);
         }
     },
@@ -407,11 +438,11 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Boolean} includeHidden True to include hidden column widths
      * @return {Number}
      */
-    getTotalWidth : function(includeHidden){
-        if(!this.totalWidth){
+    getTotalWidth : function(includeHidden) {
+        if (!this.totalWidth) {
             this.totalWidth = 0;
-            for(var i = 0, len = this.config.length; i < len; i++){
-                if(includeHidden || !this.isHidden(i)){
+            for (var i = 0, len = this.config.length; i < len; i++) {
+                if (includeHidden || !this.isHidden(i)) {
                     this.totalWidth += this.getColumnWidth(i);
                 }
             }
@@ -424,7 +455,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @return {String}
      */
-    getColumnHeader : function(col){
+    getColumnHeader : function(col) {
         return this.config[col].header;
     },
 
@@ -433,7 +464,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @param {String} header The new header
      */
-    setColumnHeader : function(col, header){
+    setColumnHeader : function(col, header) {
         this.config[col].header = header;
         this.fireEvent("headerchange", this, col, header);
     },
@@ -443,7 +474,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @return {String}
      */
-    getColumnTooltip : function(col){
+    getColumnTooltip : function(col) {
             return this.config[col].tooltip;
     },
     <div id="method-Ext.grid.ColumnModel-setColumnTooltip"></div>/**
@@ -451,7 +482,7 @@ var columns = grid.getColumnModel().getColumnsBy(function(c){
      * @param {Number} col The column index
      * @param {String} tooltip The new tooltip
      */
-    setColumnTooltip : function(col, tooltip){
+    setColumnTooltip : function(col, tooltip) {
             this.config[col].tooltip = tooltip;
     },
 
@@ -464,7 +495,7 @@ var fieldName = grid.getColumnModel().getDataIndex(columnIndex);
      * @param {Number} col The column index
      * @return {String} The column's dataIndex
      */
-    getDataIndex : function(col){
+    getDataIndex : function(col) {
         return this.config[col].dataIndex;
     },
 
@@ -473,7 +504,7 @@ var fieldName = grid.getColumnModel().getDataIndex(columnIndex);
      * @param {Number} col The column index
      * @param {String} dataIndex The new dataIndex
      */
-    setDataIndex : function(col, dataIndex){
+    setDataIndex : function(col, dataIndex) {
         this.config[col].dataIndex = dataIndex;
     },
 
@@ -482,7 +513,7 @@ var fieldName = grid.getColumnModel().getDataIndex(columnIndex);
      * @param {String} col The dataIndex to find
      * @return {Number} The column index, or -1 if no match was found
      */
-    findColumnIndex : function(dataIndex){
+    findColumnIndex : function(dataIndex) {
         var c = this.config;
         for(var i = 0, len = c.length; i < len; i++){
             if(c[i].dataIndex == dataIndex){
@@ -516,7 +547,7 @@ var grid = new Ext.grid.GridPanel({
      * @param {Number} rowIndex The row index
      * @return {Boolean}
      */
-    isCellEditable : function(colIndex, rowIndex){
+    isCellEditable : function(colIndex, rowIndex) {
         var c = this.config[colIndex],
             ed = c.editable;
 
@@ -531,7 +562,7 @@ var grid = new Ext.grid.GridPanel({
      * @return {Ext.Editor} The {@link Ext.Editor Editor} that was created to wrap
      * the {@link Ext.form.Field Field} used to edit the cell.
      */
-    getCellEditor : function(colIndex, rowIndex){
+    getCellEditor : function(colIndex, rowIndex) {
         return this.config[colIndex].getCellEditor(rowIndex);
     },
 
@@ -540,7 +571,7 @@ var grid = new Ext.grid.GridPanel({
      * @param {Number} col The column index
      * @param {Boolean} editable True if the column is editable
      */
-    setEditable : function(col, editable){
+    setEditable : function(col, editable) {
         this.config[col].editable = editable;
     },
 
@@ -550,7 +581,7 @@ var grid = new Ext.grid.GridPanel({
      * @param {Number} colIndex The column index
      * @return {Boolean}
      */
-    isHidden : function(colIndex){
+    isHidden : function(colIndex) {
         return !!this.config[colIndex].hidden; // ensure returns boolean
     },
 
@@ -560,7 +591,7 @@ var grid = new Ext.grid.GridPanel({
      * @param {Number} colIndex The column index
      * @return {Boolean}
      */
-    isFixed : function(colIndex){
+    isFixed : function(colIndex) {
         return !!this.config[colIndex].fixed;
     },
 
@@ -568,9 +599,10 @@ var grid = new Ext.grid.GridPanel({
      * Returns true if the column can be resized
      * @return {Boolean}
      */
-    isResizable : function(colIndex){
+    isResizable : function(colIndex) {
         return colIndex >= 0 && this.config[colIndex].resizable !== false && this.config[colIndex].fixed !== true;
     },
+    
     <div id="method-Ext.grid.ColumnModel-setHidden"></div>/**
      * Sets if a column is hidden.
 <pre><code>
@@ -579,7 +611,7 @@ myGrid.getColumnModel().setHidden(0, true); // hide column 0 (0 = the first colu
      * @param {Number} colIndex The column index
      * @param {Boolean} hidden True if the column is hidden
      */
-    setHidden : function(colIndex, hidden){
+    setHidden : function(colIndex, hidden) {
         var c = this.config[colIndex];
         if(c.hidden !== hidden){
             c.hidden = hidden;
@@ -593,28 +625,38 @@ myGrid.getColumnModel().setHidden(0, true); // hide column 0 (0 = the first colu
      * @param {Number} col The column index
      * @param {Object} editor The editor object
      */
-    setEditor : function(col, editor){
+    setEditor : function(col, editor) {
         this.config[col].setEditor(editor);
     },
 
     <div id="method-Ext.grid.ColumnModel-destroy"></div>/**
-     * Destroys this column model by purging any event listeners, and removing any editors.
-     */
-    destroy : function(){
-        var c;
-        for(var i = 0, len = this.config.length; i < len; i++){
-            c = this.config[i];
-            if(c.setEditor){
-                c.setEditor(null);
-            }
+     * Destroys this column model by purging any event listeners. Destroys and dereferences all Columns.
+     */
+    destroy : function() {
+        var length = this.config.length,
+            i = 0;
+
+        for (; i < length; i++){
+            this.config[i].destroy(); // Column's destroy encapsulates all cleanup.
         }
+        delete this.config;
+        delete this.lookup;
         this.purgeListeners();
+    },
+
+    /**
+     * @private
+     * Setup any saved state for the column, ensures that defaults are applied.
+     */
+    setState : function(col, state) {
+        state = Ext.applyIf(state, this.defaults);
+        Ext.apply(this.config[col], state);
     }
 });
 
 // private
-Ext.grid.ColumnModel.defaultRenderer = function(value){
-    if(typeof value == "string" && value.length < 1){
+Ext.grid.ColumnModel.defaultRenderer = function(value) {
+    if (typeof value == "string" && value.length < 1) {
         return "&#160;";
     }
     return value;