src/widgets/grid/CellSelectionModel.js

   1 /*!
   2  * Ext JS Library 3.3.1
   3  * Copyright(c) 2006-2010 Sencha Inc.
   4  * licensing@sencha.com
   5  * http://www.sencha.com/license
   6  */
   7 /**
   8  * @class Ext.grid.CellSelectionModel
   9  * @extends Ext.grid.AbstractSelectionModel
  10  * This class provides the basic implementation for <i>single</i> <b>cell</b> selection in a grid.
  11  * The object stored as the selection contains the following properties:
  12  * <div class="mdetail-params"><ul>
  13  * <li><b>cell</b> : see {@link #getSelectedCell}
  14  * <li><b>record</b> : Ext.data.record The {@link Ext.data.Record Record}
  15  * which provides the data for the row containing the selection</li>
  16  * </ul></div>
  17  * @constructor
  18  * @param {Object} config The object containing the configuration of this model.
  19  */
  20 Ext.grid.CellSelectionModel = Ext.extend(Ext.grid.AbstractSelectionModel,  {
  21
  22     constructor : function(config){
  23         Ext.apply(this, config);
  24
  25             this.selection = null;
  26
  27             this.addEvents(
  28                 /**
  29                  * @event beforecellselect
  30                  * Fires before a cell is selected, return false to cancel the selection.
  31                  * @param {SelectionModel} this
  32                  * @param {Number} rowIndex The selected row index
  33                  * @param {Number} colIndex The selected cell index
  34                  */
  35                 "beforecellselect",
  36                 /**
  37                  * @event cellselect
  38                  * Fires when a cell is selected.
  39                  * @param {SelectionModel} this
  40                  * @param {Number} rowIndex The selected row index
  41                  * @param {Number} colIndex The selected cell index
  42                  */
  43                 "cellselect",
  44                 /**
  45                  * @event selectionchange
  46                  * Fires when the active selection changes.
  47                  * @param {SelectionModel} this
  48                  * @param {Object} selection null for no selection or an object with two properties
  49                  * <div class="mdetail-params"><ul>
  50                  * <li><b>cell</b> : see {@link #getSelectedCell}
  51                  * <li><b>record</b> : Ext.data.record<p class="sub-desc">The {@link Ext.data.Record Record}
  52                  * which provides the data for the row containing the selection</p></li>
  53                  * </ul></div>
  54                  */
  55                 "selectionchange"
  56             );
  57
  58             Ext.grid.CellSelectionModel.superclass.constructor.call(this);
  59     },
  60
  61     /** @ignore */
  62     initEvents : function(){
  63         this.grid.on('cellmousedown', this.handleMouseDown, this);
  64         this.grid.on(Ext.EventManager.getKeyEvent(), this.handleKeyDown, this);
  65         this.grid.getView().on({
  66             scope: this,
  67             refresh: this.onViewChange,
  68             rowupdated: this.onRowUpdated,
  69             beforerowremoved: this.clearSelections,
  70             beforerowsinserted: this.clearSelections
  71         });
  72         if(this.grid.isEditor){
  73             this.grid.on('beforeedit', this.beforeEdit,  this);
  74         }
  75     },
  76
  77         //private
  78     beforeEdit : function(e){
  79         this.select(e.row, e.column, false, true, e.record);
  80     },
  81
  82         //private
  83     onRowUpdated : function(v, index, r){
  84         if(this.selection && this.selection.record == r){
  85             v.onCellSelect(index, this.selection.cell[1]);
  86         }
  87     },
  88
  89         //private
  90     onViewChange : function(){
  91         this.clearSelections(true);
  92     },
  93
  94         /**
  95      * Returns an array containing the row and column indexes of the currently selected cell
  96      * (e.g., [0, 0]), or null if none selected. The array has elements:
  97      * <div class="mdetail-params"><ul>
  98      * <li><b>rowIndex</b> : Number<p class="sub-desc">The index of the selected row</p></li>
  99      * <li><b>cellIndex</b> : Number<p class="sub-desc">The index of the selected cell.
 100      * Due to possible column reordering, the cellIndex should <b>not</b> be used as an
 101      * index into the Record's data. Instead, use the cellIndex to determine the <i>name</i>
 102      * of the selected cell and use the field name to retrieve the data value from the record:<pre><code>
 103 // get name
 104 var fieldName = grid.getColumnModel().getDataIndex(cellIndex);
 105 // get data value based on name
 106 var data = record.get(fieldName);
 107      * </code></pre></p></li>
 108      * </ul></div>
 109      * @return {Array} An array containing the row and column indexes of the selected cell, or null if none selected.
 110          */
 111     getSelectedCell : function(){
 112         return this.selection ? this.selection.cell : null;
 113     },
 114
 115     /**
 116      * If anything is selected, clears all selections and fires the selectionchange event.
 117      * @param {Boolean} preventNotify <tt>true</tt> to prevent the gridview from
 118      * being notified about the change.
 119      */
 120     clearSelections : function(preventNotify){
 121         var s = this.selection;
 122         if(s){
 123             if(preventNotify !== true){
 124                 this.grid.view.onCellDeselect(s.cell[0], s.cell[1]);
 125             }
 126             this.selection = null;
 127             this.fireEvent("selectionchange", this, null);
 128         }
 129     },
 130
 131     /**
 132      * Returns <tt>true</tt> if there is a selection.
 133      * @return {Boolean}
 134      */
 135     hasSelection : function(){
 136         return this.selection ? true : false;
 137     },
 138
 139     /** @ignore */
 140     handleMouseDown : function(g, row, cell, e){
 141         if(e.button !== 0 || this.isLocked()){
 142             return;
 143         }
 144         this.select(row, cell);
 145     },
 146
 147     /**
 148      * Selects a cell.  Before selecting a cell, fires the
 149      * {@link #beforecellselect} event.  If this check is satisfied the cell
 150      * will be selected and followed up by  firing the {@link #cellselect} and
 151      * {@link #selectionchange} events.
 152      * @param {Number} rowIndex The index of the row to select
 153      * @param {Number} colIndex The index of the column to select
 154      * @param {Boolean} preventViewNotify (optional) Specify <tt>true</tt> to
 155      * prevent notifying the view (disables updating the selected appearance)
 156      * @param {Boolean} preventFocus (optional) Whether to prevent the cell at
 157      * the specified rowIndex / colIndex from being focused.
 158      * @param {Ext.data.Record} r (optional) The record to select
 159      */
 160     select : function(rowIndex, colIndex, preventViewNotify, preventFocus, /*internal*/ r){
 161         if(this.fireEvent("beforecellselect", this, rowIndex, colIndex) !== false){
 162             this.clearSelections();
 163             r = r || this.grid.store.getAt(rowIndex);
 164             this.selection = {
 165                 record : r,
 166                 cell : [rowIndex, colIndex]
 167             };
 168             if(!preventViewNotify){
 169                 var v = this.grid.getView();
 170                 v.onCellSelect(rowIndex, colIndex);
 171                 if(preventFocus !== true){
 172                     v.focusCell(rowIndex, colIndex);
 173                 }
 174             }
 175             this.fireEvent("cellselect", this, rowIndex, colIndex);
 176             this.fireEvent("selectionchange", this, this.selection);
 177         }
 178     },
 179
 180         //private
 181     isSelectable : function(rowIndex, colIndex, cm){
 182         return !cm.isHidden(colIndex);
 183     },
 184
 185     // private
 186     onEditorKey: function(field, e){
 187         if(e.getKey() == e.TAB){
 188             this.handleKeyDown(e);
 189         }
 190     },
 191
 192     /** @ignore */
 193     handleKeyDown : function(e){
 194         if(!e.isNavKeyPress()){
 195             return;
 196         }
 197
 198         var k = e.getKey(),
 199             g = this.grid,
 200             s = this.selection,
 201             sm = this,
 202             walk = function(row, col, step){
 203                 return g.walkCells(
 204                     row,
 205                     col,
 206                     step,
 207                     g.isEditor && g.editing ? sm.acceptsNav : sm.isSelectable, // *** handle tabbing while editorgrid is in edit mode
 208                     sm
 209                 );
 210             },
 211             cell, newCell, r, c, ae;
 212
 213         switch(k){
 214             case e.ESC:
 215             case e.PAGE_UP:
 216             case e.PAGE_DOWN:
 217                 // do nothing
 218                 break;
 219             default:
 220                 // *** call e.stopEvent() only for non ESC, PAGE UP/DOWN KEYS
 221                 e.stopEvent();
 222                 break;
 223         }
 224
 225         if(!s){
 226             cell = walk(0, 0, 1); // *** use private walk() function defined above
 227             if(cell){
 228                 this.select(cell[0], cell[1]);
 229             }
 230             return;
 231         }
 232
 233         cell = s.cell;  // currently selected cell
 234         r = cell[0];    // current row
 235         c = cell[1];    // current column
 236
 237         switch(k){
 238             case e.TAB:
 239                 if(e.shiftKey){
 240                     newCell = walk(r, c - 1, -1);
 241                 }else{
 242                     newCell = walk(r, c + 1, 1);
 243                 }
 244                 break;
 245             case e.DOWN:
 246                 newCell = walk(r + 1, c, 1);
 247                 break;
 248             case e.UP:
 249                 newCell = walk(r - 1, c, -1);
 250                 break;
 251             case e.RIGHT:
 252                 newCell = walk(r, c + 1, 1);
 253                 break;
 254             case e.LEFT:
 255                 newCell = walk(r, c - 1, -1);
 256                 break;
 257             case e.ENTER:
 258                 if (g.isEditor && !g.editing) {
 259                     g.startEditing(r, c);
 260                     return;
 261                 }
 262                 break;
 263         }
 264
 265         if(newCell){
 266             // *** reassign r & c variables to newly-selected cell's row and column
 267             r = newCell[0];
 268             c = newCell[1];
 269
 270             this.select(r, c); // *** highlight newly-selected cell and update selection
 271
 272             if(g.isEditor && g.editing){ // *** handle tabbing while editorgrid is in edit mode
 273                 ae = g.activeEditor;
 274                 if(ae && ae.field.triggerBlur){
 275                     // *** if activeEditor is a TriggerField, explicitly call its triggerBlur() method
 276                     ae.field.triggerBlur();
 277                 }
 278                 g.startEditing(r, c);
 279             }
 280         }
 281     },
 282
 283     acceptsNav : function(row, col, cm){
 284         return !cm.isHidden(col) && cm.isCellEditable(col, row);
 285     }
 286 });