Flash Cookbook

Model View Controller

2009-11-05T13:35:00.001-08:00

Model View Controller
The Model View Controller pattern is based on three elements named, you guessed it! Model, View and Controller. Also known as MVC, the Model View Controller pattern is a perfect fit for programming graphical interfaces. Which is a big part of Flash.

MVC strives to separate data from the interface that manipulates it. In this way it uncomplicates your process of programming many types of projects. The MVC pattern may seem to be complex at first. In reality it unravels the spaghetti mess of code that you often find yourself in when programming complex user interfaces.

This is a pattern that's built of other patterns. In particular, it relies heavily on the Observer pattern. If you haven't heard of the Observer pattern before don't worry, since it's built into AS3, as the Event Listener system. If you've added listeners and set up event handler (functions called by a listener), then you've already got EventDispatcher under your belt.

MVC Overview
The MVC pattern, as I mentioned earlier, is made up of three elements: Model, View and Controller. How these elements interact is the key to MVC pattern.

The Model only contains data. This can be as little as one value. The Model is not concerned with displaying anything, the View will handle this. The Model should never have a reference to the View or the Controller.

The View is the visual portion of the system. The goal of designing the View is making a class that will display data stored in the Model. Any system using MVC might have any number of Views working with a single Model.

The Controller passes information to the Model. Often Controllers are also Views.

The key to relationship between Model, View and Controller, is the View and Controller store a reference to the Model that they are working with. The Model should never have a reference to the View or Controller. The Model is only concerned with storing, processing and making data available to the View and Controller.

The glue that holds the Model, View and Controller together is the Event Listener system. The basic arrangement is that the View and Controller will register to receive CHANGE events from the Model. When the data in the Model changes the Model dispatches a CHANGE event. Model makes it's data available to the outside world via public methods.

Simple MVC Example
The following example illustrates the Model View Controller. The example creates a Model which stores an int as it's data. The View displays the Model's data in a TextField on the stage. The Controller creates two Buttons which increment and decrement the Model's data.

The Model
The Model will not be a display class but it will dispatch event messages. So we'll need to import the EventDispatcher class and extend EventDispatcher. Below is the basic class.

package {
   import flash.events.*;
   public class Model extends EventDispatcher {
       public function Model() {

       }
   }
}

The Model for this example stores only one simple piece of information. We'll use a private variable called _data for this:

private var _data:int;

Assign _data an initial starting value of 0 in the constructor of the class:

_data = 0;

Our goal is to allow the Controller to change the value of _data by increment and decrementing by one. To make this easy we'll make two public functions. Each of these functions will dispatch a CHANGE event to notify listeners that _data has been changed.

public function add_one():void {
   _data ++;
   dispatchEvent( new Event( Event.CHANGE ) );
}

public function subtract_one():void {
   _data --;
   dispatchEvent( new Event( Event.CHANGE ) );
}

Any controller or View class will need a way to access the _data inside of the Model. Since _data is a private var, in accordance with good OOP procedure, we can't access it directly. We'll set up a public function to make this available. This is an area where your Models may vary depending on the data they store. You could make many different functions that allow access to data in many different ways. For this example we'll have a simple function that returns an int.

public function get_data():int {
   return _data;
}

Here's the entire Model class for this example:

package {
   import flash.events.*;

   public class Model extends EventDispatcher {
       private var _data:int;

       public function Model() {
           _data = 0;
       }

       public function add_one():void {
           _data ++;
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       public function subtract_one():void {
           _data --;
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       public function get_data():int {
           return _data;
       }
   }
}

The View
The View class has the job of displaying information stored in the model. The View doesn't have to display the information literally it could display it in any form you care to invent. You can also create and each could display data from the model in a different way.

All of the Views will share some features in common. They will all probably extend one of the display classes like MovieClip or Sprite. They will all receive a reference to the Model as an argument of the Constructor function. They will all register for CHANGE events with the model.

Here's the basics of the class:

package {
   import flash.display.*;
   import flash.events.*;

   public class View extends Sprite {
       private var _model:Model;

       public function View( model:Model ) {
           _model = model;
           _model.addEventListener( Event.CHANGE, on_change );
       }

       private function on_change( e:Event ):void {

       }
   }
}

When you create an instance of the View it has a reference to the Model passed to it in the argument model. The View Class stores this in _model. The class then adds an event listener to _model listening for the CHANGE event. I created a handler for this listener named on_change. Since the Model will dispatch a CHANGE event whenever it's data changes our View will now be notified and can update itself.

To complete the View we'll add a TextField and we'll add a line of code to the on_change handler that sets the text of the TextField to display the value stored in the Model.

package {
   import flash.display.*;
   import flash.events.*;
   import flash.text.*;

   public class View extends Sprite {
       private var _model:Model;
       private var _txt:TextField;

       public function View( model:Model ) {
           _model = model;
           _model.addEventListener( Event.CHANGE, on_change );
           _txt = new TextField();
           addChild( _txt );
       }

       private function on_change( e:Event ):void {
           _txt.text = String( _model.get_data() );
       }
   }
}

Here's a quick rundown of the new elements.

First I imported the flash.text.* package. We need this since our class will work with the TextField.

Next I created a new private variable _txt to hold the TextField that we will create. In the constructor I created a new TextField and added it tothe display list.

Last I added a line to the on_change function that sets the text of _txt to the value of data stored in Model. We're calling the model's get_data method, and the Model is returning the int stored in Model's _data property. Since the text property of the TextField expects a String. I'm casting the value as String.

In this example I created the TextField via AS. This is not a requirement. You could also have used a clip from the library or referenced a clip on the stage. I used AS to create everything since that keeps all of the elements in code above.

The Controller
The controller will create two buttons that call the add_one and subtract_one methods of the Model class. The controller can have many different manifestations. Often in Flash projects I find the controller is part of the View or part of the my main class.

In this example we'll make it a separate class. The class will extend Sprite, so that it will be a display object that appears on the stage.

As with the Model the Controller will take a reference to the Model as an argument of it's constructor function. This is the same as the View.

The Controller can also register with the Model to receive CHANGE events. This may or may not be needed it depends on what the does.

Here's the basic class for the view.

package {
   import flash.display.*;
   import flash.events.*;

   public class Controller extends Sprite {
       private var _model:Model;

       public function Controller( model:Model ) {
           _model = model;
       }
   }
}

For this example I will create two buttons with AS and add them to the stage. I'm creating the buttons via AS so that the example code here will contain all of the elements. You could easily use clips from your library instead if that fit your project better.

package {
   import flash.display.*;
   import flash.events.*;

   public class Controller extends Sprite {
       private var _model:Model;

       private var _up:Sprite;
       private var _down:Sprite;

       public function Controller( model:Model ) {
           _model = model;

           _up = new Sprite();
           _up.graphics.beginFill( 0x000000 );
           _up.graphics.drawRect( 0, 0, 22, 22 );
           _up.graphics.endFill();

           _down = new Sprite();
           _down.graphics.beginFill( 0x000000 );
           _down.graphics.drawRect( 0, 0, 22, 22 );
           _down.graphics.endFill();

           addChild( _up );
           addChild( _down );

           _up.x = _down.x + _down.width + 4;

           _up.addEventListener( MouseEvent.CLICK, click_up );
           _down.addEventListener( MouseEvent.CLICK, click_down );
       }

       private function click_up( e:MouseEvent ):void {
           _model.add_one();
       }

       private function click_down( e:MouseEvent ):void {
           _model.subtract_one();
       }
   }
}

The code added above does the following.

It first defines two private variables _up and _down. These will hold a reference to the two Sprites I will use as buttons.

Next it creates the _up Sprite, then draws a small rectangle 22px by 22px inside _up. Then it creates the _down Sprite and draw another box. Then I added both boxes to the display list. Next I position _up 4 pixels to the right of _down.

Last I added an event listener to each _up and _down. These call the two handlers, click_up and click_down, which are defined below.

Notice the two handlers, click_up and click_down, each use the reference _model to call on the Model's public methods.

Putting all together
Now that we have the classes written how do you put it all together? In a nutshell, make an instance of Model, then make an instance of View and Controller passing your model instance along. Since View and Controller are both display Objects you'll need to add them to the display list and position them.

Try it for yourself. Make a new Flash file. Save it into the folder containing the Model.as, View.as and Controller.as files. Then create a new AS file, we'll use this as the Document class for the example, save the file as Main.as, it must go in the same folder as the Fla.

Next add the following code to Main.as.

package {
   import flash.display.*;
   import flash.events.*;

   public class Main extends MovieClip {
       public function Main() {
           var model:Model = new Model();

           var view:View = new View( model );
           var controller:Controller = new Controller( model );

           addChild( view );
           addChild( controller );

           view.x = 100;
           view.y = 100;
           controller.x = 100;
           controller.y = view.y + view.height + 4;
       }
   }
}

I colored the Model in red, the View in blue and the Controller in green.

Test the Movie and you should see two small black squares on the stage. Clicking one should make the View display the value stored in Model and increase the value by 1. Clicking the other should decrease the value stored in Model by 1 and cause the View to display the updated value.

How does it all work?
The Model is set up to dispatch change events whenever the data it stores changes. Model provides some methods to allow the data to be changed. In this case add_one and subtract_one add or subtract one and dispatch a change event.

The View is passed a reference to Model and registers to listener for change events. If something changes in the Model, View is notified and then gets the information it wants from Model using Model's get_data method.

The Controller is passed a reference to Model. Through this reference it calls Model's methods that change the data it stores. In this it's the add_one and subtract_one methods.

Why use this Design Pattern
Using the design pattern separates the basic elements that we are working with into distinct classes that each manage one aspect of the system. This provides several advantages.

It makes editing easier. Since functions of the system are contained in separate classes, making a change is easier since we can edit the class responsible for that system. Rather than untangling code mixed with other systems.

It makes expanding the system much easier. To add another controller or View element to the system becomes as easy as writing a new class. Each new View or Controller will follow the same arrangement also. They will receive a reference to Model. View's will also register for change events.

The Model can also be more easily expanded for the same reasons.

MVC Gallery
The MVC pattern makes a great choice for a Flash image gallery. Imagine a gallery that displays a large image, a set of smaller thumbnail images, some buttons to advance to the next or previous image, and a text field to display a description of the image.

The MVC pattern might break these elements into classes.

Gallery - This class will act as the Model for our system. It will store a list of all of the images, their descriptions and the thumbnail image.
GalleryViewImage - This class will act as a View. It will load and display the large image.
GalleryViewDetails - This class will act as a View. It will display the text description for the current image.
GalleryNextPrev - This class will act as a Controller. It will generate two buttons. Click one button will advance to the next image, clicking the other go back to the previous image.
GalleryViewIcons - This will act as both a View and a Controller. The class will display a list of thumbnail images. Clicking any of these images will display the large version of that image.

These are main classes use in our system. There will be a couple other classes used but these are the classes that relate to MVC pattern.

Using XML with the Gallery
The gallery will use XML to describe the url of the images, their descriptions and the urls to their thumbnail images. If you are not familiar with XML please see the chapter on XML.

XML makes a great system to hold and organize all of the information that describes the gallery. It also makes our gallery flexible, since the XML file can be easily updated to change the images displayed in the gallery. It makes the entire project flexible in that you can reuse the swf with a different set of images and a different XML file in another site with out having create a new project.

This project will make use the XMLLoader class to load XML. Please see the chapter on this class if you are familiar with it and need more info.

The Gallery XML
The XML file we'll use for this project will be fairly simple. We'll use <gallery> as the top level tag. Inside which will be a series of <image> tags. One for each image in the Gallery. For example:

<gallery>

<image></image>
<image></image>
...

</gallery>

We'll have as many <image> tags as there are images in our gallery.

Each <image> tag will hold tags that describe each image. For each image we'll need a URL to the image, a URL to the thumnail image, and a text description of the image. For these we'll use the following tags:

<url> - URL to the image
<icon> - URL to the thumbnail image
<desc> - Text Description of the image

The finished XML file might look something like this:

<gallery>
   <image>
       <url>images/IMG_0089.jpg</url>
       <icon>images/IMG_0089_icon.jpg</icon>
       <desc>A picture of the SF skyline.</desc>
   </image>
   <image>
       <url>images/IMG_0115.jpg</url>
       <icon>images/IMG_0115_icon.jpg</icon>
       <desc>Another picture</desc>
   </image>
    ...
</gallery>

You can repeat each <image> tag and it's nested tags once for each image in your gallery.

Loading Images
This project will use the ImageLoader Class to load both the large image and the thumbnail images. Be sure to read the chapter on these classes if you are not familiar with them.

By using a class to cover this functionality we save time. It makes our job easier and our projects better.

The Gallery class
The Gallery class will act as the Model for our system. It will store a list of the images, really it will store the URL to each image as a string, we'll rely on a View to actually load and display the image. Gallery will also store the description for each image and the URL to each thumbnail image.

The Gallery will need to provide public functions to accommodate it's views. Since the GalleryViewImage will display the current image, we'll include an index property that keeps track of the current image on display. This will also work with the GalleryViewDesc. The controller will set increment the index to display the next image. Or decrement the index to show the previous image.

The Gallery class also needs a method to provide a list of the URLs of the thumbnail images. This will be needed by the GalleryViewThumbnails class.

The Gallery class will extend EventDispatcher since will need to dispatch event messages. The Gallery will dispatch two types of events. It will the CHANGE event in the same way that the Simple MVC example used it. Since it will load the XML file it will also dispatch a COMPLETE event to notify us when the XML file has been loaded.

Here's the basic Gallery class:

package {
   import flash.events.*;
   import com.webdevils.net.XMLLoader;
   import com.webdevils.utils.BasicIterator;

   public class Gallery extends EventDispatcher {
       private var _gallery_xml:XMLList;
       private var _index:uint;

       public function Gallery( url:String ) {
           load( url );
       }

       // ******* Private Functions *******
       private function on_complete( e:Event ):void {
           _gallery_xml = new XML( e.target.data ).image;
           _index = 0;
           dispatchEvent( new Event( Event.COMPLETE ) );
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       // ******* Public Functions ********
       public function load( url:String ):void {
           var xml:XMLLoader = new XMLLoader( url );
           xml.addEventListener( Event.COMPLETE, on_complete );
       }

       public function next():void {
           if ( _index < _gallery_xml.length() - 1 ) {
               _index ++;
           }
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       public function prev():void {
           if ( _index > 0 ) {
               _index --;
           }
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       public function hasNext():Boolean {
           return Boolean( _index < _gallery_xml.length() - 1 );
       }

       public function hasPrev():Boolean {
           return Boolean( _index > 0 );
       }

       public function iterate_icons():BasicIterator {
           var icons_array:Array = new Array();
           var it:XMLIterator = new XMLIterator( _gallery_xml );
           while( it.hasNext() ) {
               icons_array.push( it.next().icon.toString() );
           }
           return new BasicIterator( icons_array );
       }


       // Getter Setters
       public function get index():uint {
           return _index;
       }

       public function get length():uint {
           return _gallery_xml.length();
       }

       public function set index( n:uint ):void {
           _index = n;
           dispatchEvent( new Event( Event.CHANGE ) );
       }

       public function get image():String {
           return _gallery_xml[ _index ].url.toString();
       }

       public function get desc():String {
           return _gallery_xml[ _index ].desc.toString();
       }

   }
}

Gallery properties
The Gallery class has two private properties _gallery_xml and _index. The _gallery_xml property will hold an XML object that describes the gallery. The _index property holds the index of the current image on display in the Gallery.

Gallery methods
The Gallery class provides a few methods. They are all pretty short. Most of the methods are public and have as their goal providing information for the various Views and allowing the Controller to make changes to the Gallery.

The Constructor takes a single parameter, the URL to the gallery XML file to load. This is a String. The Constructor just passes this item on to the load method which actually starts the loading process.

public function Gallery( url:String ) {
   load( url );
}

The load method takes a single parameter, the URL of the file XML file to load. This method creates a new instance of the XMLLoader class and passes the url.

Then we add an EventListener to our XMLLoader instance. This listener listens for the COMPLETE event which is handled by the on_complete method.

Making this method public makes the class a little more flexible.

public function load( url:String ):void {
   var xml:XMLLoader = new XMLLoader( url );
   xml.addEventListener( Event.COMPLETE, on_complete );
}

The on_complete method is where store the XML file we just loaded and notify any listeners that we have completed the loading process. This method is private since it makes no sense for any other class to have access to it.

We'll also set _index to 0 here. After loading our XML file the Gallery should be viewing the first image.

We also dispatch a CHANGE event to any of our listeners. So all the listeners will update and draw themselves based on the new data loaded.

private function on_complete( e:Event ):void {
   _gallery_xml = new XML( e.target.data ).image;
   _index = 0;
   dispatchEvent( new Event( Event.COMPLETE ) );
   dispatchEvent( new Event( Event.CHANGE ) );
}

To enable the Next and Previous buttons the Gallery class provides the next and prev methods. These are very similar. They increment or decrement the _index by 1. They also check the current value of of _index to make sure that it doesn't get out of range. Last of all they dispatch a CHANGE event.

To make sure _index does not reference an index beyond the last image we check the length of the XMLList, _gallery_xml. Note the of the XMLList tells the number of items in the list, items in he list are indexed starting on 0. So we need to subtract 1 from length to get the number of the last index.

public function next():void {
   if ( _index < _gallery_xml.length() - 1 ) {
       _index ++;
   }
   dispatchEvent( new Event( Event.CHANGE ) );
}

public function prev():void {
   if ( _index > 0 ) {
       _index --;
   }
   dispatchEvent( new Event( Event.CHANGE ) );
}

We will want the next and previous buttons to know when there are images available. And, when there are no images available we'll want the next button to disable itself. The same goes for the previous button when we're on the first image. For that we'll use the hasNext and hasPrev methods.

These two methods return a Boolean (true or false). The first, hasNext, checks that the _index is less than the length of the XMLList -1. If this is true, there is a next image to view.

The second method, hasPrev, checks that _index is greater than 0. If it is there is a previous image available.

public function hasNext():Boolean {
   return Boolean( _index < _gallery_xml.length() - 1 );
}

public function hasPrev():Boolean {
   return Boolean( _index > 0 );
}

The iterate_icons method is used to list all of the URLs to the thumbnail images. This function makes use of the Iterator Patern be sure to read the section on Iterator.

The first step is to make an a new empty Array. Then create an XMLIterator to iterate through the _gallery_xml XMLList. We get the URLs of the thumbnails from the icon element and add them to the icons_array. Last, return an Iterator for the icon_array.

public function iterate_icons():BasicIterator {
   var icons_array:Array = new Array();
   var it:XMLIterator = new XMLIterator( _gallery_xml );
   while( it.hasNext() ) {
       icons_array.push( it.next().icon.toString() );
   }
   return new BasicIterator( icons_array );
}

The last four functions are getter setter functions, see the chapter on functions for more info on these. These allows us us to get and set properties of the Gallery class. This is a great example of getters and setters at work.

The set index function allows us to set the value of _index. In the same way that we would set the value of any property for any other object. Why using a setter function is so important here is that changing the value of _index means that the View and Controller need to be notified. If we had used a public property, you could change the value from outside of the class and Gallery would have no idea that the value you had changed. using a setter here allows our class to run the function when the value changes.

Notice the setter function dispatches a CHANGE event after the value of _index is set to a new value. I included the getter for index since a View or Controller for Gallery might need to know what the current index was.

public function get index():uint {
   return _index;
}

public function set index( n:uint ):void {
   _index = n;
   dispatchEvent( new Event( Event.CHANGE ) );
}

Notice that I used the name index for the name of each function. Accessing these two getter and setter functions from outside the class we'll use the name index as the property name. For example:

_gallery.index = 5; // Sets _index

or

trace( _gallery.index ); // Gets _index

Our main view will need to know what the URL for image at the current index is. For this I used a simple getter function called image. This makes it easy for a View to get the URL from the image property.

public function get image():String {
   return _gallery_xml[ _index ].url.toString();
}

For example any class with a reference to a Gallery instance could get the image at the current index with:

_gallery.index

The last getter returns the description for the current image. Again I used a simple getter named desc.

public function get desc():String {
   return _gallery_xml[ _index ].desc.toString();
}

Any View that needs the description for the current image can use the following:

_gallery.desc

A class might need to know how many images are in the Gallery. We can use the length() method of the XMLList class to find out how many images nodes there are.

public function get length():uint {
   return _gallery_xml.length();
}

Testing the Gallery class
To get a better understanding of the Gallery class test it out. Taking a good look at the Gallery itself is a good idea and will give you a better idea of it's role in the MVC pattern.

For this test we'll use the trace statement. If you're not familiar with this or need more information see the chapter on trace.

Create a new Fla file in the same folder as the Gallery.as file. In this case we'll add the script to the timeline on frame 1. This will be convenient for the test.

Make a new instance of the Gallery class:

var gallery:Gallery = new Gallery( "slideshow.xml" );

Next, set add a COMPLETE event to the gallery. The gallery needs to load it's XML before it has any data to work with. Add the following:

gallery.addEventListener( Event.COMPLETE, on_complete );
function on_complete( e:Event ):void {
    // test code here
}

From here we can test all of the Gallery classes methods and properties. Each of the followoing lines will test a property or method of the Gallery class. each line needs to be added to the on_complete handler.

Find the current index (add the following line to the on_complete handler):

trace( "The current index is:" + gallery.index );

Test your Movie. The Output window should open and show:

The current index is:0

It shows 0 because the first index, that is the position of the first image is 0.

Try another. Test the length.

trace( "Length:" + gallery.length );

Next get the URL to the current image:

trace( gallery.image );

Now advance to the next image and then test the image property again:

gallery.next();
trace( gallery.image );

You can see the Gallery contains and organizes all of the information/data needed to run the gallery. It doesn't display images or make things happen on it's own. Instead it makes these features available via it's properties and methods. This is the goal of the Model in MVC.

GalleryViewImage
The GalleryViewImage class will be used to display the current image. This is the image set by _index within the Gallery class. The gallery class will supply the URL to the GalleryViewImage will load and display the Image.

To make things easy for ourselves we'll use an instance of the ImageLoader class. If you are not familiar with this class be sure to read it's chapter. Basically this class encapsulates the Loader class and adds a few features. You could build your own View around the Loader class or another class instead of ImageLoader also.

This class extends Sprite so we can add it to the stage. Since it is a View, it takes a Gallery instance as an argument in it's constructor and registers with the Gallery instance for CHANGE events.

I've also added arguments for width and height. Since the ImageLoader class requires these, I can easily pass them along when making an instance of GalleryViewImage. This will allow us to easily set up the class to work with different sized images when using the class with different projects.

The only other function here is on_change. In this View on_change gets the image value, vie Gallery's image getter. This returns the URL to current, so we pass it along to out ImageLoader instance's load_image method, and ImageLoader loads the new image.

package {
   import flash.display.*;
   import flash.events.*;
   import com.webdevils.display.ImageLoader;

   public class GalleryViewImage extends Sprite {
       private var _gallery:Gallery;
       private var _image:ImageLoader;

       public function GalleryViewImage( gallery:Gallery, w:Number, h:Number ) {
           _gallery = gallery;
           _gallery.addEventListener( Event.CHANGE, on_change );
           _image = new ImageLoader( "", w, h );
           addChild( _image );
       }

       private function on_change( e:Event ):void {
           _image.load_image( _gallery.image );
       }
   }
}

GalleryViewDetails
This is another View that displays the description for the current image. It is very similar to the GalleryViewImage class. With the difference being it contains a TextField in place of the ImageLoader.

Again this class follows the pattern for Views. It takes a reference to the Model, in our case a Gallery instance in the constructor. It saves a reference to the Model, and registers with the Model for CHANGE events.

The on_change handler gets the description for the current image through Gallery's desc getter.

package {
   import flash.display.*;
   import flash.events.*;
   import flash.text.*;

   public class GalleryViewDetails extends Sprite {
       private var _gallery:Gallery;
       private var _txt:TextField;

       public function GalleryViewDetails( gallery:Gallery,w:Number,h:Number ) {
           _gallery = gallery;
           _gallery.addEventListener( Event.CHANGE, on_change );

           var fmt:TextFormat = new TextFormat();
           fmt.font = "Verdana";
           fmt.size = 16;

           _txt = new TextField();
           _txt.defaultTextFormat = fmt;
           addChild( _txt );
           _txt.width = w;
           _txt.height = h;
       }

       private function on_change( e:Event ):void {
           _txt.text = _gallery.desc;
       }
   }
}

GalleryPrevNext
This class acts as a Controller. It displays two buttons. In this example I have created the buttons via AS to keep the example contained in the text of the class. You could easily have used MoveClips from your library instead.

The two buttons when click call on the next and prev methods of the Gallery class. Which either advances Gallery to the next image sends it to the previous image. Gallery then, of course, in good MVC style, dispatches a CHANGE event, to notify it's Views, which then update their display.

This class also registers for CHANGE events. The on_change handler in GalleryPrevNext, is used to enable and disable the next button when there is not next image, or disable the previous button when there is not previous image. In this way this class acts as a View also.

package {
   import flash.display.*;
   import flash.events.*;

   public class GalleryPrevNext extends Sprite {
       private var _gallery:Gallery;
       private var _next:Sprite;
       private var _prev:Sprite;

       public function GalleryPrevNext( gallery:Gallery ) {
           _gallery = gallery;
           _gallery.addEventListener( Event.CHANGE, on_change );

           make_buttons();
       }

       private function make_buttons():void {
           _next = new Sprite();
           _next.graphics.beginFill( 0x999999 );
           _next.graphics.drawRect( 0, 0, 32, 32 );
           _next.graphics.endFill();
           addChild( _next );

           _prev = new Sprite();
           _prev.graphics.beginFill( 0x999999 );
           _prev.graphics.drawRect( 0, 0, 32, 32 );
           _prev.graphics.endFill();
           addChild( _prev );

           _next.x = _prev.width + 6;

           _next.addEventListener( MouseEvent.CLICK, click_next );
           _prev.addEventListener( MouseEvent.CLICK, click_prev );
       }

       private function click_next( e:MouseEvent ):void {
           _gallery.next();
       }

       private function click_prev( e:MouseEvent ):void {
           _gallery.prev();
       }

       private function on_change( e:Event ):void {
           if ( _gallery.hasNext() ) {
               _next.alpha = 1;
               _next.mouseEnabled = true;
           } else {
               _next.alpha = .5;
               _next.mouseEnabled = false;
           }

           if ( _gallery.hasPrev() ) {
               _prev.alpha = 1;
               _prev.mouseEnabled = true;
           } else {
               _prev.alpha = .5;
               _prev.mouseEnabled = false;
           }
       }
   }
}

GalleryViewIcons
The GalleryViewIcons Class is probably the most difficult class of the bunch. This class needs to display the icons and allow a click to load the image associated with the icon.

Since there may be more icons than might fit in the area you've designated for the icons, GalleryViewIcons will need to scroll or paginate the icons.

There may be even more features associated with this class. The GalleryViewIcons class could be a Model View Controller system all to itself. In the example here we won't go that far. A class this complex definitely needs to be broken down into several smaller classes.

The icons will need to load the icon image, display an over and selected state and remember the index of the image they are associated with.

The icons will need a container. The container will need to arrange and display the icons. It will need to define an area where they appear and mask off this area. The container may also need to move or paginate the icons to show icons that may not be visible under the mask.

There may be other or alternative features needed or alternate approaches to what I have described here. We'll just work with this feature set for the examples.

The GalleryIcon class
This class will load the icon image and act as a button. As a button the icon will need to show an up, over, down and disabled face.

Several approaches could be taken for this class. The example will create use a border for the selected state and modify the color of the image for the rollover and down states.

Create a new class file. Save it as GalleryIcon

Create a slide show presentation using Gallery
This Gallery makes a great base for a lot of applications. Using just the GalleryPrevNext class as the Controller you could create a linear slideshow/presentation. With a new Controller, that used the keyboard to display the next and previous image the application becomes very practical to use.

Date and Time

2009-11-04T13:36:00.001-08:00

Date and Time
Flash provides the Date Class to handle the date and time. Creating a new instance of the Date Class generates an object with properties that contain the Year, Month, Date, and Time. This information is taken from the client operating system, so if the time or date is wrong on the system Flash is not responsible.

The Date class can also take parameters naming a year, month, date and time to generate a Date object for any date and time. This is useful when creating a calendar, since a calendar might display all of the days a in a month.

Using the Date Class in this way takes care of all of the troubles with calculating days in the month or leap years.

Get the day and time
To get the day and time make a new instance of the Date class with no parameters. The following lines of code:

var now:Date = new Date();
trace( now );

Should generate something like this in the output window.

Sat Oct 31 15:18:22 GMT-0700 2009

To get the individual elements like year, month, date, day and time, you can access the properties of the date instance you have created. For example:

var now:Date = new Date();
trace( now.month, now.date, now.fullYear );

This displays something like:

9 31 2009

Note: month is displayed as a number. Looking at the first example you can see it's Halloween when I wrote this, so the month should 10. Flash numbers the Months 0 to 11. Rather than 1 to 12. So you'll need to add one if you want to display the digit and expect everyone to understand it.

The same is true for the Date.day property. This property returns an integer between 0 and 6. where 0 is Mon and 1 is Tue etc.

To get a simple easy to read day month and year you can use Date.toLocaleDateString(). For example:

var now:Date = new Date();
trace( now.toLocaleDateString() );

This outputs something like:

Sat Oct 31 2009

Which is very readable. Here's a sampling of a few of the functions supplied by the Date class to produce the date and time in different formats:

Date.toLocaleDateString() - Sat Oct 31 2009
Date.toLocaleString() - Sat Oct 31 2009 03:34:36 PM
Date.toLocaleTimeString() - 03:34:36 PM
Date.toString() - Sat Oct 31 15:34:36 GMT-0700 2009
Date.toTimeString() - 15:34:36 GMT-0700
Date.toUTCString() - Sat Oct 31 22:34:36 2009 UTC

Very interesting.

Making a clock
To make clock with the Date class you'll need to create a new instance of the Date Class each time period that you want to update your clock.

For example if you want your clock to update once a minute, you would need to make a new instance of the Date class each minute.

if you want to make a clock that includes seconds, you'll need to make a new Date instance every second.

Use the Timer class to set up a timer event that occurs at your time period. For example the following creates a TextField that displays the time and updates every second. For more info on the Timer class see Timer Recipes.

var time_txt:TextField = new TextField();
time_txt.width = 200;
addChild( time_txt );

var timer:Timer = new Timer( 1000 );
timer.addEventListener( TimerEvent.TIMER, on_timer );
timer.start();

function on_timer( e:TimerEvent ):void {
   time_txt.text = new Date().toLocaleString();
}

Getting all the days of the current month
This would be the first step to building a calendar application. It could also be used in many other ways. The basic idea is to get the current month and year then make Date Objects using that month and year each with a different day.

If you make a Date Object with a day that is greater than the number of days in the current month the month will rollover to the next month. For example, imagine you make a Date Object for Feb 19 (and the year is not a leap year). In this case the Date object created will actually show the date as March 1.

The same happens with the year. Making a Date Object with a date of Dec 32 2009, the date of the Object would actually show as Jan 1 2010.

This recipe requires a loop to generate all of the days of the month. Be sure to read the recipes on loops. The following traces each day of the current month.

var now:Date = new Date();
var current_year:int = now.fullYear;
var current_month:int = now.month;
for ( var d:uint = 1; d < 32; d++ ) {
   var date:Date = new Date( current_year, current_month, d );
   if ( date.month == current_month ) {
       trace( date );
   }
}

The code above can be broken down into three parts.

The first, lines 1, 2 and 3, make a new Date object with the current date. Then we get the year and month and store them in the variables current_year and current_month for ease of use.

Second, we set up a for loop that will count from 1 to 31, using the variable d to hold the number of the count.

Last, with each loop we make a new Date object from the current_year and current_month, using d as the date. The idea is to make Date objects with the current years and month for the dates 1 to 31. Since not all months have 31 days, we check the month of each new Date to see if the month is different. For example November has only 30 days, so creating a Date Object with month 11 and day 31, will return a Date with Month 12 and date 1.

Popup footer/Sidebar

2009-11-02T13:56:00.007-08:00

Popup footer/Sidebar

This recipe creates a movieclip that slides on from one of the edges of the stage as cursor gets within a certain distance of that edge. The immediate example shows a movieclip sliding up from the below the bottom edge of the stage.

The example is built from 2 movieclips one nested within the other. The first movieclip hit_mc has been assigned listeners, listening for the ROLL_OVER and ROLL_OUT events. While the inner, footer_mc, clip is animated. Here's the arrangement:

hit_mc

footer_mc

At first thought you might think to place both clips on the stage, rather than nesting one within the other. This the problem of causing the clip in front to block mouse events for the clip that is behind. By nesting the clips both can still receive mouse events.

The problem with two clips two separate clips, as opposed to the nested clips. Is that rolling over the first clip would start the second moving up. When the second clip interposed itself between the mouse and the first clip, the first clip would get a roll out message.

To create the motion for this example I used tweener. See the Tweener recipes for more information on using Tweener.

The registration point for footer_mc was set to the bottom left corner for this example. The position of registration point will determine the y values that you will assign to the Tweener tweens to hide and show the footer.

Here's the code that I used for the example fla.

import caurina.transitions.Tweener;

hit_mc.addEventListener( MouseEvent.MOUSE_OVER, show_footer );
hit_mc.addEventListener( MouseEvent.MOUSE_OUT, hide_footer );

function show_footer( e:MouseEvent ):void {
Tweener.addTween( hit_mc.footer_mc, { y:0, time:1 } );
}

function hide_footer( e:MouseEvent ):void {
Tweener.addTween( hit_mc.footer_mc, { y:hit_mc.footer_mc.height, time:1 } );
}

Note, since footer_mc is nested within hit_mc I refer to it in the code above with

hit_mc.footer_mc

Also note, in the exmaple movie I used a rectangular shape on the lowest layer of hit_mc (its below footer_mc). I gave this shape a fill with a 10% transparency. This could be 0% transparent to make it completely invisible. This must be a filled shape.

I used a 10% transparent fill to show where the hit area was for the example.

Popup Footer/Sidebar 2
An obvious extension of this recipe is to add interactive elements to the popup. This is easily one by adding those elements nested within the footer_mc. For example imagine you have a movieclip named button_mc. Using the previous example as a starting point, this clip would be placed within footer_mc. The arrangement could be described like this:

hit_mc

footer_mc

button_mc

Form here the interactive elements can be treated the same as they are treated in any other recipe keeping in mind that the clips must be targeted as:

hit_mc.footer_mc.button_mc

Where button_mc could be the name of any clip nested within the footer.

Sticky Footer

2009-11-02T13:56:00.005-08:00

Sticky Footer

The sticky footer is an element that sticks to the bottom of your Flash page. Imagine a MovieClip that always stays at the bottom of the stage even when the stage is resized.

Note this recipe makes use of the Full Browser Flash recipe.

The basic ingredients for this recipe are the Event.RESIZE event and stage.stageHeight and stage.stageWidth properties.

The Event.RESIZE event is dispatched when ever the stage changes size. Adding a listener for this event you can have the handler for the event look at the new size of the stage and reposition elements on the stage.

stage.addEventListener( Event.RESIZE, resize_handler );

Setting up the art. If you have a movieClip that will position itself at the bottom of the stage, placing the registration point of this clip at the bottom of the clip makes the process easier. Since setting the y of the clip to the height of the stage align the clip at the bottom edge of the stage.

footer_mc.y = stage.stageHeight;

If the registration point is at the top of the clip you can position the clip at stage.stageHeight - clip.height.

footer_mc.y = stage.stageHeight - footer_mc.height;

In order for Flash to place elements correctly the stage.align and stage.scaleMode properties need to be set so that Flash is keeping the registration point of the stage fixed in the upper left corner and is not scaling the contents of the stage as the stage is scaled.

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

The whole recipe might look like this. Assume that you have a MovieClip on the stage with the registration point aligned at the bottom of the artwork. This MovieClip is named footer_mc.

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

stage.addEventListener( Event.RESIZE, on_resize );

function on_resize( e:Event ):void {
footer_mc.y = stage.stageHeight;
}

Testing the recipe:
Testing the movie in flash. Try resizing the stage. You should see the MovieClip footer_mc move to align itself with the bottom of the stage as the stage is resized.

Anomalies:
You may notice that the motion is a little jerky when testing in Flash. Don't worry, the repositioning of the clip will be much smoother in a browser or in the Flash Player.

Details:
To position the footer at the bottom of the stage when the movie begins, you can either place the clip on the stage at the correct position on the stage. If this not possible and or you need to preposition the clip with AS, you can do that with:

footer_mc.y = stage.stageHeight;

You'll need execute this line outside of the resize handler. Since the resize handler will only be called after the stage changes size. Placing the line above on the timeline or in the Constructor of a Class will probably accomplish this. You may need to place it in handler for the ADDED_TO_STAGE event in some cases.

Sticky Footer 2: Adjustable width
The sticky footer is useful in the first configuration. But, often the stage will not only change height, it will also change in width. In many cases you will want your footer to expand to fill the width of the stage.

Scaling footer_mc is not acceptable as everything inside the footer_mc will scale with it. To keep a consistent background in the footer that can cover the width of the stage requires an extra movie clip nested within footer_mc. Imagine this arrangement:

footer_mc

back_mc

The script below sets the width of back_mc to the width of the stage whenever the stage is resized. This is the same as the code above with the addition line of code in red and the extra movieclip nested inside of footer_mc.

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

stage.addEventListener( Event.RESIZE, on_resize );

function on_resize( e:Event ):void {
footer_mc.y = stage.stageHeight;
footer_mc.back_mc.width = stage.stageWidth;
}

Sticky Footer 3: Add buttons to the footer
You may want to add interactive elements to the footer. This easily accomplished by adding these elements nested within the footer_mc.

In this case all buttons are added inside of footer_mc. From the main timeline or document class these buttons would accessed as:

footer_mc.button_mc

Sticky Footer Popup
The Sticky Footer recipe can be combined with the Popup footer sidebar recipe. Here the footer_mc sticks to the bottom of the stage even after it has been resized.

Sticky Footer

2009-11-02T13:56:00.003-08:00

back_mc

Tweener Recipes

2009-11-02T13:56:00.001-08:00

Tweener Recipes

Introduction
Tweener is a set of Actionscript classes that animate the properties of objects in Flash. In it's most common useage Tweener is used to animate MovieClips on the stage. Tweener is not limited to animating MovieClips, it can be used to animate just about any property of any Object in Flash. This includes animating the Volume or Pan of a Sound. The text in a Text Field and more.

When it comes to MovieClips Tweener can animate all of the standard MovieClip properties, like x, y, rotation and scaleX and scaleY. Tweener can also apply filters to Objects, and animate the properties of the filters.

Tweener is flexible and easy to work with.

Tweener requires only that copy the class library into the folder with your project and import the class in any script that will use it.

Downloading Tweener

Working with the Tweener class library
The Tweener class library is contained with the folder caurina. In order for any project to use Tweener you must place the caurina folder in the same folder with your fla.

For more information about working with class files and class libraries see the Working with Classes recipe.

Some recipes using Tweener

Basic Tweener recipes: Making things move
The following recipe makes things move with Tweener. Many of students, after learning Tweener, have said they find it easier to work with than using the timeline to create motion.

You must place the caurina folder in the same folder as the fla for this example.

The basic recipe for Tweener motion is first import the class with the following line.

import caurina.transitions.Tweener;

From here create a Tween by calling Tweener's static addTween function and passing two parameters, the target clip and an object describing the tween or motion that wish to create.

For example imagine you wanted to make an object move to the center of the stage, you might use the following:

Tweener.addTween( target, {x:275, time:1} );

Animate multiple properties at the same time
To animate more than one property with Tweener just add them to the tween object. For example imagine you wanted to animate both scaleX and scaleY at the same time. You could use the following:

Tweener.addTween( target, {scaleX:2, scaleY:2, time:1} );

Setting the ease type
The type of easing applied with Tweener is set via the transition property of the Tween object. The transitions properties are listed as part of the documentation.

Here's an example of an elastic ease out:

Tweener.addTween( target, {x:275, time:1, transition:"elasticEaseOut" } );

Animating Filter Properties
You can animate any of the filter properties with Tweener. You must first import the FilterShortcuts class and initialize the class with the following two lines:

import caurina.transitions.properties.FilterShortcuts;
FilterShortcuts.init();

To animate a filter you'll need to consult the Tweener documentation to check the property's name. The following line animates the _Blur_blurX property.

Tweener.addTween( target, {_Blur_blurX:40, time:2} );

Bonus: You can apply a Filter to a clip with Tweener without having to animate the Filter. If you have already used Tweener in a project it's easier to apply a Filter this way. Just use addTween() without the time parameter. The following applies a drop shadow the target with a 12 pixel blur on the x and y axis:

Tweener.addTween( astronaut_mc, { _DropShadow_blurX:12, _DropShadow_blurY:12 } );

Exluding the time property from the tween object causes the properties listed in the tween object to be applied immediately.

Note: Some filters may not become visible until certain properties are set.

Buttons

2009-11-02T13:55:00.003-08:00

Buttons
Buttons could be considered the core interactive element in any Flash project you might create. Buttons can take so many different forms that for this discussion we'll consider just about anything you can click on a Button.

There's a lot that can be done with buttons. We'll divide this into two categories. What the button does itself when you interact with it, and what actions the button invokes in your application when you interact with it.

For example, a button might glow, scale up and reflection might play across it's surface when you move the cursor over the button. These things happen tothe button. When you click the button your application might load an image. This is an action that your button is invoking in your application.

Flash provides several different ways to create buttons. The two most common options are the Button Symbol and the MovieClip Symbol. Each has it's own options. For most situations the MovieClip provides more options.

The Button Symbol
The Button symbol can be used to create a Button in flash. The Button Symbol is similar the MovieClip Symbol but only has 4 frames. These frames are labeled Up, Over, Down and Hit. The Button Symbol automatically jumps to these frames as the cursor interacts with the Symbol.

Up - Frame is shown when the cursor is not over the clip
Over - Frame is shown when the cursor is over the clip but not pressed
Down - Frame is shown when the mouse is pressed over the clip
Hit - Frame is never displayed, it sets the clickable area for the clip

Create a new Button by choosing Modify > Convert to Symbol or Insert > New Symbol. And then choosing Button from the Type menu. At this point you can draw your artwork on the various frames.

Note: Be sure to set the Hit frame. Best to use a filled rectangle. Do not use an odd shape or text for the Hit frame. This will make your button difficult to interact with.

Note: Buttons can use layers just like MovieClips. Feel free to use as many layers as you like to create the art that you envision.

Note: You can nest animated MovieClip Symbols at the Over and Down frames within a a Button and those clips will play when the button reaches their frame. But, this is not a good method to create buttons with animated states. Better to use one of the MovieClip buttons described later.

Note: Button clips only support a limited amount of Actionscript.

MovieClip Buttons
The MovieClip is the King of symbols n Flash it can do everything. It can also mimic all of the functionality of the Button symbol and more.

To create a basic Button with Up, Over and Down frames, create a new MovieClip Symbol with Insert > New Symbol or Modify > Convert to Symbol and set the Type to MovieClip. Inside the new Symbol add three key frames and set the Frame Label at each of these frames to _up, _over and _down. These names must be spelled exactly as they appear here.

_up
_over
_down

These combined with the MovieClip's buttonMode property allows the MovieClip to jump these key frames as the cursor interacts with the clip, much in the same way the Button Symbol works.

Note: The MovieClip will automatically play unless you stop it with a stop() action. This can be done by targeting the clip or it can be placed on the first frame of the clip.

The MovieClip doesn't provide a Hit frame. But you can easily simulate this by adding a layer containing a filled shape with a transparent color. Make sure this layer is below the other layers and extends across all of the frames you are using.

Buttons

2009-11-02T13:55:00.001-08:00

Up - Frame is shown when the cursor is not over the clip
Over - Frame is shown when the cursor is over the clip but not pressed
Down - Frame is shown when the mouse is pressed over the clip
Hit - Frame is never displayed, it sets the clickable area for the clip

_up
_over
_down

Drag and Drop

2009-11-02T13:54:00.001-08:00

Drag and Drop

Dragging clips on the stage is easy to do. This recipe is built on a few simple ideas.

First to get an object to follow the mouse around all Sprite and MovieClip classes share the startDrag() and stopDrag() methods. These methods do exactly what their names imply. The startDrag() method starts dragging a clip, while stopDrag() ends the drag.

Making a click and drag
This type of interactivity centers two events MOUSE_DOWN and MOUSE_UP. A drag always begins with a MOSUE_DOWN event and ends with a MOUSE_UP.

The key to making a reliable click and drag is to be sure to capture a MOUSE_UP event when the cursor is NOT over the target clip. Do this by also adding a MOUSE_UP event to the stage

Often as you drag a clip the cursor will end up outside the area of a clip. This can happen if you move the cursor beyond the boundaries of drag or if you move the cursor very fast, or drag the cursor outside the area of the stage and then release.

Setting up a simple drag
To create a simple drag, create a clip on the stage and assign it an instance name. For this example assume the name of the clip is drag_mc.

The code block below allows the clip drag_mc to be dragged all over the stage without limit.

drag_mc.addEventListener( MouseEvent.MOUSE_DOWN, on_press );

function on_press( e:MouseEvent ):void {
   drag_mc.startDrag();
   drag_mc.addEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
}

function on_release( e:MouseEvent ):void {
   drag_mc.stopDrag();
   drag_mc.removeEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
}

Explanation
The code block above works by adding an a MOUSE_DOWN event to the target clip. This event begins the dragging action.

The handler for this event, on_press, starts dragging the clip by calling startDrag(). Here we also add two more event listeners, listening for the MOUSE_UP event. One of these events is added to the target clip, drag_mc in this example. The other is added to the stage. By adding the MOSUE_UP event to the stage we can catch the MOUSE_UP event in the case where the mouse is released outside the area of the target clip. Note both of these listeners are handled with the same functions on_release.

The last part of the example is the on_release function. Here the dragging action is ended by calling stopDrag() on the target clip. Then we remove both of the MOUSE_UP event listeners.

Details
Note, when a clip is being dragged via the
startDrag() method Flash always rounds the x and y position of the clip
to the nearest whole number. This is usually not a problem. In cases
where a clip constrained to a vertical or horizontal line a clip may
shift a pixel to one side as it is being dragged. If this happens be
sure to check the x and y position of the clip and set the number to a
whole number.

Dragging from the center or dragging from an edge
The startDrag() method provides the option of dragging from the center or dragging from the point relative to the mouse when the drag was initiated.

Dragging from the center is a drag where the clip aligns it's registration point with the cursor when the drag begins.

Dragging from a relative point keeps the clip in the same relative position to the mouse as it is dragged.

Why use one method or the other? Center drag is good for games and situations where the position of the clip, as you drag it needs to aligned to the mouse in some way. Dragging relative is best for situations where you don't want the object to move when it is initially clicked. This is good for scroll bars and things like dragging images around on a light table.

This option is called lockCenter. Passing a true as the first parameter when calling startDrag() will force the clip to align at the registration point. Passing a false will cause the clip to move relative. Note false is the default value, so passing nothing defaults to a drag relative. The previous examples were working in this mode. Try out lockCenter with:

drag_mc.startDrag( true );

You should see the clip align it's registration point with the cursor.

Note: If the registration point is not in the center the clip will not align with the center. For example if the registration point is set in the upper left corner of the clip then the clip will appear to drag from the upper left corner. See registration point notes.

Limiting the area of a drag
Besides the lockCenter parameter startDrag() also takes an optional bounds parameter. This bounds parameter sets the boundaries for the drag action. The bounds defines a rectangle and during the drag the clip may only move within the rectangle.

The bounds parameter must be an instance of the Rectangle Class. The Rectangle Object object describes a rectangle using four properties, x, y, width and height. The x and y place the upper left corner of the rectangle. From that corner the width and height extend to define the area of the rectangle.

Try it out for yourself. Using the last example define a rectangle for the drag action. Below I have defined a Rectangle 300 by 200 pixels starting at x 100 and y 100. Notice that I set lockCenter to false for this example.

drag_mc.addEventListener( MouseEvent.MOUSE_DOWN, on_press );

function on_press( e:MouseEvent ):void {
    var bounds:Rectangle = new Rectangle( 100, 100, 300, 200 );
   drag_mc.startDrag( false, bounds );
   drag_mc.addEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
}

function on_release( e:MouseEvent ):void {
   drag_mc.stopDrag();
   drag_mc.removeEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
}

Note: To limit the drag to a horizontal line set the height of the bounds Rectangle to 0. To limit the drag to a vertical line set the width of the bounds to 0. For example, the following limits the drag to a horizontal line in the center of the stage, that stops 100 pixels from either side of the stage.

var bounds:Rectangle = new Rectangle( 100, 200, 350, 0 );

I came up with the numbers above by taking the left limit of 100 and setting that as the x. Then I vertical position and set that as y. Using the default stage size of 550 by 400, y of 200 is half the height 400. I wanted the right limit to stop 100 pixels from the right edge. Since the stage 550 width and I'm stopping 100 pixels from the left and right, I subtract 200 from the width for 350. Last, I don't want to move vertically so I set the height to 0.

You may have noticed testing these examples, that the the clip, if it starts outside the area of the drag, it is forced into the are when you start moving it. Often you will want to create a drag that works from the current position of the clip. The line below modifies the example so that the clip drags all the way across the stage at it's current y position.

var bounds:Rectangle = new Rectangle( 0, drag_mc.y, 550, 0 );
drag_mc.startDrag( false, bounds );

Note that I used drag_mc.y to set the y position for the bounds rectangle. This way the clip uses it's current position to set the drag.

Getting the Bounds of an Object
It is very convenient to use an object on the stage, such as another MovieClip, to define the rectangle used as bounds. This can be accomplished with the getRect() or getBounds() methods. These methods return a Rectangle that defines the are of the clip.

The getRect() and getBounds() methods are same with the difference that the rectangle returned by getRect() does not include any strokes, while getBounds() does include any strokes on the object in the area of the rectangle returned.

Both getRect() and getBounds() take a single parameter that sets the coordinate space. This should usually be set to the parent clip. In the example below I use the keyword this, since the script is written on the main timeline and both clips are contained on the main timeline.

var rect:Rectangle = bounds_mc.getRect( this );
drag_mc.startDrag( false, rect );

Note: getRect() and getBounds() return rectangles. If the object is not a rectangle the either function returns a rectangle that surrounds the Object, getBounds() would include any strokes, getRect() would ignore them.

Dragable Class
To make the drag scrip more portable you could create a class that could be added to any MovieClip to make that clip dragable. The code above could be added to a class that extends MovieClip (or Sprite).

This first example creates a Dragable class using inheritance.

The script below should be saved in an Actionscript file named Dragable.as. The Dragable class can then be assign as the Base Class of any MovieClip in your library to make it Dragable.

package {
   import flash.display.*;
   import flash.events.*;

   public class Dragable extends MovieClip {
       public function Dragable() {
           super();
           addEventListener( MouseEvent.MOUSE_DOWN, on_press );
       }

       private function on_press( e:MouseEvent ):void {
           addEventListener( MouseEvent.MOUSE_UP, on_release );
           stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
           startDrag();
       }

       private function on_release( e:MouseEvent ):void {
           removeEventListener( MouseEvent.MOUSE_UP, on_release );
           stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
           stopDrag();
       }
   }
}

You can also make instances of this class using the new keyword. In this case you'd need to add artwork to the Dragable instance and add it to the display to make it visible. For example the following creates a new instance of Dragable and draws a black ellipse inside it and adds it to the display list.

var dragable_mc:Dragable = new Dragable();
dragable_mc.graphics.beginFill( 0x000000 );
dragable_mc.graphics.drawEllipse( 0, 0, 32, 48 );
dragable_mc.graphics.endFill();
addChild( dragable_mc );

Dargable using Composition
MakeDragable has the same effect as the script above but accomplishes the effect via Composition.

package {
   import flash.display.*;
   import flash.events.*;

   public class MakeDragable {
       private var _target:MovieClip;

       public function MakeDragable( target:MovieClip ) {
           _target = target;
           _target.addEventListener( MouseEvent.MOUSE_DOWN, on_press );
       }

       private function on_press( e:MouseEvent ):void {
           _target.addEventListener( MouseEvent.MOUSE_UP, on_release );
           _target.stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
           _target.startDrag();
       }

       private function on_release( e:MouseEvent ):void {
           _target.removeEventListener( MouseEvent.MOUSE_UP, on_release );
           _target.stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
           _target.stopDrag();
       }
   }
}

Use the class in this way. Create a new instance and pass instance name of the MovieClip that will be dragable. For example the follow would make drag_mc dragable, assume that drag_mc is on the stage and has been assigned the instance name drag_mc.

new MakeDragable( drag_mc );

Note: In the MakeDragable class we need to reference the stage from the _target property. Since the class doesn't extend MovieClip or other DisplayObject, it doesn't have a reference to the stage.

Making a Scrollbar
A great application for dragging is a scrollbar. A scrollbar can be used for many different uses, scrolling text, or volume control or in place you need to allow users to present variable range for input.

The basic idea is to create an object drags along the horizontal or vertical axis within a limited range.

Key feature of the scroll bar is controlling the range of of the motion. The range of motion can be controlled in two ways. Set via a parameter, pass a value like 150 to set the range of motion. Your code would use this number to limit the range to 150 pixels. Or, reference an Object on the stage and use the size of that object to set the range. Here you would use the width or height of another object to set the range of motion.

The first method is easiest, but can takes some guess work to gauge the right distance. The second method is more flexibly but requires a little more coding and an extra object on the stage.

Drag by setting the distance
The example below assumes that you have a MovieClip with the instance name drag_mc on the stage. This example assumes the clip is at it's topmost position and will be able to drag up to 200 pixels below that point.

We'll create a Rectangle to set the bounds for the drag action and save it in a variable to use whenever we drag the clip. We'll also use the initial x and y value of the clip to generate the Rectangle. The rectangle is located at the x and y of drag_mc, has a width of 0 and a height of 200.

var drag_rect:Rectangle = new Rectangle(drag_mc.x, drag_mc.y, 0, 200);
drag_mc.addEventListener( MouseEvent.MOUSE_DOWN, on_press );

function on_press( e:MouseEvent ):void {
   drag_mc.startDrag( false, drag_rect );
   drag_mc.addEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
}

function on_release( e:MouseEvent ):void {
   drag_mc.stopDrag();
   drag_mc.removeEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
}

Note: You could set the numbers for the bounds Rectangle by typing all of the numbers. But, using the x and y of drag_mc make is convenient, since moving drag_mc will reposition the bounds without you having to change the script.

Drag by using another clip to define the distance
Let's try that again with a an object used to set the range. This example requires two MovieClips on the stage. Be sure to place the registration point for each clip in the upper left corner! This is important to make the clips drag correctly.

The first should be a tall narrow rectangle. This will set the range. Name this clip track_mc.

The second a smaller box. This will be the dragging clip. Name this clip drag_mc.

var range:Number = track_mc.x + track_mc.height;
var drag_rect:Rectangle = new Rectangle(track_mc.x, track_mc.y, 0, range );
drag_mc.addEventListener( MouseEvent.MOUSE_DOWN, on_press );

function on_press( e:MouseEvent ):void {
   drag_mc.startDrag( false, drag_rect );
   drag_mc.addEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.addEventListener( MouseEvent.MOUSE_UP, on_release );
}

function on_release( e:MouseEvent ):void {
   drag_mc.stopDrag();
   drag_mc.removeEventListener( MouseEvent.MOUSE_UP, on_release );
   stage.removeEventListener( MouseEvent.MOUSE_UP, on_release );
}

If the clips do not align on the stage, they should jump into alignment when you begin dragging.

If the clips are offset and to the left, right, top or bottom check the registration points on both clips. Be sure they are both in the upper left corner.

This example will allow the dragging clip to drag the entire height of the track. This will allow the dragging clip to move past the bottom of the track so that it stops when it's top edge reaches the bottom of the track. To keep the drag clip within the area of the track we need to make the range shorter than the track by the height of the dragger.

Try this, modify the first line of the last example as follows:

var range:Number = track_mc.x + track_mc.height - drag_mc.height;

Now the range is the difference between the height of the track and the height of the dragger.

Making a Scrollbar Class