Introduction to the ActionScript Drawing API

By Blue_Chi | Flash CS3 | ActionScript 1+2 | Intermediate

This tutorial will teach you the basics on how to use the ActionScript Drawing API, this is a set of methods for drawing lines, curves, and fills dynamically. ActionScript does not have drawing methods for making predefined shapes such as circles or rectangles, but can create shapes using the few, yet powerful, drawing API methods. This tutorial will teach you the basics on how to use the most commonly used drawing methods. The sample below shows a square that we drew and coloured using the Drawing API and then moved it around using the Tween Class.

Introduction

The drawing API resembles a simple pen-like drawing mechanism that lets you move your pointer, or pencil, from one point to the next to draw lines as you connect these points. ActionScript lets you draw directly onto any movie clip by using simple methods to move the pencil, draw using it, and fill the area you surround by the lines you create.

ActionScript has the following drawing methods:

We are going to explain in this tutorial the basic methods that do not involve gradients, so we will not cover .lineGradientStyle or .beginGradientFill, but they have a very similar function to their non-gradient alternatives, so you should be able to get the basic idea behind these as well.

Drawing Simple Lines using .lineStyle and .lineTo

Before drawing anything at all using the drawing methods, we must have a movie clip set as a canvas for us to draw in, we can use the _root of our movie clip as our canvas, but good practice suggests creating a separate movie clip for your drawings so that you can manipulate and control that movie clip without affecting the rest of your flash movie. Instead, it is better to create a movie clip using the .createEmptyMovieClip() method, we are going to create for this tutorial a movie clip we call canvas_mc:

_root.createEmptyMovieClip("canvas_mc",1);

We are going to start off by drawing a simple line, that will require setting our line style, ie the thickness, colour, and other properties of the line. This is controlled by the .lineStyle method which has many of customisation options for the line and must be set before attempting to draw any line we wish to create. We are going to set only the thickness and colour properties of our style, the general code for setting this using the .lineStyle method is as follows:

movieClip.lineStyle(thickness, colour);

The thickness property can be set as any positive number, we are going to use 1 so that our line is 1 pixel thick. The colour is set as a hexadecimal colour code, we are going to use red which has the colour code of 0xFF0000:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.lineStyle(1,0xFF0000);

We now have our canvas ready and our pen style ready, we need to define the starting point of our line, this is an optional step as by default the line would start from the registration point of the movie clip, ie point 0,0. We do not want to start from there, so we are going to move our pen to another point using the .moveTo method. The .moveTo method requires proving an _x and a _y coordinate to move, we are going to move our pen to the point 50,50 on our canvas movie clip, so we will do that this way:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.lineStyle(1,0xFF0000);
canvas_mc.moveTo(50,50);

The line that we wish to create will be a straight line starting from the point 50,50 (our current pen location) and ending at the point 100,50. We will use to do this the .lineTo method which requires providing the ending point, which we specified as 100,50, here is how this is translated into code:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.lineStyle(1,0xFF0000);
canvas_mc.moveTo(50,50);
canvas_mc.lineTo(100,50);

You can test your movie now to see your very first line coloured in red and extending from point 50,50 to point 100,50. Here is a visualisation of what we have just done:

Drawing API Ilustration

We can continue drawing our lines one by one by continuing from our existing point and targeting the next point to create all sorts of shapes, the code below will result in a square, it should be easy to understand:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.lineStyle(1,0xFF0000);
canvas_mc.moveTo(50,50);
canvas_mc.lineTo(100,50);
canvas_mc.lineTo(100,100);
canvas_mc.lineTo(50,100);
canvas_mc.lineTo(50,50);

You can test your movie to see a small square. Here is an illustration of what we have done to create it:

Drawing API

To draw another object or line without having to connect it to your last line you drew line you can use moveTo again to move your pen without drawing (as opposed to lineTo).

Drawing Curves using .curveTo

Drawing a straight line was pretty easy as you specify the end point and the line just appears extending to that point, drawing a curved line on the other hand is a bit more complex as it requires you to use the curveTo method to set the point at which the curve tips (the control point) and the end point of the curve (the anchor point) in the following format where x1 and y1 are the coordinates of the control point and x2 and y2 are the coordinates of the anchor point:

movieClip_mc.curveTo(x1, y1, x2, y2);

If we were to create a simple eye-like oval shape using two curved lines we can do that by using the code below, it is worth noting that using .curveTo requires the same prerequisites as .lineTo, namely a container movie clip (ie a canvas) and a line style:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.lineStyle(1,0xFF0000);
canvas_mc.moveTo(0,50);
canvas_mc.curveTo(25,0,50,50);
canvas_mc.curveTo(25,100,0,50);

CurveTo Illustration

Creating Fills using .beginFill

Any shape we create using .lineTo or .curveTo can be filled with a colour to close the area created between the created lines, to do that we simply use .beginFill instead of .lineStyle and assign to it the fill colour that want to use in the following format:

movieClip_mc.beginFill(colourCode, transparency);

The colour is to be specified in hexadecimal colour code and the transparency is to be set as any value between 0 and 100 where 0 is invisible and 100 is opaque. Remember that you have to tell the movie to .beginFill before you start drawing the lines of your object, here is our square example from above but with the outline replaced by a fill:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.beginFill(0xFF0000, 100);
canvas_mc.moveTo(50,50);
canvas_mc.lineTo(100,50);
canvas_mc.lineTo(100,100);
canvas_mc.lineTo(50,100);
canvas_mc.lineTo(50,50);
canvas_mc.endFill();

It is important to remember to use .endFill at the ending point to ensure that we do not carry our colour to any further lines we draw. I would also like to point out that it is possible in fact to use .lineStyle along with .beginFill to create shapes that have both an outline and a fill colour.

Removing All Drawing Using .clear

The last basic drawing API method we will go through is .clear which has the basic function of clearing all drawings made within a movie clip using the drawing methods. This method simply deletes all previously drawn shapes within a movie clip and it does not have any selective functions to delete something and keep another. To delete the square we created in the last step we simply call the method this way:

_root.createEmptyMovieClip("canvas_mc",1);
canvas_mc.beginFill(0xFF0000, 100);
canvas_mc.moveTo(50,50);
canvas_mc.lineTo(100,50);
canvas_mc.lineTo(100,100);
canvas_mc.lineTo(50,100);
canvas_mc.lineTo(50,50);
canvas_mc.endFill();
canvas_mc.clear();

That's about it, I am not going to discuss .lineGradientStyle or .beginGradientFill because they are a bit too complex for a beginner tutorial. You can explore these on your own or read the reference help pages about them. Feel free to post any questions you have on the Oman3D Forum.

- End of Tutorial