/**

* Copyright 2012-2017, Plotly, Inc.

* All rights reserved.

*

* This source code is licensed under the MIT license found in the

* LICENSE file in the root directory of this source tree.

*/

'use strict';

var d3 = require('d3');

var isNumeric = require('fast-isnumeric');

var hasHover = require('has-hover');

var Plotly = require('../plotly');

var Lib = require('../lib');

var Events = require('../lib/events');

var Queue = require('../lib/queue');

var Registry = require('../registry');

var Plots = require('../plots/plots');

var Polar = require('../plots/polar');

var initInteractions = require('../plots/cartesian/graph_interact');

var Drawing = require('../components/drawing');

var Color = require('../components/color');

var ErrorBars = require('../components/errorbars');

var xmlnsNamespaces = require('../constants/xmlns_namespaces');

var svgTextUtils = require('../lib/svg_text_utils');

var manageArrays = require('./manage_arrays');

var helpers = require('./helpers');

var subroutines = require('./subroutines');

var editTypes = require('./edit_types');

var cartesianConstants = require('../plots/cartesian/constants');

var axisConstraints = require('../plots/cartesian/constraints');

var enforceAxisConstraints = axisConstraints.enforce;

var cleanAxisConstraints = axisConstraints.clean;

var axisIds = require('../plots/cartesian/axis_ids');

/**

* Main plot-creation function

*

* @param {string id or DOM element} gd

* the id or DOM element of the graph container div

* @param {array of objects} data

* array of traces, containing the data and display information for each trace

* @param {object} layout

* object describing the overall display of the plot,

* all the stuff that doesn't pertain to any individual trace

* @param {object} config

* configuration options (see ./plot_config.js for more info)

*

*/

Plotly.plot = function(gd, data, layout, config) {

var frames;

gd = helpers.getGraphDiv(gd);

// Events.init is idempotent and bails early if gd has already been init'd

Events.init(gd);

if(Lib.isPlainObject(data)) {

var obj = data;

data = obj.data;

layout = obj.layout;

config = obj.config;

frames = obj.frames;

}

var okToPlot = Events.triggerHandler(gd, 'plotly_beforeplot', [data, layout, config]);

if(okToPlot === false) return Promise.reject();

// if there's no data or layout, and this isn't yet a plotly plot

// container, log a warning to help plotly.js users debug

if(!data && !layout && !Lib.isPlotDiv(gd)) {

Lib.warn('Calling Plotly.plot as if redrawing ' +

'but this container doesn\'t yet have a plot.', gd);

}

function addFrames() {

if(frames) {

return Plotly.addFrames(gd, frames);

}

}

// transfer configuration options to gd until we move over to

// a more OO like model

setPlotContext(gd, config);

if(!layout) layout = {};

// hook class for plots main container (in case of plotly.js

// this won't be #embedded-graph or .js-tab-contents)

d3.select(gd).classed('js-plotly-plot', true);

// off-screen getBoundingClientRect testing space,

// in #js-plotly-tester (and stored as Drawing.tester)

// so we can share cached text across tabs

Drawing.makeTester();

// collect promises for any async actions during plotting

// any part of the plotting code can push to gd._promises, then

// before we move to the next step, we check that they're all

// complete, and empty out the promise list again.

gd._promises = [];

var graphWasEmpty = ((gd.data || []).length === 0 && Array.isArray(data));

// if there is already data on the graph, append the new data

// if you only want to redraw, pass a non-array for data

if(Array.isArray(data)) {

helpers.cleanData(data, gd.data);

if(graphWasEmpty) gd.data = data;

else gd.data.push.apply(gd.data, data);

// for routines outside graph_obj that want a clean tab

// (rather than appending to an existing one) gd.empty

// is used to determine whether to make a new tab

gd.empty = false;

}

if(!gd.layout || graphWasEmpty) gd.layout = helpers.cleanLayout(layout);

// if the user is trying to drag the axes, allow new data and layout

// to come in but don't allow a replot.

if(gd._dragging && !gd._transitioning) {

// signal to drag handler that after everything else is done

// we need to replot, because something has changed

gd._replotPending = true;

return Promise.reject();

} else {

// we're going ahead with a replot now

gd._replotPending = false;

}

Plots.supplyDefaults(gd);

var fullLayout = gd._fullLayout;

// Polar plots

if(data && data[0] && data[0].r) return plotPolar(gd, data, layout);

// so we don't try to re-call Plotly.plot from inside

// legend and colorbar, if margins changed

fullLayout._replotting = true;

// make or remake the framework if we need to

if(graphWasEmpty) makePlotFramework(gd);

// polar need a different framework

if(gd.framework !== makePlotFramework) {

gd.framework = makePlotFramework;

makePlotFramework(gd);

}

// clear gradient defs on each .plot call, because we know we'll loop through all traces

Drawing.initGradients(gd);

// save initial show spikes once per graph

if(graphWasEmpty) Plotly.Axes.saveShowSpikeInitial(gd);

// prepare the data and find the autorange

// generate calcdata, if we need to

// to force redoing calcdata, just delete it before calling Plotly.plot

var recalc = !gd.calcdata || gd.calcdata.length !== (gd._fullData || []).length;

if(recalc) Plots.doCalcdata(gd);

// in case it has changed, attach fullData traces to calcdata

for(var i = 0; i < gd.calcdata.length; i++) {

gd.calcdata[i][0].trace = gd._fullData[i];

}

/*

* start async-friendly code - now we're actually drawing things

*/

var oldmargins = JSON.stringify(fullLayout._size);

// draw framework first so that margin-pushing

// components can position themselves correctly

function drawFramework() {

var basePlotModules = fullLayout._basePlotModules;

for(var i = 0; i < basePlotModules.length; i++) {

if(basePlotModules[i].drawFramework) {

basePlotModules[i].drawFramework(gd);

}

}

return Lib.syncOrAsync([

subroutines.layoutStyles

], gd);

}

// draw anything that can affect margins.

function marginPushers() {

var calcdata = gd.calcdata;

var i, cd, trace;

Registry.getComponentMethod('legend', 'draw')(gd);

Registry.getComponentMethod('rangeselector', 'draw')(gd);

Registry.getComponentMethod('sliders', 'draw')(gd);

Registry.getComponentMethod('updatemenus', 'draw')(gd);

for(i = 0; i < calcdata.length; i++) {

cd = calcdata[i];

trace = cd[0].trace;

if(trace.visible !== true || !trace._module.colorbar) {

Plots.autoMargin(gd, 'cb' + trace.uid);

}

else trace._module.colorbar(gd, cd);

}

Plots.doAutoMargin(gd);

return Plots.previousPromises(gd);

}

// in case the margins changed, draw margin pushers again

function marginPushersAgain() {

if(JSON.stringify(fullLayout._size) === oldmargins) return;

return Lib.syncOrAsync([

marginPushers,

subroutines.layoutStyles

], gd);

}

function positionAndAutorange() {

if(!recalc) {

enforceAxisConstraints(gd);

return;

}

var subplots = Plots.getSubplotIds(fullLayout, 'cartesian');

var modules = fullLayout._modules;

var setPositionsArray = [];

// position and range calculations for traces that

// depend on each other ie bars (stacked or grouped)

// and boxes (grouped) push each other out of the way

var subplotInfo, i, j;

for(j = 0; j < modules.length; j++) {

Lib.pushUnique(setPositionsArray, modules[j].setPositions);

}

if(setPositionsArray.length) {

for(i = 0; i < subplots.length; i++) {

subplotInfo = fullLayout._plots[subplots[i]];

for(j = 0; j < setPositionsArray.length; j++) {

setPositionsArray[j](gd, subplotInfo);

}

}

}

// calc and autorange for errorbars

ErrorBars.calc(gd);

// TODO: autosize extra for text markers and images

// see https://github.com/plotly/plotly.js/issues/1111

return Lib.syncOrAsync([

Registry.getComponentMethod('shapes', 'calcAutorange'),

Registry.getComponentMethod('annotations', 'calcAutorange'),

doAutoRangeAndConstraints,

Registry.getComponentMethod('rangeslider', 'calcAutorange')

], gd);

}

function doAutoRangeAndConstraints() {

if(gd._transitioning) return;

var axList = Plotly.Axes.list(gd, '', true);

for(var i = 0; i < axList.length; i++) {

var ax = axList[i];

cleanAxisConstraints(gd, ax);

Plotly.Axes.doAutoRange(ax);

}

enforceAxisConstraints(gd);

// store initial ranges *after* enforcing constraints, otherwise

// we will never look like we're at the initial ranges

if(graphWasEmpty) Plotly.Axes.saveRangeInitial(gd);

}

// draw ticks, titles, and calculate axis scaling (._b, ._m)

function drawAxes() {

return Plotly.Axes.doTicks(gd, 'redraw');

}

// Now plot the data

function drawData() {

var calcdata = gd.calcdata,

i,

rangesliderContainers = fullLayout._infolayer.selectAll('g.rangeslider-container');

// in case of traces that were heatmaps or contour maps

// previously, remove them and their colorbars explicitly

for(i = 0; i < calcdata.length; i++) {

var trace = calcdata[i][0].trace,

isVisible = (trace.visible === true),

uid = trace.uid;

if(!isVisible || !Registry.traceIs(trace, '2dMap')) {

var query = (

'.hm' + uid +

',.contour' + uid +

',#clip' + uid

);

fullLayout._paper

.selectAll(query)

.remove();

rangesliderContainers

.selectAll(query)

.remove();

}

if(!isVisible || !trace._module.colorbar) {

fullLayout._infolayer.selectAll('.cb' + uid).remove();

}

}

// loop over the base plot modules present on graph

var basePlotModules = fullLayout._basePlotModules;

for(i = 0; i < basePlotModules.length; i++) {

basePlotModules[i].plot(gd);

}

// keep reference to shape layers in subplots

var layerSubplot = fullLayout._paper.selectAll('.layer-subplot');

fullLayout._shapeSubplotLayers = layerSubplot.selectAll('.shapelayer');

// styling separate from drawing

Plots.style(gd);

// show annotations and shapes

Registry.getComponentMethod('shapes', 'draw')(gd);

Registry.getComponentMethod('annotations', 'draw')(gd);

// source links

Plots.addLinks(gd);

// Mark the first render as complete

fullLayout._replotting = false;

return Plots.previousPromises(gd);

}

// An initial paint must be completed before these components can be

// correctly sized and the whole plot re-margined. fullLayout._replotting must

// be set to false before these will work properly.

function finalDraw() {

Registry.getComponentMethod('shapes', 'draw')(gd);

Registry.getComponentMethod('images', 'draw')(gd);

Registry.getComponentMethod('annotations', 'draw')(gd);

Registry.getComponentMethod('legend', 'draw')(gd);

Registry.getComponentMethod('rangeslider', 'draw')(gd);

Registry.getComponentMethod('rangeselector', 'draw')(gd);

Registry.getComponentMethod('sliders', 'draw')(gd);

Registry.getComponentMethod('updatemenus', 'draw')(gd);

}

var seq = [

Plots.previousPromises,

addFrames,

drawFramework,

marginPushers,

marginPushersAgain,

positionAndAutorange,

subroutines.layoutStyles,

drawAxes,

drawData,

finalDraw,

initInteractions,

Plots.rehover

];

Lib.syncOrAsync(seq, gd);

// even if everything we did was synchronous, return a promise

// so that the caller doesn't care which route we took

return Promise.all(gd._promises).then(function() {

gd.emit('plotly_afterplot');

return gd;

});

};

function setBackground(gd, bgColor) {

try {

gd._fullLayout._paper.style('background', bgColor);

} catch(e) {

Lib.error(e);

}

}

function opaqueSetBackground(gd, bgColor) {

var blend = Color.combine(bgColor, 'white');

setBackground(gd, blend);

}

function setPlotContext(gd, config) {

if(!gd._context) gd._context = Lib.extendDeep({}, Plotly.defaultConfig);

var context = gd._context;

var i, keys, key;

if(config) {

keys = Object.keys(config);

for(i = 0; i < keys.length; i++) {

key = keys[i];

if(key === 'editable' || key === 'edits') continue;

if(key in context) {

if(key === 'setBackground' && config[key] === 'opaque') {

context[key] = opaqueSetBackground;

} else {

context[key] = config[key];

}

}

}

// map plot3dPixelRatio to plotGlPixelRatio for backward compatibility

if(config.plot3dPixelRatio && !context.plotGlPixelRatio) {

context.plotGlPixelRatio = context.plot3dPixelRatio;

}

// now deal with editable and edits - first editable overrides

// everything, then edits refines

var editable = config.editable;

if(editable !== undefined) {

// we're not going to *use* context.editable, we're only going to

// use context.edits... but keep it for the record

context.editable = editable;

keys = Object.keys(context.edits);

for(i = 0; i < keys.length; i++) {

context.edits[keys[i]] = editable;

}

}

if(config.edits) {

keys = Object.keys(config.edits);

for(i = 0; i < keys.length; i++) {

key = keys[i];

if(key in context.edits) {

context.edits[key] = config.edits[key];

}

}

}

}

// staticPlot forces a bunch of others:

if(context.staticPlot) {

context.editable = false;

context.edits = {};

context.autosizable = false;

context.scrollZoom = false;

context.doubleClick = false;

context.showTips = false;

context.showLink = false;

context.displayModeBar = false;

}

// make sure hover-only devices have mode bar visible

if(context.displayModeBar === 'hover' && !hasHover) {

context.displayModeBar = true;

}

// default and fallback for setBackground

if(context.setBackground === 'transparent' || typeof context.setBackground !== 'function') {

context.setBackground = setBackground;

}

}

function plotPolar(gd, data, layout) {

// build or reuse the container skeleton

var plotContainer = d3.select(gd).selectAll('.plot-container')

.data([0]);

plotContainer.enter()

.insert('div', ':first-child')

.classed('plot-container plotly', true);

var paperDiv = plotContainer.selectAll('.svg-container')

.data([0]);

paperDiv.enter().append('div')

.classed('svg-container', true)

.style('position', 'relative');

// empty it everytime for now

paperDiv.html('');

// fulfill gd requirements

if(data) gd.data = data;

if(layout) gd.layout = layout;

Polar.manager.fillLayout(gd);

// resize canvas

paperDiv.style({

width: gd._fullLayout.width + 'px',

height: gd._fullLayout.height + 'px'

});

// instantiate framework

gd.framework = Polar.manager.framework(gd);

// plot

gd.framework({data: gd.data, layout: gd.layout}, paperDiv.node());

// set undo point

gd.framework.setUndoPoint();

// get the resulting svg for extending it

var polarPlotSVG = gd.framework.svg();

// editable title

var opacity = 1;

var txt = gd._fullLayout.title;

if(txt === '' || !txt) opacity = 0;

var placeholderText = 'Click to enter title';

var titleLayout = function() {

this.call(svgTextUtils.convertToTspans, gd);

// TODO: html/mathjax

// TODO: center title

};

var title = polarPlotSVG.select('.title-group text')

.call(titleLayout);

if(gd._context.edits.titleText) {

if(!txt || txt === placeholderText) {

opacity = 0.2;

// placeholder is not going through convertToTspans

// so needs explicit data-unformatted

title.attr({'data-unformatted': placeholderText})

.text(placeholderText)

.style({opacity: opacity})

.on('mouseover.opacity', function() {

d3.select(this).transition().duration(100)

.style('opacity', 1);

})

.on('mouseout.opacity', function() {

d3.select(this).transition().duration(1000)

.style('opacity', 0);

});

}

var setContenteditable = function() {

this.call(svgTextUtils.makeEditable, {gd: gd})

.on('edit', function(text) {

gd.framework({layout: {title: text}});

this.text(text)

.call(titleLayout);

this.call(setContenteditable);

})

.on('cancel', function() {

var txt = this.attr('data-unformatted');

this.text(txt).call(titleLayout);

});

};

title.call(setContenteditable);

}

gd._context.setBackground(gd, gd._fullLayout.paper_bgcolor);

Plots.addLinks(gd);

return Promise.resolve();

}

// convenience function to force a full redraw, mostly for use by plotly.js

Plotly.redraw = function(gd) {

gd = helpers.getGraphDiv(gd);

if(!Lib.isPlotDiv(gd)) {

throw new Error('This element is not a Plotly plot: ' + gd);

}

helpers.cleanData(gd.data, gd.data);

helpers.cleanLayout(gd.layout);

gd.calcdata = undefined;

return Plotly.plot(gd).then(function() {

gd.emit('plotly_redraw');

return gd;

});

};

/**

* Convenience function to make idempotent plot option obvious to users.

*

* @param gd

* @param {Object[]} data

* @param {Object} layout

* @param {Object} config

*/

Plotly.newPlot = function(gd, data, layout, config) {

gd = helpers.getGraphDiv(gd);

// remove gl contexts

Plots.cleanPlot([], {}, gd._fullData || {}, gd._fullLayout || {});

Plots.purge(gd);

return Plotly.plot(gd, data, layout, config);

};

/**

* Wrap negative indicies to their positive counterparts.

*

* @param {Number[]} indices An array of indices

* @param {Number} maxIndex The maximum index allowable (arr.length - 1)

*/

function positivifyIndices(indices, maxIndex) {

var parentLength = maxIndex + 1,

positiveIndices = [],

i,

index;

for(i = 0; i < indices.length; i++) {

index = indices[i];

if(index < 0) {

positiveIndices.push(parentLength + index);

} else {

positiveIndices.push(index);

}

}

return positiveIndices;

}

/**

* Ensures that an index array for manipulating gd.data is valid.

*

* Intended for use with addTraces, deleteTraces, and moveTraces.

*

* @param gd

* @param indices

* @param arrayName

*/

function assertIndexArray(gd, indices, arrayName) {

var i,

index;

for(i = 0; i < indices.length; i++) {

index = indices[i];

// validate that indices are indeed integers

if(index !== parseInt(index, 10)) {

throw new Error('all values in ' + arrayName + ' must be integers');

}

// check that all indices are in bounds for given gd.data array length

if(index >= gd.data.length || index < -gd.data.length) {

throw new Error(arrayName + ' must be valid indices for gd.data.');

}

// check that indices aren't repeated

if(indices.indexOf(index, i + 1) > -1 ||

index >= 0 && indices.indexOf(-gd.data.length + index) > -1 ||

index < 0 && indices.indexOf(gd.data.length + index) > -1) {

throw new Error('each index in ' + arrayName + ' must be unique.');

}

}

}

/**

* Private function used by Plotly.moveTraces to check input args

*

* @param gd

* @param currentIndices

* @param newIndices

*/

function checkMoveTracesArgs(gd, currentIndices, newIndices) {

// check that gd has attribute 'data' and 'data' is array

if(!Array.isArray(gd.data)) {

throw new Error('gd.data must be an array.');

}

// validate currentIndices array

if(typeof currentIndices === 'undefined') {

throw new Error('currentIndices is a required argument.');

} else if(!Array.isArray(currentIndices)) {

currentIndices = [currentIndices];

}

assertIndexArray(gd, currentIndices, 'currentIndices');

// validate newIndices array if it exists

if(typeof newIndices !== 'undefined' && !Array.isArray(newIndices)) {

newIndices = [newIndices];

}

if(typeof newIndices !== 'undefined') {

assertIndexArray(gd, newIndices, 'newIndices');

}

// check currentIndices and newIndices are the same length if newIdices exists

if(typeof newIndices !== 'undefined' && currentIndices.length !== newIndices.length) {

throw new Error('current and new indices must be of equal length.');

}

}

/**

* A private function to reduce the type checking clutter in addTraces.

*

* @param gd

* @param traces

* @param newIndices

*/

function checkAddTracesArgs(gd, traces, newIndices) {

var i, value;

// check that gd has attribute 'data' and 'data' is array

if(!Array.isArray(gd.data)) {

throw new Error('gd.data must be an array.');

}

// make sure traces exists

if(typeof traces === 'undefined') {

throw new Error('traces must be defined.');

}

// make sure traces is an array

if(!Array.isArray(traces)) {

traces = [traces];

}

// make sure each value in traces is an object

for(i = 0; i < traces.length; i++) {

value = traces[i];

if(typeof value !== 'object' || (Array.isArray(value) || value === null)) {

throw new Error('all values in traces array must be non-array objects');

}

}

// make sure we have an index for each trace

if(typeof newIndices !== 'undefined' && !Array.isArray(newIndices)) {

newIndices = [newIndices];

}

if(typeof newIndices !== 'undefined' && newIndices.length !== traces.length) {

throw new Error(

'if indices is specified, traces.length must equal indices.length'

);

}

}

/**

* A private function to reduce the type checking clutter in spliceTraces.

* Get all update Properties from gd.data. Validate inputs and outputs.

* Used by prependTrace and extendTraces

*

* @param gd

* @param update

* @param indices

* @param maxPoints

*/

function assertExtendTracesArgs(gd, update, indices, maxPoints) {

var maxPointsIsObject = Lib.isPlainObject(maxPoints);

if(!Array.isArray(gd.data)) {

throw new Error('gd.data must be an array');

}

if(!Lib.isPlainObject(update)) {

throw new Error('update must be a key:value object');

}

if(typeof indices === 'undefined') {

throw new Error('indices must be an integer or array of integers');

}

assertIndexArray(gd, indices, 'indices');

for(var key in update) {

/*

* Verify that the attribute to be updated contains as many trace updates

* as indices. Failure must result in throw and no-op

*/

if(!Array.isArray(update[key]) || update[key].length !== indices.length) {

throw new Error('attribute ' + key + ' must be an array of length equal to indices array length');

}

/*

* if maxPoints is an object it must match keys and array lengths of 'update' 1:1

*/

if(maxPointsIsObject &&

(!(key in maxPoints) || !Array.isArray(maxPoints[key]) ||

maxPoints[key].length !== update[key].length)) {

throw new Error('when maxPoints is set as a key:value object it must contain a 1:1 ' +

'corrispondence with the keys and number of traces in the update object');

}

}

}

/**

* A private function to reduce the type checking clutter in spliceTraces.

*

* @param {Object|HTMLDivElement} gd

* @param {Object} update

* @param {Number[]} indices

* @param {Number||Object} maxPoints

* @return {Object[]}

*/

function getExtendProperties(gd, update, indices, maxPoints) {

var maxPointsIsObject = Lib.isPlainObject(maxPoints),

updateProps = [];

var trace, target, prop, insert, maxp;

// allow scalar index to represent a single trace position

if(!Array.isArray(indices)) indices = [indices];

// negative indices are wrapped around to their positive value. Equivalent to python indexing.

indices = positivifyIndices(indices, gd.data.length - 1);

// loop through all update keys and traces and harvest validated data.

for(var key in update) {

for(var j = 0; j < indices.length; j++) {

/*

* Choose the trace indexed by the indices map argument and get the prop setter-getter

* instance that references the key and value for this particular trace.

*/

trace = gd.data[indices[j]];

prop = Lib.nestedProperty(trace, key);

/*

* Target is the existing gd.data.trace.dataArray value like "x" or "marker.size"

* Target must exist as an Array to allow the extend operation to be performed.

*/

target = prop.get();

insert = update[key][j];

if(!Array.isArray(insert)) {

throw new Error('attribute: ' + key + ' index: ' + j + ' must be an array');

}

if(!Array.isArray(target)) {

throw new Error('cannot extend missing or non-array attribute: ' + key);

}

/*

* maxPoints may be an object map or a scalar. If object select the key:value, else

* Use the scalar maxPoints for all key and trace combinations.

*/

maxp = maxPointsIsObject ? maxPoints[key][j] : maxPoints;

// could have chosen null here, -1 just tells us to not take a window

if(!isNumeric(maxp)) maxp = -1;

/*

* Wrap the nestedProperty in an object containing required data

* for lengthening and windowing this particular trace - key combination.

* Flooring maxp mirrors the behaviour of floats in the Array.slice JSnative function.

*/

updateProps.push({

prop: prop,

target: target,

insert: insert,

maxp: Math.floor(maxp)

});

}

}

// all target and insertion data now validated

return updateProps;

}

/**

* A private function to key Extend and Prepend traces DRY

*

* @param {Object|HTMLDivElement} gd

* @param {Object} update

* @param {Number[]} indices

* @param {Number||Object} maxPoints

* @param {Function} lengthenArray

* @param {Function} spliceArray

* @return {Object}

*/

function spliceTraces(gd, update, indices, maxPoints, lengthenArray, spliceArray) {

assertExtendTracesArgs(gd, update, indices, maxPoints);

var updateProps = getExtendProperties(gd, update, indices, maxPoints),

remainder = [],

undoUpdate = {},

undoPoints = {};

var target, prop, maxp;

for(var i = 0; i < updateProps.length; i++) {

/*

* prop is the object returned by Lib.nestedProperties

*/

prop = updateProps[i].prop;

maxp = updateProps[i].maxp;

target = lengthenArray(updateProps[i].target, updateProps[i].insert);

/*

* If maxp is set within post-extension trace.length, splice to maxp length.

* Otherwise skip function call as splice op will have no effect anyway.

*/

if(maxp >= 0 && maxp < target.length) remainder = spliceArray(target, maxp);

/*

* to reverse this operation we need the size of the original trace as the reverse

* operation will need to window out any lengthening operation performed in this pass.

*/

maxp = updateProps[i].target.length;

/*

* Magic happens here! update gd.data.trace[key] with new array data.

*/

prop.set(target);

if(!Array.isArray(undoUpdate[prop.astr])) undoUpdate[prop.astr] = [];

if(!Array.isArray(undoPoints[prop.astr])) undoPoints[prop.astr] = [];

/*

* build the inverse update object for the undo operation

*/

undoUpdate[prop.astr].push(remainder);

/*

* build the matching maxPoints undo object containing original trace lengths.

*/

undoPoints[prop.astr].push(maxp);

}

return {update: undoUpdate, maxPoints: undoPoints};

}

/**

* extend && prepend traces at indices with update arrays, window trace lengths to maxPoints

*

* Extend and Prepend have identical APIs. Prepend inserts an array at the head while Extend

* inserts an array off the tail. Prepend truncates the tail of the array - counting maxPoints

* from the head, whereas Extend truncates the head of the array, counting backward maxPoints

* from the tail.

*

* If maxPoints is undefined, nonNumeric, negative or greater than extended trace length no

* truncation / windowing will be performed. If its zero, well the whole trace is truncated.

*

* @param {Object|HTMLDivElement} gd The graph div

* @param {Object} update The key:array map of target attributes to extend

* @param {Number|Number[]} indices The locations of traces to be extended

* @param {Number|Object} [maxPoints] Number of points for trace window after lengthening.

*

*/

Plotly.extendTraces = function extendTraces(gd, update, indices, maxPoints) {

gd = helpers.getGraphDiv(gd);

var undo = spliceTraces(gd, update, indices, maxPoints,

/*

* The Lengthen operation extends trace from end with insert

*/

function(target, insert) {

return target.concat(insert);

},

/*

* Window the trace keeping maxPoints, counting back from the end

*/

function(target, maxPoints) {

return target.splice(0, target.length - maxPoints);

});

var promise = Plotly.redraw(gd);

var undoArgs = [gd, undo.update, indices, undo.maxPoints];

Queue.add(gd, Plotly.prependTraces, undoArgs, extendTraces, arguments);

return promise;

};

Plotly.prependTraces = function prependTraces(gd, update, indices, maxPoints) {

gd = helpers.getGraphDiv(gd);

var undo = spliceTraces(gd, update, indices, maxPoints,

/*

* The Lengthen operation extends trace by appending insert to start

*/

function(target, insert) {

return insert.concat(target);

},

/*

* Window the trace keeping maxPoints, counting forward from the start

*/

function(target, maxPoints) {