X-Git-Url: https://adrianiainlam.tk/git/?a=blobdiff_plain;f=dygraph-utils.js;h=992242d15d2a72b9b6e3c0a8e706f14353d9c636;hb=b1e9e2e03dbccf94fff08ab37dc6e8c64c75736d;hp=7cb50198ebab6c8540560625956e796f592a734b;hpb=48e614acf3084b9836803f8b014bf0e65f1ca119;p=dygraphs.git diff --git a/dygraph-utils.js b/dygraph-utils.js index 7cb5019..992242d 100644 --- a/dygraph-utils.js +++ b/dygraph-utils.js @@ -1,5 +1,8 @@ -// Copyright 2011 Dan Vanderkam (danvdk@gmail.com) -// All Rights Reserved. +/** + * @license + * Copyright 2011 Dan Vanderkam (danvdk@gmail.com) + * MIT-licensed (http://opensource.org/licenses/MIT) + */ /** * @fileoverview This file contains utility functions used by dygraphs. These @@ -8,69 +11,31 @@ * search) and generic DOM-manipulation functions. */ -Dygraph.LOG_SCALE = 10; -Dygraph.LN_TEN = Math.log(Dygraph.LOG_SCALE); +(function() { -/** @private */ -Dygraph.log10 = function(x) { - return Math.log(x) / Dygraph.LN_TEN; -} +/*global Dygraph:false, Node:false */ +"use strict"; -// Various logging levels. -Dygraph.DEBUG = 1; -Dygraph.INFO = 2; -Dygraph.WARNING = 3; -Dygraph.ERROR = 3; +Dygraph.LOG_SCALE = 10; +Dygraph.LN_TEN = Math.log(Dygraph.LOG_SCALE); -// TODO(danvk): any way I can get the line numbers to be this.warn call? /** * @private - * Log an error on the JS console at the given severity. - * @param { Integer } severity One of Dygraph.{DEBUG,INFO,WARNING,ERROR} - * @param { String } The message to log. - */ -Dygraph.log = function(severity, message) { - if (typeof(console) != 'undefined') { - switch (severity) { - case Dygraph.DEBUG: - console.debug('dygraphs: ' + message); - break; - case Dygraph.INFO: - console.info('dygraphs: ' + message); - break; - case Dygraph.WARNING: - console.warn('dygraphs: ' + message); - break; - case Dygraph.ERROR: - console.error('dygraphs: ' + message); - break; - } - } -}; - -/** @private */ -Dygraph.info = function(message) { - Dygraph.log(Dygraph.INFO, message); -}; -/** @private */ -Dygraph.prototype.info = Dygraph.info; - -/** @private */ -Dygraph.warn = function(message) { - Dygraph.log(Dygraph.WARNING, message); + * @param {number} x + * @return {number} + */ +Dygraph.log10 = function(x) { + return Math.log(x) / Dygraph.LN_TEN; }; -/** @private */ -Dygraph.prototype.warn = Dygraph.warn; -/** @private */ -Dygraph.error = function(message) { - Dygraph.log(Dygraph.ERROR, message); -}; -/** @private */ -Dygraph.prototype.error = Dygraph.error; +/** A dotted line stroke pattern. */ +Dygraph.DOTTED_LINE = [2, 2]; +/** A dashed line stroke pattern. */ +Dygraph.DASHED_LINE = [7, 3]; +/** A dot dash stroke pattern. */ +Dygraph.DOT_DASH_LINE = [7, 2, 2, 2]; /** - * @private * Return the 2d context for a dygraph canvas. * * This method is only exposed for the sake of replacing the function in @@ -81,39 +46,71 @@ Dygraph.prototype.error = Dygraph.error; * var realContext = oldFunc(canvas); * return new Proxy(realContext); * }; + * @param {!HTMLCanvasElement} canvas + * @return {!CanvasRenderingContext2D} + * @private */ Dygraph.getContext = function(canvas) { - return canvas.getContext("2d"); + return /** @type{!CanvasRenderingContext2D}*/(canvas.getContext("2d")); }; /** + * Add an event handler. + * @param {!Node} elem The element to add the event to. + * @param {string} type The type of the event, e.g. 'click' or 'mousemove'. + * @param {function(Event):(boolean|undefined)} fn The function to call + * on the event. The function takes one parameter: the event object. * @private - * Add an event handler. This smooths a difference between IE and the rest of - * the world. - * @param { DOM element } el The element to add the event to. - * @param { String } evt The name of the event, e.g. 'click' or 'mousemove'. - * @param { Function } fn The function to call on the event. The function takes - * one parameter: the event object. - */ -Dygraph.addEvent = function(el, evt, fn) { - var normed_fn = function(e) { - if (!e) var e = window.event; - fn(e); - }; - if (window.addEventListener) { // Mozilla, Netscape, Firefox - el.addEventListener(evt, normed_fn, false); - } else { // IE - el.attachEvent('on' + evt, normed_fn); - } + */ +Dygraph.addEvent = function addEvent(elem, type, fn) { + elem.addEventListener(type, fn, false); +}; + +/** + * Add an event handler. This event handler is kept until the graph is + * destroyed with a call to graph.destroy(). + * + * @param {!Node} elem The element to add the event to. + * @param {string} type The type of the event, e.g. 'click' or 'mousemove'. + * @param {function(Event):(boolean|undefined)} fn The function to call + * on the event. The function takes one parameter: the event object. + * @private + */ +Dygraph.prototype.addAndTrackEvent = function(elem, type, fn) { + Dygraph.addEvent(elem, type, fn); + this.registeredEvents_.push({ elem : elem, type : type, fn : fn }); }; /** + * Remove an event handler. + * @param {!Node} elem The element to remove the event from. + * @param {string} type The type of the event, e.g. 'click' or 'mousemove'. + * @param {function(Event):(boolean|undefined)} fn The function to call + * on the event. The function takes one parameter: the event object. * @private + */ +Dygraph.removeEvent = function(elem, type, fn) { + elem.removeEventListener(type, fn, false); +}; + +Dygraph.prototype.removeTrackedEvents_ = function() { + if (this.registeredEvents_) { + for (var idx = 0; idx < this.registeredEvents_.length; idx++) { + var reg = this.registeredEvents_[idx]; + Dygraph.removeEvent(reg.elem, reg.type, reg.fn); + } + } + + this.registeredEvents_ = []; +}; + +/** * Cancels further processing of an event. This is useful to prevent default * browser actions, e.g. highlighting text on a double-click. * Based on the article at * http://www.switchonthecode.com/tutorials/javascript-tutorial-the-scroll-wheel - * @param { Event } e The event whose normal behavior should be canceled. + * @param {!Event} e The event whose normal behavior should be canceled. + * @private */ Dygraph.cancelEvent = function(e) { e = e ? e : window.event; @@ -133,10 +130,10 @@ Dygraph.cancelEvent = function(e) { * Convert hsv values to an rgb(r,g,b) string. Taken from MochiKit.Color. This * is used to generate default series colors which are evenly spaced on the * color wheel. - * @param { Number } hue Range is 0.0-1.0. - * @param { Number } saturation Range is 0.0-1.0. - * @param { Number } value Range is 0.0-1.0. - * @return { String } "rgb(r,g,b)" where r, g and b range from 0-255. + * @param { number } hue Range is 0.0-1.0. + * @param { number } saturation Range is 0.0-1.0. + * @param { number } value Range is 0.0-1.0. + * @return { string } "rgb(r,g,b)" where r, g and b range from 0-255. * @private */ Dygraph.hsvToRGB = function (hue, saturation, value) { @@ -175,70 +172,59 @@ Dygraph.hsvToRGB = function (hue, saturation, value) { // ... and modifications to support scrolling divs. /** - * Find the x-coordinate of the supplied object relative to the left side - * of the page. + * Find the coordinates of an object relative to the top left of the page. + * + * TODO(danvk): change obj type from Node -> !Node + * @param {Node} obj + * @return {{x:number,y:number}} * @private */ -Dygraph.findPosX = function(obj) { - var curleft = 0; - if(obj.offsetParent) { +Dygraph.findPos = function(obj) { + var curleft = 0, curtop = 0; + if (obj.offsetParent) { var copyObj = obj; - while(1) { + while (1) { + var borderLeft = "0", borderTop = "0"; + var computedStyle = window.getComputedStyle(copyObj, null); + borderLeft = computedStyle.borderLeft || "0"; + borderTop = computedStyle.borderTop || "0"; + curleft += parseInt(borderLeft, 10) ; + curtop += parseInt(borderTop, 10) ; curleft += copyObj.offsetLeft; - if(!copyObj.offsetParent) { - break; - } - copyObj = copyObj.offsetParent; - } - } else if(obj.x) { - curleft += obj.x; - } - // This handles the case where the object is inside a scrolled div. - while(obj && obj != document.body) { - curleft -= obj.scrollLeft; - obj = obj.parentNode; - } - return curleft; -}; - -/** - * Find the y-coordinate of the supplied object relative to the top of the - * page. - * @private - */ -Dygraph.findPosY = function(obj) { - var curtop = 0; - if(obj.offsetParent) { - var copyObj = obj; - while(1) { curtop += copyObj.offsetTop; - if(!copyObj.offsetParent) { + if (!copyObj.offsetParent) { break; } copyObj = copyObj.offsetParent; } - } else if(obj.y) { - curtop += obj.y; + } else { + // TODO(danvk): why would obj ever have these properties? + if (obj.x) curleft += obj.x; + if (obj.y) curtop += obj.y; } + // This handles the case where the object is inside a scrolled div. - while(obj && obj != document.body) { + while (obj && obj != document.body) { + curleft -= obj.scrollLeft; curtop -= obj.scrollTop; obj = obj.parentNode; } - return curtop; + return {x: curleft, y: curtop}; }; /** - * @private * Returns the x-coordinate of the event in a coordinate system where the * top-left corner of the page (not the window) is (0,0). * Taken from MochiKit.Signal + * @param {!Event} e + * @return {number} + * @private */ Dygraph.pageX = function(e) { if (e.pageX) { return (!e.pageX || e.pageX < 0) ? 0 : e.pageX; } else { - var de = document; + var de = document.documentElement; var b = document.body; return e.clientX + (de.scrollLeft || b.scrollLeft) - @@ -247,16 +233,18 @@ Dygraph.pageX = function(e) { }; /** - * @private * Returns the y-coordinate of the event in a coordinate system where the * top-left corner of the page (not the window) is (0,0). * Taken from MochiKit.Signal + * @param {!Event} e + * @return {number} + * @private */ Dygraph.pageY = function(e) { if (e.pageY) { return (!e.pageY || e.pageY < 0) ? 0 : e.pageY; } else { - var de = document; + var de = document.documentElement; var b = document.body; return e.clientY + (de.scrollTop || b.scrollTop) - @@ -265,13 +253,53 @@ Dygraph.pageY = function(e) { }; /** + * Converts page the x-coordinate of the event to pixel x-coordinates on the + * canvas (i.e. DOM Coords). + * @param {!Event} e Drag event. + * @param {!DygraphInteractionContext} context Interaction context object. + * @return {number} The amount by which the drag has moved to the right. + */ +Dygraph.dragGetX_ = function(e, context) { + return Dygraph.pageX(e) - context.px; +}; + +/** + * Converts page the y-coordinate of the event to pixel y-coordinates on the + * canvas (i.e. DOM Coords). + * @param {!Event} e Drag event. + * @param {!DygraphInteractionContext} context Interaction context object. + * @return {number} The amount by which the drag has moved down. + */ +Dygraph.dragGetY_ = function(e, context) { + return Dygraph.pageY(e) - context.py; +}; + +/** + * This returns true unless the parameter is 0, null, undefined or NaN. + * TODO(danvk): rename this function to something like 'isNonZeroNan'. + * + * @param {number} x The number to consider. + * @return {boolean} Whether the number is zero or NaN. * @private - * @param { Number } x The number to consider. - * @return { Boolean } Whether the number is zero or NaN. */ -// TODO(danvk): rename this function to something like 'isNonZeroNan'. Dygraph.isOK = function(x) { - return x && !isNaN(x); + return !!x && !isNaN(x); +}; + +/** + * @param {{x:?number,y:?number,yval:?number}} p The point to consider, valid + * points are {x, y} objects + * @param {boolean=} opt_allowNaNY Treat point with y=NaN as valid + * @return {boolean} Whether the point has numeric x and y. + * @private + */ +Dygraph.isValidPoint = function(p, opt_allowNaNY) { + if (!p) return false; // null or undefined object + if (p.yval === null) return false; // missing point + if (p.x === null || p.x === undefined) return false; + if (p.y === null || p.y === undefined) return false; + if (isNaN(p.x) || (!opt_allowNaNY && isNaN(p.y))) return false; + return true; }; /** @@ -287,9 +315,9 @@ Dygraph.isOK = function(x) { * 10^-6, e.g. '0.00001' instead of '1e-5'. See tests/number-format.html for * output examples. * - * @param {Number} x The number to format - * @param {Number} opt_precision The precision to use, default 2. - * @return {String} A string formatted like %g in printf. The max generated + * @param {number} x The number to format + * @param {number=} opt_precision The precision to use, default 2. + * @return {string} A string formatted like %g in printf. The max generated * string length should be precision + 6 (e.g 1.123e+300). */ Dygraph.floatFormat = function(x, opt_precision) { @@ -312,41 +340,112 @@ Dygraph.floatFormat = function(x, opt_precision) { // // Finally, the argument for toExponential() is the number of trailing digits, // so we take off 1 for the value before the '.'. - return (Math.abs(x) < 1.0e-3 && x != 0.0) ? + return (Math.abs(x) < 1.0e-3 && x !== 0.0) ? x.toExponential(p - 1) : x.toPrecision(p); }; /** - * @private * Converts '9' to '09' (useful for dates) + * @param {number} x + * @return {string} + * @private */ Dygraph.zeropad = function(x) { if (x < 10) return "0" + x; else return "" + x; }; /** + * Date accessors to get the parts of a calendar date (year, month, + * day, hour, minute, second and millisecond) according to local time, + * and factory method to call the Date constructor with an array of arguments. + */ +Dygraph.DateAccessorsLocal = { + getFullYear: function(d) {return d.getFullYear();}, + getMonth: function(d) {return d.getMonth();}, + getDate: function(d) {return d.getDate();}, + getHours: function(d) {return d.getHours();}, + getMinutes: function(d) {return d.getMinutes();}, + getSeconds: function(d) {return d.getSeconds();}, + getMilliseconds: function(d) {return d.getMilliseconds();}, + getDay: function(d) {return d.getDay();}, + makeDate: function(y, m, d, hh, mm, ss, ms) { + return new Date(y, m, d, hh, mm, ss, ms); + } +}; + +/** + * Date accessors to get the parts of a calendar date (year, month, + * day of month, hour, minute, second and millisecond) according to UTC time, + * and factory method to call the Date constructor with an array of arguments. + */ +Dygraph.DateAccessorsUTC = { + getFullYear: function(d) {return d.getUTCFullYear();}, + getMonth: function(d) {return d.getUTCMonth();}, + getDate: function(d) {return d.getUTCDate();}, + getHours: function(d) {return d.getUTCHours();}, + getMinutes: function(d) {return d.getUTCMinutes();}, + getSeconds: function(d) {return d.getUTCSeconds();}, + getMilliseconds: function(d) {return d.getUTCMilliseconds();}, + getDay: function(d) {return d.getUTCDay();}, + makeDate: function(y, m, d, hh, mm, ss, ms) { + return new Date(Date.UTC(y, m, d, hh, mm, ss, ms)); + } +}; + +/** * Return a string version of the hours, minutes and seconds portion of a date. - * @param {Number} date The JavaScript date (ms since epoch) - * @return {String} A time of the form "HH:MM:SS" + * @param {number} hh The hours (from 0-23) + * @param {number} mm The minutes (from 0-59) + * @param {number} ss The seconds (from 0-59) + * @return {string} A time of the form "HH:MM" or "HH:MM:SS" * @private */ -Dygraph.hmsString_ = function(date) { +Dygraph.hmsString_ = function(hh, mm, ss) { var zeropad = Dygraph.zeropad; - var d = new Date(date); - if (d.getSeconds()) { - return zeropad(d.getHours()) + ":" + - zeropad(d.getMinutes()) + ":" + - zeropad(d.getSeconds()); - } else { - return zeropad(d.getHours()) + ":" + zeropad(d.getMinutes()); + var ret = zeropad(hh) + ":" + zeropad(mm); + if (ss) { + ret += ":" + zeropad(ss); + } + return ret; +}; + +/** + * Convert a JS date (millis since epoch) to a formatted string. + * @param {number} time The JavaScript time value (ms since epoch) + * @param {boolean} utc Wether output UTC or local time + * @return {string} A date of one of these forms: + * "YYYY/MM/DD", "YYYY/MM/DD HH:MM" or "YYYY/MM/DD HH:MM:SS" + * @private + */ +Dygraph.dateString_ = function(time, utc) { + var zeropad = Dygraph.zeropad; + var accessors = utc ? Dygraph.DateAccessorsUTC : Dygraph.DateAccessorsLocal; + var date = new Date(time); + var y = accessors.getFullYear(date); + var m = accessors.getMonth(date); + var d = accessors.getDate(date); + var hh = accessors.getHours(date); + var mm = accessors.getMinutes(date); + var ss = accessors.getSeconds(date); + // Get a year string: + var year = "" + y; + // Get a 0 padded month string + var month = zeropad(m + 1); //months are 0-offset, sigh + // Get a 0 padded day string + var day = zeropad(d); + var frac = hh * 3600 + mm * 60 + ss; + var ret = year + "/" + month + "/" + day; + if (frac) { + ret += " " + Dygraph.hmsString_(hh, mm, ss); } + return ret; }; /** * Round a number to the specified number of digits past the decimal point. - * @param {Number} num The number to round - * @param {Number} places The number of decimals to which to round - * @return {Number} The rounded number + * @param {number} num The number to round + * @param {number} places The number of decimals to which to round + * @return {number} The rounded number * @private */ Dygraph.round_ = function(num, places) { @@ -355,69 +454,85 @@ Dygraph.round_ = function(num, places) { }; /** - * @private * Implementation of binary search over an array. * Currently does not work when val is outside the range of arry's values. - * @param { Integer } val the value to search for - * @param { Integer[] } arry is the value over which to search - * @param { Integer } abs If abs > 0, find the lowest entry greater than val - * If abs < 0, find the highest entry less than val. - * if abs == 0, find the entry that equals val. - * @param { Integer } [low] The first index in arry to consider (optional) - * @param { Integer } [high] The last index in arry to consider (optional) + * @param {number} val the value to search for + * @param {Array.} arry is the value over which to search + * @param {number} abs If abs > 0, find the lowest entry greater than val + * If abs < 0, find the highest entry less than val. + * If abs == 0, find the entry that equals val. + * @param {number=} low The first index in arry to consider (optional) + * @param {number=} high The last index in arry to consider (optional) + * @return {number} Index of the element, or -1 if it isn't found. + * @private */ Dygraph.binarySearch = function(val, arry, abs, low, high) { - if (low == null || high == null) { + if (low === null || low === undefined || + high === null || high === undefined) { low = 0; high = arry.length - 1; } if (low > high) { return -1; } - if (abs == null) { + if (abs === null || abs === undefined) { abs = 0; } var validIndex = function(idx) { return idx >= 0 && idx < arry.length; - } - var mid = parseInt((low + high) / 2); + }; + var mid = parseInt((low + high) / 2, 10); var element = arry[mid]; + var idx; if (element == val) { return mid; - } - if (element > val) { + } else if (element > val) { if (abs > 0) { // Accept if element > val, but also if prior element < val. - var idx = mid - 1; + idx = mid - 1; if (validIndex(idx) && arry[idx] < val) { return mid; } } return Dygraph.binarySearch(val, arry, abs, low, mid - 1); - } - if (element < val) { + } else if (element < val) { if (abs < 0) { // Accept if element < val, but also if prior element > val. - var idx = mid + 1; + idx = mid + 1; if (validIndex(idx) && arry[idx] > val) { return mid; } } return Dygraph.binarySearch(val, arry, abs, mid + 1, high); } + return -1; // can't actually happen, but makes closure compiler happy }; /** - * @private * Parses a date, returning the number of milliseconds since epoch. This can be * passed in as an xValueParser in the Dygraph constructor. * TODO(danvk): enumerate formats that this understands. - * @param {String} A date in YYYYMMDD format. - * @return {Number} Milliseconds since epoch. + * + * @param {string} dateStr A date in a variety of possible string formats. + * @return {number} Milliseconds since epoch. + * @private */ Dygraph.dateParser = function(dateStr) { var dateStrSlashed; var d; + + // Let the system try the format first, with one caveat: + // YYYY-MM-DD[ HH:MM:SS] is interpreted as UTC by a variety of browsers. + // dygraphs displays dates in local time, so this will result in surprising + // inconsistencies. But if you specify "T" or "Z" (i.e. YYYY-MM-DDTHH:MM:SS), + // then you probably know what you're doing, so we'll let you go ahead. + // Issue: http://code.google.com/p/dygraphs/issues/detail?id=255 + if (dateStr.search("-") == -1 || + dateStr.search("T") != -1 || dateStr.search("Z") != -1) { + d = Dygraph.dateStrToMillis(dateStr); + if (d && !isNaN(d)) return d; + } + if (dateStr.search("-") != -1) { // e.g. '2009-7-12' or '2009-07-12' dateStrSlashed = dateStr.replace("-", "/", "g"); while (dateStrSlashed.search("-") != -1) { @@ -426,8 +541,8 @@ Dygraph.dateParser = function(dateStr) { d = Dygraph.dateStrToMillis(dateStrSlashed); } else if (dateStr.length == 8) { // e.g. '20090712' // TODO(danvk): remove support for this format. It's confusing. - dateStrSlashed = dateStr.substr(0,4) + "/" + dateStr.substr(4,2) - + "/" + dateStr.substr(6,2); + dateStrSlashed = dateStr.substr(0,4) + "/" + dateStr.substr(4,2) + "/" + + dateStr.substr(6,2); d = Dygraph.dateStrToMillis(dateStrSlashed); } else { // Any format that Date.parse will accept, e.g. "2009/07/12" or @@ -436,18 +551,18 @@ Dygraph.dateParser = function(dateStr) { } if (!d || isNaN(d)) { - Dygraph.error("Couldn't parse " + dateStr + " as a date"); + console.error("Couldn't parse " + dateStr + " as a date"); } return d; }; /** - * @private * This is identical to JavaScript's built-in Date.parse() method, except that * it doesn't get replaced with an incompatible method by aggressive JS * libraries like MooTools or Joomla. - * @param { String } str The date string, e.g. "2011/05/06" - * @return { Integer } millis since epoch + * @param {string} str The date string, e.g. "2011/05/06" + * @return {number} millis since epoch + * @private */ Dygraph.dateStrToMillis = function(str) { return new Date(str).getTime(); @@ -457,9 +572,11 @@ Dygraph.dateStrToMillis = function(str) { /** * Copies all the properties from o to self. * - * @private + * @param {!Object} self + * @param {!Object} o + * @return {!Object} */ -Dygraph.update = function (self, o) { +Dygraph.update = function(self, o) { if (typeof(o) != 'undefined' && o !== null) { for (var k in o) { if (o.hasOwnProperty(k)) { @@ -473,18 +590,32 @@ Dygraph.update = function (self, o) { /** * Copies all the properties from o to self. * + * @param {!Object} self + * @param {!Object} o + * @return {!Object} * @private */ Dygraph.updateDeep = function (self, o) { + // Taken from http://stackoverflow.com/questions/384286/javascript-isdom-how-do-you-check-if-a-javascript-object-is-a-dom-object + function isNode(o) { + return ( + typeof Node === "object" ? o instanceof Node : + typeof o === "object" && typeof o.nodeType === "number" && typeof o.nodeName==="string" + ); + } + if (typeof(o) != 'undefined' && o !== null) { for (var k in o) { if (o.hasOwnProperty(k)) { - if (o[k] == null) { + if (o[k] === null) { self[k] = null; } else if (Dygraph.isArrayLike(o[k])) { self[k] = o[k].slice(); + } else if (isNode(o[k])) { + // DOM objects are shallowly-copied. + self[k] = o[k]; } else if (typeof(o[k]) == 'object') { - if (typeof(self[k]) != 'object') { + if (typeof(self[k]) != 'object' || self[k] === null) { self[k] = {}; } Dygraph.updateDeep(self[k], o[k]); @@ -498,9 +629,11 @@ Dygraph.updateDeep = function (self, o) { }; /** + * @param {*} o + * @return {boolean} * @private */ -Dygraph.isArrayLike = function (o) { +Dygraph.isArrayLike = function(o) { var typ = typeof(o); if ( (typ != 'object' && !(typ == 'function' && @@ -515,6 +648,8 @@ Dygraph.isArrayLike = function (o) { }; /** + * @param {Object} o + * @return {boolean} * @private */ Dygraph.isDateLike = function (o) { @@ -527,6 +662,8 @@ Dygraph.isDateLike = function (o) { /** * Note: this only seems to work for arrays. + * @param {!Array} o + * @return {!Array} * @private */ Dygraph.clone = function(o) { @@ -543,86 +680,249 @@ Dygraph.clone = function(o) { }; /** + * Create a new canvas element. + * + * @return {!HTMLCanvasElement} * @private - * Create a new canvas element. This is more complex than a simple - * document.createElement("canvas") because of IE and excanvas. */ Dygraph.createCanvas = function() { - var canvas = document.createElement("canvas"); + return document.createElement('canvas'); +}; + +/** + * Returns the context's pixel ratio, which is the ratio between the device + * pixel ratio and the backing store ratio. Typically this is 1 for conventional + * displays, and > 1 for HiDPI displays (such as the Retina MBP). + * See http://www.html5rocks.com/en/tutorials/canvas/hidpi/ for more details. + * + * @param {!CanvasRenderingContext2D} context The canvas's 2d context. + * @return {number} The ratio of the device pixel ratio and the backing store + * ratio for the specified context. + */ +Dygraph.getContextPixelRatio = function(context) { + try { + var devicePixelRatio = window.devicePixelRatio; + var backingStoreRatio = context.webkitBackingStorePixelRatio || + context.mozBackingStorePixelRatio || + context.msBackingStorePixelRatio || + context.oBackingStorePixelRatio || + context.backingStorePixelRatio || 1; + if (devicePixelRatio !== undefined) { + return devicePixelRatio / backingStoreRatio; + } else { + // At least devicePixelRatio must be defined for this ratio to make sense. + // We default backingStoreRatio to 1: this does not exist on some browsers + // (i.e. desktop Chrome). + return 1; + } + } catch (e) { + return 1; + } +}; + +/** + * Checks whether the user is on an Android browser. + * Android does not fully support the tag, e.g. w/r/t/ clipping. + * @return {boolean} + * @private + */ +Dygraph.isAndroid = function() { + return (/Android/).test(navigator.userAgent); +}; - isIE = (/MSIE/.test(navigator.userAgent) && !window.opera); - if (isIE && (typeof(G_vmlCanvasManager) != 'undefined')) { - canvas = G_vmlCanvasManager.initElement(canvas); + +/** + * TODO(danvk): use @template here when it's better supported for classes. + * @param {!Array} array + * @param {number} start + * @param {number} length + * @param {function(!Array,?):boolean=} predicate + * @constructor + */ +Dygraph.Iterator = function(array, start, length, predicate) { + start = start || 0; + length = length || array.length; + this.hasNext = true; // Use to identify if there's another element. + this.peek = null; // Use for look-ahead + this.start_ = start; + this.array_ = array; + this.predicate_ = predicate; + this.end_ = Math.min(array.length, start + length); + this.nextIdx_ = start - 1; // use -1 so initial advance works. + this.next(); // ignoring result. +}; + +/** + * @return {Object} + */ +Dygraph.Iterator.prototype.next = function() { + if (!this.hasNext) { + return null; } + var obj = this.peek; - return canvas; + var nextIdx = this.nextIdx_ + 1; + var found = false; + while (nextIdx < this.end_) { + if (!this.predicate_ || this.predicate_(this.array_, nextIdx)) { + this.peek = this.array_[nextIdx]; + found = true; + break; + } + nextIdx++; + } + this.nextIdx_ = nextIdx; + if (!found) { + this.hasNext = false; + this.peek = null; + } + return obj; }; /** + * Returns a new iterator over array, between indexes start and + * start + length, and only returns entries that pass the accept function + * + * @param {!Array} array the array to iterate over. + * @param {number} start the first index to iterate over, 0 if absent. + * @param {number} length the number of elements in the array to iterate over. + * This, along with start, defines a slice of the array, and so length + * doesn't imply the number of elements in the iterator when accept doesn't + * always accept all values. array.length when absent. + * @param {function(?):boolean=} opt_predicate a function that takes + * parameters array and idx, which returns true when the element should be + * returned. If omitted, all elements are accepted. * @private + */ +Dygraph.createIterator = function(array, start, length, opt_predicate) { + return new Dygraph.Iterator(array, start, length, opt_predicate); +}; + +// Shim layer with setTimeout fallback. +// From: http://paulirish.com/2011/requestanimationframe-for-smart-animating/ +// Should be called with the window context: +// Dygraph.requestAnimFrame.call(window, function() {}) +Dygraph.requestAnimFrame = (function() { + return window.requestAnimationFrame || + window.webkitRequestAnimationFrame || + window.mozRequestAnimationFrame || + window.oRequestAnimationFrame || + window.msRequestAnimationFrame || + function (callback) { + window.setTimeout(callback, 1000 / 60); + }; +})(); + +/** + * Call a function at most maxFrames times at an attempted interval of + * framePeriodInMillis, then call a cleanup function once. repeatFn is called + * once immediately, then at most (maxFrames - 1) times asynchronously. If + * maxFrames==1, then cleanup_fn() is also called synchronously. This function + * is used to sequence animation. + * @param {function(number)} repeatFn Called repeatedly -- takes the frame + * number (from 0 to maxFrames-1) as an argument. + * @param {number} maxFrames The max number of times to call repeatFn + * @param {number} framePeriodInMillis Max requested time between frames. + * @param {function()} cleanupFn A function to call after all repeatFn calls. + * @private + */ +Dygraph.repeatAndCleanup = function(repeatFn, maxFrames, framePeriodInMillis, + cleanupFn) { + var frameNumber = 0; + var previousFrameNumber; + var startTime = new Date().getTime(); + repeatFn(frameNumber); + if (maxFrames == 1) { + cleanupFn(); + return; + } + var maxFrameArg = maxFrames - 1; + + (function loop() { + if (frameNumber >= maxFrames) return; + Dygraph.requestAnimFrame.call(window, function() { + // Determine which frame to draw based on the delay so far. Will skip + // frames if necessary. + var currentTime = new Date().getTime(); + var delayInMillis = currentTime - startTime; + previousFrameNumber = frameNumber; + frameNumber = Math.floor(delayInMillis / framePeriodInMillis); + var frameDelta = frameNumber - previousFrameNumber; + // If we predict that the subsequent repeatFn call will overshoot our + // total frame target, so our last call will cause a stutter, then jump to + // the last call immediately. If we're going to cause a stutter, better + // to do it faster than slower. + var predictOvershootStutter = (frameNumber + frameDelta) > maxFrameArg; + if (predictOvershootStutter || (frameNumber >= maxFrameArg)) { + repeatFn(maxFrameArg); // Ensure final call with maxFrameArg. + cleanupFn(); + } else { + if (frameDelta !== 0) { // Don't call repeatFn with duplicate frames. + repeatFn(frameNumber); + } + loop(); + } + }); + })(); +}; + +// A whitelist of options that do not change pixel positions. +var pixelSafeOptions = { + 'annotationClickHandler': true, + 'annotationDblClickHandler': true, + 'annotationMouseOutHandler': true, + 'annotationMouseOverHandler': true, + 'axisLabelColor': true, + 'axisLineColor': true, + 'axisLineWidth': true, + 'clickCallback': true, + 'drawCallback': true, + 'drawHighlightPointCallback': true, + 'drawPoints': true, + 'drawPointCallback': true, + 'drawGrid': true, + 'fillAlpha': true, + 'gridLineColor': true, + 'gridLineWidth': true, + 'hideOverlayOnMouseOut': true, + 'highlightCallback': true, + 'highlightCircleSize': true, + 'interactionModel': true, + 'isZoomedIgnoreProgrammaticZoom': true, + 'labelsDiv': true, + 'labelsDivStyles': true, + 'labelsDivWidth': true, + 'labelsKMB': true, + 'labelsKMG2': true, + 'labelsSeparateLines': true, + 'labelsShowZeroValues': true, + 'legend': true, + 'panEdgeFraction': true, + 'pixelsPerYLabel': true, + 'pointClickCallback': true, + 'pointSize': true, + 'rangeSelectorPlotFillColor': true, + 'rangeSelectorPlotStrokeColor': true, + 'showLabelsOnHighlight': true, + 'showRoller': true, + 'strokeWidth': true, + 'underlayCallback': true, + 'unhighlightCallback': true, + 'zoomCallback': true +}; + +/** * This function will scan the option list and determine if they * require us to recalculate the pixel positions of each point. - * @param { List } a list of options to check. - * @return { Boolean } true if the graph needs new points else false. + * TODO: move this into dygraph-options.js + * @param {!Array.} labels a list of options to check. + * @param {!Object} attrs + * @return {boolean} true if the graph needs new points else false. + * @private */ Dygraph.isPixelChangingOptionList = function(labels, attrs) { - // A whitelist of options that do not change pixel positions. - var pixelSafeOptions = { - 'annotationClickHandler': true, - 'annotationDblClickHandler': true, - 'annotationMouseOutHandler': true, - 'annotationMouseOverHandler': true, - 'axisLabelColor': true, - 'axisLineColor': true, - 'axisLineWidth': true, - 'clickCallback': true, - 'colorSaturation': true, - 'colorValue': true, - 'colors': true, - 'connectSeparatedPoints': true, - 'digitsAfterDecimal': true, - 'drawCallback': true, - 'drawPoints': true, - 'drawXGrid': true, - 'drawYGrid': true, - 'fillAlpha': true, - 'gridLineColor': true, - 'gridLineWidth': true, - 'hideOverlayOnMouseOut': true, - 'highlightCallback': true, - 'highlightCircleSize': true, - 'interactionModel': true, - 'isZoomedIgnoreProgrammaticZoom': true, - 'labelsDiv': true, - 'labelsDivStyles': true, - 'labelsDivWidth': true, - 'labelsKMB': true, - 'labelsKMG2': true, - 'labelsSeparateLines': true, - 'labelsShowZeroValues': true, - 'legend': true, - 'maxNumberWidth': true, - 'panEdgeFraction': true, - 'pixelsPerYLabel': true, - 'pointClickCallback': true, - 'pointSize': true, - 'showLabelsOnHighlight': true, - 'showRoller': true, - 'sigFigs': true, - 'strokeWidth': true, - 'underlayCallback': true, - 'unhighlightCallback': true, - 'xAxisLabelFormatter': true, - 'xTicker': true, - 'xValueFormatter': true, - 'yAxisLabelFormatter': true, - 'yValueFormatter': true, - 'zoomCallback': true - }; - // Assume that we do not require new points. // This will change to true if we actually do need new points. - var requiresNewPoints = false; // Create a dictionary of series names for faster lookup. // If there are no labels, then the dictionary stays empty. @@ -633,32 +933,246 @@ Dygraph.isPixelChangingOptionList = function(labels, attrs) { } } - // Iterate through the list of updated options. - for (property in attrs) { - // Break early if we already know we need new points from a previous option. - if (requiresNewPoints) { - break; + // Scan through a flat (i.e. non-nested) object of options. + // Returns true/false depending on whether new points are needed. + var scanFlatOptions = function(options) { + for (var property in options) { + if (options.hasOwnProperty(property) && + !pixelSafeOptions[property]) { + return true; + } } - if (attrs.hasOwnProperty(property)) { - // Find out of this field is actually a series specific options list. - if (seriesNamesDictionary[property]) { - // This property value is a list of options for this series. - // If any of these sub properties are not pixel safe, set the flag. - for (subProperty in attrs[property]) { - // Break early if we already know we need new points from a previous option. - if (requiresNewPoints) { - break; - } - if (attrs[property].hasOwnProperty(subProperty) && !pixelSafeOptions[subProperty]) { - requiresNewPoints = true; - } + return false; + }; + + // Iterate through the list of updated options. + for (var property in attrs) { + if (!attrs.hasOwnProperty(property)) continue; + + // Find out of this field is actually a series specific options list. + if (property == 'highlightSeriesOpts' || + (seriesNamesDictionary[property] && !attrs.series)) { + // This property value is a list of options for this series. + if (scanFlatOptions(attrs[property])) return true; + } else if (property == 'series' || property == 'axes') { + // This is twice-nested options list. + var perSeries = attrs[property]; + for (var series in perSeries) { + if (perSeries.hasOwnProperty(series) && + scanFlatOptions(perSeries[series])) { + return true; } - // If this was not a series specific option list, check if its a pixel changing property. - } else if (!pixelSafeOptions[property]) { - requiresNewPoints = true; - } + } + } else { + // If this was not a series specific option list, check if it's a pixel + // changing property. + if (!pixelSafeOptions[property]) return true; } } - return requiresNewPoints; + return false; }; + +Dygraph.Circles = { + DEFAULT : function(g, name, ctx, canvasx, canvasy, color, radius) { + ctx.beginPath(); + ctx.fillStyle = color; + ctx.arc(canvasx, canvasy, radius, 0, 2 * Math.PI, false); + ctx.fill(); + } + // For more shapes, include extras/shapes.js +}; + +/** + * To create a "drag" interaction, you typically register a mousedown event + * handler on the element where the drag begins. In that handler, you register a + * mouseup handler on the window to determine when the mouse is released, + * wherever that release happens. This works well, except when the user releases + * the mouse over an off-domain iframe. In that case, the mouseup event is + * handled by the iframe and never bubbles up to the window handler. + * + * To deal with this issue, we cover iframes with high z-index divs to make sure + * they don't capture mouseup. + * + * Usage: + * element.addEventListener('mousedown', function() { + * var tarper = new Dygraph.IFrameTarp(); + * tarper.cover(); + * var mouseUpHandler = function() { + * ... + * window.removeEventListener(mouseUpHandler); + * tarper.uncover(); + * }; + * window.addEventListener('mouseup', mouseUpHandler); + * }; + * + * @constructor + */ +Dygraph.IFrameTarp = function() { + /** @type {Array.} */ + this.tarps = []; +}; + +/** + * Find all the iframes in the document and cover them with high z-index + * transparent divs. + */ +Dygraph.IFrameTarp.prototype.cover = function() { + var iframes = document.getElementsByTagName("iframe"); + for (var i = 0; i < iframes.length; i++) { + var iframe = iframes[i]; + var pos = Dygraph.findPos(iframe), + x = pos.x, + y = pos.y, + width = iframe.offsetWidth, + height = iframe.offsetHeight; + + var div = document.createElement("div"); + div.style.position = "absolute"; + div.style.left = x + 'px'; + div.style.top = y + 'px'; + div.style.width = width + 'px'; + div.style.height = height + 'px'; + div.style.zIndex = 999; + document.body.appendChild(div); + this.tarps.push(div); + } +}; + +/** + * Remove all the iframe covers. You should call this in a mouseup handler. + */ +Dygraph.IFrameTarp.prototype.uncover = function() { + for (var i = 0; i < this.tarps.length; i++) { + this.tarps[i].parentNode.removeChild(this.tarps[i]); + } + this.tarps = []; +}; + +/** + * Determine whether |data| is delimited by CR, CRLF, LF, LFCR. + * @param {string} data + * @return {?string} the delimiter that was detected (or null on failure). + */ +Dygraph.detectLineDelimiter = function(data) { + for (var i = 0; i < data.length; i++) { + var code = data.charAt(i); + if (code === '\r') { + // Might actually be "\r\n". + if (((i + 1) < data.length) && (data.charAt(i + 1) === '\n')) { + return '\r\n'; + } + return code; + } + if (code === '\n') { + // Might actually be "\n\r". + if (((i + 1) < data.length) && (data.charAt(i + 1) === '\r')) { + return '\n\r'; + } + return code; + } + } + + return null; +}; + +/** + * Is one node contained by another? + * @param {Node} containee The contained node. + * @param {Node} container The container node. + * @return {boolean} Whether containee is inside (or equal to) container. + * @private + */ +Dygraph.isNodeContainedBy = function(containee, container) { + if (container === null || containee === null) { + return false; + } + var containeeNode = /** @type {Node} */ (containee); + while (containeeNode && containeeNode !== container) { + containeeNode = containeeNode.parentNode; + } + return (containeeNode === container); +}; + + +// This masks some numeric issues in older versions of Firefox, +// where 1.0/Math.pow(10,2) != Math.pow(10,-2). +/** @type {function(number,number):number} */ +Dygraph.pow = function(base, exp) { + if (exp < 0) { + return 1.0 / Math.pow(base, -exp); + } + return Math.pow(base, exp); +}; + +/** + * Converts any valid CSS color (hex, rgb(), named color) to an RGB tuple. + * + * @param {!string} colorStr Any valid CSS color string. + * @return {{r:number,g:number,b:number}} Parsed RGB tuple. + * @private + */ +Dygraph.toRGB_ = function(colorStr) { + // TODO(danvk): cache color parses to avoid repeated DOM manipulation. + var div = document.createElement('div'); + div.style.backgroundColor = colorStr; + div.style.visibility = 'hidden'; + document.body.appendChild(div); + var rgbStr = window.getComputedStyle(div, null).backgroundColor; + document.body.removeChild(div); + var bits = /^rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)$/.exec(rgbStr); + return { + r: parseInt(bits[1], 10), + g: parseInt(bits[2], 10), + b: parseInt(bits[3], 10) + }; +}; + +/** + * Checks whether the browser supports the <canvas> tag. + * @param {HTMLCanvasElement=} opt_canvasElement Pass a canvas element as an + * optimization if you have one. + * @return {boolean} Whether the browser supports canvas. + */ +Dygraph.isCanvasSupported = function(opt_canvasElement) { + try { + var canvas = opt_canvasElement || document.createElement("canvas"); + canvas.getContext("2d"); + } catch (e) { + return false; + } + return true; +}; + +/** + * Parses the value as a floating point number. This is like the parseFloat() + * built-in, but with a few differences: + * - the empty string is parsed as null, rather than NaN. + * - if the string cannot be parsed at all, an error is logged. + * If the string can't be parsed, this method returns null. + * @param {string} x The string to be parsed + * @param {number=} opt_line_no The line number from which the string comes. + * @param {string=} opt_line The text of the line from which the string comes. + */ +Dygraph.parseFloat_ = function(x, opt_line_no, opt_line) { + var val = parseFloat(x); + if (!isNaN(val)) return val; + + // Try to figure out what happeend. + // If the value is the empty string, parse it as null. + if (/^ *$/.test(x)) return null; + + // If it was actually "NaN", return it as NaN. + if (/^ *nan *$/i.test(x)) return NaN; + + // Looks like a parsing error. + var msg = "Unable to parse '" + x + "' as a number"; + if (opt_line !== undefined && opt_line_no !== undefined) { + msg += " on line " + (1+(opt_line_no||0)) + " ('" + opt_line + "') of CSV."; + } + console.error(msg); + + return null; +}; + +})();