src/widgets/grid/RowSelectionModel.js

   1 /*!
   2  * Ext JS Library 3.3.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.grid.RowSelectionModel
   9  * @extends Ext.grid.AbstractSelectionModel
  10  * The default SelectionModel used by {@link Ext.grid.GridPanel}.
  11  * It supports multiple selections and keyboard selection/navigation. The objects stored
  12  * as selections and returned by {@link #getSelected}, and {@link #getSelections} are
  13  * the {@link Ext.data.Record Record}s which provide the data for the selected rows.
  14  * @constructor
  15  * @param {Object} config
  16  */
  17 Ext.grid.RowSelectionModel = Ext.extend(Ext.grid.AbstractSelectionModel,  {
  18     /**
  19      * @cfg {Boolean} singleSelect
  20      * <tt>true</tt> to allow selection of only one row at a time (defaults to <tt>false</tt>
  21      * allowing multiple selections)
  22      */
  23     singleSelect : false,
  24
  25     constructor : function(config){
  26         Ext.apply(this, config);
  27         this.selections = new Ext.util.MixedCollection(false, function(o){
  28             return o.id;
  29         });
  30
  31         this.last = false;
  32         this.lastActive = false;
  33
  34         this.addEvents(
  35                 /**
  36                  * @event selectionchange
  37                  * Fires when the selection changes
  38                  * @param {SelectionModel} this
  39                  */
  40                 'selectionchange',
  41                 /**
  42                  * @event beforerowselect
  43                  * Fires before a row is selected, return false to cancel the selection.
  44                  * @param {SelectionModel} this
  45                  * @param {Number} rowIndex The index to be selected
  46                  * @param {Boolean} keepExisting False if other selections will be cleared
  47                  * @param {Record} record The record to be selected
  48                  */
  49                 'beforerowselect',
  50                 /**
  51                  * @event rowselect
  52                  * Fires when a row is selected.
  53                  * @param {SelectionModel} this
  54                  * @param {Number} rowIndex The selected index
  55                  * @param {Ext.data.Record} r The selected record
  56                  */
  57                 'rowselect',
  58                 /**
  59                  * @event rowdeselect
  60                  * Fires when a row is deselected.  To prevent deselection
  61                  * {@link Ext.grid.AbstractSelectionModel#lock lock the selections}.
  62                  * @param {SelectionModel} this
  63                  * @param {Number} rowIndex
  64                  * @param {Record} record
  65                  */
  66                 'rowdeselect'
  67         );
  68         Ext.grid.RowSelectionModel.superclass.constructor.call(this);
  69     },
  70
  71     /**
  72      * @cfg {Boolean} moveEditorOnEnter
  73      * <tt>false</tt> to turn off moving the editor to the next row down when the enter key is pressed
  74      * or the next row up when shift + enter keys are pressed.
  75      */
  76     // private
  77     initEvents : function(){
  78
  79         if(!this.grid.enableDragDrop && !this.grid.enableDrag){
  80             this.grid.on('rowmousedown', this.handleMouseDown, this);
  81         }
  82
  83         this.rowNav = new Ext.KeyNav(this.grid.getGridEl(), {
  84             up: this.onKeyPress,
  85             down: this.onKeyPress,
  86             scope: this
  87         });
  88
  89         this.grid.getView().on({
  90             scope: this,
  91             refresh: this.onRefresh,
  92             rowupdated: this.onRowUpdated,
  93             rowremoved: this.onRemove
  94         });
  95     },
  96
  97     onKeyPress : function(e, name){
  98         var up = name == 'up',
  99             method = up ? 'selectPrevious' : 'selectNext',
 100             add = up ? -1 : 1,
 101             last;
 102         if(!e.shiftKey || this.singleSelect){
 103             this[method](false);
 104         }else if(this.last !== false && this.lastActive !== false){
 105             last = this.last;
 106             this.selectRange(this.last,  this.lastActive + add);
 107             this.grid.getView().focusRow(this.lastActive);
 108             if(last !== false){
 109                 this.last = last;
 110             }
 111         }else{
 112            this.selectFirstRow();
 113         }
 114     },
 115
 116     // private
 117     onRefresh : function(){
 118         var ds = this.grid.store,
 119             s = this.getSelections(),
 120             i = 0,
 121             len = s.length,
 122             index;
 123
 124         this.silent = true;
 125         this.clearSelections(true);
 126         for(; i < len; i++){
 127             r = s[i];
 128             if((index = ds.indexOfId(r.id)) != -1){
 129                 this.selectRow(index, true);
 130             }
 131         }
 132         if(s.length != this.selections.getCount()){
 133             this.fireEvent('selectionchange', this);
 134         }
 135         this.silent = false;
 136     },
 137
 138     // private
 139     onRemove : function(v, index, r){
 140         if(this.selections.remove(r) !== false){
 141             this.fireEvent('selectionchange', this);
 142         }
 143     },
 144
 145     // private
 146     onRowUpdated : function(v, index, r){
 147         if(this.isSelected(r)){
 148             v.onRowSelect(index);
 149         }
 150     },
 151
 152     /**
 153      * Select records.
 154      * @param {Array} records The records to select
 155      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
 156      */
 157     selectRecords : function(records, keepExisting){
 158         if(!keepExisting){
 159             this.clearSelections();
 160         }
 161         var ds = this.grid.store,
 162             i = 0,
 163             len = records.length;
 164         for(; i < len; i++){
 165             this.selectRow(ds.indexOf(records[i]), true);
 166         }
 167     },
 168
 169     /**
 170      * Gets the number of selected rows.
 171      * @return {Number}
 172      */
 173     getCount : function(){
 174         return this.selections.length;
 175     },
 176
 177     /**
 178      * Selects the first row in the grid.
 179      */
 180     selectFirstRow : function(){
 181         this.selectRow(0);
 182     },
 183
 184     /**
 185      * Select the last row.
 186      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
 187      */
 188     selectLastRow : function(keepExisting){
 189         this.selectRow(this.grid.store.getCount() - 1, keepExisting);
 190     },
 191
 192     /**
 193      * Selects the row immediately following the last selected row.
 194      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
 195      * @return {Boolean} <tt>true</tt> if there is a next row, else <tt>false</tt>
 196      */
 197     selectNext : function(keepExisting){
 198         if(this.hasNext()){
 199             this.selectRow(this.last+1, keepExisting);
 200             this.grid.getView().focusRow(this.last);
 201             return true;
 202         }
 203         return false;
 204     },
 205
 206     /**
 207      * Selects the row that precedes the last selected row.
 208      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
 209      * @return {Boolean} <tt>true</tt> if there is a previous row, else <tt>false</tt>
 210      */
 211     selectPrevious : function(keepExisting){
 212         if(this.hasPrevious()){
 213             this.selectRow(this.last-1, keepExisting);
 214             this.grid.getView().focusRow(this.last);
 215             return true;
 216         }
 217         return false;
 218     },
 219
 220     /**
 221      * Returns true if there is a next record to select
 222      * @return {Boolean}
 223      */
 224     hasNext : function(){
 225         return this.last !== false && (this.last+1) < this.grid.store.getCount();
 226     },
 227
 228     /**
 229      * Returns true if there is a previous record to select
 230      * @return {Boolean}
 231      */
 232     hasPrevious : function(){
 233         return !!this.last;
 234     },
 235
 236
 237     /**
 238      * Returns the selected records
 239      * @return {Array} Array of selected records
 240      */
 241     getSelections : function(){
 242         return [].concat(this.selections.items);
 243     },
 244
 245     /**
 246      * Returns the first selected record.
 247      * @return {Record}
 248      */
 249     getSelected : function(){
 250         return this.selections.itemAt(0);
 251     },
 252
 253     /**
 254      * Calls the passed function with each selection. If the function returns
 255      * <tt>false</tt>, iteration is stopped and this function returns
 256      * <tt>false</tt>. Otherwise it returns <tt>true</tt>.
 257      * @param {Function} fn The function to call upon each iteration. It is passed the selected {@link Ext.data.Record Record}.
 258      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to this RowSelectionModel.
 259      * @return {Boolean} true if all selections were iterated
 260      */
 261     each : function(fn, scope){
 262         var s = this.getSelections(),
 263             i = 0,
 264             len = s.length;
 265
 266         for(; i < len; i++){
 267             if(fn.call(scope || this, s[i], i) === false){
 268                 return false;
 269             }
 270         }
 271         return true;
 272     },
 273
 274     /**
 275      * Clears all selections if the selection model
 276      * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
 277      * @param {Boolean} fast (optional) <tt>true</tt> to bypass the
 278      * conditional checks and events described in {@link #deselectRow}.
 279      */
 280     clearSelections : function(fast){
 281         if(this.isLocked()){
 282             return;
 283         }
 284         if(fast !== true){
 285             var ds = this.grid.store,
 286                 s = this.selections;
 287             s.each(function(r){
 288                 this.deselectRow(ds.indexOfId(r.id));
 289             }, this);
 290             s.clear();
 291         }else{
 292             this.selections.clear();
 293         }
 294         this.last = false;
 295     },
 296
 297
 298     /**
 299      * Selects all rows if the selection model
 300      * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
 301      */
 302     selectAll : function(){
 303         if(this.isLocked()){
 304             return;
 305         }
 306         this.selections.clear();
 307         for(var i = 0, len = this.grid.store.getCount(); i < len; i++){
 308             this.selectRow(i, true);
 309         }
 310     },
 311
 312     /**
 313      * Returns <tt>true</tt> if there is a selection.
 314      * @return {Boolean}
 315      */
 316     hasSelection : function(){
 317         return this.selections.length > 0;
 318     },
 319
 320     /**
 321      * Returns <tt>true</tt> if the specified row is selected.
 322      * @param {Number/Record} index The record or index of the record to check
 323      * @return {Boolean}
 324      */
 325     isSelected : function(index){
 326         var r = Ext.isNumber(index) ? this.grid.store.getAt(index) : index;
 327         return (r && this.selections.key(r.id) ? true : false);
 328     },
 329
 330     /**
 331      * Returns <tt>true</tt> if the specified record id is selected.
 332      * @param {String} id The id of record to check
 333      * @return {Boolean}
 334      */
 335     isIdSelected : function(id){
 336         return (this.selections.key(id) ? true : false);
 337     },
 338
 339     // private
 340     handleMouseDown : function(g, rowIndex, e){
 341         if(e.button !== 0 || this.isLocked()){
 342             return;
 343         }
 344         var view = this.grid.getView();
 345         if(e.shiftKey && !this.singleSelect && this.last !== false){
 346             var last = this.last;
 347             this.selectRange(last, rowIndex, e.ctrlKey);
 348             this.last = last; // reset the last
 349             view.focusRow(rowIndex);
 350         }else{
 351             var isSelected = this.isSelected(rowIndex);
 352             if(e.ctrlKey && isSelected){
 353                 this.deselectRow(rowIndex);
 354             }else if(!isSelected || this.getCount() > 1){
 355                 this.selectRow(rowIndex, e.ctrlKey || e.shiftKey);
 356                 view.focusRow(rowIndex);
 357             }
 358         }
 359     },
 360
 361     /**
 362      * Selects multiple rows.
 363      * @param {Array} rows Array of the indexes of the row to select
 364      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep
 365      * existing selections (defaults to <tt>false</tt>)
 366      */
 367     selectRows : function(rows, keepExisting){
 368         if(!keepExisting){
 369             this.clearSelections();
 370         }
 371         for(var i = 0, len = rows.length; i < len; i++){
 372             this.selectRow(rows[i], true);
 373         }
 374     },
 375
 376     /**
 377      * Selects a range of rows if the selection model
 378      * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
 379      * All rows in between startRow and endRow are also selected.
 380      * @param {Number} startRow The index of the first row in the range
 381      * @param {Number} endRow The index of the last row in the range
 382      * @param {Boolean} keepExisting (optional) True to retain existing selections
 383      */
 384     selectRange : function(startRow, endRow, keepExisting){
 385         var i;
 386         if(this.isLocked()){
 387             return;
 388         }
 389         if(!keepExisting){
 390             this.clearSelections();
 391         }
 392         if(startRow <= endRow){
 393             for(i = startRow; i <= endRow; i++){
 394                 this.selectRow(i, true);
 395             }
 396         }else{
 397             for(i = startRow; i >= endRow; i--){
 398                 this.selectRow(i, true);
 399             }
 400         }
 401     },
 402
 403     /**
 404      * Deselects a range of rows if the selection model
 405      * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
 406      * All rows in between startRow and endRow are also deselected.
 407      * @param {Number} startRow The index of the first row in the range
 408      * @param {Number} endRow The index of the last row in the range
 409      */
 410     deselectRange : function(startRow, endRow, preventViewNotify){
 411         if(this.isLocked()){
 412             return;
 413         }
 414         for(var i = startRow; i <= endRow; i++){
 415             this.deselectRow(i, preventViewNotify);
 416         }
 417     },
 418
 419     /**
 420      * Selects a row.  Before selecting a row, checks if the selection model
 421      * {@link Ext.grid.AbstractSelectionModel#isLocked is locked} and fires the
 422      * {@link #beforerowselect} event.  If these checks are satisfied the row
 423      * will be selected and followed up by  firing the {@link #rowselect} and
 424      * {@link #selectionchange} events.
 425      * @param {Number} row The index of the row to select
 426      * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
 427      * @param {Boolean} preventViewNotify (optional) Specify <tt>true</tt> to
 428      * prevent notifying the view (disables updating the selected appearance)
 429      */
 430     selectRow : function(index, keepExisting, preventViewNotify){
 431         if(this.isLocked() || (index < 0 || index >= this.grid.store.getCount()) || (keepExisting && this.isSelected(index))){
 432             return;
 433         }
 434         var r = this.grid.store.getAt(index);
 435         if(r && this.fireEvent('beforerowselect', this, index, keepExisting, r) !== false){
 436             if(!keepExisting || this.singleSelect){
 437                 this.clearSelections();
 438             }
 439             this.selections.add(r);
 440             this.last = this.lastActive = index;
 441             if(!preventViewNotify){
 442                 this.grid.getView().onRowSelect(index);
 443             }
 444             if(!this.silent){
 445                 this.fireEvent('rowselect', this, index, r);
 446                 this.fireEvent('selectionchange', this);
 447             }
 448         }
 449     },
 450
 451     /**
 452      * Deselects a row.  Before deselecting a row, checks if the selection model
 453      * {@link Ext.grid.AbstractSelectionModel#isLocked is locked}.
 454      * If this check is satisfied the row will be deselected and followed up by
 455      * firing the {@link #rowdeselect} and {@link #selectionchange} events.
 456      * @param {Number} row The index of the row to deselect
 457      * @param {Boolean} preventViewNotify (optional) Specify <tt>true</tt> to
 458      * prevent notifying the view (disables updating the selected appearance)
 459      */
 460     deselectRow : function(index, preventViewNotify){
 461         if(this.isLocked()){
 462             return;
 463         }
 464         if(this.last == index){
 465             this.last = false;
 466         }
 467         if(this.lastActive == index){
 468             this.lastActive = false;
 469         }
 470         var r = this.grid.store.getAt(index);
 471         if(r){
 472             this.selections.remove(r);
 473             if(!preventViewNotify){
 474                 this.grid.getView().onRowDeselect(index);
 475             }
 476             this.fireEvent('rowdeselect', this, index, r);
 477             this.fireEvent('selectionchange', this);
 478         }
 479     },
 480
 481     // private
 482     acceptsNav : function(row, col, cm){
 483         return !cm.isHidden(col) && cm.isCellEditable(col, row);
 484     },
 485
 486     // private
 487     onEditorKey : function(field, e){
 488         var k = e.getKey(),
 489             newCell,
 490             g = this.grid,
 491             last = g.lastEdit,
 492             ed = g.activeEditor,
 493             shift = e.shiftKey,
 494             ae, last, r, c;
 495
 496         if(k == e.TAB){
 497             e.stopEvent();
 498             ed.completeEdit();
 499             if(shift){
 500                 newCell = g.walkCells(ed.row, ed.col-1, -1, this.acceptsNav, this);
 501             }else{
 502                 newCell = g.walkCells(ed.row, ed.col+1, 1, this.acceptsNav, this);
 503             }
 504         }else if(k == e.ENTER){
 505             if(this.moveEditorOnEnter !== false){
 506                 if(shift){
 507                     newCell = g.walkCells(last.row - 1, last.col, -1, this.acceptsNav, this);
 508                 }else{
 509                     newCell = g.walkCells(last.row + 1, last.col, 1, this.acceptsNav, this);
 510                 }
 511             }
 512         }
 513         if(newCell){
 514             r = newCell[0];
 515             c = newCell[1];
 516
 517             if(last.row != r){
 518                 this.selectRow(r); // *** highlight newly-selected cell and update selection
 519             }
 520
 521             if(g.isEditor && g.editing){ // *** handle tabbing while editorgrid is in edit mode
 522                 ae = g.activeEditor;
 523                 if(ae && ae.field.triggerBlur){
 524                     // *** if activeEditor is a TriggerField, explicitly call its triggerBlur() method
 525                     ae.field.triggerBlur();
 526                 }
 527             }
 528             g.startEditing(r, c);
 529         }
 530     },
 531
 532     destroy : function(){
 533         Ext.destroy(this.rowNav);
 534         this.rowNav = null;
 535         Ext.grid.RowSelectionModel.superclass.destroy.call(this);
 536     }
 537 });