Plot.Grid upgrades, Closest-Point methods, and Interaction upgrades

Good afternoon,

This release features an improved Plot.Grid, a method for retrieving the closest PlotData from a Plot, a new Interaction, and an upgrade to Dispatcher.Mouse.

Features

The new Plot.Grid built on Plot.Rectangle

Plot.Rectangle is a new type of plot that draws rectangles given values for x1/x2 and y1/y2. We are going to be gradually migrating all rectangle-based plots to this; in the meantime, there probably won't be a need for you to use Plot.Rectangle directly unless you're doing some really crazy stuff (and if you are, we would love to hear about it!)

Plot.Grid has been rearchitected to leverage Plot.Rectangle. As a consequence, Plot.Grid can now be used on both Category and Quantitative Scales. Plot.Grid is initialized with an xScale, a yScale, and a colorScale. Projections on Plot.Grid from various scales are as follows

• Scale.Category - In order to project data onto a GridPlot using a Scale.Category, we need to project the x/y attribute on the xScale/yScale.
• Quantitative Scales - In order to project data onto a GridPlot using a Quantitative Scale (could include Scale.Time, Scale.Linear, Scale.ModifiedLog), you have to project the lower bound as x/y and the upper bound as x2/y2.

Existing instances of Plot.Grid should continue to work with no modification needed; this feature simply added more functionality to the existing API points.

Examples of Plot.Grid with (1) a Scale.Time on the X-axis and a Scale.Linear on the Y-axis and (2) a Scale.Time on the X-axis and a Scale.Category on the Y-axis can be found at the following link: http://jsfiddle.net/L861y4s1/1/

getClosestPlotData() on Plots

Similar to how Plots have a getAllPlotData API, there is now a getClosestPlotData() API on Plots. The signature is

public getClosestPlotData(queryPoint: Point, withinDistance = Infinity, datasetKeys: string | string[] = this.datasetOrder())

As seen from the signature above, getClosestPlotData takes in a Point to find the PlotData closest to that point within the withinDistance for all Datasets listed in datasetKeys.

The calculation is done by looping through each of the pixelPoints from getAllPlotData(), finding the closest point, and reporting the appropriate selection / data information under the given circumstances.

This method treats all Plots as though their data values are represented by a single point (because it uses the pixelPoint property of the PlotData for computing distance); for example, it does not take the shape of the bars into account when finding the closest PlotData on Plot.Bar. getAllPlotData() can be used to implement alternative closest-point algorithms, in conjunction with generateProjectors() to account for additional shape information.

Interaction.Pointer

Interaction.Pointer has been added. This Interaction triggers callbacks when the user mouses into a Component, moves the mouse within the Component, or mouses out of the Component. Example usage:

var pointerInteraction = new Plottable.Interaction.Pointer();
pointerInteraction.onPointerMove(function(p) {
  // do something with the point p, maybe call getClosestPlotData()
});
pointerInteraction.onPointerExit(function(p) {
  // some code that cleans up
});
plot.registerInteraction(pointerInteraction);

onWheel() API on Dispatcher.Mouse

The onWheel() method has been added Dispatcher.Mouse. This method can be used to register callbacks to be called when the scroll-wheel on the mouse is activated. The signature is

public onWheel(key: any, callback: MouseCallback): Dispatcher.Mouse

Wheel data can be retrieved from the Event passed to the MouseCallback.

Bugfixes

• Plot.Line used to return one <line> selection per datum in its PlotData, even though the line represents the entire Dataset. Now it returns only one <line> selection per Dataset.