EVOLVE

AS3 Classes on GitHub

Matt Przybylski — Sat, 09 Jul 2011 17:46:39 +0000

Just wanted to give a quick note that I’ve put some of my classes up on GitHub. That is the best way to keep track of some of the code as I’ll probably be updating that more than the blog when I make small changes. Feel free to fork or whatever it is people do with Git

Flash Game Development by Example Mini Review

Matt Przybylski — Tue, 24 May 2011 14:52:07 +0000

When you think of where the Flash Platform is headed you’re undoubtedly talking about gaming. With the new Molehill stuff coming upon us and the ability to do crazy 3D stuff in the Flash player there’s no doubt in anyone’s mind that the platform is going to be a serious contender when it comes to games not only online but on mobile devices as well. Molehill doesn’t only mean 3D however and you can certainly develop some great 2D games that run really well on these devices as well. I’ve never been much of a game developer as my focus has always been mostly on creating interactive online sites/experiences so when I got hold of a copy of Flash Game Development by Example I was pretty happy to see that it outlines 9 different game types and walks you through creating them from start to finish.

The book is written by Emanuele Feronato whose site I’ve frequented for the better part of the last five years. He’s always put out really good game development tutorials on his blog so expect this book to be no different. The 9 games you’ll be making include:

Concentration
Minesweeper
Connect 4
Snake
Tetris
Astro-Panic!
Bejeweled
Puzzle Bobble
BallBalance

The starting point is relatively basic so you can pick it up even if you’ve not programmed much in Flash and by the time you’ve completed the ninth game you end up with a pretty firm understanding of ActionScript and what its capable of. You’ll learn everything from setting up classes and how to use arrays to some useful trigonometry functions and properly using keyboard input. If you’re a seasoned game dev you’re probably not going to get much out of this book but if you’re just starting up and want to get inside the mind of a game developer and how to structure your code you’ll definitely benefit from reading this. My only gripe (and this isn’t so much with the book as it is with Emanuele’s coding style) is that he always uses lowercase class names (even on his blog) rather than the standard camel case I’m used to. Nevertheless, don’t let this get in the way of reading a great book that is sure to give you a lot of great insight.

AS3: Drag a Clip Along an Arc

Matt Przybylski — Mon, 09 May 2011 15:01:28 +0000

View Example
Download Source

A while ago I was creating a video player for a project that needed to have the scrubber sit on an arc and be draggable. I asked around on Twitter if anyone knew of something that had this type of functionality already built (because it seems like something I shouldn't have to write from the ground up) and someone pointed me to senocular's Path class. It seemed promising and turned out to be the perfect class I needed to make this work. I included the class in the download files just because I wanted to make sure all files are provided but if you're going to use this make sure you grab it from his site as it's probably the latest version and all credit goes to him for making the class.

Here is the code to make the example run properly:

PLAIN TEXT

Actionscript:

package
{
import flash.text.TextField;
import flash.geom.Point;
import com.senocular.drawing.Path;
import flash.display.Sprite;
import flash.events.MouseEvent;
import flash.utils.getQualifiedClassName;
/**
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class Main extends Sprite
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
private var _point:Point = new Point();
private var _localPoint:Point = new Point();
private var _percent:Number;
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
public var scrubPath:Path = new Path();
public var pathHolder:Sprite = new Sprite();
public var scrubber:Sprite = new Sprite();
public var tf:TextField = new TextField();
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
public function Main()
{
super();
init();
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
/**
*
*/
protected function init():void
{
pathHolder.graphics.lineStyle(1, 0x000000, .1);
pathHolder.x = pathHolder.y = 100;
scrubPath.moveTo(0, 0);
scrubPath.curveTo(300, 100, 600, 0);
scrubPath.draw(pathHolder.graphics);
scrubber.graphics.beginFill(0xFF0000, .5);
scrubber.graphics.drawCircle(0, 0, 10);
scrubber.graphics.endFill();
scrubber.buttonMode = true;
scrubber.addEventListener(MouseEvent.MOUSE_DOWN, handleScrubberPressed);
scrubber.addEventListener(MouseEvent.MOUSE_UP, handleScrubberReleased);
tf.width = 800;
tf.x = 20;
tf.y = 200;
pathHolder.addChild(scrubber);
addChild(pathHolder);
addChild(tf);
}
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
/**
*
*/
private function handleScrubberPressed($evt:MouseEvent):void
{
stage.addEventListener(MouseEvent.MOUSE_MOVE, handleMouseMoved);
stage.addEventListener(MouseEvent.MOUSE_UP, handleScrubberReleased);
}
/**
*
*/
private function handleScrubberReleased($evt:MouseEvent):void
{
stage.removeEventListener(MouseEvent.MOUSE_MOVE, handleMouseMoved);
stage.removeEventListener(MouseEvent.MOUSE_UP, handleScrubberReleased);
}
/**
*
*/
private function handleMouseMoved($evt:MouseEvent):void
{
_localPoint = pathHolder.globalToLocal(new Point($evt.stageX, $evt.stageY));
_percent = (_localPoint.x / scrubPath.length);
_point = scrubPath.pointAt(_percent);
if ((_localPoint.x>= 0) && (_localPoint.x <= scrubPath.length))
{
scrubber.x = _point.x;
scrubber.y = _point.y;
tf.text = String("PERCENT: " + Math.round(_percent * 100) + "%\nPOINT: " + _point);
}
$evt.updateAfterEvent();
}
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
/**
* @private
*/
override public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

The magic happens at this stage:

PLAIN TEXT

Actionscript:

scrubPath.moveTo(0, 0);
scrubPath.curveTo(300, 100, 600, 0);
scrubPath.draw(pathHolder.graphics);

Basically what we're doing here is using an API similar to the drawing API in the native graphics class which we're all accustomed to. Once the curve is made, it's drawn into the holder sprite's graphics. Later, we can grab the point while we are scrubbing it in a MOUSE_MOVE event.

PLAIN TEXT

Actionscript:

private function handleMouseMoved($evt:MouseEvent):void
{
_localPoint = pathHolder.globalToLocal(new Point($evt.stageX, $evt.stageY));
_percent = (_localPoint.x / scrubPath.length);
_point = scrubPath.pointAt(_percent);
if ((_localPoint.x>= 0) && (_localPoint.x <= scrubPath.length))
{
scrubber.x = _point.x;
scrubber.y = _point.y;
tf.text = String("PERCENT: " + Math.round(_percent * 100) + "%\nPOINT: " + _point);
}
$evt.updateAfterEvent();
}

Here I'm grabbing the point at which the mouse currently sits, converting it to a local point and calculating the percent that it's at along the path. I can then use the pointAt() method of the Path class to figure out at which point on the path I currently need to be and move the scrubber to that point. I'm also checking if I'm between the start and end points on the path so that I'm only dragging along the path and not past that area to the left or the right.

Turned out to be a very simple solution thanks to senocular's Path class and I hope it helps someone out in the future.

AS3: SoundManager v1.4

Matt Przybylski — Thu, 06 Jan 2011 19:05:31 +0000

UPDATE 1/14/11: As pointed out in the comments by a few users, I just fixed a bug that didn't allow you to replay a sound once it was played for the first time. Sorry about that. Please keep testing and sending in reports!

View SoundManager Documentation
View SoundItem Documentation
Download TweenLite (needed to run example files/SoundManager)
Download Classes & Example Files

The SoundManager has been the most popular item I've ever posted on this blog and I got a lot of e-mails through the years asking to update/make changes to it and also some really good feature requests as well as people actually putting in features and passing them back to me. Admittedly I don't add very many sounds to my projects but it's always been a goal of mine to go back and update the SoundManager since it is so popular (and I'd like to put more sounds into my own work). About two years ago I had a ton of e-mails from users with bugs and requests which I meant to implement. Unfortunately I went through an e-mail migration and I ended up losing a lot of those e-mails (sorry, so if you don't see your changes and you e-mailed me, please send it again). Since then I've gotten some more e-mails and when I had time to put a new version together I did. I actually updated the classes three times and went back and forth on a bunch of issues but finally came up with this version which is pretty solid.

This (as with the previous version) has not been tested "in the wild" and could contain bugs so use at your own risk. If you do find a bug or have a feature request, please by all means contact me and I'll try my best to get it in there/fix it. I'm posting this up because I've had many requests to do so but also so that it could go through the rigors of everyday use and become a very useful library down the road for sound work in Flash. Here is a list of the features in each version that have been updated since I last posted:

1.4

General refactoring.
Added areAllMuted getter. Fixed bug where if muteAllSounds() was called, playing a sound after that caused it to play rather than stay muted.
Fixed bug where calling muteAllSounds() didn't mute sounds that were being tweened at the same time (thanks Milan Orszagh).
Reverted to TweenLite for default fading behavior.
Reconfigured SoundItem to not extend sound and be its own object so that we can add preloaded sounds without hassle.
Added addPreloadedSound() method to add sounds that are loaded by an external loading system (thanks Nuajan for the idea).
Renamed events being fired by SoundManagerEvent to be more appropriate with what's happening.
Added SoundManagerEvent.SOUND_ITEM_PLAY_COMPLETE event.
Added a destroy() method to SoundItem to clean up for garbage collection.

1.3

Added the new SoundItem class so that each sound is strongly typed rather than being a generic Object. When using sounds in your library, your sound MUST extend com.reintroducing.sound.SoundItem and NOT flash.media.Sound. Set this as the Base class in the properties panel for each library sound.
Added the getSoundItem() method and removed getSoundObject() method in favor of using the new SoundItem class.
Added the SoundManagerEvent and set the manager to fire off appropriate events.
Changed to TweenMax for default fading behavior.

1.2

Removed ability to play the sound again if it is already playing (causes conflict with stopAllSounds). To play the same sound at the same time, add the sound under a differnet name (thanks Yu-Chung Chen).
Fixed bug where playSound() wouldn't play from specified position if the sound was paused (thanks Yu-Chung Chen).

1.1

Fixed bug where calling playSound() on a sound that was muted by muteAllSounds() was causing it to play. Use unmuteAllSounds() to resume playback of muted sounds.

Here is the new class in all its glory:

PLAIN TEXT

Actionscript:

package com.reintroducing.sound
{
import com.reintroducing.events.SoundManagerEvent;
import flash.events.Event;
import flash.events.EventDispatcher;
import flash.events.IOErrorEvent;
import flash.events.ProgressEvent;
import flash.media.Sound;
import flash.media.SoundLoaderContext;
import flash.net.URLRequest;
import flash.utils.Dictionary;
import flash.utils.getQualifiedClassName;
/**
* The SoundManager is a singleton that allows you to have various ways to control sounds in your project.
*
* The SoundManager can load external sounds, play sounds loaded through an asset loader, or library sounds,
* pause/mute/stop/control volume for one or more sounds at a time, fade sounds up or down, and allows additional
* control to sounds not readily available through the default classes.
*
* The supplementary SoundItem class is dependent on TweenLite (http://www.tweenlite.com) to aid in easily fading the volume of the sound.
*
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.4
*
* VERSION HISTORY:
*
* 1.4
* - General refactoring.
*
* - Added areAllMuted getter. Fixed bug where if muteAllSounds() was called, playing a sound after that caused it
* to play rather than stay muted.
*
* - Fixed bug where calling muteAllSounds() didn't mute sounds that were being tweened at the same time (thanks Milan Orszagh).
*
* - Reverted to TweenLite for default fading behavior.
*
* - Reconfigured SoundItem to not extend sound and be its own object so that we can add preloaded sounds without hassle.
*
* - Added addPreloadedSound() method to add sounds that are loaded by an external loading system (thanks Nuajan for the idea).
*
* - Renamed events being fired by SoundManagerEvent to be more appropriate with what's happening.
*
* - Added SoundManagerEvent.SOUND_ITEM_PLAY_COMPLETE event.
*
* - Added a destroy() method to SoundItem to clean up for garbage collection.
*
* 1.3
* - Added the new SoundItem class so that each sound is strongly typed rather than being a generic Object.
* When using sounds in your library, your sound MUST extend com.reintroducing.sound.SoundItem and NOT
* flash.media.Sound. Set this as the Base class in the properties panel for each library sound.
*
* - Added the getSoundItem() method and removed getSoundObject() method in favor of using the new SoundItem class.
*
* - Added the SoundManagerEvent and set the manager to fire off appropriate events.
*
* - Changed to TweenMax for default fading behavior.
*
* 1.2
* - Removed ability to play the sound again if it is already playing (causes conflict with stopAllSounds).
* To play the same sound at the same time, add the sound under a differnet name (thanks Yu-Chung Chen).
*
* - Fixed bug where playSound() wouldn't play from specified position if the sound was paused (thanks Yu-Chung Chen).
*
* 1.1
* - Fixed bug where calling playSound() on a sound that was muted by muteAllSounds() was causing it to play.
* Use unmuteAllSounds() to resume playback of muted sounds.
*/
public class SoundManager extends EventDispatcher
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
// singleton instance
private static var _instance:SoundManager;
private static var _allowInstance:Boolean;
private var _soundsDict:Dictionary;
private var _sounds:Array;
private var _areAllMuted:Boolean;
private var _tempExternalSoundItem:SoundItem;
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
// singleton instance of SoundManager
public static function getInstance():SoundManager
{
if (_instance == null)
{
_allowInstance = true;
_instance = new SoundManager();
_allowInstance = false;
}
return _instance;
}
public function SoundManager()
{
this._soundsDict = new Dictionary(true);
this._sounds = [];
if (!_allowInstance)
{
throw new Error("Error: Use SoundManager.getInstance() instead of the new keyword.");
}
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
/**
*
*/
private function addSound($linkageID:*, $preloadedSound:Sound, $path:String, $name:String, $buffer:Number = 1000, $checkPolicyFile:Boolean = false):Boolean
{
// check to see if sound already exists by the specified name
var len:int = _sounds.length;
for (var i:int = 0; i )
{
if ((_sounds[i] as SoundItem).name == $name) return false;
}
// sound doesn't exist yet, go ahead and create it
var si:SoundItem = new SoundItem();
if ($linkageID == null)
{
if ($preloadedSound == null)
{
// adding external sound
si.sound = new Sound(new URLRequest($path), new SoundLoaderContext($buffer, $checkPolicyFile));
si.sound.addEventListener(IOErrorEvent.IO_ERROR, onSoundLoadError);
si.sound.addEventListener(ProgressEvent.PROGRESS, onSoundLoadProgress);
si.sound.addEventListener(Event.COMPLETE, onSoundLoadComplete);
_tempExternalSoundItem = si;
}
else
{
// adding a preloaded sound
si.sound = $preloadedSound;
}
}
else
{
// adding library sound
si.sound = new $linkageID;
}
si.name = $name;
si.position = 0;
si.paused = true;
si.volume = (_areAllMuted) ? 0 : 1;
si.savedVolume = si.volume;
si.startTime = 0;
si.loops = 0;
si.pausedByAll = false;
si.muted = _areAllMuted;
si.addEventListener(SoundManagerEvent.SOUND_ITEM_PLAY_COMPLETE, handleSoundPlayComplete);
_soundsDict[$name] = si;
_sounds.push(si);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_ADDED, si));
return true;
}
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
/**
* Adds a sound from the library to the sounds dictionary for playing in the future.
*
* @param $linkageID The class name of the library symbol that was exported for AS
* @param $name The string identifier of the sound to be used when calling other methods on the sound
*
* @return Boolean A boolean value representing if the sound was added successfully
*/
public function addLibrarySound($linkageID:*, $name:String):Boolean
{
return addSound($linkageID, null, "", $name);
}
/**
* Adds an external sound to the sounds dictionary for playing in the future.
*
* @param $path A string representing the path where the sound is on the server
* @param $name The string identifier of the sound to be used when calling other methods on the sound
* @param $buffer The number, in milliseconds, to buffer the sound before you can play it (default: 1000)
* @param $checkPolicyFile A boolean that determines whether Flash Player should try to download a cross-domain policy file from the loaded sound's server before beginning to load the sound (default: false)
*
* @return Boolean A boolean value representing if the sound was added successfully
*/
public function addExternalSound($path:String, $name:String, $buffer:Number = 1000, $checkPolicyFile:Boolean = false):Boolean
{
return addSound(null, null, $path, $name, $buffer, $checkPolicyFile);
}
/**
* Adds a sound that was preloaded by an external library to the sounds dictionary for playing in the future.
*
* @param $sound The sound object that was preloaded
* @param $name The string identifier of the sound to be used when calling other methods on the sound
*
* @return Boolean A boolean value representing if the sound was added successfully
*/
public function addPreloadedSound($sound:Sound, $name:String):Boolean
{
return addSound(null, $sound, "", $name);
}
/**
* Removes a sound from the sound dictionary. After calling this, the sound will not be available until it is re-added.
*
* @param $name The string identifier of the sound to remove
*
* @return void
*/
public function removeSound($name:String):void
{
var len:int = _sounds.length;
var si:SoundItem;
for (var i:int = 0; i )
{
si = (_sounds[i] as SoundItem);
if (si.name == $name)
{
si.sound.removeEventListener(IOErrorEvent.IO_ERROR, onSoundLoadError);
si.sound.removeEventListener(ProgressEvent.PROGRESS, onSoundLoadProgress);
si.sound.removeEventListener(Event.COMPLETE, onSoundLoadComplete);
si.removeEventListener(SoundManagerEvent.SOUND_ITEM_PLAY_COMPLETE, handleSoundPlayComplete);
si.destroy();
_sounds.splice(i, 1);
break;
}
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_REMOVED, (_soundsDict[$name] as SoundItem)));
delete (_soundsDict[$name] as SoundItem);
}
/**
* Removes all sounds from the sound dictionary.
*
* @return void
*/
public function removeAllSounds():void
{
var len:int = _sounds.length;
var si:SoundItem;
for (var i:int = 0; i )
{
si = (_sounds[i] as SoundItem);
si.sound.removeEventListener(IOErrorEvent.IO_ERROR, onSoundLoadError);
si.sound.removeEventListener(ProgressEvent.PROGRESS, onSoundLoadProgress);
si.sound.removeEventListener(Event.COMPLETE, onSoundLoadComplete);
}
_sounds = [];
_soundsDict = new Dictionary(true);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.REMOVED_ALL));
}
/**
* Plays or resumes a sound from the sound dictionary with the specified name. If the sounds in the dictionary were muted by
* the muteAllSounds() method, no sounds are played until unmuteAllSounds() is called.
*
* @param $name The string identifier of the sound to play
* @param $volume A number from 0 to 1 representing the volume at which to play the sound (default: 1)
* @param $startTime A number (in milliseconds) representing the time to start playing the sound at (default: 0)
* @param $loops An integer representing the number of times to loop the sound (default: 0)
* @param $resumeTween A boolean that indicates if a faded sound's volume should resume from the last saved state (default: true)
*
* @return void
*/
public function playSound($name:String, $volume:Number = 1, $startTime:Number = 0, $loops:int = 0, $resumeTween:Boolean = true):void
{
var si:SoundItem = (_soundsDict[$name] as SoundItem);
si.play($startTime, $loops, $volume, $resumeTween);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_PLAY_START, si));
}
/**
* Pauses the specified sound.
*
* @param $name The string identifier of the sound
* @param $pauseTween A boolean that either pauses the fadeTween or allows it to continue (default: true)
*
* @return void
*/
public function pauseSound($name:String, $pauseTween:Boolean = true):void
{
var si:SoundItem = (_soundsDict[$name] as SoundItem);
si.pause($pauseTween);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_PAUSE, si));
}
/**
* Stops the specified sound.
*
* @param $name The string identifier of the sound
*
* @return void
*/
public function stopSound($name:String):void
{
var si:SoundItem = (_soundsDict[$name] as SoundItem);
si.stop();
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_STOP, si));
}
/**
* Plays all the sounds that are in the sound dictionary.
*
* @param $resumeTweens A boolean that resumes all unfinished fade tweens (default: true)
* @param $useCurrentlyPlayingOnly A boolean that only plays the sounds which were currently playing before a pauseAllSounds() or stopAllSounds() call (default: false)
*
* @return void
*/
public function playAllSounds($resumeTweens:Boolean = true, $useCurrentlyPlayingOnly:Boolean = false):void
{
var len:int = _sounds.length;
for (var i:int = 0; i )
{
var id:String = (_sounds[i] as SoundItem).name;
if ($useCurrentlyPlayingOnly)
{
if ((_soundsDict[id] as SoundItem).pausedByAll)
{
(_soundsDict[id] as SoundItem).pausedByAll = false;
playSound(id, (_soundsDict[id] as SoundItem).volume, 0, 0, $resumeTweens);
}
}
else
{
playSound(id, (_soundsDict[id] as SoundItem).volume, 0, 0, $resumeTweens);
}
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.PLAY_ALL));
}
/**
* Pauses all the sounds that are in the sound dictionary.
*
* @param $pauseTweens A boolean that either pauses each SoundItem's fadeTween or allows them to continue (default: true)
* @param $useCurrentlyPlayingOnly A boolean that only pauses the sounds which are currently playing (default: true)
*
* @return void
*/
public function pauseAllSounds($pauseTweens:Boolean = true, $useCurrentlyPlayingOnly:Boolean = true):void
{
var len:int = _sounds.length;
for (var i:int = 0; i )
{
var id:String = (_sounds[i] as SoundItem).name;
if ($useCurrentlyPlayingOnly)
{
if (!(_soundsDict[id] as SoundItem).paused)
{
(_soundsDict[id] as SoundItem).pausedByAll = true;
pauseSound(id, $pauseTweens);
}
}
else
{
pauseSound(id, $pauseTweens);
}
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.PAUSE_ALL));
}
/**
* Stops all the sounds that are in the sound dictionary.
*
* @param $useCurrentlyPlayingOnly A boolean that only stops the sounds which are currently playing (default: true)
*
* @return void
*/
public function stopAllSounds($useCurrentlyPlayingOnly:Boolean = true):void
{
var len:int = _sounds.length;
for (var i:int = 0; i )
{
var id:String = (_sounds[i] as SoundItem).name;
if ($useCurrentlyPlayingOnly)
{
if (!(_soundsDict[id] as SoundItem).paused)
{
(_soundsDict[id] as SoundItem).pausedByAll = true;
stopSound(id);
}
}
else
{
stopSound(id);
}
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.STOP_ALL));
}
/**
* Fades the sound to the specified volume over the specified amount of time.
*
* @param $name The string identifier of the sound
* @param $targVolume The target volume to fade to, between 0 and 1 (default: 0)
* @param $fadeLength The time to fade over, in seconds (default: 1)
* @param $stopOnComplete Added by Danny Miller from K2xL, stops the sound once the fade is done if set to true
*
* @return void
*/
public function fadeSound($name:String, $targVolume:Number = 0, $fadeLength:Number = 1, $stopOnComplete:Boolean = false):void
{
var si:SoundItem = (_soundsDict[$name] as SoundItem);
si.addEventListener(SoundManagerEvent.SOUND_ITEM_FADE_COMPLETE, handleFadeComplete);
si.fade($targVolume, $fadeLength, $stopOnComplete);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_FADE, si));
}
/**
* Mutes the volume for all sounds in the sound dictionary.
*
* @return void
*/
public function muteAllSounds():void
{
_areAllMuted = true;
var len:int = _sounds.length;
var id:String;
var si:SoundItem;
for (var i:int = 0; i )
{
id = (_sounds[i] as SoundItem).name;
si = (_soundsDict[id] as SoundItem);
si.savedVolume = si.channel.soundTransform.volume;
si.muted = true;
setSoundVolume(id, 0);
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.MUTE_ALL));
}
/**
* Resets the volume to their original setting for all sounds in the sound dictionary.
*
* @return void
*/
public function unmuteAllSounds():void
{
_areAllMuted = false;
var len:int = _sounds.length;
var id:String;
var si:SoundItem;
for (var i:int = 0; i )
{
id = (_sounds[i] as SoundItem).name;
si = (_soundsDict[id] as SoundItem);
si.muted = false;
setSoundVolume(id, si.savedVolume);
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.UNMUTE_ALL));
}
/**
* Sets the volume of the specified sound.
*
* @param $name The string identifier of the sound
* @param $volume The volume, between 0 and 1, to set the sound to
*
* @return void
*/
public function setSoundVolume($name:String, $volume:Number):void
{
(_soundsDict[$name] as SoundItem).setVolume($volume);
}
/**
* Gets the volume of the specified sound.
*
* @param $name The string identifier of the sound
*
* @return Number The current volume of the sound
*/
public function getSoundVolume($name:String):Number
{
return (_soundsDict[$name] as SoundItem).channel.soundTransform.volume;
}
/**
* Gets the position of the specified sound.
*
* @param $name The string identifier of the sound
*
* @return Number The current position of the sound, in milliseconds
*/
public function getSoundPosition($name:String):Number
{
return (_soundsDict[$name] as SoundItem).channel.position;
}
/**
* Gets the duration of the specified sound.
*
* @param $name The string identifier of the sound
*
* @return Number The length of the sound, in milliseconds
*/
public function getSoundDuration($name:String):Number
{
return (_soundsDict[$name] as SoundItem).sound.length;
}
/**
* Gets the SoundItem instance of the specified sound.
*
* @param $name The string identifier of the SoundItem
*
* @return SoundItem The SoundItem
*/
public function getSoundItem($name:String):SoundItem
{
return (_soundsDict[$name] as SoundItem);
}
/**
* Identifies if the sound is paused or not.
*
* @param $name The string identifier of the sound
*
* @return Boolean The boolean value of paused or not paused
*/
public function isSoundPaused($name:String):Boolean
{
return (_soundsDict[$name] as SoundItem).paused;
}
/**
* Identifies if the sound was paused or stopped by calling the stopAllSounds() or pauseAllSounds() methods.
*
* @param $name The string identifier of the sound
*
* @return Number The boolean value of pausedByAll or not pausedByAll
*/
public function isSoundPausedByAll($name:String):Boolean
{
return (_soundsDict[$name] as SoundItem).pausedByAll;
}
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
/**
* Dispatched when an external sound can't load and produces an error.
*/
private function onSoundLoadError($evt:IOErrorEvent):void
{
_tempExternalSoundItem = null;
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_LOAD_ERROR));
}
/**
* Dispatched when an external sound is loading.
*/
private function onSoundLoadProgress($evt:ProgressEvent):void
{
var percent:uint = Math.round(100 * ($evt.bytesLoaded / $evt.bytesTotal));
var snd:Sound = ($evt.target as Sound);
var duration:Number = 0;
if (snd && snd.length> 0)
{
duration = ((snd.bytesTotal / (snd.bytesLoaded / snd.length)) * .001);
}
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_LOAD_PROGRESS, _tempExternalSoundItem, duration, percent));
}
/**
* Dispatched when an external sound is fully loaded.
*/
private function onSoundLoadComplete($evt:Event):void
{
var snd:Sound = ($evt.target as Sound);
var duration:Number = (snd.length * .001);
dispatchEvent(new SoundManagerEvent(SoundManagerEvent.SOUND_ITEM_LOAD_COMPLETE, _tempExternalSoundItem, duration));
_tempExternalSoundItem = null;
}
/**
* Dispatched once a sound's fadeTween is completed if the sound was called to fade.
*/
private function handleFadeComplete($evt:SoundManagerEvent):void
{
dispatchEvent($evt);
var si:SoundItem = $evt.soundItem;
si.removeEventListener(SoundManagerEvent.SOUND_ITEM_FADE_COMPLETE, handleFadeComplete);
}
/**
* Dispatched when a SoundItem has finished playback.
*/
private function handleSoundPlayComplete($evt:SoundManagerEvent):void
{
dispatchEvent($evt);
}
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
/**
*
*/
public function get sounds():Array
{
return _sounds;
}
/**
*
*/
public function get areAllMuted():Boolean
{
return _areAllMuted;
}
//- HELPERS -----------------------------------------------------------------------------------------------
override public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

What To Deliver A Flash Developer

Matt Przybylski — Mon, 03 May 2010 17:24:16 +0000

Flash developers are usually the last line of defense (meaning that we are the last ones to touch the project before the client sees it) and there is a lot of pressure put on us to deliver a polished product. At the point we start, chances are the deadline has already been stretched due to hang ups in the process before we ever see what we’re about to get ourselves into and being organized and receiving well-organized assets/direction is the key to success. Ideally, you should really bring the developer in during the kick-off meetings as it will ease the process down the line and make everyone’s lives easier. Even with the list below, it’s always good to explain to the developer during the early stages your vision and concept for the site, the animation style, demographic, and similar items that will aid during the process of development. Sadly, this usually never happens and we’ve got to buckle down and micro-manage everything to make sure all systems are go.

I’ve gone through this on every project it seems. I am ready to code and get the assets/necessary files from a designer/producer/back-end developer. I start opening stuff up and am underwhelmed at how much is provided. I’m missing a bunch of stuff and there are underlying questions about what needs to be done. In the interest of saving time, I thought I’d write a little guide as to what I (personally, at least) would love to get every time I start a new project so I can reference this in the future as well as hopefully get some input on stuff I may have missed or never realized in my process. This is an ideal scenario, of course, and a lot of times you won’t receive this entire list (and in some tragic cases, any of it), but it makes life so much easier on a Flash developer to actually have all of these things ready to go when the project is handed to you for the final stretch and you want to hit that deadline.

Topics include:

MUST HAVES

Requirements
Copy Deck
Fonts
External Assets
Vectors
Rollover States
Preloaders
Error Handling
“No Flash” Page

NICE TO HAVES

Wireframes
Layer Comps
Interaction/Motion Guide
Scripting Guide
Asset Organization

MUST HAVES
Requirements
Every project has different requirements. You can’t start coding unless you know that the project is supposed to run in Flash Player 8, 9, or 10+. The target Flash Player is huge because it will make the difference between AS2 (8 and below, please don’t do this to us!) and AS3 (9+), which makes a HUGE difference. You also need to know what the target file size is (if you’re doing banners or something that needs to be kept relatively small) and physical dimensions (is this full screen, a set size, liquid, or need to fit into a small part of a hybrid site?). It’s also imperative at this time to make sure the designer is designing for whatever the target resolution is (hopefully nobody is designing for lower than 1024x768 at this point) and what the target audience is.

Copy Deck
No matter what project you’re on, there is a 99.9% chance that you will be adding copy to it (probably closer to 100%, but you get the idea). Lots of times you are handed Photoshop PSD files that have copy in them because the designer obviously used the copy to aid in designing the appropriate sections. Sometimes, however, there is no one single document that holds all the copy on the site. This is problematic for two reasons:

You can’t easily scan the document and rip out sections that may not be visible in the comps.
Editing site copy becomes a chore because now you have to have the designer make new comps of site changes and somehow show them on the comp to make sure the developer catches what has been changed.

With a separate Word document that has all the copy you can easily make a change and highlight it in a different color or background for the developer to quickly scan the file and find what has been changed. Word-savvy power users can us also use the snappy little comment tool to add comments (only issue I’ve seen with this approach is that after a lot of edits, the file starts to have lines pointing to a bunch of things in the document and is hard to follow, let alone the margins filled with comment bubbles). Be sure to remember to version the file as well, as ideally you’ll want to remove all color changes/highlights when making new revisions and add the newest ones in. That way, if you hand off a bunch of edits to the developer, then make more edits, he can look at each version separately and go back and make the appropriate changes while still easily finding what has been changed by a quick color scan. Even better, if you have a change log at the top of your file (unrealistic usually, but awesome if done right) you can track changes that way as well. If your developer is color blind, however, this causes another issue that is outside of the scope of this article.

Fonts
Everybody loves fonts! There has not been one single project that I’ve worked on where we have not run into some type of font issues. Whether it’s Mac to PC, PC to Mac, OpenType to TrueType, not delivering the fonts at all, or whatever the heck else, there is always some kind of issue with fonts. Designers have to be absolutely sure they keep track of all fonts used in a set of designs and package those up for a developer. Ideally, you want to use cross-platform fonts that are OpenType, as it works on both Mac and PC.

External Assets
There are all kinds of external assets that get used in a project and it all depends on what the job calls for. Nine times out of ten, however, they will fall into these three categories:

Images – Make sure you size these (yes, all of them) to whatever the final output in the project should be. You would also be wise to speak with the developer at this point to see if, for instance, you have a product shot that is repeated on the site but sized differently, if you can make it one size (the larger size) and scale proportionately down to whatever size it needs to be in the other area. It is also a good practice, I have found, to save them as JPGs in Photoshop using the Save for Web dialog and setting the quality to 60 while checking “Optimized”. This has always worked great for me and I don’t see much of a difference between this and the other, higher settings, while retaining a manageable size. Again, though, it’s a good idea to speak with your developer at this point so he can tell you how they want the files saved out in case they want to control the compression through Flash rather than during the saving process. (NOTE: This is for external images that get loaded in to the Flash, NOT for images that are part of the design/layout of the project. Those should not be saved out as the developer or whoever is preparing the files for the developer will handle this accordingly)
Sounds – I normally prefer them to be saved out in the .mp3 format. This is native to Flash and it handles MP3s relatively well. Just as with images, speak with your developer and see if you should compress your sounds or if they will handle it on their end.
Video – Flash does not have video editing capabilities so it is imperative to output the file in the state that it is supposed to look like when the project is finalized. This means that all cropping/post-production should be done in other programs like Final Cut/Premiere/After Effects and output as an uncompressed .mov file at Millions of colors. If alpha transparency is involved, use Millions+ as this will allow the encoder (which is normally the Adobe Media Encoder that ships with the Creative Suites) to preserve the alpha channel.

Vectors
Flash is great and compression is fun (NOT!), but exporting a bunch of transparent PNGs and putting them in your application is bound to cause performance issues. I like to use vectors wherever possible because they preserve their editing capabilities and because I can always set them to act like bitmaps if necessary. A few things to note on this topic:

A lot of designers like to draw a vector in Photoshop. This isn’t really a true vector in terms of what Flash sees. If you export it out of Photoshop, you will be exporting a bitmap unless you go back and trace the path, make a selection, export whatever, etc. It gets messy. You should really be creating the vectors in Illustrator, which is a TON easier to create vectors with in the first place, and importing them into your Photoshop designs as smart objects.
While on the topic of smart objects, these are insanely helpful for a developer and take only seconds to create. PLEASE use smart objects in your designs. If you’re unfamiliar with them, there are tons of tutorials on smart objects out there. You would do wise for yourself as well as the developer to Google it real quick and incorporate it into your workflow.

Rollover States
This is another item that always seems to be forgotten. You should be creating rollover states for all of your interactive objects as you go along. One of the great things about Flash is interactivity, and what better way to go interactive than to show the user some kind of feedback that they’re rolling over an object that is clickable/selectable/etc? Isn’t that the whole point of using Flash in the first place? It’s always very helpful to the developer to show the rollover states of buttons and other such items along with layer comps (see below).

Preloaders
Sadly, preloaders are like the forgotten stepchildren of the Flash world. It’s a shame, really, that they become an afterthought because it’s usually the first thing a user sees when they come to your site and you want to set a good first impression. I’ve been captivated by many awesome preloaders in the past and so have others, so much so that there is a site dedicated to show off the coolest preloaders out there (Pretty Loaded). Most of my projects I never even get designs for a preloader and thus I end up creating the good ole boring line loader when everything else is said and done. Please remember as well that when you talk preloaders you’re not only talking about the main site but external assets that are being loaded in as well. This includes images, sounds, and video, and usually you also need (if different) a buffer animation for those. It’s such a small treatment but can add so much to a site’s overall look and feel.

Error Handling
In today’s day and age a lot of the projects you will be working on have some type of user input, be it a log in page, a registration form, or a contact page. Designers almost always deliver these but do not show scenarios for when errors occur. What happens if the user enters an invalid email address? What happens if the user doesn’t fill in all of the required fields? Where does this error show up and how does it look? Is there different error treatments for different input fields or do they all show up in the same spot depending on what portion the user is currently filling out? Are they inline errors or do they appear when you press submit? These are all questions that the developer will undoubtedly have so they need to be accounted for in the user experience as well as the design process.

“No Flash” Page
Unfortunately, there is still a very small percentage of users who don’t have Flash installed or have Javascript turned off thus not allowing to display Flash content through normal embedding methods used today. There is also the possibility that the user has a version of the player installed that is lower than what the targeted player was for your project so you need to show an HTML page that outlines these points and how to upgrade/download/etc. If there is no alternate content page on the site the user will feel frustrated and leave without trying to remedy the situation. It’s necessary for the designer to provide a page to the Flash developer (or HTML developer if there is a separate one on the project) to incorporate into the site.

NICE TO HAVES
Wireframes
Normally, this isn’t a requirement. Some projects are small enough that just looking at the comps is feasible (although not recommended). For larger projects, it’s really handy to have a nice set of wireframes that clearly illustrate the project’s roadmap and are detailed enough so that most of the usability questions are answered within the wireframes themselves. These are like a site map and show processes, such as logging in and the resulting pages for each possible scenario (success, fail, server failure, etc). This is also a great place to show error handling (see above).

Layer Comps
Much like smart objects, layer comps take only seconds to make and could save a developer a ton of showing/hiding layers/folders in a PSD. For those unfamiliar, a layer comp is basically a snap shot of your PSD at the current state. A designer who is familiar with the layers of the PSD can quickly go through and show/hide each set of layers necessary for each state of the application and take a layer comp (snapshot) of it and save it into the layer comps palette. The developer can then quickly show whatever state was defined and see all the states of the application without having to fumble through layers and folders. Of course, you should be organizing your layers as you go along as well, but this is even more effective in the hand-off process. Just make sure to name the layer comps (just like you do actual layers) so you can recognize what’s what at a glance. Of important notice here is also that if you change your design after creating layer comps, you will have to re-create the layer comp or Photoshop gets confused and doesn’t know what has been changed and what it needs to show. In this instance there will be a notification icon on the layer comp in the layer comps palette notifying you that something has been changed and that Photoshop doesn’t know what to render for this layer comp any longer. For this reason, layer comps should ALWAYS be the last thing you do before hand off. Don’t forget to make layer comps for rollovers as well if everything is contained in one file. This will make your developer so happy that you’ll be recommended for future work with them, guaranteed!

Interaction/Motion Guide
Let’s face it. Developers are not super creative, and those that are and have some kind of background in motion/design come few and far between. Most developers come from a computer science background where graphics were just ones and zeros on a screen. Even I have a degree in “Multimedia and Web Design” and experimented with 3D Studio Max, After Effects, and a slew of other programs where motion was a plenty and have lost my touch in animation as I’ve come along as a programmer. It is SUPER helpful to see the designer’s vision in a nice and clear document that possibly shows frames of an animation or even a description of what it should do. You can even send example links of something you may have seen before if applicable to help the developer picture your vision. Just remember, not everything you’ve seen before on another design applies to your design. A flat rectangle in 3D space won’t animate the same in perspective as an oddly shaped image of an animal or some other type of organic shape so make sure to keep those details in mind when figuring out animations for your project.

Scripting Guide
If you’re working closely with a database programmer or a back-end developer in general, it’s always nice to know what methods they are writing, what parameters those methods expect, and what the output results for all operations is. For instance, if you’re sending along some information into a database, it’s good to know what variables you need to send. Then, when those items are added to the database, you normally get a result. It could be an XML/JSON output of a query or something along those lines and seeing that result clearly laid out in an example is extremely helpful to a Flash developer so they know how to treat it and what to expect. This is usually one of the easiest steps to achieve as developers usually speak the same language and can understand each other more clearly.

Asset Organization
If you’re providing external assets, organization is VERY important (it’s always important, but the importance here is even greater). Speak with the developer and figure out a good folder structure/naming convention for your assets so that they can easily pick them up and transfer them right in to the project’s folder structure without having to make many (if any at all) changes. I’ve been in a situation before where I’ve spent literally one or two whole days organizing assets and re-saving things because they were not very easy to find or not compressed properly. Everyone has his or her own preferences on this so I won’t get too specific here, but just know that you will be loved for handling this from the get-go.

That concludes my list of things that you would be considered a genius for if you delivered to a Flash developer at the start of each project. This is certainly open for discussion as well as revisions and I encourage others to give input so I can add them to the list and make this an ever-growing resource for Flash developers to send others at a kick-off to ease the pain.

Contributors:
John Fisher
Jack Doyle

Tip: Output Trace Statements Through Terminal

Matt Przybylski — Fri, 11 Dec 2009 19:36:11 +0000

Recently I've been using the technique found here for outputting trace statements to the terminal when viewing your sites in a browser and it has worked flawlessly for me. I've been doing a lot of projects lately that include database integration so they have to be run in a staging environment and tracing in the Flash IDE is not an option.

The reason I'm pasting that whole article right here is for the sole purpose of archiving it on my site just in case that site goes down. Thanks goes to the original author for this.

You first need to create the txt file and directories here:
/Users/YourUserName/Library/Preferences/Macromedia/Flash\ Player/Logs/flashlog.txt

Then you need to create the mm.cfg file in both location:
/Library/Application Support/Macromedia/mm.cfg
/Users/YourUserName/mm.cfg

Then paste the follwing code in the mm.cfg:
ErrorReportingEnable=1
TraceOutputFileEnable=1
MaxWarnings=0

Initially, I pasted the code only in the first directory and couldn’t get it to work, not sure why, so place the file in both directories to play it safe.
I am running the Flash Debug Player 10, on Mac OS X.

To see the messages as they come on Terminal, navigate to the flashlog directory and type in:
tail -f flashlog.txt

Server Issues Resolved

Matt Przybylski — Thu, 22 Oct 2009 02:12:55 +0000

My HUGE apologies for not realizing the site was down. I was mostly connected to the internet through VPN for the past few weeks as I was finishing a large project remotely for Razorfish and I just figured the issue was with the VPN connection until I tried to go to the site one day when I wasn't on VPN. I spoke with MediaTemple about the issues and they pointed me to my .htaccess file. It turned out that was not the issue and the issue was what is outlined here. Thanks a ton to that article and now the site should be up and running correctly. PLEASE if you see anything wrong with the site e-mail me and let me know. Thanks and my apologies.

AS3: Collection, ValueObject, & Iterator

Matt Przybylski — Sat, 08 Aug 2009 02:38:07 +0000

View Collection Documentation
View Iterator Documentation
View Value Object Documentation
Download Classes & Example Files

A while ago I blogged about converting Collection and Iterator classes to AS3 since storing data in ValueObjects has become a regular practice in my coding. I really like how VOs are strongly typed and how you use a Collection to hold all the data together nicely. I am working on a project right now that allowed me to see even better uses for these things so I added a couple of simple (but helpful) methods to my Collection class (most notably the ability to add an item at a specified index as well as output the data currently existing in the collection easily) and created a base ValueObject class that allows you to easily output the data in that VO.

Important to also note is the package move. I've moved everything into a com.reintroducing.data package as I believe this fits better with what these classes are actually doing. There is also interfaces for ValueObject and Collection as well.

Just so you don't have to flip back and forth between posts, I'll post the classes and data here with a little explanation of each.

Here is Collection.as:

PLAIN TEXT

Actionscript:

package com.reintroducing.data
{
import flash.utils.getQualifiedClassName;
/**
* A base class for storing strongly typed Value Objects.
*
* @author Adobe [http://www.adobe.com]
* @author Ported to AS3 by Matt Przybylski [http://www.reintroducing.com]
* @version 1.1
*/
public class Collection implements ICollection
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
private var _name:String;
private var _items:Array;
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
/**
* Helper class used to manage a collection of objects. This class is similar to the Java
* Collection interface. Developers can extend this class to create new Collection types
* that provide additional functionality such as ordering and sorting.
*
* @param $name the name of the Collection.
*
* @return Nothing
*/
public function Collection($name:String):void
{
super();
this._name = $name;
this._items = new Array();
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
// Finds an item within the Collection and returns it's index.
private function internalGetItem($item:Object):int
{
var result:int = -1;
for (var i:int = 0; i length; i++)
{
if (this._items[i] == $item)
{
result = i;
break;
}
}
return result;
}
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
/**
* Gets the name of the Collection.
*
* @return String the name of the Collection.
*/
public function getName():String
{
return this._name;
}
/**
* Adds a new item to the end of the Collection.
*
* @param $item * to be added to the Collection. If item is null it will not be added to the Collection.
*
* @return Boolean true if the Collection was changed as a result of the operation.
*/
public function addItem($item:*):Boolean
{
var result:Boolean = false;
if ($item != null)
{
this._items.push($item);
result = true;
}
return result;
}
/**
* Adds a new item at the specified index in the Collection.
*
* @param $index position to add the specified item in
* @param $item * to be added to the Collection.
*
* @return Nothing
*/
public function addItemAt($index:int, $item:*):void
{
this._items.splice($index, 0, $item);
}
/**
* Removes a single item from the Collection. Returns false if item is not found.
*
* @param $item reference to Collection item to be removed from Collection.
*
* @return Boolean true if item is found and successfully removed. False if item is not found.
*/
public function removeItem($item:*):Boolean
{
var result:Boolean = false;
var itemIndex:int = this.internalGetItem($item);
if (itemIndex> -1)
{
this._items.splice(itemIndex, 1);
result = true;
}
return result;
}
/**
* Removes all items from the Collection.
*
* @return Nothing
*/
public function clear():void
{
this._items = new Array();
}
/**
* Returns true if this Collection contains the specified item.
*
* @param $item * whose presence in this collection is to be tested.
*
* @return Boolean true if this collection contains the specified item.
*/
public function contains($item:*):Boolean
{
return (this.internalGetItem($item)> -1);
}
/**
* Returns an item within the Collection using it's index.
*
* @param $index location of item within the Collection.
*
* @return * reference to item.
*/
public function getItemAt($index:int):*
{
return this._items[$index];
}
/**
* Returns an iterator over the elements in this collection. There are no guarantees concerning
* the order in which the elements are returned (unless this collection is an instance of some
* class that provides a guarantee).
*
* @return Iterator object that is used to iterate through the collection.
*/
public function getIterator():Iterator
{
return (new Iterator(this));
}
/**
* Returns the current length
*
* @return int value reflecting the number of items in this Collection.
*/
public function getLength():int
{
return this._items.length;
}
/**
* Returns true if the Collection is empty.
*
* @return Boolean true if Collection is empty.
*/
public function isEmpty():Boolean
{
return (this._items.length == 0);
}
/**
* Traces the Value Objects of the Collection to the Output panel.
*
* @return Nothing
*/
public function output():void
{
trace("Start " + this.getName() + " Contents:");
trace("---------------------------------------------\n");
for (var i:int = 0; i getLength(); i++)
{
var vo:IValueObject = this.getItemAt(i);
vo.output();
}
trace("End " + this.getName() + " Contents");
trace("---------------------------------------------\n");
}
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

This class has a lot of methods which you can go through with descriptions in the documentation. The only thing to point out here is the new output() and addItemAt() methods as described above.

Here is ValueObject.as:

PLAIN TEXT

Actionscript:

package com.reintroducing.data
{
import flash.utils.describeType;
import flash.utils.getQualifiedClassName;
/**
* A base class for storing strongly typed data.
*
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class ValueObject implements IValueObject
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
public function ValueObject():void
{
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
/**
* Outputs the data in the value object.
*
* @return Nothing
*/
public function output():void
{
trace(this.toString());
trace("\t-----------------------------------------");
var props:XMLList = describeType(this).variable;
for (var i:int = 0; i length(); i++)
{
trace("\t" + props[i].@name + ":" + props[i].@type + " = " + this[props[i].@name]);
}
trace("\t-----------------------------------------\n");
}
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

The reason I made this class was so that I could easily output the data in the VO without having to rewrite that method in every VO moving forward. It was very useful on this project I am working on and I definitely wished I had something like that previously rather than trying to loop through the class when necessary.

The following is Iterator.as:

PLAIN TEXT

Actionscript:

package com.reintroducing.data
{
import flash.utils.getQualifiedClassName;
/**
* Works in conjunction with a Collection to iterate through its contents.
*
* @author Adobe [http://www.adobe.com]
* @author Ported to AS3 by Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class Iterator
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
private var _collection:Collection;
private var _cursor:int;
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
/**
* Initialize the Iterator and maintain a link to it's Collection.
*
* @param $coll Collection to which this Iterator belongs.
*/
public function Iterator($coll:Collection):void
{
this._collection = $coll;
this._cursor = 0;
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
/**
* Returns true if the iteration has more items.
*
* @return Boolean true if iteration has more items.
*/
public function hasNext():Boolean
{
return (this._cursor getLength());
}
/**
* Return the next item in the iteration and increment the cursor. Returns null if the
* iteration has no more items.
*
* @return * the next item in the Iteration.
*/
public function next():*
{
return (this._collection.getItemAt(this._cursor++));
}
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

There have been no changes to this class.

Here is a sample XML file that I am going to use in a project:

PLAIN TEXT

XML:

>
name="Portfolio" id="0" src="http://www.reintroducing.com" />
name="Flash Dev Blog" id="1" src="http://evolve.reintroducing.com" />
name="Company" id="2" src="http://www.b-r-e-e-d.com" />
name="Girlfriend" id="3" src="http://www.jessicanovales.com" />
name="Sport" id="4" src="http://www.nba.com" />
>

Then, here is the corresponding TestVO class that extends ValueObject:

PLAIN TEXT

Actionscript:

package
{
import com.reintroducing.data.ValueObject;
import flash.utils.getQualifiedClassName;
/**
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class TestVO extends ValueObject
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
public var name:String;
public var id:int;
public var src:String;
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
public function TestVO():void
{
super();
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
override public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

Nothing fancy here, just extending ValueObject and defining some properties for later use.

Here is the corresponding TestVOCollection which will store all of our VOs:

PLAIN TEXT

Actionscript:

package
{
import com.reintroducing.data.Collection;
import com.reintroducing.data.Iterator;
import flash.utils.getQualifiedClassName;
/**
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class TestVOCollection extends Collection
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
public function TestVOCollection($name:String):void
{
super($name);
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
/**
*
*/
public function getItemByID($id:int):TestVO
{
var itr:Iterator = this.getIterator();
var testVO:TestVO;
var rVO:TestVO;
while (itr.hasNext())
{
testVO = TestVO(itr.next());
if (testVO.id == $id)
{
rVO = testVO;
break;
}
}
return rVO;
}
/**
*
*/
public function getItemByName($name:String):TestVO
{
var itr:Iterator = this.getIterator();
var testVO:TestVO;
var rVO:TestVO;
while (itr.hasNext())
{
testVO = TestVO(itr.next());
if (testVO.name == $name)
{
rVO = testVO;
break;
}
}
return rVO;
}
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
override public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

Basically I've extended Collection and also given it some specific methods for this particular collection to access data a little easier.

Lastly, here is the code I wrote in the Document class of my FLA to pull everything together:

PLAIN TEXT

Actionscript:

package
{
import flash.display.Sprite;
import flash.events.Event;
import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.utils.getQualifiedClassName;
import com.reintroducing.debug.Environment;
/**
* @author Matt Przybylski [http://www.reintroducing.com]
* @version 1.0
*/
public class Main extends Sprite
{
//- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
private var _env:Environment;
private var _testVOCollection:TestVOCollection;
//- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
//- CONSTRUCTOR -------------------------------------------------------------------------------------------
public function Main():void
{
this._env = Environment.getInstance();
this._env.setPaths("../", "");
this.loadXML();
}
//- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
private function loadXML():void
{
var xmlURL:String = this._env.basePath + "xml/info.xml";
var xmlLoader:URLLoader = new URLLoader();
xmlLoader.addEventListener(Event.COMPLETE, parseXML, false, 0, true);
xmlLoader.load(new URLRequest(xmlURL));
}
/**
*
*/
private function parseXML($evt:Event):void
{
var info:XML = new XML($evt.target.data);
var numItems:int = info.children().length();
var testVO:TestVO;
this._testVOCollection = new TestVOCollection("TestVOCollection");
for (var i:int = 0; i )
{
testVO = new TestVO();
testVO.name = info.entry[i].@name;
testVO.id = int(info.entry[i].@id);
testVO.src = info.entry[i].@src;
this._testVOCollection.addItem(testVO);
}
this.traceBlogInfo();
}
/**
*
*/
private function traceBlogInfo():void
{
trace("Entry Name: " + this._testVOCollection.getItemAt(1).name);
trace("Entry ID: " + this._testVOCollection.getItemByID(1).id);
trace("Entry Source: " + this._testVOCollection.getItemByName("Flash Dev Blog").src);
trace("\nAlternate Output Method\n");
this._testVOCollection.output();
}
//- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
//- EVENT HANDLERS ----------------------------------------------------------------------------------------
//- GETTERS & SETTERS -------------------------------------------------------------------------------------
//- HELPERS -----------------------------------------------------------------------------------------------
override public function toString():String
{
return getQualifiedClassName(this);
}
//- END CLASS ---------------------------------------------------------------------------------------------
}
}

Not much has changed in this version except I've specified the name of the Collection when defining it and showed how to output the data in two different approaches (the latter using the new output() method of the Collection class.

As you can see, the new methods for outputting data can really be a big time saver so you don't have to loop through your VOs/Collections and output stuff manually.

Tip: Convert An Object To A Class By Name

Matt Przybylski — Mon, 03 Aug 2009 14:00:10 +0000

Have you ever had to convert an object into a class based on its name? If you've got a string representation of the object (like its class identifier from the library) you can convert it to the data type that you'd like. All you have to do is use the handy little method called getDefinitionByName().

Here is an example of a sound that is in a library with the class field set to MySound:

PLAIN TEXT

Actionscript:

var SoundRef:Class = getDefinitionByName("MySound") as Class;
var _sound:Sound = new SoundRef();
_sound.play();

What this does is defines the class SoundRef as a "holder" for your class name using getDefinitionByName(). You can then create a variable that is the type of object you want to use and set it as your SoundRef class. Then, you can use that variable to run methods of the class on it. You're essentially doing the same thing as casting the variable but you're using the name of the class rather than casting it directly. This is useful if, for instance, you are looping through an array of class names that you know exist and want to convert them to their type. This is exactly the example that I gave to Stephen Matthews in my comments on my post about attaching sounds from the library.

PLAIN TEXT

Actionscript:

for (var so in _sfxArr)
{
var ClassRef:Class = getDefinitionByName(_sfxArr[so]) as Class;
var _tempSOUND:Sound = new ClassRef();
_tempSOUND.play();
_soArr.push(_tempSOUND);
}

Tip: Tools To Document Your Code

Matt Przybylski — Sat, 01 Aug 2009 18:14:46 +0000

I got an e-mail the other day from someone asking about what tools he can use to document his code. I had written a reply to him but I was using webmail and it froze up on me. I was able to, just in time, copy the reply over and saved it for later where I can reply when I got home using my regular e-mail program. Unfortunately I deleted the e-mail on accident and apparently it was from someone named Carlos.

Anyway, Carlos, I apologize and here is the reply that I gave you but lost your e-mail to send it back (hence I'm posting it here):

Carlos,
I use ZenDoc which is an online tool built by Senocular. It doesn't do packages at once (it does one class at a time) so if you're looking for that you'd have to set up ASDoc or if you want to purchase a solution you can use VisDoc. Hope that helps.

Hopefully you find this reply. Sorry about the mix up.