As I mentioned in my last post, I have begun a project using the Flare data visualization toolkit, and I intend to document things I learn along the way. One of the first things I investigated, after familiarizing myself with the basics was how customizable the grids and axes for visualizations could be. It took me longer than I expected to figure things out, but now that I have I would say the grids and axes in Flare are highly customizable, and should be capable of accommodating just about any needs you may have.
This post is mostly code and images, but in case you want to jump around here is a table of contents.
- Background info
- Base code and a basic grid Controlling grid bounds
- Customizing grids and axes
- Useful methods
Background info
Before we dive in to the examples, I need to cover a tiny bit of background information and establish some constants we’ll be using. First, all of the examples will be using this simple data source:
[as]
// source data
private var arr:Array = [
{ x: 2, y: 2 },
{ x: 4, y: 4 },
{ x: 6, y: 6 }
];
[/as]
As you can see, its just an array containing 3 elements who each have an x and y property. Next, we’ll look at a bare bones plot chart built with Flare. The following is essentially the bare minimum of code required to create a visualization in Flare. The default visualization is a plot chart using circular shape renderers, which is fine for our purposes here. We’ll be using this code as a basis for the code added/demonstrated through the rest of the post, but I won’t be repeating it all every time. Lastly, remember that Flare visualizations are really just Sprites, which means they cannot be added directly to Flex containers, only to DisplayObjectContainers, which is also Sprite’s super class. UIComponent, and therefore most every Flex component, are in fact descendants of Sprite, meaning you can add Sprites to UIComponents. For more information on Flash Player’s core display classes, see this page.
Base code and a basic grid
[as]
// visualization (Flare’s core element)
// use Flare’s Data class to convert
// our Array into a format it can use
vis = new Visualization( Data.fromArray( arr ) );
// fill the UIComponent that will be our parent
// this is a Flex app, so assume uic looks like this
//
vis.bounds = new Rectangle( 0, 0, uic.width, uic.height );
// create an axis layout (Cartesian chart)
// instruct the layout/grid to use the x and y properties
// of our data elements for plotting
var axisLayout:AxisLayout = new AxisLayout( “data.x”, “data.y” );
// add it to the visualization’s operators collection
// (operators will be discussed in a future post)
vis.operators.add( axisLayout );
// update the vis
// (make it process and apply any pending changes)
vis.update();
// add it to the display list as a child of our UIComponent
uic.addChild( vis );
[/as]
This code produces the following visualization:
As you can see, the grid bounds are dynamically created based on the data being shown. This would be very convenient if that is what we wanted, but in my case it was not.
Controlling grid bounds
If we’d like the chart’s minimum values to always be zero, we can use the zeroBased property of the xScale and/or yScale properties of our axisLayout. The following code will cause both the x and y axis to begin at zero.
[as]
axisLayout.xScale.zeroBased = true;
axisLayout.yScale.zeroBased = true;
[/as]
To control the maximum values of our chart we can use the preferredMax property.
[as]
axisLayout.xScale.preferredMax = 10;
axisLayout.yScale.preferredMax = 10;
[/as]
Note that there is a preferredMin property as well, but it (oddly) is ignored when set to zero. You can use it to set the lower bounds of your axes to any value other than zero. Adding the two snippets above has specified that our chart axes should begin at zero and end at 10, regardless of the data being shown. The resulting chart looks like this:
Customizing grids and axes
To really start customizing your chart, you’ll want to use the xyAxes property of Flare’s Visualization class. xyAxes is of type CartesianAxes and contains several convenient properties, as well as providing access to xAxis and yAxis properties that represent exactly what their names say, and are both of type Axis.
Maybe you want to eliminate the default grid pattern in favor of a simple bottom and left border.
[as]
// effectively only hides top and right borders
vis.xyAxes.showBorder = false;
// show bottom border
vis.xyAxes.showXLine = true;
// show left border
vis.xyAxes.showYLine = true;
// hide vertical grid lines (along x axis)
vis.xyAxes.xAxis.showLines = false;
// hide horizontal grid lines (along y axis)
vis.xyAxes.yAxis.showLines = false;
[/as]
The xAxis and yAxis elements also provide some useful properties that we can use to further customize our chart.
[as]
vis.xyAxes.showBorder = false;
vis.xyAxes.showXLine = true;
vis.xyAxes.showYLine = true;
// distance beyond left edge of axis
vis.xyAxes.yAxis.lineCapX1 = 20;
// distance beyond right edge of axis
vis.xyAxes.yAxis.lineCapX2 = -(vis.xyAxes.layoutBounds.width);
// distance to move labels
vis.xyAxes.yAxis.labelOffsetX = -25;
// distance beyond bottom edge of axis
vis.xyAxes.xAxis.lineCapY1 = 15;
// distance beyond top edge of axis
vis.xyAxes.xAxis.lineCapY2 = -(vis.xyAxes.layoutBounds.height);
// distance to move labels
vis.xyAxes.xAxis.labelOffsetY = 20;
[/as]
This code produces the following chart:
Useful methods
There is also an axisScale property on the Axis class (our xAxis and yAxis elements). axisScale is typed as Scale, but will usually be a ScaleBinding instance as Scale is essentially an abstract class. Scale (or rather its subclasses) provide two very useful methods, interpolate( value:Object ):Number and lookup( f:Number ):Object. The interpolate method will return a number representing where on the scale the passed in value falls. In our example where our range is 0 to 10, 5 would return .5, 8 would return .8, etc. The lookup method essentially does the opposite, accepting a number and returning the corresponding value on the scale, meaning .5 would return 5 in our example, 2 would return 20, and so on. These methods can be extremely helpful if you need to do custom drawing on your chart, and are the kind of value translation methods that seem to be missing from the Flex charts.
Conclusion
This is obviously not an exhaustive list of customizations possible with Flare, but it hopefully gives you an idea of the kinds of things you can do out of the box. I haven’t decided which topic to cover next, so if there are specific questions or features people would like to see let me know in the comments.