3 * Copyright(c) 2006-2009 Ext JS, LLC
5 * http://www.extjs.com/license
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.
15 * @param {Object} config
17 Ext.grid.RowSelectionModel = Ext.extend(Ext.grid.AbstractSelectionModel, {
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)
25 constructor : function(config){
26 Ext.apply(this, config);
27 this.selections = new Ext.util.MixedCollection(false, function(o){
32 this.lastActive = false;
36 * @event selectionchange
37 * Fires when the selection changes
38 * @param {SelectionModel} this
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
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
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
68 Ext.grid.RowSelectionModel.superclass.constructor.call(this);
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.
77 initEvents : function(){
79 if(!this.grid.enableDragDrop && !this.grid.enableDrag){
80 this.grid.on('rowmousedown', this.handleMouseDown, this);
83 this.rowNav = new Ext.KeyNav(this.grid.getGridEl(), {
85 if(!e.shiftKey || this.singleSelect){
86 this.selectPrevious(false);
87 }else if(this.last !== false && this.lastActive !== false){
89 this.selectRange(this.last, this.lastActive-1);
90 this.grid.getView().focusRow(this.lastActive);
95 this.selectFirstRow();
99 if(!e.shiftKey || this.singleSelect){
100 this.selectNext(false);
101 }else if(this.last !== false && this.lastActive !== false){
102 var last = this.last;
103 this.selectRange(this.last, this.lastActive+1);
104 this.grid.getView().focusRow(this.lastActive);
109 this.selectFirstRow();
115 this.grid.getView().on({
117 refresh: this.onRefresh,
118 rowupdated: this.onRowUpdated,
119 rowremoved: this.onRemove
124 onRefresh : function(){
125 var ds = this.grid.store, index;
126 var s = this.getSelections();
127 this.clearSelections(true);
128 for(var i = 0, len = s.length; i < len; i++){
130 if((index = ds.indexOfId(r.id)) != -1){
131 this.selectRow(index, true);
134 if(s.length != this.selections.getCount()){
135 this.fireEvent('selectionchange', this);
140 onRemove : function(v, index, r){
141 if(this.selections.remove(r) !== false){
142 this.fireEvent('selectionchange', this);
147 onRowUpdated : function(v, index, r){
148 if(this.isSelected(r)){
149 v.onRowSelect(index);
155 * @param {Array} records The records to select
156 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
158 selectRecords : function(records, keepExisting){
160 this.clearSelections();
162 var ds = this.grid.store;
163 for(var i = 0, len = records.length; i < len; i++){
164 this.selectRow(ds.indexOf(records[i]), true);
169 * Gets the number of selected rows.
172 getCount : function(){
173 return this.selections.length;
177 * Selects the first row in the grid.
179 selectFirstRow : function(){
184 * Select the last row.
185 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
187 selectLastRow : function(keepExisting){
188 this.selectRow(this.grid.store.getCount() - 1, keepExisting);
192 * Selects the row immediately following the last selected row.
193 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
194 * @return {Boolean} <tt>true</tt> if there is a next row, else <tt>false</tt>
196 selectNext : function(keepExisting){
198 this.selectRow(this.last+1, keepExisting);
199 this.grid.getView().focusRow(this.last);
206 * Selects the row that precedes the last selected row.
207 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
208 * @return {Boolean} <tt>true</tt> if there is a previous row, else <tt>false</tt>
210 selectPrevious : function(keepExisting){
211 if(this.hasPrevious()){
212 this.selectRow(this.last-1, keepExisting);
213 this.grid.getView().focusRow(this.last);
220 * Returns true if there is a next record to select
223 hasNext : function(){
224 return this.last !== false && (this.last+1) < this.grid.store.getCount();
228 * Returns true if there is a previous record to select
231 hasPrevious : function(){
237 * Returns the selected records
238 * @return {Array} Array of selected records
240 getSelections : function(){
241 return [].concat(this.selections.items);
245 * Returns the first selected record.
248 getSelected : function(){
249 return this.selections.itemAt(0);
253 * Calls the passed function with each selection. If the function returns
254 * <tt>false</tt>, iteration is stopped and this function returns
255 * <tt>false</tt>. Otherwise it returns <tt>true</tt>.
256 * @param {Function} fn The function to call upon each iteration. It is passed the selected {@link Ext.data.Record Record}.
257 * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to this RowSelectionModel.
258 * @return {Boolean} true if all selections were iterated
260 each : function(fn, scope){
261 var s = this.getSelections();
262 for(var i = 0, len = s.length; i < len; i++){
263 if(fn.call(scope || this, s[i], i) === false){
271 * Clears all selections if the selection model
272 * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
273 * @param {Boolean} fast (optional) <tt>true</tt> to bypass the
274 * conditional checks and events described in {@link #deselectRow}.
276 clearSelections : function(fast){
281 var ds = this.grid.store;
282 var s = this.selections;
284 this.deselectRow(ds.indexOfId(r.id));
288 this.selections.clear();
295 * Selects all rows if the selection model
296 * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
298 selectAll : function(){
302 this.selections.clear();
303 for(var i = 0, len = this.grid.store.getCount(); i < len; i++){
304 this.selectRow(i, true);
309 * Returns <tt>true</tt> if there is a selection.
312 hasSelection : function(){
313 return this.selections.length > 0;
317 * Returns <tt>true</tt> if the specified row is selected.
318 * @param {Number/Record} index The record or index of the record to check
321 isSelected : function(index){
322 var r = Ext.isNumber(index) ? this.grid.store.getAt(index) : index;
323 return (r && this.selections.key(r.id) ? true : false);
327 * Returns <tt>true</tt> if the specified record id is selected.
328 * @param {String} id The id of record to check
331 isIdSelected : function(id){
332 return (this.selections.key(id) ? true : false);
336 handleMouseDown : function(g, rowIndex, e){
337 if(e.button !== 0 || this.isLocked()){
340 var view = this.grid.getView();
341 if(e.shiftKey && !this.singleSelect && this.last !== false){
342 var last = this.last;
343 this.selectRange(last, rowIndex, e.ctrlKey);
344 this.last = last; // reset the last
345 view.focusRow(rowIndex);
347 var isSelected = this.isSelected(rowIndex);
348 if(e.ctrlKey && isSelected){
349 this.deselectRow(rowIndex);
350 }else if(!isSelected || this.getCount() > 1){
351 this.selectRow(rowIndex, e.ctrlKey || e.shiftKey);
352 view.focusRow(rowIndex);
358 * Selects multiple rows.
359 * @param {Array} rows Array of the indexes of the row to select
360 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep
361 * existing selections (defaults to <tt>false</tt>)
363 selectRows : function(rows, keepExisting){
365 this.clearSelections();
367 for(var i = 0, len = rows.length; i < len; i++){
368 this.selectRow(rows[i], true);
373 * Selects a range of rows if the selection model
374 * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
375 * All rows in between startRow and endRow are also selected.
376 * @param {Number} startRow The index of the first row in the range
377 * @param {Number} endRow The index of the last row in the range
378 * @param {Boolean} keepExisting (optional) True to retain existing selections
380 selectRange : function(startRow, endRow, keepExisting){
386 this.clearSelections();
388 if(startRow <= endRow){
389 for(i = startRow; i <= endRow; i++){
390 this.selectRow(i, true);
393 for(i = startRow; i >= endRow; i--){
394 this.selectRow(i, true);
400 * Deselects a range of rows if the selection model
401 * {@link Ext.grid.AbstractSelectionModel#isLocked is not locked}.
402 * All rows in between startRow and endRow are also deselected.
403 * @param {Number} startRow The index of the first row in the range
404 * @param {Number} endRow The index of the last row in the range
406 deselectRange : function(startRow, endRow, preventViewNotify){
410 for(var i = startRow; i <= endRow; i++){
411 this.deselectRow(i, preventViewNotify);
416 * Selects a row. Before selecting a row, checks if the selection model
417 * {@link Ext.grid.AbstractSelectionModel#isLocked is locked} and fires the
418 * {@link #beforerowselect} event. If these checks are satisfied the row
419 * will be selected and followed up by firing the {@link #rowselect} and
420 * {@link #selectionchange} events.
421 * @param {Number} row The index of the row to select
422 * @param {Boolean} keepExisting (optional) <tt>true</tt> to keep existing selections
423 * @param {Boolean} preventViewNotify (optional) Specify <tt>true</tt> to
424 * prevent notifying the view (disables updating the selected appearance)
426 selectRow : function(index, keepExisting, preventViewNotify){
427 if(this.isLocked() || (index < 0 || index >= this.grid.store.getCount()) || (keepExisting && this.isSelected(index))){
430 var r = this.grid.store.getAt(index);
431 if(r && this.fireEvent('beforerowselect', this, index, keepExisting, r) !== false){
432 if(!keepExisting || this.singleSelect){
433 this.clearSelections();
435 this.selections.add(r);
436 this.last = this.lastActive = index;
437 if(!preventViewNotify){
438 this.grid.getView().onRowSelect(index);
440 this.fireEvent('rowselect', this, index, r);
441 this.fireEvent('selectionchange', this);
446 * Deselects a row. Before deselecting a row, checks if the selection model
447 * {@link Ext.grid.AbstractSelectionModel#isLocked is locked}.
448 * If this check is satisfied the row will be deselected and followed up by
449 * firing the {@link #rowdeselect} and {@link #selectionchange} events.
450 * @param {Number} row The index of the row to deselect
451 * @param {Boolean} preventViewNotify (optional) Specify <tt>true</tt> to
452 * prevent notifying the view (disables updating the selected appearance)
454 deselectRow : function(index, preventViewNotify){
458 if(this.last == index){
461 if(this.lastActive == index){
462 this.lastActive = false;
464 var r = this.grid.store.getAt(index);
466 this.selections.remove(r);
467 if(!preventViewNotify){
468 this.grid.getView().onRowDeselect(index);
470 this.fireEvent('rowdeselect', this, index, r);
471 this.fireEvent('selectionchange', this);
476 restoreLast : function(){
478 this.last = this._last;
483 acceptsNav : function(row, col, cm){
484 return !cm.isHidden(col) && cm.isCellEditable(col, row);
488 onEditorKey : function(field, e){
495 var shift = e.shiftKey;
500 newCell = g.walkCells(ed.row, ed.col-1, -1, this.acceptsNav, this);
502 newCell = g.walkCells(ed.row, ed.col+1, 1, this.acceptsNav, this);
504 }else if(k == e.ENTER){
505 if(this.moveEditorOnEnter !== false){
507 newCell = g.walkCells(last.row - 1, last.col, -1, this.acceptsNav, this);
509 newCell = g.walkCells(last.row + 1, last.col, 1, this.acceptsNav, this);
518 this.selectRow(r); // *** highlight newly-selected cell and update selection
521 if(g.isEditor && g.editing){ // *** handle tabbing while editorgrid is in edit mode
523 if(ae && ae.field.triggerBlur){
524 // *** if activeEditor is a TriggerField, explicitly call its triggerBlur() method
525 ae.field.triggerBlur();
528 g.startEditing(r, c);
532 destroy : function(){
534 this.rowNav.disable();
537 Ext.grid.RowSelectionModel.superclass.destroy.call(this);