ActionScript Graphing Cookbook

All recipes in this book are completely editor-agnostic; you can use them in any ActionScript editor you like. The samples are provided for the free FlashDevelop IDE available at http://www.flashdevelop.org/ , because it is completely free and of a very high quality.

If you want to follow along with FlashDevelop, now is the time to download and install it. Make sure you also configure the Flex SDK, if FlashDevelop does not do this for you. The Flex SDK is the part that will be responsible for compiling and executing your programs. More information can be found on the FlashDevelop wiki found at http://www.flashdevelop.org/wikidocs/index.php?title=Configuration#Configuring_the_Flex_SDK.

In FlashDevelop, create a new AS3 project. You can create one for each chapter, or re-use the same one for most of the recipes. Most recipes will require you to set the document class. This is done by right-clicking on the class in the project view and picking set document class from the options.

If you are using Flash Professional, we will not use the timeline that you may be used to. Information on setting up the document class can be found in the following blog article: http://active.tutsplus.com/tutorials/actionscript/quick-tip-how-to-use-a-document-class-in-flash/.

The first three steps will need to be performed for virtually all the recipes in this book, so we won't repeat them, unless they differ:

ActionScript 3.0 uses a concept called a display list. A display list is a collection of visual elements. The most important display list is your main class. This is the list that will be displayed (that is the reason why it extends Sprite).

This list is organized as a tree. It has a root node, to which various display objects are attached. Some of these display objects can also contain more display objects, hence the tree structure.

For instance, if you add a Sprite child to your main class, it will be displayed. If you add yet another Sprite child to that child, it too will be drawn on the screen.

However this isn't the end of the story. You can apply transformations to objects in the display list. A transformation can be scaling, rotating, and moving, or all at once. If you apply a transformation to one object, this transformation will also apply to all its children. This is how we displayed a point at (0,0) that was in the center of the screen.

When drawing a point, we do this by adding a shape to the display list:

To understand the transformation that takes place, you should take note of two different coordinate systems that are used:

In the next recipe, we will see a transformation matrix. This matrix is a mathematical shorthand notation for a coordinate transformation.

Although this recipe seems simple; there's much you can learn from it. Let's look at some more features.

If you want to read up on the display list, most of the ActionScript 3.0 fundamental books have a dedicated chapter about it. For instance, Learning ActionScript 3 or Essential ActionScript 3 (both published by O'Reilly) are good references.

If you want to read up on coordinate systems and transformations, you can find the best coverage in any vector maths book. Wikipedia is also a very informative source: http://en.wikipedia.org/wiki/Coordinate_system .

Make sure you at least glanced over the previous recipe. You'll need it here.

Create a new, blank Recipe2 class, set it as the document class, and copy and paste the code inside the Recipe1 constructor placed inside it. To be sure, run the class and verify that everything looks the same as in the previous recipe.

We will tackle the generalization of the code in a few steps. If you take a look at the code, you'll notice that there are actually two important blocks: one that creates the graph shape and one that draws a point.

To see how the transformation actually works, add the following line to the end of the graph constructor:

trace(graph.transform.matrix);

This trace statement will display the transformation matrix in use. If you still remember your math, you may find this other way of looking at the process enlightening (see http://en.wikipedia.org/wiki/Transformation_matrix for an in-depth discussion on the topic).

The createGraph method sets up the following transformations:

The drawPoint method draws a new point and can be called repeatedly to draw multiple points.

It creates a new shape for every point. This is not strictly necessary and might even cause a degraded performance when drawing many points. In the coming chapters, we'll see some uses for this approach, but if you have issues with performance, you can directly draw on the Recipe2 sprite and not instantiate new shapes for every point.

Again, this basic program is very powerful. And with a few changes, it allows for lots of experimentation.

This recipe closely relates to many of the others in this chapter. So if something isn't clear, go back to the previous one, or skip ahead and come back to it later.

Before starting this recipe, we will go through one final iteration of our code in order to have a proper object-oriented structure that we can easily and quickly extend in this and later recipes.

Start by creating a Recipe3 class, set it as document class, and have it extend Sprite.

Next create a Graph class (in a new file, with name Graph.as) where we will centralize all graph drawing methods:

package  
{
  import flash.display.Shape;
  import flash.display.Sprite;
  import flash.events.Event;

  public class Graph extends Sprite
  {
    private var left:Number;
    private var top:Number;
    private var right:Number;
    private var bottom:Number;

    private var matrix:Matrix;

    public function Graph(left:Number, top:Number, right:Number, bottom:Number) 
    {
      this.left   = left;
      this.top    = top;
      this.right  = right;
      this.bottom = bottom;

      addEventListener(Event.ADDED_TO_STAGE, createGraph);
    }
    
    private function createGraph(event:Event):void
    {
      removeEventListener(Event.ADDED_TO_STAGE, createGraph);
      
      var width:Number = Math.abs(right - left);
      var height:Number = Math.abs(bottom - top);
      var scaleWidth:Number = stage.stageWidth / width;
      var scaleHeight:Number = stage.stageHeight / height;
      var flipX:Boolean = (left > right);
      var flipY:Boolean = (top > bottom);

      matrix = new Matrix(
        (flipX ? -1 : 1) * scaleWidth,
        0,
        0,
        (flipY ? -1 : 1) * scaleHeight,
        scaleWidth * Math.abs(left),
        scaleHeight * Math.abs(top)
      );
    }

    public function drawPoint(x:Number, y:Number):void
    {
      var transformedLocation:Point = matrix.transformPoint(new Point(x, y));
      var point:Shape = new Shape(); 
            point.graphics.beginFill( 0xff9933 , 1 );
            point.graphics.drawCircle( 0 , 0 , 3 );
      point.x = transformedLocation.x;
      point.y = transformedLocation.y;
            addChild(point);
    }
  }
}

You'll notice two major changes from the previous recipe:

To draw a line, we use the Graphics methods as follows:

You can try this out with any data, not just a function. Replace the drawPoint method calls in Recipe3 with the following piece of code:

      graph.drawLine(0, 0, 20, 40);

You should see a short line appear. Once we can draw a line, drawing a function just builds on top of that:

If function drawing is the main aim of your program, there are quite a few ways this code can be extended and improved.

If you want to read up on linear interpolation, a good starting point is Wikipedia http://en.wikipedia.org/wiki/Linear_interpolation or your old, math books.

The sine function is also well explained on Wikipedia:

http://en.wikipedia.org/wiki/Sine.

This recipe continues to expand the Graph class presented in the previous recipe. So if you haven't written that yet, copy it from the provided sources.

Next, create a Recipe4 class, just as we did in the previous recipes.

To create axes, we will add two methods to the Graph class. They are as follows:

Calling the methods will draw a straight line from (x,y1) to (x,y2) and (x1,y) to (x2,y), respectively.

This recipe is probably one of the least spectacular ones. It just builds on top of ActionScript methods for drawing lines and displaying text. There's a lot of mechanical work involved in getting everything in the right location, but nothing complicated.

The best way to understand the recipe is to play with the various parameters:

Now let's talk about some other options, or possibly some pieces of general information that are relevant to this task.

Create a new document class called Recipe5 and have it extend Sprite. Also make sure to copy the updated Graph class from the provided source package. It has enhanced and more flexible axes methods (if you implemented any of the items mentioned in the There's more... section of the Adding labels and axes recipe in this chapter, you may have already created a very similar one).

This time we'll focus on only positive numeric data, so we'll put the origin (0,0) of the graph in the bottom-left corner:

package  
{
  import flash.display.Sprite;

    private const MAX_X:int  = 700;
    private const MAX_Y:int  = 500;
    private const BORDER:int = 50;
    private const TICK:int   = 50;

  public class Recipe5 extends Sprite 
  {
    private var graph:Graph;

    public function Recipe5() 
    {
      graph = new Graph( -BORDER, MAX_Y + BORDER, MAX_X + BORDER, -BORDER);
      addChild(graph);
      graph.drawHorizontalAxis(0, 0, MAX_X, TICK, ["0", MAX_X]);
      graph.drawVerticalAxis(0, 0, MAX_Y, TICK, ["0", MAX_Y/2, MAX_Y]);
    }
  }
}

If you run this program, you should see both axes run from the bottom-left corner and there should be two labels on the horizontal axis and three on the vertical axis.

For now, we'll just show point charts. Feel free to convert this into a line chart (as shown in the Creating a line graph based on a function recipe in this chapter) and in later recipes you'll learn how to draw many different types of charts.

If we have the following table:

We want to draw two points: (10,40) and (20,60).

Storing data is easiest in a two dimensional array. In the next chapter, we'll go over many different ways of storing data (such as in files and on the Internet). The array mimics how you represent this data in a program such as MS Excel:

private var graph2d:Array = [[0,20],[50,70],[100,0],[150,150],[200,300],[250,200],
[300,400],[350,20],[400,60],[450,250],[500,90],[550,400],
[600,500],[650,450],[700,320]];

All the points are grouped together. Each entry in the array is one (x , y) coordinate on the graph.

The code to draw this dataset is just a simple loop:

for (i = 0; i < graph2d.length; i++)
{
  graph.drawPoint(graph2d[i][0], graph2d[i][1], 0x3399ff);
}

This structure does have one problem: it's not easy to manipulate the data. You may want to change the data, for instance, if this was connected to live web statistics that are updated every minute (we'll see more on that in the next chapter). Say you want to change the point (150,150) to (150,200). How would you do that? You need to loop over the array and find the correct entry and change it.

However, searching this way in a large array can become slow quite quickly. If the array is always sorted, like in the preceding example, you could implement your own version of a search algorithm to make it quicker. But then you'd need to create your own insertion algorithm to make sure the data remains in order.

No matter how you solve this, if you need to manipulate the data a lot, this is not a good data structure.

See the There's more... section of this recipe for other solutions to these problems.

The data we want to display is a simple data mapping from one value to the another. Imagine an Excel spreadsheet with two columns. One column holds the x-axis values while the other holds the y-axis value. Two numbers on the same row present one (x , y) point.

That is why a two-dimensional array is one of the best ways to represent data: it's an easy structure to program and it's easy to read. However, it is hard to manipulate. If you have a fixed data set, this is the structure you want.

There are an endless number of possible ways to represent data. Depending on your data source or your specific data set, you may want to look into other options. In the following section, we present the two most popular ones, each with its own advantages and disadvantages. Ultimately, it is possible to combine most advantages into one structure, but it will require additional development.

private var graph1x:Array = 
[0, 50, 100, 150, 200, 250, 300, 350, 400, 
450, 500, 550, 600, 650, 700];
private var graph1y:Array = 
[20, 70, 0, 150, 300, 200, 400, 20, 60, 250, 90, 400, 500, 450, 320];

for (var i:int = 0; i < graph1x.length; i++)
{
  graph.drawPoint(graph1x[i], graph1y[i], 0xff9933);
}

private var graphObject:Object = { 0:20,50:70,100:0,150:150,200:300,250:200,
300:400,350:20,400:60,450:250,500:90,550:400,
600:500,650:450,700:320 };

for (var s:String in graphObject)
{
  graph.drawPoint(Number(s) + 8, graphObject[s], 0xff3399);
}

graphObject[150] = 200;

var point:Point = new Point(0,20);

var graphVector:Vector.<Point> = new Vector.<Point>();
graphVector.push(point);

If you're not confident with manipulating (associative) arrays, it's best to look at one of the ActionScript fundamentals books. Both data structures are vital to understanding most of the recipes in this book.

Create a Recipe6 document class and set up the graph as in the previous recipe. We will use the two-dimensional data set because we will need an ordered data set:

package  
{
  import flash.display.Sprite;

  public class Recipe6 extends Sprite
  {
    private var graph:Graph;
    private var data:Array = [[0, 20], [50, 70], [100, 0], [150, 150], [200, 300], [250, 200], [300, 400], [350, 20], [400, 60], [450, 250], [500, 90], [550, 400], [600, 500], [650, 450], [700, 320]];
    public function Recipe6() 
    {
      graph = new Graph( -50, 550, 750, -50);
      addChild(graph);
      graph.drawHorizontalAxis(0, 0, 700, 50, ["0", "700"]);
      graph.drawVerticalAxis(0, 0, 500, 50, ["0","250","500"]);
    }

  }
}

This recipe is created in two steps: first, display a line chart and next, fill the void beneath the line to obtain an area.

Because drawing a line requires two points, we start counting at 1 instead of 0. In the loop, we draw a line between the previous point and the current one.

There are two other things to note from the code:

As with previous recipes, there's a lot that can be customized. Most of these will be discussed in some of the next recipes, but there's nothing keeping you from starting to experiment.

The ActionScript 3.0 reference has a lot more detail on creating and drawing filled shapes. It can be found at the following URL:

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/Graphics.html

As usual, create a Recipe7 document class. We'll start with the code from the previous recipe. Only now, we've slightly changed the data set to demonstrate some of the items covered better. There's also an added set of data. We've chosen to store it in the same array for simplicity, but there are other ways of course.

The following is the starting class:

package  
{
  import flash.display.Sprite;

  public class Recipe7 extends Sprite
  {
    private var graph:Graph;
    private var data:Array = [[0, 20, 50], [50, 70, 40], [100, 0, 100], 
[150, 150, 150], [200, 300, 200], [250, 200, 170], 
[300, 170, 160], [350, 20, 120], [400, 60, 80], 
[450, 250, 150], [500, 90, 20], [550, 50, 40], 
[600, 110, 90], [650, 150, 150], [700, 320, 200]];

    public function Recipe7() 
    {
      graph = new Graph( -50, 550, 750, -50);
      addChild(graph);
      graph.drawHorizontalAxis(0, 0, 700, 50, ["0", "700"]);
      graph.drawVerticalAxis(0, 0, 500, 50, ["0", "250", "500"]);

      for (var i:Number = 1; i < data.length; i++)
      {
        graph.drawArea(data[i-1][0], data[i-1][1], data[i][0], data[i][1]);
      }

    }

  }

}

There are two ways to show multiple area charts. You can stack the charts on top of each other or you can make them transparent and have them overlaid.

We'll cover the transparent overlay first, because it's the easiest.

Areas are drawn by moving from one point to the other, either clockwise or counter-clockwise. We rushed over this important point in the previous recipe, but it is important in this one.

Because the areas are a little more complex, you need to be extra careful to get the order right. Otherwise you'll run into some strange phenomena.

When overlaying multiple charts, we use the alpha property of the fills. The alpha value controls the transparency of the fill. By making the fill translucent, we can see both areas behind each other.

When stacking multiple charts, we need to use the sum of both coordinates to properly place the different data sets. The bottom coordinates of the second data set are given by the first area chart, while the top coordinates are the sum of two data sets.

We've seen the basics of drawing multiple data sets on one chart. In later chapters, there will be many more ways of displaying this information. In the meantime, here are a few ways to expand this recipe.

We start by having a graph that shows all three types of charts we've discussed:

package  
{
  import flash.display.Sprite;

  public class Recipe8 extends Sprite
  {
    private var graph:Graph;
    private var data:Array = [[0, 20], [50, 70], [100, 0], [150, 150], [200, 300], [250, 200], [300, 400], [350, 20], [400, 60], [450, 250], [500, 90], [550, 400], [600, 500], [650, 450], [700, 320]];

    public function Recipe8() 
    {
      graph = new Graph( -50, 550, 750, -50);
      addChild(graph);
      graph.drawHorizontalAxis(0, 0, 700, 50, ["0", "700"]);
      graph.drawVerticalAxis(0, 0, 500, 50, ["0", "250", "500"]);

      graph.drawPoint(data[0][0], data[0][1] + 50);
      for (var i:Number = 1; i < data.length; i++)
      {
        graph.drawArea(data[i - 1][0], data[i - 1][1], data[i][0], data[i][1]);
        graph.drawLine(data[i - 1][0], data[i - 1][1] + 25, data[i][0], data[i][1] + 25);
        graph.drawPoint(data[i][0], data[i][1] + 50);
      }

    }

  }

}

Notice that we have shifted the y-coordinate of the different charts, so that it's clear which one is which. If you run this program you should see an area chart, 25 pixels higher a line graph, and the another 25 pixels higher a point chart.

ActionScript's Graphic class offers a rich set of drawing primitives. This allows you to create virtually any vector graphic you like. Some of the concepts will feel natural, while others can take a while to properly grasp. It's worth learning the ins and outs of the Graphics class because a well-placed gradient or bitmap can really spice up any graph.

As in all other drawing methods we've seen in this chapter, first the coordinates are transformed.

When drawing a bitmap point, the embedded resource class is instantiated into a Bitmap class. This is the class that will display the image.

Next we use some simple math to place the bitmap at the center of the coordinates. In ActionScript, the bitmap's (x , y) coordinates reflect the upper-left corner. So if we want to place the center of the bitmap at our coordinates, we need to subtract half of the width and height.

As usual, the final step is adding the bitmap to the graph sprite.

Drawing gradients requires extra work. To draw an area that is filled with a gradient, we use the beginGradientFill method. It takes the following parameters:

Optionally, you can also add a matrix that transforms the gradient. This will allow you to correctly place the gradient. In the case of this example, we stretch the gradient over the full screen and rotate it by 90 degrees.

When drawing bitmap fills for lines, there are a few points worth noting:

If you want to change the exact placement of the bitmaps, the lineBitmapStyle method takes an optional Matrix as an argument. This works similar to all the other matrix operations we've seen. Getting this exactly right isn't easy, so you may need to do some experimentation.

We've only covered the very tip of the iceberg that is the Graphics class.

Most ActionScript books have good coverage of the Graphics class. But there are also a few that go into much more detail.

Although it can be a bit hard to get into, the live docs also provide a fairly in-depth overview of the features. This is available at: http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/Graphics.html .

For the Recipe9 class, we start from the overlapping multiple area charts class. So copy that class and rename it to Recipe9 to follow along.

Just like with the Graph class, we use the Legend class to hold all of the separate graphical elements of the legend. That way we can just work from the (0,0) origin and not worry about the exact location where the legend will be placed.

Since this would require its own chapter, we won't be going into the details of styling and customizing the textField class. The only option that we use the autoSize property. It will make sure that the size of the text field fits the text and isn't just left at the default 100x100. This guarantees that the sprite's size will be exactly the size of the text and allows us to easily draw a nice fitting box around the entire legend display.

The line counter is responsible for making sure we can place each individual legend key at the right distance.

You may have noticed that we draw the legend in screen coordinates, not graph coordinates. In many cases, it's easier to place it in the correct location that way. Although if you want to fix the legend in relation to the graph (for instance, always in the bottom, at the center) you may want to think about putting it inside the Graph class and use the transformed coordinates. In that case, the Legend class would probably be a child of the Graph class.

The legend is a sprite, which means you can use the legend like any other one. You can resize it, move it, and even rotate it if you want (you may need to use embedded fonts on the text fields to perform some of those operations).

With this recipe, we've only scratched the surface of what you can do with legends.

More information on customizing textField can be found in the Adobe live docs:

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/text/TextField.html.

The textFormat class is the main way to change fonts, sizes, and many more options:

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/text/TextFormat.html.

Since we need access to the Flex library, we'll need to set up our FlashDevelop workspace differently. The easiest way is to create a new project. When asked for the type of project, pick Flex 3 project (instead of AS3 Project, which we use throughout the other parts of this book).

If you browse through the files in the src directory of your project, you will now find a Main.mxml file instead of the previous Main.as file. This is the file that describes your user interface. Instead of programmatically adding all the sprites and shapes to your interface, you will add them to this file.

Flex has a few new data structures; in this recipe we use the ArrayCollection data structure. This is a specially defined data structure that makes it easy to manage chart data. In fact, if you wanted to include the Flex library in your project, you could use the class for your own graph drawing.

Now let's look at the structure as a display list: the root element is a Panel class. This is a simple wrapper class to which you can add a title.

Inside this panel, there are two visual elements: an area chart and a legend. The legend is the easiest of the two explain; we use the default settings and let it read its data from the chart. It's all automatically added and filled.

The area chart is a little more involved:

If you run the program, you will see a graph similar to the one presented in the multiple area charts recipe.

The difference is the way we defined the chart. With Flex you describe how the chart will look and let Flex do the work for you. In plain ActionScript, you have full control, but you have to do all the hard work.

The choice will depend on the application and most likely also on personal preferences.

The Flex charting API is immense and with the recipe above, and we haven't even scratched the surface. If you think this style of development is for you, here are a few more things you can do.

If you like to get into Flex, there are numerous books. Also, the online documentation is very complete. For charting, your best starting point is available here:

http://livedocs.adobe.com/flex/3/html/help.html?content=charts_intro_7.html.