ClickPopMedia » XML

Creating an XML Gallery with ActionScript 3.0

Paul — Thu, 15 May 2008 02:37:28 +0000

For any dynamic Flash project, XML will be a powerful tool. One of the most common examples (and one of the simplest) is a picture gallery like the one I have here:

Images came from http://www.stockvault.net/

I will be talking about how to use Flash and XML to make a simple, yet superfly, gallery.

So, let us start off by looking at my XML file’s structure:

dir="//url/Photos/">
id=‘0′ file="photo_7030_20070301.jpg" width=‘500′ height=‘375′>
Cute Puppy! Who couldn’t love that face?
>
id=‘1′ file="photo_4095_20070301.jpg" width=‘500′ height=‘375′>
Three Friendly Cats.
>
id=‘2′ file="photo_4281_20070301.jpg" width=‘500′ height=‘375′>
The Terror of the UnderSofa!
>
id=‘3′ file="photo_6257_20070301.jpg" width=‘500′ height=‘375′>
Bored? Let’s play catch!
>
id=‘4′ file="photo_6882_20070301.jpg" width=‘500′ height=‘377′>
It may be natural, but this picture still feels weird to me.
>
id=‘5′ file="photo_7241_20070301.jpg" width=‘500′ height=‘375′>
My cats hate the snow.
>
id=‘6′ file="photo_7538_20070507.jpg" width=‘500′ height=‘622′>
LOOK IT'S HTML!!!]]>
>
id=‘7′ file="photo_7915_20070609.jpg" width=‘500′ height=‘371′>
Skinny cats are OK too.
>
>

XML is very simple to understand if you know anything about HTML’s tag structure. The XML document has a root tag that has an attribute dir=”//url/Photos/”. Every tag has to be closed within it’s own level of the tree. Our gallery tag is closed at the bottom of the document with . This means that all the tags are elements inside the gallery element (both open and close tags combined make up an element).

Our tags have several attributes, such as the images file name and it’s pixel demensions. Inside each element we have a short comment about the image that will be displayed in a TextField in our Flash movie.

One important thing to notice here is that if you want to have HTML in your TextField then you need to tell the code that something is a string containing HTML and not more elements. We do this with a special bracket HTML GOES HERE ]]> Isn’t that GREAT! That right there probably made this whole tutorial worth while (that was a problem that took me a long time to solve).

OK, now that we’ve looked at the XML we need to make it work with ActionScript 3. In Adobe Flash CS3 I created a new AS3 FLA doc and a new AS doc. In the FLA I simply created some very basic MovieClips for my left and right arrows and I placed a TextField at the bottom of my stage (which I set to 600 X 700 with a black background). After naming my instances and setting up the Document Class linkage I was done with the FLA side of thing and the rest is ActionScript.

Our Document Class has to extend MovieClip so we take our first steps thusly:

public class Main extends MovieClip {
public var currentImg:Number;
public var lastImg:Number;
public var xml:XML;
public var loader:Loader;
public var xmlLoader:URLLoader;

public function Main() {
loader = new Loader();
addChild(loader);

xmlLoader = new URLLoader(new URLRequest("//url/gallery.xml"));
xmlLoader.addEventListener(Event.COMPLETE, parseXML);

left_mc.stop(); //Need to stop the arrows from flickering
right_mc.stop();
}
}

In our constructor we are initializing our Loader which will contain the loaded images and we are loading our XML document. When the XML doc is done loading, the function parseXML will handle the content.

protected function parseXML(event:Event):void {
left_mc.addEventListener(MouseEvent.MOUSE_UP, nextImg);
left_mc.addEventListener(MouseEvent.MOUSE_OUT, arrowOut);
left_mc.addEventListener(MouseEvent.MOUSE_OVER, arrowOver);
right_mc.addEventListener(MouseEvent.MOUSE_UP, prevImg);
right_mc.addEventListener(MouseEvent.MOUSE_OUT, arrowOut);
right_mc.addEventListener(MouseEvent.MOUSE_OVER, arrowOver);

xml = new XML(event.currentTarget.data);
lastImg = xml.img.length() – 1;
currentImg = 0;
loadImg();
}

I’ve recently gotten into the habit of using protected functions rather then private functions. There is only one difference between the two and that’s that private anything won’t be inherited by child classes.
In this function I set the MouseEvents for the arrows because if the XML failed to load, there would be no reason for the arrows to work.

Alright, so I saved my XML tree in the var xml for ease of use later. I also saved the number of images in my XML doc using the length() method. Something to know about the length method is it will only tell you how many elements there are of that tag type at that level. For example, if I were to have child elements inside my img elements that would not affect the return value of xml.img.length(); It’s only telling you how many img elements are children of gallery (gallery is accessed with the var xml directly).

protected function loadImg():void {
loader.x = (stage.width – Number(xml.img[currentImg].@width))/2;
loader.y = (stage.height – 50 – Number(xml.img[currentImg].@height))/2;
loader.load(new URLRequest(xml.@dir + xml.img[currentImg].@file));
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loadFin);
}
protected function loadFin(event:Event):void {
textDisp_TF.htmlText = xml.img[currentImg];
}

In that first function I’m just going to focus on the one line with the URLRequest. In order to traverse an XML tree you need start with the base. Your XML var (in our case it’s called xml) points to that base (in this case the base is gallery). So when we want to access the attribute dir in the tag gallery, we need to type xml.@dir and this will return “//url/Photos/”. The ‘@’ symbol denotes that it’s an attribute and not an element (tag).

Getting the file name is just one step further. currentImg is a Number variable that stores which image we are on. Thinking of our XML var as something similar to a bunch of nested arrays we can see how you might access a specific file name with xml.img[currentImg].@file This says we want the file attribute in the [currentImg] (first second so forth) img element which is in our base element. There are quite a few ways of finding what you need in an XML doc and you can learn more about them here.

In the second function we are displaying the text from within our XML img element. Here we aren’t accessing any attributes or anything, this is where we get the content between the open and close tags.

Finally we have the arrow MouseEvent handlers:

protected function arrowOut(event:MouseEvent):void {
MovieClip(event.currentTarget).gotoAndStop(1);
}

protected function arrowOver(event:MouseEvent):void {
MovieClip(event.currentTarget).gotoAndStop(2);
}

protected function nextImg(event:MouseEvent):void {
loader.unload();
currentImg = (currentImg < lastImg)? currentImg + 1 : 0;
loadImg();
}

protected function prevImg(event:MouseEvent):void {
loader.unload();
currentImg = (currentImg > 0)? currentImg – 1 : lastImg;
loadImg();
}

Once again I’m using the less obvious form of the if..else statement.

if(num>5) {
num = 5;
}else {
num = 0;
}
//OR, THIS NEXT PART DOES THE SAME THING
num = (num>5)? 5 : 0;

Well that’s about it for this level of a gallery. You can make galleries look really nice with fade transitions between images, small loading animations for larger images, scrollable thumbnail selection menu… etc.

Here is a downloadable source of my example file (images not included… get them here): XMLGallery.zip

Making an MP3 player in AS3

Paul — Wed, 16 Apr 2008 00:12:24 +0000

Music Credits:
Title: The Best Day Ever
Artist: SpongBob
Album: The SpongeBob SquarePants Movie: Music From the Movie and More

Creating an MP3 Player in ActionScript 3.0 is fairly straight forward. The complexity varies greatly depending on what kind of features you want your player to have. I don’t plan on getting into ID3 tags here, but otherwise (as you can see) I will be going over the full functionality of a normal MP3 Player.

The first step is setting up the display and graphics. I went into the FLVPlayback skin SkinOverAll.fla file and fetched all the button graphics I needed (I’m not a very good artist). It was only a little trouble to recreate the buttons in a way that satisfied me (The only important thing to note about my buttons is that I gave them frame labels on the keyframes to make it easier to remember while writing the code).

Setting up the framework:

Now for the code! You can approach code like this from a number of different directions. I chose to start with making my button instances look like buttons, even though they don’t do anything yet. It’s really just a matter of setting up a LOT of event listeners (4 for each button):

…
stop_mc.addEventListener(MouseEvent.MOUSE_OVER, StopOver);
stop_mc.addEventListener(MouseEvent.MOUSE_OUT, StopOut);
stop_mc.addEventListener(MouseEvent.MOUSE_DOWN, StopDown);
stop_mc.addEventListener(MouseEvent.MOUSE_UP, StopUp);
…
private function StopOver(event:MouseEvent):void {
var obj:Object = event.currentTarget;
obj.gotoAndStop(’stop_over’);
}
private function StopOut(event:MouseEvent):void {
var obj:Object = event.currentTarget;
obj.gotoAndStop(’stop’);
}
private function StopDown(event:MouseEvent):void {
var obj:Object = event.currentTarget;
obj.gotoAndStop(’stop_down’);
}
private function StopUp(event:MouseEvent):void {
var obj:Object = event.currentTarget;
playPause_mc.playing = false;
playPause_mc.gotoAndStop(‘play’);
obj.gotoAndStop(’stop_over’);
}
…

At this point most of the buttons are the same. The only difference might lay in the MOUSE_UP event or how the play button has to switch between play and pause, so I have the boolean property playing in my PlayPauseBtn class.

Bringing in a PlayList:

Now that we have basic working buttons that don’t do anything, it feels like the framework is in place to start making our MP3 player play music. To do this we will need a few elements:

public var url:URLRequest;
public var xmlLoad:URLLoader;
public var musicXML:XML;
public var song:Sound;
public var channel:SoundChannel;
public var sndTrans:SoundTransform;
public var position:Number;

Our song:Sound will load the song and play it. The play() method in the Sound class returns a sound channel which we need to store in our channel:SoundChannel in order to pause/play/stop, or change the volume of our music.

The SoundTransform class is what is used to change the volume through the channel. It can also change the pan (balance of left and right speakers), but I’m not going to get into that.

What we are going to do is load an external XML file with our playlist in it… something like this:

>
id="/url/TheBestDayEver.mp3" disp="The Best Day Ever"/>
id="/url/come_away.mp3" disp="Come Away"/>
id="/url/nightmares.mp3" disp="Nightmares and Dreams"/>
id="/url/override.mp3" disp="Override"/>
id="/url/rescue.mp3" disp="Rescue"/>
id="/url/stick_em_up.mp3" disp="Stick’em Up"/>
id="/url/trogdor.mp3" disp="TROGDOOOR"/>
id="/url/you_are.mp3" disp="You Are"/>
>

Then we want to add each song on that playlist to a list component on the stage (I’ve called it playList). After we have the URLs of our songs, then we can start to load and play them.

In our xmlComplete(event:Event) event handler (handling the COMPLETE event from loading our XML file with a URLLoader) we need to parse the playlist into our List:

private function xmlComplete(event:Event):void {
var item:Object;
musicXML = new XML(event.currentTarget.data);

for each(var prop:XML in musicXML.song){
item = new Object();
item.label = prop.@disp;
item.data = prop.@id;
playList.addItem(item);
}

song = new Sound();
song.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
song.load(new URLRequest(playList.getItemAt(0).data));
this.addEventListener(Event.ENTER_FRAME, updateSeek);
playList.selectedIndex = 0;
}

The for each..in loop is one that not everyone knows about. It’s very useful for getting all the elements of an XML object when you aren’t sure how many elements there will be. Basically it’s assigning each song tag from the XMLList musicXML.song to prop and then runs the code within the curly brackets {}.

I don’t like it when music or sounds start playing on the internet without my consent. So, whenever I make something like and MP3 Player, I set it up to NOT automatically play.

Still, I want it to be ready to play as soon as the user tells it to. So, I needed to add those lines after my for each..in loop. What is happening might be obvious enough. I’m creating a new Sound object and storing it in song. I always check for load errors so that the end user doesn’t get annoying pop-ups telling them that I’m a bad programmer. Then I’m loading the first song on the playList and making that song highlighted in my List component.

The event listener with a handle of updateSeek is needed for my seekbar. I will get to that later.

Playing the music and traversing out PlayList:

Great! So, now we have everything set up to look like a complete player. We even have our first song loaded. But, there is no way to get it to play yet. Our PLAY button doesn’t work yet.

This is where we have to start giving those buttons some functionality. Most (if not all) of the functionality for each button is going to be in the MOUSE_UP event handlers:

private function PlayUp(event:MouseEvent):void {
var obj:Object = event.currentTarget;
if(obj.playing) {
obj.gotoAndStop(‘play_over’);
position = channel.position;
channel.stop();
obj.playing = false;
} else {
obj.gotoAndStop(‘pause_over’);
channel = song.play(position);
channel.soundTransform = (mute_mc.isMute)? new SoundTransform(0) : sndTrans;
channel.addEventListener(Event.SOUND_COMPLETE, soundComplete);
obj.playing = true;
}
}

…

private function StopUp(event:MouseEvent):void {
var obj:Object = event.currentTarget;
channel.stop();
position = 0;
playPause_mc.playing = false;
playPause_mc.gotoAndStop(‘play’);
obj.gotoAndStop(’stop_over’);
}

…

playList.addEventListener(ListEvent.ITEM_CLICK, SnglClick);

…

private function SnglClick(event:ListEvent):void {
var item:Object = event.item;

try
{song.close();}
catch(error)
{trace(error);}
try
{channel.stop();}
catch(error)
{trace(error);}

song = new Sound();
song.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
song.load(new URLRequest(item.data));
channel = song.play();
channel.soundTransform = (mute_mc.isMute)? new SoundTransform(0) : sndTrans;
channel.addEventListener(Event.SOUND_COMPLETE, soundComplete);
position = 0;
playPause_mc.playing = true;
playPause_mc.gotoAndStop(‘pause’);
}

…

private function soundComplete(event:Event):void {
if(playList.length > playList.selectedIndex + 1){
playList.selectedIndex++;
playList.scrollToSelected();
} else {
playList.selectedIndex = 0;
playList.scrollToSelected();
}
playList.dispatchEvent(new ListEvent(ListEvent.ITEM_CLICK, false, true, 0, playList.selectedIndex, playList.selectedIndex, playList.selectedItem));
}

…

private function ForwardUp(event:MouseEvent):void {
var obj:Object = event.currentTarget;
obj.gotoAndStop(‘forward_over’);

if(playList.length > playList.selectedIndex + 1){
playList.selectedIndex++;
playList.scrollToSelected();
} else {
playList.selectedIndex = 0;
playList.scrollToSelected();
}
playList.dispatchEvent(new ListEvent(ListEvent.ITEM_CLICK, false, true, 0, playList.selectedIndex, playList.selectedIndex, playList.selectedItem));
}

My Play/Pause button, if playing, will save the current position and then stop the music through the channel. Otherwise, it will play from position and set the volume and add a listener for the end of the song.

The Stop button obviously just stops the song and sets the position back to zero (0). I guess it also resets the Play button.

The ListEvent.ITEM_CLICK is when we click on a list item (a new song in the playlist). The handler closes any open stream that might be there (thus the try..catch) and if not then to simply stop the channel. It then loads the song URL stored in that items data provider and starts it playing.

The forward and back buttons are almost exactly the same. They just change the selection in the List component and then dispatch a fake ITEM_CLICK event.

The soundComplete() method, as you can see, is also very similar to the forward button. This event handler is called when a song played right to the end.

Working with volume:

Since I’ve already mentioned setting the volume, I might as well get into that next. The volume is a property of the SoundTransform class. We already made a SoundTransform variable, we just haven’t stored an ST object in it yet.

My main volume control is sndTrans:SoundTransform; After setting the volume property within it I can assign it to the channel.soundTransform and it will take effect. My volume bar has it’s own class to handle the effect of dragging the handle around:

package controls {
import flash.display.MovieClip;
import flash.events.*;
import flash.geom.Rectangle;

public class VolControl extends MovieClip {
private var bounds:Rectangle;
public var percent:Number;

public function VolControl() {
percent = 1;
bounds = new Rectangle(0, 10, 50, 0);

volBar_mc.hit_mc.addEventListener(MouseEvent.MOUSE_DOWN, dragHandle);
volHandle_mc.addEventListener(MouseEvent.MOUSE_DOWN, dragHandle);
volHandle_mc.addEventListener(MouseEvent.MOUSE_UP, endDrag);
volHandle_mc.addEventListener(MouseEvent.MOUSE_OUT, endDrag);
}

private function dragHandle(event:MouseEvent):void {
volHandle_mc.startDrag(true, bounds);
this.addEventListener(Event.ENTER_FRAME, changeVol);
}
private function endDrag(event:MouseEvent):void {
volHandle_mc.stopDrag();
volBar_mc.fullness_mc.fill_mc.x = volHandle_mc.x – volBar_mc.fullness_mc.fill_mc.width;
percent = volHandle_mc.x/50;
dispatchEvent(new Event("volume_change"));
this.removeEventListener(Event.ENTER_FRAME, changeVol);
}
private function changeVol(event:Event):void {
volBar_mc.fullness_mc.fill_mc.x = volHandle_mc.x – volBar_mc.fullness_mc.fill_mc.width;
percent = volHandle_mc.x/50;
dispatchEvent(new Event("volume_change"));
}
}
}

This is simply letting you drag around the little pointer within its bounds and dispatching an event to let the main class know that the volume has been changed. I needed to repeat some of the code from changeVol() in endDrag() because if you just click quickly then the ENTER_FRAME event never gets handled before it’s removed.

Back in the main class we are handling that “volume_change” event:

vol_mc.addEventListener("volume_change", updateVolume);
…
private function updateVolume(event:Event):void {
sndTrans.volume = vol_mc.percent;
channel.soundTransform = (mute_mc.isMute)? new SoundTransform(0) : sndTrans;
}

Another thing that a lot of new programmers don’t know about is the conditional ? : operator. It’s shorthand for an if..else statement. Basically these two bits of code are the same:

if(num>5) {
num = 5;
}else {
num = 0;
}
//OR THIS NEXT PART DOES THE SAME THING
num = (num>5)? 5 : 0;

Isn’t that great?

Getting back to our MP3 player. We should add our Mute button while we are working with volume. You’ve already seen that I take the mute condition into account when I set that volume. Here is where I set the mute condition:

private function MuteUp(event:MouseEvent):void {
var obj:Object = event.currentTarget;
if(obj.isMute) {
obj.gotoAndStop(‘mute_over’);
obj.isMute = false;
channel.soundTransform = sndTrans;
} else {
obj.gotoAndStop(‘unmute_over’);
obj.isMute = true;
channel.soundTransform = new SoundTransform(0);
}
}

I never want to set sndTrans.volume to zero (0) just because I pressed the mute button. I would rather leave that as it is so that I can unmute back to the original volume again.

*phew* About this time I’m thinking to myself, “It sure takes a lot of code to get a simple MP3 Player to work correctly.” But, there is light on the horizon so we must press on.

Making the seek bar to search a song:

Now for the most complicated part of our player. The seek bar. The seek bar isn’t THAT bad, but it’s definitely worse then what we have done so far.

First of all we will give the seek bar the same drag or click functionality that we gave to volume control bar:

public class SeekControl extends MovieClip {
private var bounds:Rectangle;
public var percent:Number;
public var seeking:Boolean;

public function SeekControl() {
seeking = false;
percent = 0;
bounds = new Rectangle(0, 12, 100, 0); //I made the seek bar 100 wide for convenience

seekHit_mc.addEventListener(MouseEvent.MOUSE_DOWN, dragHandle);
seekHandle_mc.addEventListener(MouseEvent.MOUSE_DOWN, dragHandle);
seekHandle_mc.addEventListener(MouseEvent.MOUSE_UP, endDrag);
}

private function dragHandle(event:MouseEvent):void {
seeking = true;
seekHandle_mc.startDrag(true, bounds);
}
private function endDrag(event:MouseEvent):void {
seeking = false;
seekHandle_mc.stopDrag();
fillBar_mc.x = seekHandle_mc.x – fillBar_mc.width;
percent = seekHandle_mc.x/100;
dispatchEvent(new Event("seek_change"));
}

public function moveSeekPos(perc:Number):void {
fillBar_mc.x = (fillBar_mc.width * perc) – fillBar_mc.width;
if(!seeking)
seekHandle_mc.x = 100 * perc;
}
}

The biggest difference here is that I don’t want a live update while dragging the pointer around. Otherwise, a few values have changed, some var names have changed, but it should look familiar (well it would if you had written this code yourself).

The moveSeekPos() method is going to be updated constantly from our main class. This is here so that we can see the play progress when listening to a song.

Getting back to the main class again, we have to write a thing or two about our seek bar there:

/*Remember that
this.addEventListener(Event.ENTER_FRAME, updateSeek);
is added when we start to load a new song.*/
seek_mc.addEventListener("seek_change", changeSeekBar);
…
private function changeSeekBar(event:Event):void {
position = song.length * seek_mc.percent;
if(playPause_mc.playing){
channel.stop();
channel = song.play(position);
channel.soundTransform = (mute_mc.isMute)? new SoundTransform(0) : sndTrans;
channel.addEventListener(Event.SOUND_COMPLETE, soundComplete);
}
}
…
private function updateSeek(event:Event):void {
if(playPause_mc.playing) {
var perc:Number = channel.position / song.length;
seek_mc.moveSeekPos(perc);
display_mc.timeDisp.text = formatTime(channel.position) + "/" + formatTime(song.length);
}
}
…
public function formatTime(time:Number):String {
var min:String = Math.floor(time/60000).toString();
var sec:String = (Math.floor((time/1000)%60) < 10)? "0" + Math.floor((time/1000)%60).toString() : Math.floor((time/1000)%60).toString();

return(min+":"+sec);
}

I went ahead and added the code here to display the current play time and the total play time in a dynamic text field on the stage. That seemed to be closely related to the seek bar, so I figured showing it here is suitable.

A final note:

Now would be a good time to mention that I didn’t bother fixing a “minor” bug. While a song is still streaming (loading), Flash doesn’t know how long it is. Thus, song.length will be growing over time till it’s done loading. This is only an issue for our seek bar, because it uses the ratio between the current position and the total length to decide how to display itself.

To work around this issue (which is really only an issue for slower internet connections), you will need to pass Flash the songs length along with the file path in the XML doc. It seemed like a lot of trouble to me and since this isn’t for a client, I figured I would just tell you about it instead of do it for you.

Wow. This was so long that I wouldn’t be surprised to find later that I forgot something. If I find anything I will make sure to update this post and make a note of what I changed.

Anyways, that is it! I think…

Let me know what you think about it and also let me know if you even use my Player on your site somewhere. I would love to see my work being used.

You can get the source files for this tutorial and the example at the beginning to the page here: MP3 Player Source Code.rar

UPDATE: I have updated the source file to include changes which will fix a few bugs pointed out to me over time. I also added a few new lines to the disclaimer at the beginning of my code which explains that WE DO NOT PROVIDE TECHNICAL SUPPORT FOR OUR EXAMPLE CODE. It is there for reference only. We would hope that you would use our code in conjunction with the tutorial to learn how to do it yourself.
We understand that most people will just download and use the code without much effort towards learn new skills, but we aren’t going to answer your questions in that case. If you notice something wrong with the code and want to bring it to our attention that would be appreciated, but any questions on how to use the code will be answered with “Read the tutorial.”