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