ActionScript 3.0 Cookbook: Chapter 6, Display List
Pages: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Section 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.

This excerpt is from ActionScript 3.0 Cookbook. Well before Ajax and Windows Presentation Foundation, Macromedia Flash provided the first method for building "rich" web pages. Now, Adobe is making Flash a full-fledged development environment, and learning ActionScript 3.0 is key. That's a challenge for even the most experienced Flash developer. This Cookbook offers more than 300 solutions to solve a wide range of coding dilemmas, so you can learn to work with the new version right away.

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 );
    }
  }
}

See Also

Recipes 6.1 and 7.3

Section 6.5: Creating Simple Buttons

Problem

You want to create an interactive button that enables a user to click and perform an action, such as submitting a form or calculating a total.

Solution

Create an instance of the SimpleButton class and create display objects for upState, downState, overState, and hitTestState. Alternatively, create a subclass of SimpleButton that describes your desired button behavior.

Use the click event to invoke a method whenever the user presses the button.

Discussion

The display list model provides an easy way to create buttons through the SimpleButton class. The SimpleButton class allows a user to interact with the display object using their mouse, and makes it easy for you to define that interaction through various button states. The possible button states, listed here, are available as properties of the SimpleButton class:

upState

A display object for the default "up" state of the button. The "up" state is shown whenever the mouse is not over the button.

overState

A display object that determines what the button looks like when the mouse moves over the button. When the mouse leaves the button area, the button moves back to the "up" state.

downState

A display object that's shown when the button is pressed (or clicked) "down". When the button is in the "over" state, the "down" state displays when the user presses the left mouse button.

hitTestState

A display object that defines a button's bounds. When the mouse moves inside of the button's hit area, the button enters the "over" state. The hitTestState is typically set to the same display object as the upState. The hitTestState is never actually displayed on-screen; it is only used for mouse tracking purposes.