Recipe 6.4. Creating Custom Visual Classes

Problem

You want to create a new type of DisplayObject.

Solution

Create a new class that extends DisplayObject or one of its subclasses so it can be added into a display object container via addChild( ) or addChildAt( ).

Discussion

Among the benefits of moving toward the display list model is the ease of creating new visual classes. In the past, it was possible to extend MovieClip to create custom visuals, but there always had to be a MovieClip symbol in the library linked to the ActionScript class to create an on-screen instance via attachMovie( ). Creating a custom visual could never be done entirely in ActionScript. With the display list model, the process has been simplified, allowing you to do everything in pure ActionScript code in a much more intuitive manner.

In the display list model, as discussed in the introduction of this chapter, there are many more display classes available besides just MovieClip. Before you create your custom visual, you need to decide which type it is going to be. If you're just creating a custom shape, you'll want to extend the Shape class. If you're creating a custom button, you'll probably want to extend SimpleButton. If you want to create a container to hold other display objects, Sprite is a good choice if you don't require the use of a timeline. If you need a timeline, you'll need to subclass MovieClip.

All of the available display object classes are tailored for specific purposes. It's best to decide what purpose your own visual class is going to serve, and then choose the appropriate parent class based on that. By choosing the parent class carefully you optimize size and resource overhead. For example, a simple Circle class doesn't need to subclass MovieClip because it doesn't need the timeline. The Shape class is the better choice in this case because it's the most lightweight option that appropriately fits the concept of a circle.

Once the base class has been decided, all you need to do is write the code for the class. Let's follow through with the circle example and create a new Circle class that extends the Shape display object. In a new ActionScript file named Circle.as, enter the following code:

package {
  import flash.display.Shape;

  /* The Circle class is a custom visual class */
  public class Circle extends Shape {
  
    // Local variables to store the circle properties
    private var _color:uint;
    private var _radius:Number;
    
    /*
     * Constructor: called when a Circle is created. The default
     * color is black, and the default radius is 10.
     */
    public function Circle( color:uint = 0x000000, radius:Number = 10 ) {
      // Save the color and radius values
      _color = color;
      _radius = radius;
      
      // When the circle is created, automatically draw it
      draw(  );
    }
    
    /*
     * Draws the circle based on the color and radius values
     */
    private function draw(  ):void {
      graphics.beginFill( _color );
      graphics.drawCircle( 0, 0, _radius );
      graphics.endFill(  );
    }
  }
}

The preceding code defines a new Circle display object. When a Circle instance is created, you can specify both a color and a radius in the constructor. Methods from the Drawing API (discussed in Recipe 7.3) are used to create the body of the circle with the graphics property, which is inherited from the superclass Shape.

It is always a good idea to separate all drawing code into a separate draw( ) method. The constructor for Circle does not draw the circle directly, but it calls the draw( ) method to create the visual elements.

All that is left to do is create new instances of our custom Circle class and add them to the display list with addChild( ) or addChildAt( ) so they appear on-screen. To create new instances of the class, use the new keyword. The following code example creates a few Circle instances and displays them on the screen:

package {
  import flash.display.Sprite;
  public class UsingCircleExample extends Sprite {
    public function UsingCircleExample(  ) {
      // Create some circles with the Circle class and
      // change their coordinates so they are staggered
      // and aren't all located at (0,0).
      var red:Circle = new Circle( 0xFF0000, 10 );
      red.x = 10;
      red.y = 20;
      var green:Circle = new Circle( 0x00FF00, 10 );
      green.x = 15;
      green.y = 25;
      var blue:Circle = new Circle( 0x0000FF, 10 );
      blue.x = 20;
      blue.y = 20;
        
      // Add the circles to the display list
      addChild( red );
      addChild( green );
      addChild( blue );
    }
  }
}