Support for preventing event in setSelection and revamped coloredAreas as...

Support for preventing event in setSelection and revamped coloredAreas as markings with support for lines

git-svn-id: https://flot.googlecode.com/svn/trunk@91 1e0a6537-2640-0410-bfb7-f154510ff394

API.txt

@@ -454,8 +454,7 @@ Customizing the grid
     backgroundColor: color or null
     tickColor: color
     labelMargin: number
-    coloredAreas: array of areas or (fn: plot area -> array of areas)
-    coloredAreasColor: color
+    markings: array of markings or (fn: axes -> array of markings)
     borderWidth: number
     clickable: boolean
     hoverable: boolean
@@ -477,28 +476,37 @@ labels with CSS, e.g. to change the color. They have class "tickLabel".
 "borderWidth" is the width of the border around the plot. Set it to 0
 to disable the border.
 
-"coloredAreas" is an array of areas that will be drawn on top of the
-background. You can either specify an array of objects with { x1, y1,
-x2, y2 } or a function that returns such an array given the plot area
-as { xmin, xmax, ymin, ymax }. The default color of the areas are
-"coloredAreasColor". You can override the color of individual areas by
-specifying "color" in the area object.
+"markings" is used to draw simple lines and rectangular areas in the
+background of the plot. You can either specify an array of ranges on
+the form { xaxis: { from, to }, yaxis: { from, to } } (secondary axis
+coordinates with x2axis/y2axis) or with a function that returns such
+an array given the axes for the plot in an object as the first
+parameter.
 
-Here's an example array:
+You can set the color of markings by specifying "color" in the ranges
+object. Here's an example array:
 
-  coloredAreas: [ { x1: 0, y1: 10, x2: 2, y2: 15, color: "#bb0000" }, ... ]
+  markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]
 
 If you leave out one of the values, that value is assumed to go to the
-border of the plot. So for example { x1: 0, x2: 2 } means an area that
-extends from the top to the bottom of the plot in the x range 0-2.
+border of the plot. So for example if you only specify { xaxis: {
+from: 0, to: 2 } } it means an area that extends from the top to the
+bottom of the plot in the x range 0-2.
+
+A line is drawn if from and to are the same, e.g.
+
+  markings: [ { yaxis: { from: 1, to: 1 } }, ... ]
+
+would draw a line parallel to the x axis at y = 1. You can control the
+line width with "lineWidth" in the ranges objects.
 
 An example function might look like this:
 
-  coloredAreas: function (plotarea) {
-    var areas = [];
-    for (var x = Math.floor(plotarea.xmin); x < plotarea.xmax; x += 2)
-      areas.push({ x1: x, x2: x + 1 });
-    return areas;
+  markings: function (axes) {
+    var markings = [];
+    for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)
+      markings.push({ xaxis: { from: x, to: x + 1 } });
+    return markings;
   }
 
 
@@ -595,7 +603,7 @@ can call:
     Clear the selection rectangle.
 
 
-  - setSelection(ranges)
+  - setSelection(ranges, preventEvent)
 
     Set the selection rectangle. The passed in ranges is on the same
     form as returned in the "plotselected" event. If the selection
@@ -606,10 +614,10 @@ can call:
 
       setSelection({ xaxis: { from: 0, to: 10 }, yaxis: { from: 40, to: 60 } });
 
-    setSelection will trigger the "plotselected" event when called so you
-    may have to do a bit of shortcircuiting to prevent an eternal loop
-    if you invoke setSelection inside a "plotselected" handler.
-
+    setSelection will trigger the "plotselected" event when called. If
+    you don't want that to happen, e.g. if you're inside a
+    "plotselected" handler, pass true as the second parameter.
+    
 
   - highlight(series, datapoint)
 

NEWS.txt

@@ -4,7 +4,8 @@ Flot x.x
 Backwards API change summary: Timestamps are now in UTC. Also
 "selected" event -> becomes "plotselected" with new data, the
 parameters for setSelection are now different (but backwards
-compatibility hooks are in place).
+compatibility hooks are in place), coloredAreas becomes markings with
+a new interface (but backwards compatibility hooks are in place).
 
 
 Interactivity: added a new "plothover" event and this and the
@@ -19,9 +20,10 @@ Support for dual axis has been added (based on patch by someone who's
 annoyed and /david). For each data series you can specify which axes
 it belongs to, and there are two more axes, x2axis and y2axis, to
 customize. This affects the "selected" event which has been renamed to
-"plotselected" and spews out { xaxis: { from: -10, to: 20 } ... } and
+"plotselected" and spews out { xaxis: { from: -10, to: 20 } ... },
 setSelection in which the parameters are on a new form (backwards
-compatible hooks are in place so old code shouldn't break).
+compatible hooks are in place so old code shouldn't break) and
+markings (formerly coloredAreas).
 
 Timestamps in time mode are now displayed according to
 UTC instead of the time zone of the visitor. This affects the way the
@@ -35,6 +37,11 @@ Added support for specifying the size of tick labels (axis.labelWidth,
 axis.labelHeight). Useful for specifying a max label size to keep
 multiple plots aligned.
 
+Markings, previously coloredAreas, are now specified as ranges on the
+axes, like { xaxis: { from: 0, to: 10 }}. Furthermore you can now draw
+horizontal/vertical lines by setting from and to to the same
+coordinate (idea from line support patch by by Ryan Funduk).
+
 The "fill" option can now be a number that specifies the opacity of
 the fill.
 
@@ -45,6 +52,9 @@ will take the other coordinate into account when scaling the axes
 New option for bars "align". Set it to "center" to center the bars on
 the value they represent.
 
+setSelection now takes a second parameter which you can use to prevent
+the method from firing the "plotselected" handler. 
+
 Using the "container" option in legend now overwrites the container
 element instead of just appending to it (fixes infinite legend bug,
 reported by several people, fix by Brad Dewey).

examples/visitors.html

@@ -29,9 +29,9 @@ $(function () {
       d[i][0] += 60 * 60 * 1000;
 
     // helper for returning the weekends in a period
-    function weekendAreas(plotarea) {
-        var areas = [];
-        var d = new Date(plotarea.xmin);
+    function weekendAreas(axes) {
+        var markings = [];
+        var d = new Date(axes.xaxis.min);
         // go to the first Saturday
         d.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 1) % 7))
         d.setUTCSeconds(0);
@@ -39,19 +39,19 @@ $(function () {
         d.setUTCHours(0);
         var i = d.getTime();
         do {
-            // when we don't set y1 and y2 the rectangle
-            // automatically extends to infinity in those directions
-            areas.push({ x1: i, x2: i + 2 * 24 * 60 * 60 * 1000 });
+            // when we don't set yaxis the rectangle automatically
+            // extends to infinity upwards and downwards
+            markings.push({ xaxis: { from: i, to: i + 2 * 24 * 60 * 60 * 1000 } });
             i += 7 * 24 * 60 * 60 * 1000;
-        } while (i < plotarea.xmax);
+        } while (i < axes.xaxis.max);
 
-        return areas;
+        return markings;
     }
     
     var options = {
         xaxis: { mode: "time" },
         selection: { mode: "x" },
-        grid: { coloredAreas: weekendAreas }
+        grid: { markings: weekendAreas }
     };
     
     var plot = $.plot($("#placeholder"), [d], options);
@@ -65,7 +65,6 @@ $(function () {
     });
 
     // now connect the two
-    var internalSelection = false;
     
     $("#placeholder").bind("plotselected", function (event, ranges) {
         // do the zooming
@@ -73,20 +72,13 @@ $(function () {
                       $.extend(true, {}, options, {
                           xaxis: { min: ranges.xaxis.from, max: ranges.xaxis.to }
                       }));
-        
-        if (internalSelection)
-            return; // prevent eternal loop
-        internalSelection = true;
-        overview.setSelection(ranges);
-        internalSelection = false;
+
+        // don't fire event on the overview to prevent eternal loop
+        overview.setSelection(ranges, true);
     });
     
     $("#overview").bind("plotselected", function (event, ranges) {
-        if (internalSelection)
-            return;
-        internalSelection = true;
         plot.setSelection(ranges);
-        internalSelection = false;
     });
 });
 </script>

examples/zooming.html

@@ -63,7 +63,6 @@ $(function () {
     });
 
     // now connect the two
-    var internalSelection = false;
     
     $("#placeholder").bind("plotselected", function (event, ranges) {
         // clamp the zooming to prevent eternal zoom
@@ -79,18 +78,11 @@ $(function () {
                           yaxis: { min: ranges.yaxis.from, max: ranges.yaxis.to }
                       }));
         
-        if (internalSelection)
-            return; // prevent eternal loop
-        internalSelection = true;
-        overview.setSelection(ranges);
-        internalSelection = false;
+        // don't fire event on the overview to prevent eternal loop
+        overview.setSelection(ranges, true);
     });
     $("#overview").bind("plotselected", function (event, ranges) {
-        if (internalSelection)
-            return;
-        internalSelection = true;
         plot.setSelection(ranges);
-        internalSelection = false;
     });
 });
 </script>