add extjs 6.0.1 sources

[extjs.git] / extjs / packages / charts / src / draw / Surface.js

/**\r
 * A Surface is an interface to render methods inside a draw {@link Ext.draw.Container}.\r
 * A Surface contains methods to render sprites, get bounding boxes of sprites, add\r
 * sprites to the canvas, initialize other graphic components, etc. One of the most used\r
 * methods for this class is the `add` method, to add Sprites to the surface.\r
 *\r
 * Most of the Surface methods are abstract and they have a concrete implementation\r
 * in Canvas or SVG engines.\r
 *\r
 * A Surface instance can be accessed as a property of a draw container. For example:\r
 *\r
 *     drawContainer.getSurface('main').add({\r
 *         type: 'circle',\r
 *         fill: '#ffc',\r
 *         radius: 100,\r
 *         x: 100,\r
 *         y: 100\r
 *     });\r
 *     drawContainer.renderFrame();\r
 *\r
 * The configuration object passed in the `add` method is the same as described in the {@link Ext.draw.sprite.Sprite}\r
 * class documentation.\r
 *\r
 * ## Example\r
 *\r
 *     drawContainer.getSurface('main').add([\r
 *         {\r
 *             type: 'circle',\r
 *             radius: 10,\r
 *             fill: '#f00',\r
 *             x: 10,\r
 *             y: 10\r
 *         },\r
 *         {\r
 *             type: 'circle',\r
 *             radius: 10,\r
 *             fill: '#0f0',\r
 *             x: 50,\r
 *             y: 50\r
 *         },\r
 *         {\r
 *             type: 'circle',\r
 *             radius: 10,\r
 *             fill: '#00f',\r
 *             x: 100,\r
 *             y: 100\r
 *         },\r
 *         {\r
 *             type: 'rect',\r
 *             radius: 10,\r
 *             x: 10,\r
 *             y: 10\r
 *         },\r
 *         {\r
 *             type: 'rect',\r
 *             radius: 10,\r
 *             x: 50,\r
 *             y: 50\r
 *         },\r
 *         {\r
 *             type: 'rect',\r
 *             radius: 10,\r
 *             x: 100,\r
 *             y: 100\r
 *         }\r
 *     ]);\r
 *     drawContainer.renderFrame();\r
 *\r
 */\r
Ext.define('Ext.draw.Surface', {\r
    extend: 'Ext.draw.SurfaceBase',\r
    xtype: 'surface',\r
\r
    requires: [\r
        'Ext.draw.sprite.*',\r
        'Ext.draw.gradient.*',\r
        'Ext.draw.sprite.AttributeDefinition',\r
        'Ext.draw.Matrix',\r
        'Ext.draw.Draw'\r
    ],\r
\r
    uses: [\r
        'Ext.draw.engine.Canvas'\r
    ],\r
\r
    /**\r
     * The reported device pixel density.\r
     * devicePixelRatio is only supported from IE11,\r
     * so we use deviceXDPI and logicalXDPI that are supported from IE6.\r
     */\r
    devicePixelRatio: window.devicePixelRatio || window.screen.deviceXDPI / window.screen.logicalXDPI,\r
\r
    deprecated: {\r
        '5.1.0': {\r
            statics: {\r
                methods: {\r
                    /**\r
                     * @deprecated 5.1.0\r
                     * Stably sort the list of sprites by their zIndex.\r
                     * Deprecated, use the {@link Ext.Array#sort} method instead.\r
                     * @param {Array} list\r
                     * @return {Array} Sorted array.\r
                     */\r
                    stableSort: function (list) {\r
                        return Ext.Array.sort(list, function (a, b) {\r
                            return a.attr.zIndex - b.attr.zIndex;\r
                        });\r
                    }\r
                }\r
            }\r
        }\r
    },\r
\r
    config: {\r
        cls: Ext.baseCSSPrefix + 'surface',\r
        /**\r
         * @cfg {Array}\r
         * The [x, y, width, height] rect of the surface related to its container.\r
         */\r
        rect: null,\r
\r
        /**\r
         * @cfg {Object}\r
         * Background sprite config of the surface.\r
         */\r
        background: null,\r
\r
        /**\r
         * @cfg {Array}\r
         * Array of sprite instances.\r
         */\r
        items: [],\r
\r
        /**\r
         * @cfg {Boolean}\r
         * Indicates whether the surface needs to redraw.\r
         */\r
        dirty: false,\r
\r
        /**\r
         * @cfg {Boolean} flipRtlText\r
         * If the surface is in the RTL mode, text will render with the RTL direction,\r
         * but the alignment and position of the text won't change by default.\r
         * Setting this config to 'true' will get text alignment and its position\r
         * within a surface mirrored.\r
         */\r
        flipRtlText: false\r
    },\r
\r
    isSurface: true,\r
\r
    /**\r
     * @private\r
     * This flag is used to indicate that `predecessors` surfaces that should render\r
     * before this surface renders are dirty, and to call `renderFrame`\r
     * when all `predecessors` have their `renderFrame` called (i.e. not dirty anymore).\r
     * This flag indicates that current surface has surfaces that are yet to render\r
     * before current surface can render. When all the `predecessors` surfaces\r
     * have rendered, i.e. when `dirtyPredecessorCount` reaches zero,\r
     */\r
    isPendingRenderFrame: false,\r
\r
    dirtyPredecessorCount: 0,\r
\r
    constructor: function (config) {\r
        var me = this;\r
\r
        me.predecessors = [];\r
        me.successors = [];\r
        me.map = {};\r
\r
        me.callParent([config]);\r
        me.matrix = new Ext.draw.Matrix();\r
        me.inverseMatrix = me.matrix.inverse();\r
    },\r
\r
    /**\r
     * Round the number to align to the pixels on device.\r
     * @param {Number} num The number to align.\r
     * @return {Number} The resultant alignment.\r
     */\r
    roundPixel: function (num) {\r
        return Math.round(this.devicePixelRatio * num) / this.devicePixelRatio;\r
    },\r
\r
    /**\r
     * Mark the surface to render after another surface is updated.\r
     * @param {Ext.draw.Surface} surface The surface to wait for.\r
     */\r
    waitFor: function (surface) {\r
        var me = this,\r
            predecessors = me.predecessors;\r
\r
        if (!Ext.Array.contains(predecessors, surface)) {\r
            predecessors.push(surface);\r
            surface.successors.push(me);\r
            if (surface.getDirty()) {\r
                me.dirtyPredecessorCount++;\r
            }\r
        }\r
    },\r
\r
    updateDirty: function (dirty) {\r
        var successors = this.successors,\r
            ln = successors.length,\r
            i = 0,\r
            successor;\r
\r
        for (; i < ln; i++) {\r
            successor = successors[i];\r
            if (dirty) {\r
                successor.dirtyPredecessorCount++;\r
                successor.setDirty(true);\r
            } else {\r
                successor.dirtyPredecessorCount--;\r
                // Don't need to call `setDirty(false)` on a successor here,\r
                // as this will be done by `renderFrame`.\r
                if (successor.dirtyPredecessorCount === 0 && successor.isPendingRenderFrame) {\r
                    successor.renderFrame();\r
                }\r
            }\r
        }\r
    },\r
\r
    applyBackground: function (background, oldBackground) {\r
        this.setDirty(true);\r
        if (Ext.isString(background)) {\r
            background = { fillStyle: background };\r
        }\r
        return Ext.factory(background, Ext.draw.sprite.Rect, oldBackground);\r
    },\r
\r
    applyRect: function (rect, oldRect) {\r
        if (oldRect && rect[0] === oldRect[0] && rect[1] === oldRect[1] && rect[2] === oldRect[2] && rect[3] === oldRect[3]) {\r
            return;\r
        }\r
        if (Ext.isArray(rect)) {\r
            return [rect[0], rect[1], rect[2], rect[3]];\r
        } else if (Ext.isObject(rect)) {\r
            return [\r
                rect.x || rect.left,\r
                rect.y || rect.top,\r
                rect.width || (rect.right - rect.left),\r
                rect.height || (rect.bottom - rect.top)\r
            ];\r
        }\r
    },\r
\r
    updateRect: function (rect) {\r
        var me = this,\r
            l = rect[0],\r
            t = rect[1],\r
            r = l + rect[2],\r
            b = t + rect[3],\r
            background = me.getBackground(),\r
            element = me.element;\r
\r
        element.setLocalXY(Math.floor(l), Math.floor(t));\r
        element.setSize(Math.ceil(r - Math.floor(l)), Math.ceil(b - Math.floor(t)));\r
\r
        if (background) {\r
            background.setAttributes({\r
                x: 0,\r
                y: 0,\r
                width: Math.ceil(r - Math.floor(l)),\r
                height: Math.ceil(b - Math.floor(t))\r
            });\r
        }\r
        me.setDirty(true);\r
    },\r
\r
    /**\r
     * Reset the matrix of the surface.\r
     */\r
    resetTransform: function () {\r
        this.matrix.set(1, 0, 0, 1, 0, 0);\r
        this.inverseMatrix.set(1, 0, 0, 1, 0, 0);\r
        this.setDirty(true);\r
    },\r
\r
    /**\r
     * Get the sprite by id or index.\r
     * It will first try to find a sprite with the given id, otherwise will try to use the id as an index.\r
     * @param {String|Number} id\r
     * @return {Ext.draw.sprite.Sprite}\r
     */\r
    get: function (id) {\r
        return this.map[id] || this.getItems()[id];\r
    },\r
\r
    /**\r
     * @method\r
     * Add a Sprite to the surface.\r
     * You can put any number of objects as the parameter.\r
     * See {@link Ext.draw.sprite.Sprite} for the configuration object to be passed into this method.\r
     *\r
     * For example:\r
     *\r
     *     drawContainer.getSurface().add({\r
     *         type: 'circle',\r
     *         fill: '#ffc',\r
     *         radius: 100,\r
     *         x: 100,\r
     *         y: 100\r
     *     });\r
     *     drawContainer.renderFrame();\r
     *\r
     * @param {Object/Object[]} sprite\r
     * @returns {Ext.draw.sprite.Sprite/Ext.draw.sprite.Sprite[]}\r
     *\r
     */\r
    add: function () {\r
        var me = this,\r
            args = Array.prototype.slice.call(arguments),\r
            argIsArray = Ext.isArray(args[0]),\r
            map = me.map,\r
            results = [],\r
            items, item, sprite,\r
            i, ln;\r
\r
        items = Ext.Array.clean(argIsArray ? args[0] : args);\r
\r
        if (!items.length) {\r
            return results;\r
        }\r
\r
        for (i = 0, ln = items.length; i < ln; i++) {\r
            item = items[i];\r
            sprite = null;\r
            if (item.isSprite && !map[item.getId()]) {\r
                sprite = item;\r
            } else if (!map[item.id]) {\r
                sprite = this.createItem(item);\r
            }\r
            if (sprite) {\r
                map[sprite.getId()] = sprite;\r
                results.push(sprite);\r
                sprite.setParent(me);\r
                sprite.setSurface(me);\r
                me.onAdd(sprite);\r
            }\r
        }\r
\r
        items = me.getItems();\r
        if (items) {\r
            items.push.apply(items, results);\r
        }\r
\r
        me.dirtyZIndex = true;\r
        me.setDirty(true);\r
\r
        if (!argIsArray && results.length === 1) {\r
            return results[0];\r
        } else {\r
            return results;\r
        }\r
    },\r
\r
    /**\r
     * @method\r
     * @protected\r
     * Invoked when a sprite is added to the surface.\r
     * @param {Ext.draw.sprite.Sprite} sprite The sprite to be added.\r
     */\r
    onAdd: Ext.emptyFn,\r
\r
    /**\r
     * Remove a given sprite from the surface,\r
     * optionally destroying the sprite in the process.\r
     * You can also call the sprite's own `remove` method.\r
     *\r
     * For example:\r
     *\r
     *      drawContainer.surface.remove(sprite);\r
     *      // or...\r
     *      sprite.remove();\r
     *\r
     * @param {Ext.draw.sprite.Sprite/String} sprite A sprite instance or its ID.\r
     * @param {Boolean} [isDestroy=false] If `true`, the sprite will be destroyed.\r
     * @returns {Ext.draw.sprite.Sprite} Returns the removed/destroyed sprite or `null` otherwise.\r
     */\r
    remove: function (sprite, isDestroy) {\r
        var me = this,\r
            id, isOwnSprite;\r
\r
        if (sprite) {\r
            if (sprite.charAt) { // is String\r
                sprite = me.map[sprite];\r
            }\r
            if (!sprite || !sprite.isSprite) {\r
                return null;\r
            }\r
            if (sprite.isDestroyed || sprite.isDestroying) {\r
                return sprite;\r
            }\r
            id = sprite.getId();\r
            isOwnSprite = me.map[id];\r
            delete me.map[id];\r
\r
            if (isDestroy) {\r
                sprite.destroy();\r
            }\r
            if (!isOwnSprite) {\r
                return sprite;\r
            }\r
            sprite.setParent(null);\r
            sprite.setSurface(null);\r
            Ext.Array.remove(me.getItems(), sprite);\r
\r
            me.dirtyZIndex = true;\r
            me.setDirty(true);\r
        }\r
\r
        return sprite || null;\r
    },\r
\r
    /**\r
     * Remove all sprites from the surface, optionally destroying the sprites in the process.\r
     *\r
     * For example:\r
     *\r
     *     drawContainer.getSurface('main').removeAll();\r
     *\r
     * @param {Boolean} [isDestroy=false]\r
     */\r
    removeAll: function (isDestroy) {\r
        var items = this.getItems(),\r
            i = items.length - 1,\r
            item;\r
\r
        if (isDestroy) {\r
            for (; i >= 0; i--) {\r
                items[i].destroy();\r
            }\r
        } else {\r
            for (; i >= 0; i--) {\r
                item = items[i];\r
                item.setParent(null);\r
                item.setSurface(null);\r
            }\r
        }\r
\r
        items.length = 0;\r
        this.map = {};\r
        this.dirtyZIndex = true;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    applyItems: function (items) {\r
        if (this.getItems()) {\r
            this.removeAll(true);\r
        }\r
        return Ext.Array.from(this.add(items));\r
    },\r
\r
    /**\r
     * @private\r
     * Creates an item and appends it to the surface. Called\r
     * as an internal method when calling `add`.\r
     */\r
    createItem: function (config) {\r
        return Ext.create(config.xclass || 'sprite.' + config.type, config);\r
    },\r
\r
    /**\r
     * Return the minimal bounding box that contains all the sprites bounding boxes in the given list of sprites.\r
     * @param {Ext.draw.sprite.Sprite[]|Ext.draw.sprite.Sprite} sprites\r
     * @param {Boolean} [isWithoutTransform=false]\r
     * @return {{x: Number, y: Number, width: number, height: number}}\r
     */\r
    getBBox: function (sprites, isWithoutTransform) {\r
        var sprites = Ext.Array.from(sprites),\r
            left = Infinity,\r
            right = -Infinity,\r
            top = Infinity,\r
            bottom = -Infinity,\r
            sprite, bbox, i, ln;\r
\r
        for (i = 0, ln = sprites.length; i < ln; i++) {\r
            sprite = sprites[i];\r
            bbox = sprite.getBBox(isWithoutTransform);\r
            if (left > bbox.x) {\r
                left = bbox.x;\r
            }\r
            if (right < bbox.x + bbox.width) {\r
                right = bbox.x + bbox.width;\r
            }\r
            if (top > bbox.y) {\r
                top = bbox.y;\r
            }\r
            if (bottom < bbox.y + bbox.height) {\r
                bottom = bbox.y + bbox.height;\r
            }\r
        }\r
        return {\r
            x: left,\r
            y: top,\r
            width: right - left,\r
            height: bottom - top\r
        };\r
    },\r
\r
    emptyRect: [0, 0, 0, 0],\r
\r
    // Converts event's page coordinates into surface coordinates.\r
    // Note: surface's x-coordinates always go LTR, regardless of RTL mode.\r
    getEventXY: function (e) {\r
        var me = this,\r
            isRtl = me.getInherited().rtl,\r
            pageXY = e.getXY(), // Event position in page coordinates.\r
            container = me.getOwnerBody(), // The body of the chart (doesn't include docked items like legend).\r
            xy = container.getXY(), // Surface container position in page coordinates.\r
            rect = me.getRect() || me.emptyRect, // Surface position in surface container coordinates (LTR).\r
            result = [],\r
            width;\r
\r
        if (isRtl) {\r
            width = container.getWidth();\r
            // The line below is actually a simplified form of\r
            // rect[2] - (pageXY[0] - xy[0] - (width - (rect[0] + rect[2]))).\r
            result[0] = xy[0] - pageXY[0] - rect[0] + width;\r
        } else {\r
            result[0] = pageXY[0] - xy[0] - rect[0];\r
        }\r
        result[1] = pageXY[1] - xy[1] - rect[1];\r
        return result;\r
    },\r
\r
    /**\r
     * Empty the surface content (without touching the sprites.)\r
     */\r
    clear: Ext.emptyFn,\r
\r
    /**\r
     * @private\r
     * Order the items by their z-index if any of that has been changed since last sort.\r
     */\r
    orderByZIndex: function () {\r
        var me = this,\r
            items = me.getItems(),\r
            dirtyZIndex = false,\r
            i, ln;\r
\r
        if (me.getDirty()) {\r
            for (i = 0, ln = items.length; i < ln; i++) {\r
                if (items[i].attr.dirtyZIndex) {\r
                    dirtyZIndex = true;\r
                    break;\r
                }\r
            }\r
            if (dirtyZIndex) {\r
                // sort by zIndex\r
                Ext.Array.sort(items, function (a, b) {\r
                    return a.attr.zIndex - b.attr.zIndex;\r
                });\r
                this.setDirty(true);\r
            }\r
\r
            for (i = 0, ln = items.length; i < ln; i++) {\r
                items[i].attr.dirtyZIndex = false;\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Force the element to redraw.\r
     */\r
    repaint: function () {\r
        var me = this;\r
        me.repaint = Ext.emptyFn;\r
        Ext.defer(function () {\r
            delete me.repaint;\r
            me.element.repaint();\r
        }, 1);\r
    },\r
\r
    /**\r
     * Triggers the re-rendering of the canvas.\r
     */\r
    renderFrame: function () {\r
        var me = this;\r
\r
        if (!me.element) {\r
            return;\r
        }\r
        if (me.dirtyPredecessorCount > 0) {\r
            me.isPendingRenderFrame = true;\r
            return;\r
        }\r
\r
        var rect = me.getRect(),\r
            background = me.getBackground(),\r
            items = me.getItems(),\r
            item, i, ln;\r
\r
        // Cannot render before the surface is placed.\r
        if (!rect) {\r
            return;\r
        }\r
\r
        // This will also check the dirty flags of the sprites.\r
        me.orderByZIndex();\r
        if (me.getDirty()) {\r
            me.clear();\r
            me.clearTransform();\r
\r
            if (background) {\r
                me.renderSprite(background);\r
            }\r
\r
            for (i = 0, ln = items.length; i < ln; i++) {\r
                item = items[i];\r
                if (me.renderSprite(item) === false) {\r
                    return;\r
                }\r
                item.attr.textPositionCount = me.textPosition;\r
            }\r
\r
            me.setDirty(false);\r
        }\r
    },\r
\r
    /**\r
     * @method\r
     * @private\r
     * Renders a single sprite into the surface.\r
     * Do not call it from outside `renderFrame` method.\r
     *\r
     * @param {Ext.draw.sprite.Sprite} sprite The Sprite to be rendered.\r
     * @return {Boolean} returns `false` to stop the rendering to continue.\r
     */\r
    renderSprite: Ext.emptyFn,\r
\r
    /**\r
     * @method flatten\r
     * Flattens the given drawing surfaces into a single image\r
     * and returns an object containing the data (in the DataURL format)\r
     * and the type (e.g. 'png' or 'svg') of that image.\r
     * @param {Object} size The size of the final image.\r
     * @param {Number} size.width\r
     * @param {Number} size.height\r
     * @param {Ext.draw.Surface[]} surfaces The surfaces to flatten.\r
     * @return {Object}\r
     * @return {String} return.data The DataURL of the flattened image.\r
     * @return {String} return.type The type of the image.\r
     *\r
     */\r
\r
    /**\r
     * @private\r
     * Clears the current transformation state on the surface.\r
     */\r
    clearTransform: Ext.emptyFn,\r
\r
    /**\r
     * Destroys the surface. This is done by removing all components from it and\r
     * also removing its reference to a DOM element.\r
     *\r
     * For example:\r
     *\r
     *      drawContainer.surface.destroy();\r
     */\r
    destroy: function () {\r
        var me = this;\r
\r
        me.removeAll(true);\r
        me.predecessors = null;\r
        me.successors = null;\r
\r
        me.callParent();\r
    }\r
});\r
\r
\r