add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / mixin / Selectable.js

/**\r
 * Tracks what records are currently selected in a databound widget. This class is mixed in to\r
 * {@link Ext.view.View dataview} and all subclasses.\r
 * @private\r
 */\r
Ext.define('Ext.mixin.Selectable', {\r
    extend: 'Ext.Mixin',\r
\r
    mixinConfig: {\r
        id: 'selectable',\r
        after: {\r
            updateStore: 'updateStore'\r
        }\r
    },\r
\r
    /**\r
     * @event beforeselectionchange\r
     * Fires before an item is selected.\r
     * @param {Ext.mixin.Selectable} this\r
     * @preventable\r
     * @deprecated 2.0.0 Please listen to the {@link #selectionchange} event with an order of `before` instead.\r
     */\r
\r
    /**\r
     * @event selectionchange\r
     * Fires when a selection changes.\r
     * @param {Ext.mixin.Selectable} this\r
     * @param {Ext.data.Model[]} records The records whose selection has changed.\r
     */\r
\r
    config: {\r
        /**\r
         * @cfg {Boolean} disableSelection `true` to disable selection.\r
         * This configuration will lock the selection model that the DataView uses.\r
         * @accessor\r
         */\r
        disableSelection: null,\r
\r
        /**\r
         * @cfg {String} mode\r
         * Modes of selection.\r
         * Valid values are `'SINGLE'`, `'SIMPLE'`, and `'MULTI'`.\r
         * @accessor\r
         */\r
        mode: 'SINGLE',\r
\r
        /**\r
         * @cfg {Boolean} allowDeselect\r
         * Allow users to deselect a record in a DataView, List or Grid. Only applicable when the Selectable's `mode` is\r
         * `'SINGLE'`.\r
         * @accessor\r
         */\r
        allowDeselect: false,\r
\r
        /**\r
         * @cfg {Ext.data.Model} lastSelected\r
         * @private\r
         * @accessor\r
         */\r
        lastSelected: null,\r
\r
        /**\r
         * @cfg {Ext.data.Model} lastFocused\r
         * @private\r
         * @accessor\r
         */\r
        lastFocused: null,\r
\r
        /**\r
         * @cfg {Boolean} deselectOnContainerClick `true` to deselect current selection when the container body is\r
         * clicked.\r
         * @accessor\r
         */\r
        deselectOnContainerClick: true,\r
\r
        /**\r
         * @cfg {Ext.data.Model} selection\r
         * The selected record.\r
         */\r
        selection: null,\r
\r
        twoWayBindable: {\r
            selection: 1\r
        },\r
\r
        publishes: {\r
            selection: 1\r
        }\r
    },\r
\r
    modes: {\r
        SINGLE: true,\r
        SIMPLE: true,\r
        MULTI: true\r
    },\r
\r
    selectableEventHooks: {\r
        add: 'onSelectionStoreAdd',\r
        remove: 'onSelectionStoreRemove',\r
        update: 'onSelectionStoreUpdate',\r
        clear: {\r
            fn: 'onSelectionStoreClear',\r
            priority: 1000\r
        },\r
        load: 'refreshSelection',\r
        refresh: 'refreshSelection'\r
    },\r
\r
    constructor: function() {\r
        this.selected = new Ext.util.MixedCollection();\r
        this.callParent(arguments);\r
    },\r
\r
    initSelectable: function() {\r
        this.publishState('selection', this.getSelection());\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    applyMode: function(mode) {\r
        mode = mode ? mode.toUpperCase() : 'SINGLE';\r
        // set to mode specified unless it doesnt exist, in that case\r
        // use single.\r
        return this.modes[mode] ? mode : 'SINGLE';\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateStore: function(newStore, oldStore) {\r
        var me = this,\r
            bindEvents = Ext.apply({}, me.selectableEventHooks, { scope: me });\r
\r
        if (oldStore && Ext.isObject(oldStore) && oldStore.isStore) {\r
            if (oldStore.autoDestroy) {\r
                oldStore.destroy();\r
            } else {\r
                oldStore.un(bindEvents);\r
            }\r
        }\r
\r
        if (newStore) {\r
            newStore.on(bindEvents);\r
            me.refreshSelection();\r
        }\r
    },\r
\r
    /**\r
     * Selects all records.\r
     * @param {Boolean} silent `true` to suppress all select events.\r
     */\r
    selectAll: function(silent) {\r
        var me = this,\r
            selections = me.getStore().getRange();\r
\r
        me.select(selections, true, silent);\r
    },\r
\r
    /**\r
     * Deselects all records.\r
     */\r
    deselectAll: function(supress) {\r
        var me = this,\r
            selections = me.getStore().getRange();\r
\r
        me.deselect(selections, supress);\r
\r
        me.selected.clear();\r
        me.setLastSelected(null);\r
        me.setLastFocused(null);\r
    },\r
\r
    updateSelection: function(selection) {\r
        if (this.changingSelection) {\r
            return;\r
        }\r
\r
        if (selection) {\r
            this.select(selection);\r
        } else {\r
            this.deselectAll();\r
        }\r
    },\r
\r
    // Provides differentiation of logic between MULTI, SIMPLE and SINGLE\r
    // selection modes.\r
    selectWithEvent: function(record) {\r
        var me = this,\r
            isSelected = me.isSelected(record);\r
        switch (me.getMode()) {\r
            case 'MULTI':\r
            case 'SIMPLE':\r
                if (isSelected) {\r
                    me.deselect(record);\r
                }\r
                else {\r
                    me.select(record, true);\r
                }\r
                break;\r
            case 'SINGLE':\r
                if (me.getAllowDeselect() && isSelected) {\r
                    // if allowDeselect is on and this record isSelected, deselect it\r
                    me.deselect(record);\r
                } else {\r
                    // select the record and do NOT maintain existing selections\r
                    me.select(record, false);\r
                }\r
                break;\r
        }\r
    },\r
\r
    /**\r
     * Selects a range of rows if the selection model {@link Ext.mixin.Selectable#getDisableSelection} is not locked.\r
     * All rows in between `startRecord` and `endRecord` are also selected.\r
     * @param {Number} startRecord The index of the first row in the range.\r
     * @param {Number} endRecord The index of the last row in the range.\r
     * @param {Boolean} [keepExisting] `true` to retain existing selections.\r
     */\r
    selectRange: function(startRecord, endRecord, keepExisting) {\r
        var me = this,\r
            store = me.getStore(),\r
            records = [],\r
            tmp, i;\r
\r
        if (me.getDisableSelection()) {\r
            return;\r
        }\r
\r
        // swap values\r
        if (startRecord > endRecord) {\r
            tmp = endRecord;\r
            endRecord = startRecord;\r
            startRecord = tmp;\r
        }\r
\r
        for (i = startRecord; i <= endRecord; i++) {\r
            records.push(store.getAt(i));\r
        }\r
        this.doMultiSelect(records, keepExisting);\r
    },\r
\r
    /**\r
     * Adds the given records to the currently selected set.\r
     * @param {Ext.data.Model/Array/Number} records The records to select.\r
     * @param {Boolean} keepExisting If `true`, the existing selection will be added to (if not, the old selection is replaced).\r
     * @param {Boolean} suppressEvent If `true`, the `select` event will not be fired.\r
     */\r
    select: function(records, keepExisting, suppressEvent) {\r
        var me = this,\r
            record;\r
\r
        if (me.getDisableSelection()) {\r
            return;\r
        }\r
\r
        if (typeof records === "number") {\r
            records = [me.getStore().getAt(records)];\r
        }\r
\r
        if (!records) {\r
            return;\r
        }\r
\r
        if (me.getMode() == "SINGLE" && records) {\r
            record = records.length ? records[0] : records;\r
            me.doSingleSelect(record, suppressEvent);\r
        } else {\r
            me.doMultiSelect(records, keepExisting, suppressEvent);\r
        }\r
    },\r
\r
    /**\r
     * Selects a single record.\r
     * @private\r
     */\r
    doSingleSelect: function(record, suppressEvent) {\r
        var me = this,\r
            selected = me.selected;\r
\r
        if (me.getDisableSelection()) {\r
            return;\r
        }\r
\r
        // already selected.\r
        // should we also check beforeselect?\r
        if (me.isSelected(record)) {\r
            return;\r
        }\r
\r
        if (selected.getCount() > 0) {\r
            me.deselect(me.getLastSelected(), suppressEvent);\r
        }\r
\r
        selected.add(record);\r
        me.setLastSelected(record);\r
        me.onItemSelect(record, suppressEvent);\r
        me.setLastFocused(record);\r
\r
        if (!suppressEvent) {\r
            me.fireSelectionChange([record]);\r
        }\r
    },\r
\r
    /**\r
     * Selects a set of multiple records.\r
     * @private\r
     */\r
    doMultiSelect: function(records, keepExisting, suppressEvent) {\r
        if (records === null || this.getDisableSelection()) {\r
            return;\r
        }\r
        records = !Ext.isArray(records) ? [records] : records;\r
\r
        var me = this,\r
            selected = me.selected,\r
            ln = records.length,\r
            change = false,\r
            i = 0,\r
            record;\r
\r
        if (!keepExisting && selected.getCount() > 0) {\r
            change = true;\r
            me.deselect(me.getSelections(), true);\r
        }\r
        for (; i < ln; i++) {\r
            record = records[i];\r
            if (keepExisting && me.isSelected(record)) {\r
                continue;\r
            }\r
            change = true;\r
            me.setLastSelected(record);\r
            selected.add(record);\r
            if (!suppressEvent) {\r
                me.setLastFocused(record);\r
            }\r
\r
            me.onItemSelect(record, suppressEvent);\r
        }\r
        if (change && !suppressEvent) {\r
            this.fireSelectionChange(records);\r
        }\r
    },\r
\r
    /**\r
     * Deselects the given record(s). If many records are currently selected, it will only deselect those you pass in.\r
     * @param {Number/Array/Ext.data.Model} records The record(s) to deselect. Can also be a number to reference by index.\r
     * @param {Boolean} suppressEvent If `true` the `deselect` event will not be fired.\r
     */\r
    deselect: function(records, suppressEvent) {\r
        var me = this;\r
\r
        if (me.getDisableSelection()) {\r
            return;\r
        }\r
\r
        records = Ext.isArray(records) ? records : [records];\r
\r
        var selected = me.selected,\r
            change   = false,\r
            i        = 0,\r
            store    = me.getStore(),\r
            ln       = records.length,\r
            record;\r
\r
        for (; i < ln; i++) {\r
            record = records[i];\r
\r
            if (typeof record === 'number') {\r
                record = store.getAt(record);\r
            }\r
\r
            if (selected.remove(record)) {\r
                if (me.getLastSelected() == record) {\r
                    me.setLastSelected(selected.last());\r
                }\r
                change = true;\r
            }\r
            if (record) {\r
                me.onItemDeselect(record, suppressEvent);\r
            }\r
        }\r
\r
        if (change && !suppressEvent) {\r
            me.fireSelectionChange(records);\r
        }\r
    },\r
\r
    /**\r
     * Sets a record as the last focused record. This does NOT mean\r
     * that the record has been selected.\r
     * @param {Ext.data.Record} newRecord\r
     * @param {Ext.data.Record} oldRecord\r
     */\r
    updateLastFocused: function(newRecord, oldRecord) {\r
        this.onLastFocusChanged(oldRecord, newRecord);\r
    },\r
\r
    fireSelectionChange: function(records) {\r
        var me = this;\r
\r
        me.changingSelection = true;\r
        me.setSelection(me.getLastSelected() || null);\r
        me.changingSelection = false;\r
        me.fireAction('selectionchange', [me, records], 'getSelections');\r
    },\r
\r
    /**\r
     * Returns the currently selected records.\r
     * @return {Ext.data.Model[]} The selected records.\r
     */\r
    getSelections: function() {\r
        return this.selected.getRange();\r
    },\r
\r
    /**\r
     * Returns `true` if the specified row is selected.\r
     * @param {Ext.data.Model/Number} record The record or index of the record to check.\r
     * @return {Boolean}\r
     */\r
    isSelected: function(record) {\r
        record = Ext.isNumber(record) ? this.getStore().getAt(record) : record;\r
        return this.selected.indexOf(record) !== -1;\r
    },\r
\r
    /**\r
     * Returns `true` if there is a selected record.\r
     * @return {Boolean}\r
     */\r
    hasSelection: function() {\r
        return this.selected.getCount() > 0;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    refreshSelection: function() {\r
        var me = this,\r
            selections = me.getSelections();\r
\r
        me.deselectAll(true);\r
        if (selections.length) {\r
            me.select(selections, false, true);\r
        }\r
    },\r
\r
    // prune records from the SelectionModel if\r
    // they were selected at the time they were\r
    // removed.\r
    onSelectionStoreRemove: function(store, records) {\r
        var me = this,\r
            selected = me.selected,\r
            ln = records.length,\r
            removed, record, i;\r
\r
        if (me.getDisableSelection()) {\r
            return;\r
        }\r
\r
        for (i = 0; i < ln; i++) {\r
            record = records[i];\r
            if (selected.remove(record)) {\r
                if (me.getLastSelected() == record) {\r
                    me.setLastSelected(null);\r
                }\r
                if (me.getLastFocused() == record) {\r
                    me.setLastFocused(null);\r
                }\r
                removed = removed || [];\r
                removed.push(record);\r
            }\r
        }\r
\r
        if (removed) {\r
            me.fireSelectionChange([removed]);\r
        }\r
    },\r
\r
    onSelectionStoreClear: function(store) {\r
        var records = store.getData().items;\r
        this.onSelectionStoreRemove(store, records);\r
    },\r
\r
    /**\r
     * Returns the number of selections.\r
     * @return {Number}\r
     */\r
    getSelectionCount: function() {\r
        return this.selected.getCount();\r
    },\r
\r
    onSelectionStoreAdd: Ext.emptyFn,\r
    onSelectionStoreUpdate: Ext.emptyFn,\r
    onItemSelect: Ext.emptyFn,\r
    onItemDeselect: Ext.emptyFn,\r
    onLastFocusChanged: Ext.emptyFn,\r
    onEditorKey: Ext.emptyFn\r
}, function() {\r
    /**\r
     * Selects a record instance by record instance or index.\r
     * @member Ext.mixin.Selectable\r
     * @method doSelect\r
     * @param {Ext.data.Model/Number} records An array of records or an index.\r
     * @param {Boolean} keepExisting\r
     * @param {Boolean} suppressEvent Set to `false` to not fire a select event.\r
     * @deprecated 2.0.0 Please use {@link #select} instead.\r
     */\r
\r
    /**\r
     * Deselects a record instance by record instance or index.\r
     * @member Ext.mixin.Selectable\r
     * @method doDeselect\r
     * @param {Ext.data.Model/Number} records An array of records or an index.\r
     * @param {Boolean} suppressEvent Set to `false` to not fire a deselect event.\r
     * @deprecated 2.0.0 Please use {@link #deselect} instead.\r
     */\r
\r
    /**\r
     * Returns the selection mode currently used by this Selectable.\r
     * @member Ext.mixin.Selectable\r
     * @method getSelectionMode\r
     * @return {String} The current mode.\r
     * @deprecated 2.0.0 Please use {@link #getMode} instead.\r
     */\r
\r
    /**\r
     * Returns the array of previously selected items.\r
     * @member Ext.mixin.Selectable\r
     * @method getLastSelected\r
     * @return {Array} The previous selection.\r
     * @deprecated 2.0.0\r
     */\r
\r
    /**\r
     * Returns `true` if the Selectable is currently locked.\r
     * @member Ext.mixin.Selectable\r
     * @method isLocked\r
     * @return {Boolean} True if currently locked\r
     * @deprecated 2.0.0 Please use {@link #getDisableSelection} instead.\r
     */\r
\r
    /**\r
     * This was an internal function accidentally exposed in 1.x and now deprecated. Calling it has no effect\r
     * @member Ext.mixin.Selectable\r
     * @method setLastFocused\r
     * @deprecated 2.0.0\r
     */\r
\r
    /**\r
     * Deselects any currently selected records and clears all stored selections.\r
     * @member Ext.mixin.Selectable\r
     * @method clearSelections\r
     * @deprecated 2.0.0 Please use {@link #deselectAll} instead.\r
     */\r
\r
    /**\r
     * Returns the number of selections.\r
     * @member Ext.mixin.Selectable\r
     * @method getCount\r
     * @return {Number}\r
     * @deprecated 2.0.0 Please use {@link #getSelectionCount} instead.\r
     */\r
\r
    /**\r
     * @cfg {Boolean} locked\r
     * @inheritdoc Ext.mixin.Selectable#disableSelection\r
     * @deprecated 2.0.0 Please use {@link #disableSelection} instead.\r
     */\r
});\r