API Drawing, Part1: The Basics
Move the mouse within the window to draw.
As Flash began to evolve away from purely graphical operations toward a mixed code-and-graphics approach, a tool was added to the FlashPlayer permitting scripters to create graphical elements through the execution of ActionScript. This is called the Drawing API. The acronym stands for application programming interface. An API is a set of code tools specialized for a particular purpose, in this case, drawing simple geometry on the screen.
While API drawing doesn't offer the full range of options available in the drawing and other graphics tools in the Flash editor, it does offer a very interesting supplement to those tools. For those of us trying to learn our way into ActionScript, it also provides a good occasion to further sharpen programming skills.
Postings this week will describe a number of projects using the Drawing API, proceeding from the simplest automatic line tracing (shown above, described below), to more complex cycling displays and screensavers.
I. Mouse drawing
The demonstration above illustrates the most basic application of the Drawing API: turning the mouse pointer into a virtual pen that constantly draws a line on the screen. The code behind this trick is refreshingly simple. In our example, it is contained in a document class attached to the main movie. Here's everything in the class, omitting only its package{} container:
import flash.display.MovieClip;
import flash.events.Event
public class autoLineDocClass extends MovieClip
{
public function autoLineDocClass()
{
graphics.moveTo(mouseX, mouseY);
addEventListener(Event.ENTER_FRAME, lineOut);
}
public function lineOut(event:Event):void
{
graphics.lineStyle(6, Math.random()*0xFFFFFF, 1);
graphics.lineTo(mouseX, mouseY);
}
}
The imports are familiar. We import Event because we'll be using a frame-entry loop, and MovieClip because we're scripting the main movie -- and because the graphics property we'll be using is common to all Flash DisplayObjects. As you may recall, a MovieClip is a subclass of DisplayObject.
In the Constructor, we invoke this graphics property, calling its moveTo() method. (How can properties have methods? When the property in question -- graphics -- actually contains an instance of a class: in this case, the class Graphics. Why don't we need to import Graphics? That's not necessary when we're working with a DisplayObject such as a MovieClip.)
The method moveTo() sets the point at which drawing will begin. It's like picking up a pen and touching its point to the paper, before making a stroke. Here we set our virtual pen-point at the current X and Y position of the mouse pointer. Note that moveTo() does not create any visible pixels, as opposted to lineTo(), which we'll see below.
Notice that we don't express this position as MovieClip(root).x, MovieClip(root).y (though you can do so if it makes you feel better). This is a document class, in the root position of the object hierarchy, so mouse coordinates are already set to the root. Remember that if you program drawing on the mouse from some object not in root position, you will need the longer notation.
In the second line of the Constructor, we add a listener for the ENTER_FRAME event. This is entirely as you've seen it before.
The callback method for this listener is lineOut(), which contains two statements. The first calls the lineStyle() method of the graphics property (and the associated Graphics class). This method sets features of the line segment we intend to draw, including its width, color, and alpha. We set width to 6 pixels and alpha to 1 (fully opaque). We randomize the color value for the entire range of 32-bit color, by using the maximum hexadecimal value, 0xFFFFFF, as the multiplier for the Math.random() method.
We could have put the lineStyle() method elsewhere. Putting it in the enter-frame callback lets us change the line color constantly, giving our lines that curious, rainbow effect. If you'd rather stick with monochrome, then put the lineStyle() method call in the Constructor.
The final piece of the trick is lineTo(), a method that draws a line segment from the previous position of the mouse to its present location. You'll note that only one point is given in this method, representing the endpoint of the line. The start point is implied. Once our loop starts running, the start point is always the endpoint reached on the previous lineTo() operation. We set the initial starting position in the Constructor by invoking moveTo().
II. NotesLike everything else in ActionScript 3.0, API drawing gets a whole lot more complicated than this simple introduction suggests. In our next posting, we'll look at a drawing demonstration allowing the user to turn the pen on and off. Unfortunately, this involves many more pieces and parts; but the basics of API drawing -- calling methods of the graphics property of a MovieClip -- remain the same.
III. Source files
Source files for the demonstration at the top of this page can be found in the directory APIDrawing, within MULTIMEDIA in the shared account on student-iat. The main movie file is autoline.fla. The associated document class is autolineDocClass.as.
|