ActionScript - Drawing Lines and Boxes

ActionScript3 (AS3) provides tools to draw on a canvas. Unfortunately, the documentation is far from complete ... this page will help. It took me several weeks of extreme frustration to figure this stuff out.

Overview

When it comes to drawing, there are 3 important methods - moveTo, lineTo, drawRect. In addition, you need to set the pen color and fill color.

These methods are implemented via the graphics property (an instance of the Graphics class) of the following objects.

Shape	Shape -> DisplayObject -> EventDispatcher -> Object Does not support mouse events - click, down, ... Can not have children Uses less memory
Sprite	Sprite -> DisplayObjectContainer -> InteractiveObject -> DisplayObject -> EventDispatcher -> Object Accepts mouse events - click, down, ... Can contain children - addChild(), ...
MovieClip	MovieClip -> Sprite -> ... Has a timeline The designer can create these in the IDE

Graphis.lineStyle()

public function lineStyle(thickness:Number, color:uint = 0, alpha:Number = 1.0,
   pixelHinting:Boolean = false, scaleMode:String = "normal", caps:String = null, 
   joints:String = null, miterLimit:Number = 3):void

lineStyle is used to draw lines and borders around boxes. If it is not set, then nothing will be drawn.

thickness	The thickness of the line in points (points are not defined)
pixelHinting	Apparently, when true, this makes lines an exact number of pixels wide and causes them to align to the grid. The help on this is totally obscure.
scaleMode	This controls what is seen when objects are scaled. Setting this to NONE allows you to resize movies without the line widths changing. While this seems desirable, don't do it ... when you resize a running Flash movie you will want the line widths to change so that things look ok. (This is important.)
joints	When 2 lines overlap, Flash tries to make the joint look pretty (how sweet). As a result, joints always look sloppy. The default is ROUND ... which I really hate. MITER looks better, but leaves little pieces that really detract from a clean design.

Drawing Boxes

Before drawing a box (rectangle), the code needs to set

The line color, width, etc.
The fill color
Or both

This example has a black border and a red fill.

import flash.display.*;
import flash.events.*;

var box    : Sprite = new Sprite();
var canvas : Graphics;

canvas = box.graphics;
canvas.beginFill( 0xFF0000 ) ; // red
canvas.lineStyle(1, 0x000000, 1, true, LineScaleMode.NORMAL, CapsStyle.SQUARE, JointStyle.MITER);
canvas.drawRect(1, 1, 100, 200);
canvas.endFill();

stage.addChild(box);

trace(box.width, box.height); // shows: 101 201

The Problem

Besides the obvious problem that all this code is a pain in the neck, there is a serious problem that the sizes don't work out.

100 x 200

point

In every other language I've used, the height and width will be what you requested ... not some other value. If this implementation was described in the help files, then I would call it a *feature* ... since it is not, I use much less polite terms.

Size	Border	height	width	Comment
100 x 100	0	100.2	100.2	This has a thin black line around the box and a second thin line the same color as the border color outside the black line
100 x 100	1	101.0	101.0	No extra black line
100 x 100	5	105.0	105.0	No extra black line

With lines,

canvas.lineStyle(5, 0x000000, 1, false, LineScaleMode.NORMAL, CapsStyle.SQUARE, JointStyle.MITER);
canvas.moveTo(0,0);
canvas.lineTo(100,0);

trace(box.width, box.height); // shows: 100 5

It would make sense if a 100 x 200 box with a 5 pixel border had a width of 100 or 110 ... but 105 makes no sense at all.

At any rate, the only way I've found to draw a box without a visible border is to

Set the line thickness to 1
Set the line color to the fill color
Draw the box with the width and height set to one less than required

Using the code above

canvas.beginFill( 0xFF0000 ) ; // red
canvas.lineStyle(1, 0xFF0000, 1, true, LineScaleMode.NORMAL, CapsStyle.SQUARE, JointStyle.MITER);
canvas.drawRect(1, 1, 99, 199);
canvas.endFill();

trace(box.width, box.height); // shows: 100 200

In my opinion, Adobe should have included this information with the drawRect documentation.

Placing Objects

When you set the x/y properties of an object, you are specifying the location of the object's (0,0) point relative to the (0,0) point of the container.

For the stage, (0,0) is the upper left corner - in the IDE, this is the upper left corner of the white area - only the white area is displayed when the movie (form) is rendered.

For objects (MovieClips) drawn in the IDE, (0,0) is indicated by the plus sign. To change the location of the plus sign, open the MovieClip in design mode and reposition the sub-components as appropriate.

New Drawing Classes

Because this is so complicated, I created the following new classes to make things simpler.

Class	Description
TmcPen	Provides a separate property for each parameter. Applications can create a number of TmcPen objects and select them as appropriate.
TmcRect	Automatically assumes that the border has zero width. If the Pen property is not null, then create a border with it. Otherwise, do not create a border.

Author: Robert Clemenzi - clemenzi@cpcug.org