Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / 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 });