add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / grid / CellContext.js

/**\r
 * Instances of this class encapsulate a position in a grid's row/column coordinate system.\r
 *\r
 * Cells are addressed using the owning {@link #record} and {@link #column} for robustness. \r
 * the column may be moved, the store may be sorted, and the CellContext will still reference\r
 * the same *logical* cell. Be aware that due to buffered rendering the *physical* cell may not exist.\r
 *\r
 * The {@link #setPosition} method however allows a numeric row and column to be passed in. These\r
 * are immediately converted.\r
 *\r
 * Be careful not to make `CellContext` objects *too* persistent. If the owning record is removed, or the owning column\r
 * is removed, the reference will be stale.\r
 *\r
 * Freshly created context objects, such as those exposed by events from the {Ext.grid.selection.SpreadsheetModel spreadsheet selection model}\r
 * are safe to use until your application mutates the store, or changes the column set.\r
 */\r
Ext.define('Ext.grid.CellContext', {\r
\r
    /**\r
     * @property {Boolean} isCellContext\r
     * @readonly\r
     * `true` in this class to identify an object as an instantiated CellContext, or subclass thereof.\r
     */\r
    isCellContext: true,\r
\r
    /**\r
     * @readonly\r
     * @property {Ext.grid.column.Column} column\r
     * The grid column which owns the referenced cell.\r
     */\r
    \r
    /**\r
     * @readonly\r
     * @property {Ext.data.Model} record\r
     * The store record which maps to the referenced cell.\r
     */\r
\r
    /**\r
     * @readonly\r
     * @property {Number} rowIdx\r
     * The row number in the store which owns the referenced cell.\r
     *\r
     * *Be aware that after the initial call to {@link #setPosition}, this value may become stale due to subsequent store mutation.*\r
     */\r
\r
    /**\r
     * @readonly\r
     * @property {Number} colIdx\r
     * The column index in the owning View's leaf column set of the referenced cell.\r
     *\r
     * *Be aware that after the initial call to {@link #setPosition}, this value may become stale due to subsequent column mutation.*\r
     */\r
\r
     /**\r
      * Creates a new CellContext which references a {@link Ext.view.Table GridView}\r
      * @param {Ext.view.Table} view The {@link Ext.view.Table GridView} for which the cell context is needed.\r
      *\r
      * To complete creation of a valid context, use the {@link #setPosition} method.\r
      */\r
    constructor: function(view) {\r
        this.view = view;\r
    },\r
    \r
    /**\r
     * Binds this cell context to a logical cell defined by the {@link #record} and {@link #column}.\r
     *\r
     * @param {Number/Ext.data.Model} row The row index or record which owns the required cell.\r
     * @param {Number/Ext.grid.column.Column} col The column index (In the owning View's leaf column set), or the owning {@link Ext.grid.column.Column column}.\r
     *\r
     * A one argument form may be used in the form of an array:\r
     *\r
     *     [column, row]\r
     *\r
     * Or another CellContext may be passed.\r
     *\r
     * @return {Ext.grid.CellContext} this CellContext object.\r
     */\r
    setPosition: function(row, col) {\r
        var me = this;\r
\r
        // We were passed {row: 1, column: 2, view: myView} or [2, 1]\r
        if (arguments.length === 1) {\r
            // A [column, row] array passed\r
            if (row.length) {\r
                col = row[0];\r
                row = row[1];\r
            }\r
            else if (row.isCellContext) {\r
                return me.setAll(row.view, row.rowIdx, row.colIdx, row.record, row.columnHeader);\r
            }\r
            // An object containing {row: r, column: c}\r
            else {\r
                if (row.view) {\r
                    me.view = row.view;\r
                }\r
                col = row.column;\r
                row = row.row;\r
            }\r
        }\r
\r
        me.setRow(row);\r
        me.setColumn(col);\r
        return me;\r
    },\r
\r
    setAll: function(view, recordIndex, columnIndex, record, columnHeader) {\r
        var me = this;\r
\r
        me.view = view;\r
        me.rowIdx = recordIndex;\r
        me.colIdx = columnIndex;\r
        me.record = record;\r
        me.column = columnHeader;\r
        return me;\r
    },\r
\r
    setRow: function(row) {\r
        var me = this,\r
            dataSource = me.view.dataSource;\r
        \r
        if (row !== undefined) {\r
            // Row index passed\r
            if (typeof row === 'number') {\r
                me.rowIdx = Math.max(Math.min(row, dataSource.getCount() - 1), 0);\r
                me.record = dataSource.getAt(row);\r
            }\r
            // row is a Record\r
            else if (row.isModel) {\r
                me.record = row;\r
                me.rowIdx = dataSource.indexOf(row);\r
            }\r
            // row is a grid row, or Element wrapping row\r
            else if (row.tagName || row.isElement) {\r
                me.record = me.view.getRecord(row);\r
                me.rowIdx = dataSource.indexOf(me.record);\r
            }\r
        }\r
        return me;\r
    },\r
    \r
    setColumn: function(col) {\r
        var me = this,\r
                colMgr = me.view.getVisibleColumnManager();\r
\r
        // Maintainer:\r
        // We MUST NOT update the context view with the column's view because this context\r
        // may be for an Ext.locking.View which spans two grid views, and a column references\r
        // its local grid view.\r
        if (col !== undefined) {\r
            if (typeof col === 'number') {\r
                me.colIdx = col;\r
                me.column = colMgr.getHeaderAtIndex(col);\r
            } else if (col.isHeader) {\r
                me.column = col;\r
                // Must use the Manager's indexOf because view may be a locking view\r
                // And Column#getVisibleIndex returns the index of the column within its own header.\r
                me.colIdx = colMgr.indexOf(col);\r
            }\r
        }\r
        return me;\r
    },\r
\r
    /**\r
     * Returns the cell object referenced *at the time of calling*. Note that grid DOM is transient, and \r
     * the cell referenced may be removed from the DOM due to paging or buffered rendering or column or record removal.\r
     *\r
     * @param {Boolean} returnDom Pass `true` to return a DOM object instead of an {@link Ext.dom.Element Element).\r
     * @return {HTMLElement/Ext.dom.Element} The cell referenced by this context.\r
     */\r
    getCell: function(returnDom) {\r
        return this.view.getCellByPosition(this, returnDom);\r
    },\r
\r
    /**\r
     * Returns the row object referenced *at the time of calling*. Note that grid DOM is transient, and \r
     * the row referenced may be removed from the DOM due to paging or buffered rendering or column or record removal.\r
     *\r
     * @param {Boolean} returnDom Pass `true` to return a DOM object instead of an {@link Ext.dom.Element Element).\r
     * @return {HTMLElement/Ext.dom.Element} The grid row referenced by this context.\r
     */\r
    getRow: function(returnDom) {\r
        var result = this.view.getRow(this.record);\r
        return returnDom ? result : Ext.get(result);\r
    },\r
\r
    /**\r
     * Returns the view node object (the encapsulating element of a data row) referenced *at the time of\r
     * calling*. Note that grid DOM is transient, and the node referenced may be removed from the DOM due\r
     * to paging or buffered rendering or column or record removal.\r
     *\r
     * @param {Boolean} returnDom Pass `true` to return a DOM object instead of an {@link Ext.dom.Element Element).\r
     * @return {HTMLElement/Ext.dom.Element} The grid item referenced by this context.\r
     */\r
    getNode: function(returnDom) {\r
        var result = this.view.getNode(this.record);\r
        return returnDom ? result : Ext.get(result);\r
    },\r
\r
    /**\r
     * Compares this CellContext object to another CellContext to see if they refer to the same cell.\r
     * @param {Ext.grid.CellContext} other The CellContext to compare.\r
     * @return {Boolean} `true` if the other cell context references the same cell as this.\r
     */\r
    isEqual: function(other) {\r
        return (other && other.isCellContext && other.record === this.record && other.column === this.column);\r
    },\r
\r
    /**\r
     * Creates a clone of this CellContext.\r
     *\r
     * The clone may be retargeted without affecting the reference of this context.\r
     * @return {Ext.grid.CellContext} A copy of this context, referencing the same cell.\r
     */\r
    clone: function() {\r
        var me = this,\r
            result = new me.self(me.view);\r
\r
        result.rowIdx = me.rowIdx;\r
        result.colIdx = me.colIdx;\r
        result.record = me.record;\r
        result.column = me.column;\r
        return result;\r
    },\r
\r
    privates: {\r
        isFirstColumn: function() {\r
            var cell = this.getCell(true);\r
\r
            if (cell) {\r
                return !cell.previousSibling;\r
            }\r
        },\r
\r
        isLastColumn: function() {\r
            var cell = this.getCell(true);\r
\r
            if (cell) {\r
                return !cell.nextSibling;\r
            }\r
        },\r
\r
        getLastColumnIndex: function() {\r
            var row = this.getRow(true);\r
\r
            if (row) {\r
                return row.lastChild.cellIndex;\r
            }\r
            return -1;\r
        },\r
\r
        /**\r
         * @private\r
         * Navigates left or right within the current row.\r
         * @param {Number} direction `-1` to go towards the row start or `1` to go towards row end\r
         */\r
        navigate: function(direction) {\r
            var me = this,\r
                columns = me.view.getVisibleColumnManager().getColumns();\r
\r
            switch (direction) {\r
                case -1:\r
                    do {\r
                        // If we iterate off the start, wrap back to the end.\r
                        if (!me.colIdx) {\r
                            me.colIdx = columns.length - 1;\r
                        } else {\r
                            me.colIdx--;\r
                        }\r
                        me.setColumn(me.colIdx);\r
                    } while (!me.getCell(true))\r
                    break;\r
                case 1:\r
                    do {\r
                        // If we iterate off the end, wrap back to the start.\r
                        if (me.colIdx >= columns.length) {\r
                            me.colIdx = 0;\r
                        } else {\r
                            me.colIdx++;\r
                        }\r
                        me.setColumn(me.colIdx);\r
                    } while (!me.getCell(true))\r
                    break;\r
            }\r
        }\r
    },\r
\r
    statics: {\r
        compare: function(c1, c2) {\r
            return c1.rowIdx - c2.rowIdx || c1.colIdx - c2.colIdx;\r
        }\r
    }\r
});