Move selection support to a plugin (based on patch from andershol),

move color code to separate jQuery plugin inlined in the Flot code
(and hosted here for the time being), fixup some various other little
things in preparation for the 0.6 release


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

API.txt

@@ -665,39 +665,6 @@ can set "hoverable" and "clickable" to false in the options for that
 series, like this { data: [...], label: "Foo", clickable: false }.
 
 
-Customizing the selection
-=========================
-
-  selection: {
-    mode: null or "x" or "y" or "xy",
-    color: color
-  }
-
-You enable selection support by setting the mode to one of "x", "y" or
-"xy". In "x" mode, the user will only be able to specify the x range,
-similarly for "y" mode. For "xy", the selection becomes a rectangle
-where both ranges can be specified. "color" is color of the selection.
-
-When selection support is enabled, a "plotselected" event will be emitted
-on the DOM element you passed into the plot function. The event
-handler gets one extra parameter with the ranges selected on the axes,
-like this:
-
-  placeholder.bind("plotselected", function(event, ranges) {
-    alert("You selected " + ranges.xaxis.from + " to " + ranges.xaxis.to)
-    // similar for yaxis, secondary axes are in x2axis
-    // and y2axis if present
-  });
-
-The "plotselected" event is only fired when the user has finished
-making the selection. A "plotselecting" event is fired during the
-process with the same parameters as the "plotselected" event, in case
-you want to know what's happening while it's happening,
-
-A "plotunselected" event with no arguments is emitted when the user
-clicks the mouse to remove the selection.
-
-
 Specifying gradients
 ====================
 
@@ -739,34 +706,6 @@ Plot Methods
 The Plot object returned from the plot function has some methods you
 can call:
 
-  - 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
-    mode is "x", you should put in either an xaxis (or x2axis) object,
-    if the mode is "y" you need to put in an yaxis (or y2axis) object
-    and both xaxis/x2axis and yaxis/y2axis if the selection mode is
-    "xy", like this:
-
-      setSelection({ xaxis: { from: 0, to: 10 }, yaxis: { from: 40, to: 60 } });
-
-    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.
-
-    
-  - clearSelection(preventEvent)
-
-    Clear the selection rectangle. Pass in true to avoid getting a
-    "plotunselected" event.
-
-  - getSelection()
-
-    Returns the current selection in the same format as the
-    "plotselected" event. If there's currently no selection, it
-    returns null.
-    
-
   - highlight(series, datapoint)
 
     Highlight a specific datapoint in the data series. You can either
@@ -815,7 +754,7 @@ can call:
   - triggerRedrawOverlay()
 
     Schedules an update of an overlay canvas used for drawing
-    interactive things like the selection and point highlights. This
+    interactive things like a selection and point highlights. This
     is mostly useful for writing plugins. The redraw doesn't happen
     immediately, instead a timer is set to catch multiple successive
     redraws (e.g. from a mousemove).

NEWS.txt

-Flot 0.x
+Flot 0.6
 --------
 
 API changes:
 
-1. In the global options specified in the $.plot command,
+1. Selection support has been moved to a plugin. Thus if you're
+passing selection: { mode: something }, you MUST include the file
+jquery.flot.selection.js after jquery.flot.js. This reduces the size
+of base Flot and makes it easier to customize the selection as well as
+improving code clarity. The change is based on patch from andershol.
+
+2. In the global options specified in the $.plot command,
 "lines", "points", "bars" and "shadowSize" have been moved to a
 sub-object called "series", i.e.
 
   $.plot(placeholder, data, { lines: { show: true }})
 
-becomes
+should be changed to
 
   $.plot(placeholder, data, { series: { lines: { show: true }}})
 
 All future series-specific options will go into this sub-object to
-simplify plugin writing. Backward-compatibility hooks are in place,
-so old code should not break.
+simplify plugin writing. Backward-compatibility code is in place, so
+old code should not break.
 
-2. "plothover" no longer provides the original data point, but instead
+3. "plothover" no longer provides the original data point, but instead
 a normalized one, since there may be no corresponding original point.
 
-3. Due to a bug in previous versions of jQuery, you now need at least
+4. Due to a bug in previous versions of jQuery, you now need at least
 jQuery 1.2.6. But if you can, try jQuery 1.3.2 as it got some
 improvements in event handling speed.
 
@@ -85,9 +91,9 @@ Changes:
   offset within the placeholder.
   
 - Plugin system: register an init method in the $.flot.plugins array
-  to get started, see PLUGINS.txt for details on how to write plugins.
-  There are also some extra methods to enable access to internal
-  state.
+  to get started, see PLUGINS.txt for details on how to write plugins
+  (it's easy). There are also some extra methods to enable access to
+  internal state.
 
 - Hooks: you can register functions that are called while Flot is
   crunching the data and doing the plot. This can be used to modify
@@ -116,6 +122,11 @@ Changes:
 
 - Support for twelve-hour date formatting (patch by Forrest Aldridge).
 
+- The color parsing code in Flot has been cleaned up and split out so
+  it's now available as a separate jQuery plugin. It's included inline
+  in the Flot source to make dependency managing easier. This also
+  makes it really easy to use the color helpers in Flot plugins.
+
 Bug fixes:
 
 - Fixed two corner-case bugs when drawing filled curves (report and
@@ -130,7 +141,7 @@ Bug fixes:
   problem reported by Sergio Nunes).
 - Updated mousemove position expression to the latest from jQuery (bug
   reported by meyuchas).
-- Use borders instead of background in legend (fix printing issue 25
+- Use CSS borders instead of background in legend (fix printing issue 25
   and 45).
 - Explicitly convert axis min/max to numbers.
 - Fixed a bug with drawing marking lines with different colors

examples/basic.html

@@ -21,6 +21,10 @@
 
 <script id="source" language="javascript" type="text/javascript">
 $(function () {
+    var c = 0;
+    
+    function plot() {
+        ++c;
         var d1 = [];
         for (var i = 0; i < 14; i += 0.5)
             d1.push([i, Math.sin(i)]);
@@ -31,6 +35,14 @@ $(function () {
         var d3 = [[0, 12], [7, 12], null, [7, 2.5], [12, 2.5]];
 
         $.plot($("#placeholder"), [ d1, d2, d3 ]);
+    
+        $("p").text("" +c);
+    
+        if (c < 1000)
+            setTimeout(plot, 10);
+    }
+
+    plot();
 });
 </script>
 

examples/dual-axis.html

@@ -28,7 +28,8 @@ $(function () {
     $.plot($("#placeholder"),
            [ { data: oilprices, label: "Oil price ($)" },
              { data: exchangerates, label: "USD/EUR exchange rate", yaxis: 2 }],
-           { xaxis: { mode: 'time' },
+           { 
+             xaxis: { mode: 'time' },
              yaxis: { min: 0 },
              y2axis: { tickFormatter: function (v, axis) { return v.toFixed(axis.tickDecimals) +"€" }},
              legend: { position: 'sw' } });

examples/index.html

@@ -11,7 +11,7 @@
  <body>
     <h1>Flot Examples</h1>
 
-    <p>Here are some examples for <a href="http://code.google.com/p/flot/">Flot</a>:</p>
+    <p>Here are some examples for <a href="http://code.google.com/p/flot/">Flot</a>, the Javascript charting library for jQuery:</p>
 
     <ul>
       <li><a href="basic.html">Basic example</a></li>
@@ -24,20 +24,20 @@
     
     <ul>
       <li><a href="turning-series.html">Turning series on/off</a></li>
-      <li><a href="selection.html">Selection support and zooming</a> and <a href="zooming.html">zooming with overview</a></li>
+      <li><a href="selection.html">Rectangular selection support and zooming</a> and <a href="zooming.html">zooming with overview</a></li> (both with selection plugin)
       <li><a href="interacting.html">Interacting with the data points</a></li>
-      <li><a href="navigate.html">Panning and zooming</a> (with plugin)</li>
+      <li><a href="navigate.html">Panning and zooming</a> (with navigation plugin)</li>
     </ul>
 
     <p>Some more esoteric features:</p>
     
     <ul>
-      <li><a href="time.html">Plotting time series</a> and <a href="visitors.html">visitors per day with zooming and weekends</a></li>
+      <li><a href="time.html">Plotting time series</a> and <a href="visitors.html">visitors per day with zooming and weekends</a> (with selection plugin)</li>
       <li><a href="dual-axis.html">Dual axis support</a></li>
-      <li><a href="thresholding.html">Thresholding the data</a> (with plugin)</li>
-      <li><a href="stacking.html">Stacked charts</a> (with plugin)</li>
-      <li><a href="tracking.html">Tracking curves with crosshair</a> (with plugin)</li>
-      <li><a href="image.html">Plotting prerendered images</a> (with plugin)</li>
+      <li><a href="thresholding.html">Thresholding the data</a> (with threshold plugin)</li>
+      <li><a href="stacking.html">Stacked charts</a> (with stacking plugin)</li>
+      <li><a href="tracking.html">Tracking curves with crosshair</a> (with crosshair plugin)</li>
+      <li><a href="image.html">Plotting prerendered images</a> (with image plugin)</li>
     </ul>
  </body>
 </html>

examples/interacting.html

@@ -38,7 +38,6 @@ $(function () {
                    lines: { show: true },
                    points: { show: true }
                },
-               selection: { mode: "xy" },
                grid: { hoverable: true, clickable: true },
                yaxis: { min: -1.2, max: 1.2 }
              });

examples/selection.html

@@ -7,6 +7,7 @@
     <!--[if IE]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
     <script language="javascript" type="text/javascript" src="../jquery.js"></script>
     <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.selection.js"></script>
  </head>
     <body>
     <h1>Flot Examples</h1>
@@ -15,23 +16,23 @@
 
     <p>1000 kg. CO<sub>2</sub> emissions per year per capita for various countries (source: <a href="http://en.wikipedia.org/wiki/List_of_countries_by_carbon_dioxide_emissions_per_capita">Wikipedia</a>).</p>
 
-    <p>Flot supports selections. You can enable
-       rectangular selection
+    <p>Flot supports selections through the selection plugin.
+       You can enable rectangular selection
        or one-dimensional selection if the user should only be able to
-       select on one axis. Try left-clicking and drag on the plot above
+       select on one axis. Try left-click and drag on the plot above
        where selection on the x axis is enabled.</p>
 
     <p>You selected: <span id="selection"></span></p>
 
-    <p>The plot command returns a Plot object you can use to control
-       the selection. Try clicking the buttons below.</p>
+    <p>The plot command returns a plot object you can use to control
+       the selection. Click the buttons below.</p>
 
     <p><input id="clearSelection" type="button" value="Clear selection" />
        <input id="setSelection" type="button" value="Select year 1994" /></p>
 
     <p>Selections are really useful for zooming. Just replot the
        chart with min and max values for the axes set to the values
-       in the "plotselected" event triggered. Try enabling the checkbox
+       in the "plotselected" event triggered. Enable the checkbox
        below and select a region again.</p>
 
     <p><input id="zoom" type="checkbox">Zoom to selection.</input></p>

examples/visitors.html

@@ -7,6 +7,7 @@
     <!--[if IE]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
     <script language="javascript" type="text/javascript" src="../jquery.js"></script>
     <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.selection.js"></script>
  </head>
     <body>
     <h1>Flot Examples</h1>

examples/zooming.html

@@ -7,6 +7,7 @@
     <!--[if IE]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
     <script language="javascript" type="text/javascript" src="../jquery.js"></script>
     <script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
+    <script language="javascript" type="text/javascript" src="../jquery.flot.selection.js"></script>
  </head>
     <body>
     <h1>Flot Examples</h1>

jquery.flot.crosshair.js

@@ -102,16 +102,18 @@ The plugin also adds four public methods:
             });
             
             eventHolder.mousemove(function (e) {
-                if (!plot.getSelection()) {
-                    if (!crosshair.locked) {
+                if (plot.getSelection && plot.getSelection()) {
+                    crosshair.x = -1; // hide the crosshair while selecting
+                    return;
+                }
+                
+                if (crosshair.locked)
+                    return;
+                
                 var offset = plot.offset();
                 crosshair.x = Math.max(0, Math.min(e.pageX - offset.left, plot.width()));
                 crosshair.y = Math.max(0, Math.min(e.pageY - offset.top, plot.height()));
                 plot.triggerRedrawOverlay();
-                    }
-                }
-                else
-                    crosshair.x = -1; // hide the crosshair while selecting
             });
         });