X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/selection/Model.js

diff --git a/src/selection/Model.js b/src/selection/Model.js
index f4475a80..c3a3d289 100644
--- a/src/selection/Model.js
+++ b/src/selection/Model.js
@@ -13,19 +13,14 @@ If you are unsure which license is appropriate for your use, please contact the
 
 */
 /**
- * @class Ext.selection.Model
- * @extends Ext.util.Observable
+ * Tracks what records are currently selected in a databound component.
  *
- * Tracks what records are currently selected in a databound widget.
+ * This is an abstract class and is not meant to be directly used. Databound UI widgets such as
+ * {@link Ext.grid.Panel Grid} and {@link Ext.tree.Panel Tree} should subclass Ext.selection.Model
+ * and provide a way to binding to the component.
  *
- * This is an abstract class and is not meant to be directly used.
- *
- * DataBound UI widgets such as GridPanel, TreePanel, and ListView
- * should subclass AbstractStoreSelectionModel and provide a way
- * to binding to the component.
- *
- * The abstract methods onSelectChange and onLastFocusChanged should
- * be implemented in these subclasses to update the UI widget.
+ * The abstract methods `onSelectChange` and `onLastFocusChanged` should be implemented in these
+ * subclasses to update the UI widget.
  */
 Ext.define('Ext.selection.Model', {
     extend: 'Ext.util.Observable',
@@ -35,24 +30,28 @@ Ext.define('Ext.selection.Model', {
 
     /**
      * @cfg {String} mode
-     * Modes of selection.
-     * Valid values are SINGLE, SIMPLE, and MULTI. Defaults to 'SINGLE'
+     * Mode of selection.  Valid values are:
+     *
+     * - **SINGLE** - Only allows selecting one item at a time.  Use {@link #allowDeselect} to allow
+     *   deselecting that item.  This is the default.
+     * - **SIMPLE** - Allows simple selection of multiple items one-by-one. Each click in grid will either
+     *   select or deselect an item.
+     * - **MULTI** - Allows complex selection of multiple items using Ctrl and Shift keys.
      */
 
     /**
      * @cfg {Boolean} allowDeselect
-     * Allow users to deselect a record in a DataView, List or Grid. Only applicable when the SelectionModel's mode is 'SINGLE'. Defaults to false.
+     * Allow users to deselect a record in a DataView, List or Grid.
+     * Only applicable when the {@link #mode} is 'SINGLE'.
      */
     allowDeselect: false,
 
     /**
-     * @property selected
-     * READ-ONLY A MixedCollection that maintains all of the currently selected
-     * records.
+     * @property {Ext.util.MixedCollection} selected
+     * A MixedCollection that maintains all of the currently selected records. Read-only.
      */
     selected: null,
 
-
     /**
      * Prune records when they are removed from the store from the selection.
      * This is a private flag. For an example of its usage, take a look at
@@ -69,12 +68,12 @@ Ext.define('Ext.selection.Model', {
 
         me.addEvents(
             /**
-             * @event selectionchange
+             * @event
              * Fired after a selection change has occurred
              * @param {Ext.selection.Model} this
-             * @param  {Array} selected The selected records
+             * @param {Ext.data.Model[]} selected The selected records
              */
-             'selectionchange'
+            'selectionchange'
         );
 
         me.modes = {
@@ -98,7 +97,7 @@ Ext.define('Ext.selection.Model', {
 
         if(!initial && me.store){
             if(store !== me.store && me.store.autoDestroy){
-                me.store.destroy();
+                me.store.destroyStore();
             }else{
                 me.store.un("add", me.onStoreAdd, me);
                 me.store.un("clear", me.onStoreClear, me);
@@ -123,8 +122,8 @@ Ext.define('Ext.selection.Model', {
     },
 
     /**
-     * Select all records in the view.
-     * @param {Boolean} suppressEvent True to suppress any selects event
+     * Selects all records in the view.
+     * @param {Boolean} suppressEvent True to suppress any select events
      */
     selectAll: function(suppressEvent) {
         var me = this,
@@ -143,7 +142,7 @@ Ext.define('Ext.selection.Model', {
     },
 
     /**
-     * Deselect all records in the view.
+     * Deselects all records in the view.
      * @param {Boolean} suppressEvent True to suppress any deselect events
      */
     deselectAll: function(suppressEvent) {
@@ -206,7 +205,7 @@ Ext.define('Ext.selection.Model', {
      * All rows in between startRow and endRow are also selected.
      * @param {Ext.data.Model/Number} startRow The record or index of the first row in the range
      * @param {Ext.data.Model/Number} endRow The record or index of the last row in the range
-     * @param {Boolean} keepExisting (optional) True to retain existing selections
+     * @param {Boolean} [keepExisting] True to retain existing selections
      */
     selectRange : function(startRow, endRow, keepExisting, dir){
         var me = this,
@@ -265,18 +264,21 @@ Ext.define('Ext.selection.Model', {
 
     /**
      * Selects a record instance by record instance or index.
-     * @param {Ext.data.Model/Index} records An array of records or an index
-     * @param {Boolean} keepExisting
-     * @param {Boolean} suppressEvent Set to false to not fire a select event
+     * @param {Ext.data.Model[]/Number} records An array of records or an index
+     * @param {Boolean} [keepExisting] True to retain existing selections
+     * @param {Boolean} [suppressEvent] Set to true to not fire a select event
      */
     select: function(records, keepExisting, suppressEvent) {
-        this.doSelect(records, keepExisting, suppressEvent);
+        // Automatically selecting eg store.first() or store.last() will pass undefined, so that must just return;
+        if (Ext.isDefined(records)) {
+            this.doSelect(records, keepExisting, suppressEvent);
+        }
     },
 
     /**
      * Deselects a record instance by record instance or index.
-     * @param {Ext.data.Model/Index} records An array of records or an index
-     * @param {Boolean} suppressEvent Set to false to not fire a deselect event
+     * @param {Ext.data.Model[]/Number} records An array of records or an index
+     * @param {Boolean} [suppressEvent] Set to true to not fire a deselect event
      */
     deselect: function(records, suppressEvent) {
         this.doDeselect(records, suppressEvent);
@@ -365,7 +367,7 @@ Ext.define('Ext.selection.Model', {
         }
 
         len = records.length;
-        
+
         for (; i < len; i++) {
             record = records[i];
             if (me.isSelected(record)) {
@@ -420,9 +422,9 @@ Ext.define('Ext.selection.Model', {
     },
 
     /**
-     * @param {Ext.data.Model} record
-     * Set a record as the last focused record. This does NOT mean
+     * Sets a record as the last focused record. This does NOT mean
      * that the record has been selected.
+     * @param {Ext.data.Model} record
      */
     setLastFocused: function(record, supressFocus) {
         var me = this,
@@ -433,7 +435,7 @@ Ext.define('Ext.selection.Model', {
 
     /**
      * Determines if this record is currently focused.
-     * @param Ext.data.Record record
+     * @param {Ext.data.Model} record
      */
     isFocused: function(record) {
         return record === this.getLastFocused();
@@ -462,22 +464,23 @@ Ext.define('Ext.selection.Model', {
 
     /**
      * Returns an array of the currently selected records.
-     * @return {Array} The selected records
+     * @return {Ext.data.Model[]} The selected records
      */
     getSelection: function() {
         return this.selected.getRange();
     },
 
     /**
-     * Returns the current selectionMode. SINGLE, MULTI or SIMPLE.
-     * @return {String} The selectionMode
+     * Returns the current selectionMode.
+     * @return {String} The selectionMode: 'SINGLE', 'MULTI' or 'SIMPLE'.
      */
     getSelectionMode: function() {
         return this.selectionMode;
     },
 
     /**
-     * Sets the current selectionMode. SINGLE, MULTI or SIMPLE.
+     * Sets the current selectionMode.
+     * @param {String} selModel 'SINGLE', 'MULTI' or 'SIMPLE'.
      */
     setSelectionMode: function(selMode) {
         selMode = selMode ? selMode.toUpperCase() : 'SINGLE';
@@ -495,17 +498,16 @@ Ext.define('Ext.selection.Model', {
     },
 
     /**
-     * Locks the current selection and disables any changes from
-     * happening to the selection.
-     * @param {Boolean} locked
+     * Locks the current selection and disables any changes from happening to the selection.
+     * @param {Boolean} locked  True to lock, false to unlock.
      */
     setLocked: function(locked) {
         this.locked = !!locked;
     },
 
     /**
-     * Returns <tt>true</tt> if the specified row is selected.
-     * @param {Record/Number} record The record or index of the record to check
+     * Returns true if the specified row is selected.
+     * @param {Ext.data.Model/Number} record The record or index of the record to check
      * @return {Boolean}
      */
     isSelected: function(record) {
@@ -611,7 +613,7 @@ Ext.define('Ext.selection.Model', {
     },
 
     /**
-     * Gets the count of selected records.
+     * Returns the count of selected records.
      * @return {Number} The number of selected records
      */
     getCount: function() {