Requirements:

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites:

• Having done Part 1 and 2 of this tutorial.
• Intermediate programming skills.
• Moderate knowledge of AS3.
• Basic Familiarity with OOP.
• Basic knowledge of Flash CS3.

Step 0:

This is the last section of the tutorial we’ve been working on. We’re going to wrap up everything we’ve done so far and make our work a solid, working application, which we can use and even extend in the future. First, we will centralize all arbitrary parameters into what’s known as a model, then, we’re going to connect the photo gallery into an external xml so we can load images dynamically, and finally we’re going to enhance our graphics a little bit by adding a reflection effect to the 3D scene.

Step 1 – Centralizing data:

As I stated before, we will start by creating a place holder for all arbitrary variables used so far. With arbitrary variables I mean values that we’ve chosen such as the camera’s tween time in the “moveTo()” method within CameraController, or the Z position of the cameraTarget that can greatly affect the nature of the camera’s motion. All these will be placed in a class that will hold these static constants and will also be used to hold dynamic variables further on, so they can be accessed easily from anywhere in the application. So, go ahead and create a new folder next to “view” called “model”. In it, create a new Actionscript Class called “Model.as”.

Now, I need you to work alone for a while. The job to do is recognise all the values you have used so far throughout the application, that you think would be a good idea to name into a variable and control from this central class. Then, all these variables will be declared in Model.as as static constants. This is how my class looks after doing just that:

package  com.li.photoviewer.model

{ 

     public class Model

     {

          public static const  CAMERA_Z:Number = -2000;

          public static const  CAMERA_Z_ZOOMED:Number = -1500;

          public static const  CAMERA_ZOOM_TIME:Number = 1;

          public static const  CAMERA_ZOOM_EASE:String = "easeoutexpo";

          public static const  CAMERATARGET_FRICTION:Number = 0.95;

          public static const  CAMERATARGET_BOUNCE_FACTOR:Number = 0.5;

          public static const  CAMERATARGET_DRAG_FACTOR:Number = 0.1;

          public static const CAMERATARGET_SPEED_FACTOR:Number  = 0.05;

          public static const  CAMERATARGET_Z:Number = -100;

          public static const  CAMERATARGET_MOVETO_TIME:Number = 1;

          public static const  CAMERATARGET_MOVETO_EASE:String = "easeoutexpo";

          public static const  PHOTO_PLANE_SEGMENTS:Number = 3;

          public static const  PHOTO_MATERIAL_SMOOTH:Boolean = true;

          public static const  PHOTO_FADEIN_TIME:Number = 0.25;

          public static const  PHOTO_SPACING:Number = 750;

          public static const  BG_COLOR1:uint = 0x222222;

          public static const  BG_COLOR2:uint = 0x000000;

          public static const  BG_COLOR_RATIO:uint = 80

          public function Model()

          {

          }

     }

}

“public static const” is a way to declare a variable that will be accessible from the outside of the class, can be accessed without instantiating the holder class, and will not change. If you don’t what Im talking about, you should see how we are going to use these variables and then come back to what I’ve just said and you should get it right away.

Step 2 – Connecting to the centralized data:

So far all this is completely useless unless we connect our classes to Model.as, so that the constants can be used. This is done very easily; for instance to connect the “0.05” value representing a camera velocity factor, we do as in the following code:

private function followTarget(evt:Event):void

{

     camera.lookAt(cameraTarget.position);

     var dX:Number = cameraTarget.x - camera.x;

     camera.x  += dX*0.05;

...

Simply change to:

private function followTarget(evt:Event):void

{

     camera.lookAt(cameraTarget.position);

     var dX:Number = cameraTarget.x - camera.x;

     camera.x  += dX*Model.CAMERATARGET_SPEED_FACTOR;

     ...

As long as the model has been imported in CameraController of course:

import com.li.photoviewer.model.Model;

So this is what you should do next. Import Model.as in all the view and controller classes, and connect the values to it. If you’ve imported the model into a class first, you should get useful codehints from Flex to help you complete this task. When you’re done, you’ll have the power to very precisely tweak the entire application from Model.as. You should play around with this to tune it to your liking.

Step 3 – Setting up an external XML:

Now that our model is set up and working, we will read data from an external xml, and also use the model to store the data contained in the xml. We will trigger a service that will read an xml and detail the images that will be loaded in our application, and once this service is done, the 3D scene will build itself based on this data. For this, lets start by designing our xml. Create a folder named “data” and in it a new file named “data.xml”. The folder should be next to “com” or  “away3d” folders. Then design the xml structure of data.xml like this:

<?xml  version="1.0"?>

<imgs>

     <img name="testImage.jpg"/>

     <img  name="1.jpg"/>

     <img  name="2.jpg"/>

     <img  name="3.jpg"/>

     <img  name="4.jpg"/>

     <img  name="5.jpg"/>

     <img  name="6.jpg"/>

     <img  name="7.jpg"/>

     <img  name="8.jpg"/>

     <img  name="9.jpg"/>

     <img  name="10.jpg"/>

</imgs>

The xml is extremely simple, it just contains the name of each image.

Step 4 – Creating an XML Reader:

We should continue by creating a folder called “services” next to “view” and in it a new Actionscript Class called “XmlReader”, which will take care of extracting the data from the xml. This class should have two variables in its constructor, “xmlPath” as a string and “onComplete” as a function, It will also have a “loader” variable as a URLoader:

private var xmlPath:String;

private var onComplete:Function;

private var loader:URLLoader;

public function XmlReader(xmlPath:String,  onComplete:Function)

{

     this.xmlPath = xmlPath;

     this.onComplete = onComplete;

     loader = new URLLoader();

     loader.addEventListener(Event.COMPLETE,  completeHandler);

     loader.load(new URLRequest(xmlPath));

}

The path of the xml file is stored, (as well as “onComplete” which we will see in a minute), then the loader is initialized and triggered. The function “completeHandler()” will, as its name says, handle the loader once it’s done:

private function completeHandler(evt:Event):void

{

     var xmlDocument:XMLDocument = new  XMLDocument();

     xmlDocument.ignoreWhite  = true;

     var xml:XML = new XML(evt.target.data);

     xmlDocument.parseXML(xml.toString());

     for(var i:uint; i<xmlDocument.firstChild.childNodes.length;  i++)

          Model.data.push(xmlDocument.firstChild.childNodes[i].attributes.name);

     onComplete();

}

The handler parses all the data in the xml and injects it in the model. Of course, we need to go back to Model.as and declare this “data” variable that we are referring to. Just add it after all the constants:

public static var data:Array = [];

Finally (referring again to the completeHandler method), “onComplete()” gets called as soon as all the parsing is done. Remember that we designed this XmlReader to receive a reference to this external function when it is instantiated. This will simply be the function to be called when the reader has finished its job.

Step 5 – Using the reader:

Lets implement this now in the application’s main class, PhotoViewer3D.as. Carefully study these modifications:

package

{

     import com.li.photoviewer.services.XmlReader;

     import com.li.photoviewer.view.PhotoScene;

     import flash.display.Sprite;

     import flash.display.StageAlign;

     import flash.display.StageScaleMode;

     [SWF(backgroundColor="0x000000", frameRate="30")]

     public class PhotoViewer3D extends Sprite

     {

          public function PhotoViewer3D()

          {

               stage.scaleMode  = StageScaleMode.NO_SCALE;

               stage.align  = StageAlign.TOP_LEFT;

               var reader:XmlReader = new XmlReader(”data/data.xml”, init);

          }

          private function init():void

          {

               var photoScene:PhotoScene = new PhotoScene();

               addChild(photoScene);

          }

     }

}

I’ve just instantiated an XmlReader, pointed it to the xml path, put the creation of the scene in its own separate method, and also pointed the reader to this method so its called as soon as its done.

Step 6 – Loading the images:

The next step is pretty obvious. We now have the data array containing all the names of our images, waiting for us in the model and we’ve also delayed the creation of the 3D scene till after this data has been obtained. So we just need to alter the “initObjects()” method of PhotoScene.as to read this data. It’s too simple actually:

private function initObjects():void

{

     for(var i:uint; i<Model.data.length; i++)

     {

          var photo:PhotoLoader = new PhotoLoader("imgs/" + Model.data[i]);

          photo.x  = i*Model.PHOTO_SPACING;

          scene.addChild(photo);

          cameraController.maxX  = photo.x;

          photo.addOnMouseDown(photoClickHandler);

     }

}

That’s it. Test the application and see how it now loads all the corresponding different images. We’re practically done now, I just want to add an additional effect to the app…

Step 7 – Adding a reflection:

As it is usual in many open source projects, many people share their code in classes that can be very handy and easy to use. You can very often download a class that does a particular thing, use it, and never know how it actually works. So that’s what we’ll do, we will greatly enhance the look of our application by downloading a class, and I will make my point of showing how great it is to use other people’s classes, or even design classes yourself to be reusable in this way.

Download Reflection.as and paste it in the view folder.

The class should be ready to work, except that its package path is all wrong. This is pretty logical, since I’ve just used it for another project and it was placed completely on a different place. Correct this path to the class’ current location. You can also look into the class, now or later, to understand how it works and maybe learn new things that could motivate you to other uses or even new ideas with Away3D.

Step 8 – Plugging in the reflection:

Go back to PhotoScene.as and declare the reflection instance (we don’t need to import Reflection.as since it is in the same package as PhotoScene.as):

private var  reflection:Reflection;

Then, in the “initScene()” method, initialize it and add it to the display list:

reflection = new Reflection(scene, camera);
addChild(reflection);

And finally, in “renderScene()” add a call to the reflections rendering method:

private function renderScene(evt:Event):void

{

reflection.render();

view.render();

}

I also took the time to connect the Reflection class to the model and drop its arbitrary variables there. I even set up a USE_REFLECTION constant in the model and applied this Boolean value in the initialization of the reflection in “initScene()” and the “renderScene()” method too. All this allows you to, not only tweak the app to look good, but also to consider performance issues. With the values that you should have in the model after you do this, you can really optimize the application.

public static const USE_REFLECTION:Boolean = false;

public static const REFLECTION_OFFSET:Number = -525;

public static const REFLECTION_BLUR:Number = 8;

public static const REFLECTION_ALPHA:Number = 0.25;

public static const REFLECTION_SCALING:Number = 2;

So, that’s it! The application is flexible enough to be extended easily. Maybe a horizontal scroller could be a good idea, for example… I leave that to your creativity. I wanted to keep the MVC architecture as simple as I could by avoiding custom events, singleton classes, etc, but those could be good things to investigate for future projects. On the other hand, I really recommend playing with the Away3D engine, the possibilities with it are endless!!

I hope you’ve enjoyed the tutorial. I’m looking forward to make another one when I can =)

In the final the result will be this.

Requirements:

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites:

• Having done Part 1 of this tutorial
• Intermediate programming skills
• Moderate knowledge of AS3
• Basic Familiarity with OOP
• Basic knowledge of Flash CS3

Step 0

In this part we’re going to use the PhotoLoader component we designed previously, and set up the 3D scene showing multiple instances of it. Then, we’re going to develop the interactivity of the user for that scene. This will be the most intense part of the series, but hopefully the most fun.

Step 1 – Adapting the TestScene to the official scene

So, the first thing we have to do is rename our TestScene.as. Right click on the file, choose Rename and select PhotoScene as the new name. Flex should have updated the references to this class in your source, so that no errors are shown. However, you should go to the main file, “PhotoViewer3D” and rename the PhotoScene instance to “scene”, its not necessary, but its tidy. If any errors are thrown, it’s a good time to get to know the Flex Console. It is a panel at the bottom of Flex, in which errors are detected before compilation time. Its very probable that you noticed it already, just making sure. If you double click on one of the errors it shows you, Flex takes you directly to the source of that error. I really don’t know any quicker way to debug errors in Actionscript projects.

Step 2 – Multiple objects

Now, we’re going to modify the “initObjects()” method in PhotoScene to create 10 instances of PhotoLoader instead of just one, and arrange these instances horizontally. Use this code:

private function initObjects():void
{
     for(var i:uint; i<10; i++)
     {
          var photo:PhotoLoader = new PhotoLoader(“imgs/testImage.jpg”);
          photo.x  = i*700; <
          scene.addChild(photo);
     }
}

You should now see more instances to the right of the first one, even though we cant see all of them due to our limited camera control lines in the “renderScene()” method.

Step 3 – Enhancing camera controls

That’s what we’re going to do now; begin building a controller class that will provide more advanced camera user control. This part is pretty fun, since we’ve reached the level of complexity in which Away3D starts showing off its awesome capabilities.

Delete these lines in the “renderScene()” method in PhotoScene, we wont need them anymore:

camera.x = 3*(mouseX - stage.stageWidth/2);
camera.y = 3*(mouseY - stage.stageHeight/2);
camera.lookAt(new Number3D(0, 0, 0));

The new code that we will develop to achieve the enhanced camera motion will be more complex, logically, so it will not reside in our PhotoScene class. It will be in its own class, designed specifically for this, that is, camera motion control. Create a new folder next to “view” and name it “controller”. In it, create a new Actionscript Class named “CameraController”. Once done, make this class extend Sprite.

Now, back in PhotoScene.as, create a new variable named cameraController as:

private var cameraController:CameraController; 

After the “initScene()” call in the “init()” method in PhotoScene, place a new call to “initCameraController()”. And lets define this as follows:

private function initCameraController():void
{
    var cube:Cube = new Cube();
    cube.width  = cube.height = cube.depth = 10; 

     cube.z =  -100; 

     scene.addChild(cube); 

     cameraController  = new CameraController(camera, cube); 

     addChild(cameraController);

Don’t worry, I’ll explain. What we did is create a small cube and added it to the scene. Then, we instantiated our new CameraController, passing it two parameters and added it to the display. Why those two parameters? And what is the purpose of that cube?! As you will fully understand later, the cube will be used as the camera’s target, the camera will constantly be “looking” at it and trying to follow it. This is a very interesting technique used in 3D, since it provides a way to simulate natural and realistic camera motion effects.

Step 4 – Building the CameraController

Great, now lets go back to the controller and shape it up a little. In PhotoScene, when we instantiated it, we passed it 2 parameters. Lets assimilate them in the constructor and store these references. We’re also going to create an init method that will be called once the instance has been added to the stage, as we’ve done before:

private var camera:Camera3D; 

private var cameraTarget:Cube; 

public function CameraController(camera:Camera3D,  cameraTarget:Cube) 

{ 

     this.camera = camera; 

     this.cameraTarget = cameraTarget; 

     this.addEventListener(Event.ADDED_TO_STAGE, init, false, 0, true); 

} 

private function init(evt:Event):void 

{ 

     this.removeEventListener(Event.ADDED_TO_STAGE, init); 

}

Add a new event listener in the “init()” method to call a new “followTarget()” in enterframe.

this.addEventListener(Event.ENTER_FRAME,  followTarget);

And define “followTarget()” as:

private function followTarget(evt:Event):void 

{ 

     cameraTarget.x  += 10; 

     camera.lookAt(cameraTarget.position); 

}

Test it out. You should be able to see the little cube starting next to the first photo and then moving to the right. The camera will look at it as it goes away. Lets extend it a bit further by telling the camera not just to look at it, but also to try to keep up with it. Add these lines to the “followTarget()” method:

var  dX:Number = cameraTarget.x - camera.x;

camera.x += dX*0.05;

Test it again… Im sure you can tell the different and understand the code with what you see.

Before we go on, delete the first line in “followTarget()” that moves the camera target to the right, it was just used for demonstration purposes. From now on, the target wont move by its own, we are going to move it.

Step 5 – Setting up interactivity

That looks good, but now lets make it more realistic, and most importantly, interactive. In PhotoScene, we are going to modify the “initObjects()” method again to register a click listener on the photos, and that method is going to call another method in the camera controller, telling it to move the camera to that photo. Don’t worry, you’ll be amazed by how simple this is going to be.

In the for loop inside of “initObjects()” in PhotoScene, add this line at the end:

photo.addOnMouseDown(photoClickHandler);

And add a couple of lines in the constructor of PhotoLoader to tell the cursor to show a hand when we roll over the photos:

this.ownCanvas = true; 

this.useHandCursor = true; 

Then, define the “photoClickHandler()” back in PhotoScene method as:

private function photoClickHandler(evt:MouseEvent3D):void 

{ 

     cameraController.moveTo(evt.object.x); 

}

Yes, we need to define the public “moveTo()” method in the CameraController, so lets do it:

public function moveTo(X:Number):void 

{ 

Tweener.addTween(cameraTarget, {x:X,  time:1, transition:“easeoutexpo”}); 

}

It will work as long as you import the Tweener class in CameraController. Test the application and click on the images. That’s it!!

Step 6 – Setting up mouse drag

Next, the app is going to have a pretty cool feature, which is the ability of the user to click on the canvas and drag himself (the camera that is) around the scene. We’ll manage this in 3 steps, so follow along.

First, we’re going to need 2 clips that will capture the mouse down and mouse up for the dragging. One will be behind the photos, and the other above them. Besides, we will take advantage of the one behind to make the app look a bit better by using it as a background as well. Modify “initScene()” in PhotoScene like this:

private function initScene():void 

{ 

     scene = new Scene3D(); 

     camera = new Camera3D(); 

     camera.zoom  = 10; 

     camera.focus  = 200; 

     camera.z =  -2000; 

     background  = new Sprite(); 

     var mat:Matrix = new Matrix(); 

     mat.rotate(-Math.PI/2); 

     background.graphics.beginGradientFill(GradientType.LINEAR,  [0x222222, 0x000000], [1, 1], [0, 80], mat); 

     background.graphics.drawRect(0,  0, stage.stageWidth, stage.stageHeight); 

     background.graphics.endFill(); 

     addChild(background); 

     background.addEventListener(MouseEvent.MOUSE_DOWN,  handleBackgroundMouseDown); 

     view = new View3D(); 

     view.camera  = camera; 

     view.scene  = scene; 

     view.x =  stage.stageWidth/2; 

     view.y =  stage.stageHeight/2; 

     view.clip  = new RectangleClipping(-stage.stageWidth/2,  -stage.stageHeight/2, stage.stageWidth/2, stage.stageHeight/2); 

     addChild(view); 

     foreground  = new Sprite(); 

     foreground.graphics.beginFill(0×00FF00,  0.5); 

     foreground.graphics.drawRect(0,  0, stage.stageWidth, stage.stageHeight); 

     foreground.graphics.endFill(); 

     foreground.visible  = false; 

     addChild(foreground); 

     foreground.addEventListener(MouseEvent.MOUSE_UP,  handleForegroundMouseUp); 

     foreground.addEventListener(MouseEvent.MOUSE_OUT,  handleForegroundMouseUp); 

}

And don’t forget to declare background and foreground private variables at the beginning of the class, plus import the GradientType class:

import flash.display.GradientType; 

What we just did was add these two before and after the view. It was done in this order to maintain the layering we talked about before. The background is simply a sprite with a gradient, and the foreground is a semi transparent green clip above everything. Comment the 3 listener lines we’ve just added, and “foreground.visible = false” and test the app. As you can see, the sprites have been added to the display.

Now, uncomment those lines and go ahead and define the handler methods as:

private function handleBackgroundMouseDown(evt:MouseEvent):void 

{ 

     foreground.visible  = true; 

} 

private function handleForegroundMouseUp(evt:MouseEvent):void 

{ 

     foreground.visible  = false; 

}

If you test the app again, you’ll see the idea behind all this. The background captures the mouse down and shows the foreground, which is simply there to capture the mouse up. Even though this might look confusing, its pretty practical. If it wasn’t there and we had set up the background to capture the mouse up, it wouldn’t work very well since we could press on the background and then, while the mouse is still pressed, move over to a photo and release the mouse once we’re there… The background wouldn’t have captured the mouse up, because the photo would have captured it. So, what we’ve just done makes sure we don’t have to worry about this kind of stuff. It’s solid, Im sure there might be other methods, but Im comfortable with this one. Before we continue, set the foreground’s draw alpha from 0.5 to 0 so we don’t see it anymore (it will do its job anyway).

Step 7 – Designing the mouse drag

We need to define the dragging now. On the handlers we’ve just created, add “cameraController.startCameraDrag();” for the mouse down handler, and “cameraController.stopCameraDrag();” for the mouse up handler. And of course, we need to define those methods in the CameraController class. These two methods will simply toggle a mouse move event listener that will continuously call a dragCamera method while the mouse is pressed:

public function startCameraDrag():void 

{ 

lastMouseX = stage.mouseX; 

     stage.addEventListener(MouseEvent.MOUSE_MOVE,  dragCamera, false, 0 , true); 

} 

public function stopCameraDrag():void 

{ 

     stage.removeEventListener(MouseEvent.MOUSE_MOVE,  dragCamera); 

} 

private function dragCamera(evt:MouseEvent):void 

{ 

     var dX:Number = lastMouseX - stage.mouseX; 

     cameraTargetVX  += dX*0.1; 

     lastMouseX  = stage.mouseX; 

}

Of course, you’re going to need to define “lastMouseX” and “cameraTargetVX” as private variables at the top of the class. Make sure you set cameraTargetVX to zero when you declare it. Ill explain what’s going on shortly, I want you to see it working first…

To apply what we’ve just done, add these lines to the “followTarget()” method:

cameraTarget.x += cameraTargetVX; 

cameraTargetVX *= 0.95;

And to correct incongruencies, add “cameraTargetVX = 0;” in the “moveTo()” method.

Check it out by testing the app and clicking and dragging from the background. Its simple code, with pretty impressive smooth results. So, as I said, let me explain a little now. When a drag is started, the controller stores the current mouse position and begins the continuous call to the drag method. In this method, the first thing that happens is that the stored initial mouse position is compared to the actual mouse position every time the mouse moves. This value is then used to alter “cameratargetVX” which is just a variable that represents the velocity of the camera, and the current mouse position is again stored. On the mean time, in the “followTarget()” method, the velocity variable is constantly being added to the cameraTarget’s position. This is the very basics of simulating velocity physics on programming. In this method, the velocity value is also dampened by 5% to simulate friction. Finally, the “stopCameraDrag()” method unplugs the continuous call to “dragCamera()”.

Step 8 – Adding zoom

Next, we will add a cool zoom effect, which is going to be really simple. Add this methods in Camera Controller:

private function zoomIn():void 

{ 

     Tweener.addTween(camera,  {z:-1500, time:1, transition:“easeoutexpo”}); 

} 

private function zoomOut():void 

{ 

     Tweener.addTween(camera,  {z:-2000, time:1, transition:“easeoutexpo”}); 

}

And add a zoomIn() call in the “moveTo()” method, and a zoomOut() call in the “startCameraDrag()” method. Test the app. It’s as simple as that, we now have a little zoom effect working.

Step 9 – Containing motion

Before we finish this part of the tutorial, we need to face a little issue you might have noticed: The user can drag himself far away from the photos, and we don’t want this. We want to contain the camera in an area where the user will always see the photos.

To define the area that the user will move in, define two public variables in CameraController. They’re public because, even though we define them in CameraController, they will be filled up from the PhotoScene each time a new photo is created:

public var minX:Number = 0; 

public var maxX:Number =  0;

Now go to PhotoScene and, in “initObjects()” add “cameraController.maxX = photo.x;” inside the end of for loop. This results in that each time a photo is created, the scene reports the camera controller how far the camera target should be able to move.

Now last, but not least, add this containment code to the end of “followTarget()” in cameraController:

if(cameraTarget.x  > maxX) 

{ 

     cameraTarget.x  = maxX; 

     cameraTargetVX  *= -0.5; 

} 

else if(cameraTarget.x < minX) 

{ 

     cameraTarget.x  = minX; 

     cameraTargetVX  *= -0.5; 

}

This simply checks if the target has exceeded the limits of the scene, and if so, docks the target at one of the limits and inverts its velocity to make it “bounce”. You may enhance this code by making it consider positions before a velocity value is applied, etc. It would look better, but I wanted to keep things as simple as possible here.

And that does it for part 2 of the tutorial… To wrap things up go to PhotoScene and add “cube.visible = false;” in “initCameraController()” so that the little cube is hidden from the user.

Next

On part 3 we will give the application a closure by centralizing arbitrary variables, enhancing graphics a bit, and connecting it to an external XML that will indicate it what images to load.

In the final the result will be this.

Requirements

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites

• Intermediate programming skills
• Moderate knowledge of AS3
• Basic Familiarity with OOP
• Basic knowledge of Flash CS3

Step 0

In this tutorial I will assume that you are familiar with the basics of building an Actionscript Away3D project in Flex. If you haven’t used these two technologies together before, it would be best if you go through my previous tutorial first. Due to the complexity of this application, I will need to skip some things to go faster. So, if something is not explained here, or suddenly a large chunk of code is dropped with no descriptions, it has been covered (hopefully) in the mentioned tutorial.

Step 1 – New Project

Lets get started. Create a new Actionscript Project in Flex and name it “PhotoViewer3D”. Then, download the libraries I listed in the requirements and paste them in the project’s folder.

Now, one of the things that will be covered here is a very simplified application architecture that could be a good starting point for any project you do that implies a moderate level of complexity. For this, all code will be placed in a folder structure, carefully separating functions between different classes, and hence emulating the basics of a Model View Controller design pattern. You should have a general grasp of it by the end of this series.

Right click on the project’s folder in the Flex Navigator and choose New -> Folder, then type “com/li/photoviewer/view” and press Finish. Naming folders this way is known as Reverse Domain Syntax, and is a good programming practice.

Step 2 – Setting up the scene

Go to PhotoViewer3D.as and build a basic main class:

package
{
     import flash.display.Sprite;
     import flash.display.StageAlign;
     import flash.display.StageScaleMode;

     import com.li.photoviewer.view.TestScene;

[SWF(backgroundColor="0x000000", frameRate="30")] 

     public class PhotoViewer3D extends Sprite
     {
          public function PhotoViewer3D()
          {
               stage.scaleMode  = StageScaleMode.NO_SCALE;
               stage.align  = StageAlign.TOP_LEFT;

               var testScene:TestScene = new TestScene();
               addChild(testScene);
          }
     }
}

Line 7 imports an away3D holding class that we haven’t made yet, so we should create it right away. Right click on the “view” folder and choose New -> Actionscript Class and name it “TestScene”. It should have the following code in it:

package com.li.photoviewer.view 

{ 

     import away3d.cameras.Camera3D;
     import away3d.containers.Scene3D;
     import away3d.containers.View3D;
     import away3d.core.clip.RectangleClipping;
     import away3d.core.math.Number3D; 

     import flash.display.Sprite;
     import flash.events.Event; 

     public class TestScene extends Sprite
     {
          private var scene:Scene3D;
          private var camera:Camera3D;
          private var view:View3D; 

          public function TestScene()
          {
               addEventListener(Event.ADDED_TO_STAGE,  init, false, 0, true);
          } 

          public function init(evt:Event):void
          {
               removeEventListener(Event.ADDED_TO_STAGE,  init); 

               initScene();
               initObjects();
               addEventListener(Event.ENTER_FRAME,  renderScene);
          } 

          private function initScene():void
          {
               scene  = new Scene3D(); 

               camera  = new Camera3D();
               camera.zoom  = 10;
               camera.focus  = 200;
               camera.z  = -2000; 

               view  = new View3D();
               view.camera  = camera;
               view.scene  = scene;
               view.x  = stage.stageWidth/2;
               view.y  = stage.stageHeight/2;
               view.clip  = new RectangleClipping(-stage.stageWidth/2,  -stage.stageHeight/2, stage.stageWidth/2, stage.stageHeight/2);
               addChild(view);
          } 

          private function initObjects():void
          {
                
          } 

          private function renderScene(evt:Event):void
          {
               camera.x  = 3*(mouseX - stage.stageWidth/2);
               camera.y  = 3*(mouseY - stage.stageHeight/2);
               camera.lookAt(new Number3D(0, 0, 0)); 

               view.render();
          }
     }
}

NOTE: If any of this shocked you, it has all been explained in the tutorial mentioned in Step 0.

Step 3 – Setting up our PhotoLoader component

Create a new Actionscript Class in the view folder and name it “PhotoLoader”. These will be our 3D photograph object. The class will extend Away3D’s Plane primitive, with a few additional features, more particularly, the ability to load an external image. So, lets start by setting up the plane:

package com.li.photoviewer.view
{
import away3d.primitives.Plane;

public class PhotoLoader extends Plane
     {
private var urlPath:String;

          public function PhotoLoader(urlPath:String)
          { 

               super();

               this.urlPath = urlPath;

               this.rotationX = 90;
               this.width = 640;
               this.height = 480;
               this.segmentsH = 4;
               this.segmentsW = 4;
          }
     }
}

As you can see, we’ve set up the constructor so that when we instantiate a PhotoLoader object, we pass it the image name it has to load as a parameter. Now, go back to TestScene, and in the “iniObjects()” method, make an instance of PhotoLoader and add it to the scene:

var testPhoto:PhotoLoader = new PhotoLoader(“imgs/testImage.jpg”);

scene.addChild(testPhoto);

The urlPath we passed this time will be irrelevant, but we’ll pass it anyway so no errors are thrown. Go ahead and test the application, you should see something like this:

Step 4 – Skinning the plane with Flash

First of all, we need to give the plane a skin or texture. Even though it will contain an image, it needs to contain something else while it’s loading, and somehow show progress for that load process. For this, we will design some graphics in Flash, and bring them to Flex with what I find to be a very practical and simple technique. We will use a fla file to generate a library.swf file that will contain some graphics for our application, and then embed that swf in Flex and extract the clips as we need them. This is a very useful technique, and I definitely recommend it for any Flex projects that contain design based vector graphics.

Open Flash, create a new AS3 Flash File and save it in your project’s folder, next to PhotoViewer3D.as. Once in it, select File -> Publish Settings and type “assets/library.swf” for the swf output path (deselect the html output). Now, create a new folder next to that fla called “assets” either from your file explorer or by right clicking the project’s folder in the Flex Navigator. Now, if you publish the fla you will see that library.swf shows up in your newly created assets folder.

Step 5 – Creating and extracting the graphics created in Flash

Great, now I wont be describing how to make the graphics in Flash since I believe you must be very familiar with this. You should download the fla and overwrite the one you just made. Sorry! Just wanted to make sure you understood what’s going on. Now, open the downloaded fla. You will see a clip called “LoaderFront” made up of a gray box and a progressBar clip which has in turn a sub clip. The important thing to notice here is that LoaderFront has a Linkage and its Base Class was changed to Sprite. Publish it again, go back to Flex, right click on library.swf in the assets folder and choose Refresh.

This is the only code you’ll need to pull those graphics from Flex, type it at the top of the PhotoLoader class (inside Public class…):

[Embed(source="assets/library.swf", symbol="LoaderFront")]
public var LoaderFront:Class;

You’ve just extracted the symbol from the swf’s library and assigned it to a LoaderFront class. If you create a new instance of this class (and add it to the display tree), you’ll have a graphics object that extends Sprite! And you can treat it as any other sprite. Great isn’t it?

Step 6 – Applying the graphics to the plane

Go back to PhotoLoader.as and create these variables for the class:

private var materialSprite:Sprite;
private var progressBar:Sprite;
private var progressBarSubClip:Sprite;

And then this method:

private function initClips():void
{
     materialSprite  = new LoaderFront();

     progressBar  = Sprite(materialSprite.getChildByName(“progressBar”));
     progressBarSubClip  = Sprite(progressBar.getChildByName(“subClip”));
}

Now we have references to all the clips that we need. You have to add the “initClips()” call at the end of the constructor class.

Next, type this new method under the last one and also make sure you call it from the constructor:

private function initMaterial():void
{
     var material:MovieMaterial = new MovieMaterial(materialSprite);
     material.smooth  = true;

     this.material = material;
}

And Test the application. You should now see that the plane has taken the graphics as its material. Your PhotoLoader class should look like this so far:

package com.li.photoviewer.view
{
     import away3d.materials.MovieMaterial;
     import away3d.primitives.Plane;
     import flash.display.Sprite;
     public class PhotoLoader extends Plane
     {
         [Embed(source="assets/library.swf", symbol="LoaderFront")]
          public var LoaderFront:Class;
          private var urlPath:String;
          private var materialSprite:Sprite;
          private var progressBar:Sprite;
          private var progressBarSubClip:Sprite;
          public function PhotoLoader(urlPath:String)
          {
               super();
               this.urlPath = urlPath;
               this.rotationX = 90;
               this.width = 640;
               this.height = 480;
               this.segmentsH = 4;
               this.segmentsW = 4;
               initClips();
               initMaterial();
          }
          private function initClips():void
          {
               materialSprite  = new LoaderFront();
               progressBar  = Sprite(materialSprite.getChildByName(“progressBar”));
               progressBarSubClip  = Sprite(progressBar.getChildByName(“subClip”));
          }
          private function initMaterial():void
          {
               var material:MovieMaterial = new MovieMaterial(materialSprite);
               material.smooth  = true;
               this.material = material;
          }
     }
}

Step 7 – Loading images into the plane

The final thing to do for Part 1 of this tutorial, is implement all the image loading features of our extended plane. For this, we will use a regular Loader instance and add a few event listeners to check for progress and complete events.

Add the loader variable next to the other class variables:

private var loader:Loader;

And call a new method under the “initMaterial()” call in the constructor as “initLoader()”, then build the method:

private function initLoader():void
{
     loader = new Loader();
     loader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS,  progressHandler);
     loader.contentLoaderInfo.addEventListener(Event.INIT,  initHandler);
     materialSprite.addChild(loader);
     loader.alpha  = 0;
}

The loader is initialized, two listeners are registered, then the loader is injected to the plane’s material sprite completely invisible. I’ve made it invisible because I’m going to make it fade in once the image has been loaded into it.

Now, lets set up the handlers and a little “setProgress()” utilitary method:

private function progressHandler(evt:ProgressEvent):void
{
     setProgress(evt.bytesLoaded/evt.bytesTotal);
}
private function initHandler(evt:Event):void
{
     Tweener.addTween(loader,  {alpha:1, time:1, transition:“easeoutexpo”});
}
 
private function setProgress(value:Number):void
{
     progressBarSubClip.scaleX  = value;
}

Pretty straight forward. As the image downloads, the progress handler calls the “setProgress()” function which in turn sets the horizontal scale of the progress bar, and when the download completes, or more precisely when the loaded content is initialized, Tweener makes the loader fade in by animating its alpha. Don’t forget to import Tweener for this:

import caurina.transitions.Tweener;

Step 8 – Triggering the load

Next, lets trigger the load by adding a “loadImage()” method as the last method called in the constructor and defining it:

private function loadImage():void
{
     loader.unload();
     loader.alpha  = 0;
     setProgress(0);
     loader.load(new URLRequest(urlPath));
}

Finally, create the imgs folder in the project, download THESE images and paste them in it. Test the app, you should see the image loaded on the plane:

Watch the Demo HERE.

Next:

On the next part we will continue to develop our application by using multiple instances of this PhotoLoader object, developing advanced camera motion and interactivity.

The result is THIS and you can download the source HERE.

Requirements:

Flex 3

Try/Buy

Pre Requisites:

- Intermediate programming skills.

- Some knowledge and understanding of the Actionscript 3 language.

- Basic principles of OOP (Object Oriented Programming).

Step 0

NOTE: you may skip this if you’re already familiar with Flex, and know what away3d is.

This tutorial deals with 2 technologies. Away3d and Flex. Before we start, let me say a few words about them:

Away3d is an open source 3d engine designed to boost flash based applications with powerful 3d capabilities. There are a few other3d engines out there, such as Papervision3d, Sandy3d, Alternativa3d and more, each with its pros and cons. I personally useAway3d, because I think its the most apt engine at this time.

Flex is something most developers that come from the Flash arena fear pretty badly. What is it?? Well, the thing is that Flex can be used in complement with Flash for Actionscript projects very easily, providing them with powerful programming tools.Let me list a few:

- When you create a new variable and introduce the “:” character, Flex lists all available object types, and if you press enter after you found the appropriate type, flex automatically creates the import statements for you. This is extremely handy, since you don’t need to remember what package an object belongs to, nor consult the API reference to write the appropriate import statement.

- Flex detects errors while you code! That is, you don’t need to compile your project to see if you made mistakes. This is simple magical.

- By pressing F1 over an object type, Flex takes you to the help section for that type, and if you press F3, it takes you right to the definition of that object. This dramatically accelerates the learning process of any given API.

Well, enough, lets get started. I just wanted to emphasize on the great help that Flex provides when dealing with AS3 development. Personally, once I got over the scary, “what the hell is flex” phase, I cant imagine working without it now.

Step 1

Download the FlexBuilder 3 fully functional 60 day trial from adobe and install it. You just need to create an Adobe account and download the trial from this link.

Then download the latest Away3d API.

Step 2

Create a folder somewhere in your hard drive that will work as your workspace for initial Away3d experimentation. This folder will be able to hold many flex projects.

Open flex, select file -> switch workspace, and point flex to the folder you just created.

Now, right click on the Flex Navigator panel, and select new “Actionscript Project”.

Once the dialog shows up, enter Away3dProject as the project name and click finish.

If you go back to your HD file browser and see the folder you created initially, you can notice that flex created an inner folder for this project. The Flex Navigator pretty much works like a regular file browser, listing the projects you have on that workspace and the files that conform them.

Step 3

Go to your away3d download in your file browser and copy the folder in it named away3d. Come back to the flex navigator, right click on the Away3dProjectfolder icon and paste.

That’s it! Flex is ready to work with the Away3d engine.

Step 4

Its time to code. Right click the Away3dProject folder icon in the Flex Navigator again, and choose new “Actionscript class”, name itAway3dScene and click finish. This should automatically open the file in the coding area, to the right of the Flex Navigator.

The class should extend Sprite, since this class will contain all away3d stuff and be treated as any other graphic object. Start by placing this code in it:

package
{
     import flash.display.Sprite;

     public class Away3dScene extends Sprite
     {
           public function Away3dScene()
           {
                graphics.beginFill(0xFF0000);
                graphics.drawRect(0, 0, 100,  100);
                graphics.endFill();
           }
     }
}

Step 5

Double click the other .as file in the navigator named Away3dProject.as. Notice that this one has a little green triangle attached to its icon. This simply states that when you compile the application, this is the base class, what’s known in Flash as the Document class.

Place this code in it:

package
{
     import flash.display.Sprite;
     import flash.display.StageScaleMode;
     import flash.display.StageAlign;

     public class Away3dProject extends Sprite
     {
           public function Away3dProject()
           {
                stage.scaleMode =  StageScaleMode.NO_SCALE;
                stage.align =  StageAlign.TOP_LEFT;

                var scene:Sprite = new  Away3dScene();
                addChild(scene);
           }
     }
}

Lines 11 to 12 simply set a couple of stage properties that allow us to be in control of how the stage is scaled and positioned in the browser, and lines 4 to 5 provide the appropriate import statements for this.

Lines 14 to 15, create an instance of the Away3dScene (which is a Sprite!) and add it to the stage.

Step 6

Above the Flex Navigator is a little green button with a white play icon in it. This is what you press to compile the application.Go ahead and compile it. Flex will open your default web browser and run the demo in it.

Once you compiled, you should simply see a red square, at the top left corner of the browser.

Hmm… What? Well, I just wanted to show you how a class that will be holding all the 3d content can be a Sprite itself, and you can treat it as such, 100%.Alright, delete lines 9 through 11 of Away3dScene.as and lets get started with the 3d stuff.

Step 7

Now, lets create an event listener on the constructor that will call the initialization of the scene when the instance of Away3dScene is added to the stage. The initialization will be a method called “init()”, consisting of two sub methods and an event listener registration for enterframe events.

In Away3dScene.as, modify the constructor and add the other methods under it as follows:

public  function Away3dScene()
{
     addEventListener(Event.ADDED_TO_STAGE,  init, false, 0, true);
}

private  function init(evt:Event):void
{
     removeEventListener(Event.ADDED_TO_STAGE,  init);

     init3dScene();
     init3dObjects();
     addEventListener(Event.ENTER_FRAME,  renderScene);
}

private  function init3dScene():void
{

}

private  function init3dObjects():void
{

}

private  function renderScene(evt:Event):void
{

}

Make sure that as you type “evt:Eve…”, press enter when the flex auto complete dialogue box shows “Event”on one of the function declaration parameters of “init()” or “renderScene()”. Doing this will ensure that Flex creates the appropriate import statements automatically.

Now, why wait until the instance is added to the stage to call the “init()” method? Its a simple matter actually: In “init3dScene()” we will set up the core of the 3d environment, and when doing this, we need to know the dimensions of the stage… and we wouldn’t be able to know this if the sprite (or Away3dScene instance) wasn’t yet added to the stage! In “init3dObjects()”, as the name of the method makes it pretty obvious, we will create a bunch of objects and place them inside the 3d environment.

Step 8

The 3d scene will have 3 main elements: a Scene3D object, a Camera3D object, and View3D. These are all very important classes within the Away3d API. Declare instances of these as private variables in Away3dScene.as:

private  var scene:Scene3D;
private  var camera:Camera3D;
private  var view:View3D;

Make sure you rewrite this and not just paste it to make sure that Flex imports the correct classes. Don’t worry, you’ll get used to this ;D

Step 9

Lets build the 3d environment. Place the following code within the “init3dScene()” method:

scene  = new Scene3D();

camera  = new Camera3D();
camera.zoom  = 10;
camera.focus  = 200;
camera.z  = -3000;
camera.lookAt(new  Number3D(0, 0, 0));

view  = new View3D();
view.scene  = scene;
view.camera  = camera;
view.clip  = new RectangleClipping(-stage.stageWidth/2, -stage.stageHeight/2,  stage.stageWidth/2, stage.stageHeight/2);
view.x  = stage.stageWidth/2;
view.y  = stage.stageHeight/2;
addChild(view);

Now, lets go over those lines slowly. First, we created “scene”, an instance of Scene3D. This is actually the container of all the objects of the 3d environment. Those of you who are familiar with 3D, it is the main node of the environment. Then, we create a camera as an instance of Camera3D. This is pretty intuitive; its the object we will move around and that will represent us, the spectator, inside the 3denvironment. Notice the parameters of the camera that are set immediately after its initialization. If you type “camera.”, Flex will automatically bring up the auto complete dialogue box and show you all available methods and parameters that you can use for this object, so, if you want to see if the camera has a “y” property, type “camera.” And see if it shows up… Its pretty handy, and we’ve never looked at the API reference yet.

Finally, we create an instance of View3D. The view will represent the graphical output of the situation of our camera looking at our scene or environment. It is an object that extends sprite, and that represents what we see.The first 2 parameters of the view are the scene and the camera. What we are doing here is just telling it what camera and what scene

It will refer to.

Then, we clip and position the view. The clipping part is telling the view which are its limits in x, y, width and height, and hence setting the center of coordinates. The positioning part just places the view as if it were a normal sprite.

Oh, and of course, the view is added to the display, since it is a graphical element after all.

Note: To avoid confusion, Away3dScene (our class) and View3D both extend Sprite, Scene3D doesn’t! Away3dScene is just a class that we are using to place all the 3d stuff in, it has nothing to do with Scene3D. Sorry about that, I don’t know why but I see I got used to naming things this way.

Step 10

So, the 3d environment is set. Lets put some stuff in it. I’ve decided to make a little nested loop structure, in order to make this tutorial a little fancier, but don’t mind this, what really matters is the creation of the 3d objects:

var i:uint;
var j:uint;
var  k:uint;
var  spacing:Number = 250;
var  quantity:uint = 3;
var  offset:Number = (quantity-1)*spacing/2;
for(i  = 0; i<quantity; i++)
{
     for(j = 0; j<quantity; j++)
     {
           for(k = 0; k<quantity; k++)
           {
                var cube:Cube = new Cube();
                cube.x = i*spacing - offset;
                cube.y = j*spacing - offset;
                cube.z = k*spacing - offset;
                scene.addChild(cube);
           }
     }
}

We are creating the cube instance and then adjusting its parameters the same way as we created the scene and camera before. To see what kind of primitives you can create with Away3d, bookmark the away API reference http://away3d.com/livedocs/, check out the primitives package and have the API handy for future experiments.

Step 11

So, what’s left?

We just need to implement on more thing and were done. Add this line at the end of the “init()” method:

addEventListener(Event.ENTER_FRAME,  renderScene);

…and add this method at the end of the class

private  function renderScene(evt:Event):void
{
     camera.x = 3*(mouseX - stage.stageWidth/2);
     camera.y = 3*(mouseY -  stage.stageHeight/2);
     camera.lookAt(new Number3D(0, 0, 0));

     view.render();
}

We’ve just indicated that after initializing the scene, and then the objects in it, the application should call the “renderScene()” method on enterframe, that is every frame of course.

In “renderScene()”, we will position the camera according to the position of the mouse over the stage, and of course, render the view.

The render() method of a View3D object is what calls all the 3d transformation algorithms of the away3d engine and show us the display output in a view Sprite.

Now compile… and voila!! That’s it.

Final words.

Pretty nice huh? If you like it, there are some obvious steps you can take from here. You can look on the Away3d Blog for lots of info, samples and

Tutorials, or you could sign up to the mailing list to see a vivid community learning and expanding the away3d.Away3d can do pretty advanced stuff, specially when you are ready to play with materials on your objects, or importing 3d models from external programs. Ill be writing more tutorials about this when I can.

Hope its helpful…

Enjoy!

Complete Code

Away3dProject.as

package
{
     import flash.display.Sprite;
     import flash.display.StageScaleMode;
     import flash.display.StageAlign;

     publicclass Away3dProject extends Sprite
     {
           publicfunction Away3dProject()
           {
                stage.scaleMode =  StageScaleMode.NO_SCALE;
                stage.align =  StageAlign.TOP_LEFT;

                var scene:Away3dScene = new Away3dScene();
                addChild(scene);
           }
     }
}

Away3dScene.as

package
{
     import away3d.cameras.Camera3D;
     import away3d.containers.Scene3D;
     import away3d.containers.View3D;
     import away3d.core.math.Number3D;
     import away3d.core.render.RectangleClipping;
     import away3d.primitives.Cube;

     import flash.display.Sprite;
     import flash.events.Event;

     publicclass Away3dScene extends Sprite
     {
           privatevar scene:Scene3D;
           privatevar camera:Camera3D;
           privatevar view:View3D;

           publicfunction Away3dScene()
           {
                addEventListener(Event.ADDED_TO_STAGE,  init, false, 0, true);
           }

           privatefunction init(evt:Event):void
           {
                removeEventListener(Event.ADDED_TO_STAGE,  init);

                init3dScene();
                init3dObjects();
                addEventListener(Event.ENTER_FRAME,  renderScene);
           }

           privatefunction init3dScene():void
           {
                scene = new Scene3D();

                camera = new Camera3D();
                camera.zoom = 10;
                camera.focus = 200;
                camera.z = -3000;
                camera.lookAt(new Number3D(0, 0, 0));

                view = new View3D();
                view.scene = scene;
                view.camera =  camera;
                view.clip = new RectangleClipping(-stage.stageWidth/2, -stage.stageHeight/2,  stage.stageWidth/2, stage.stageHeight/2);
                view.x =  stage.stageWidth/2;
                view.y =  stage.stageHeight/2;
                addChild(view);
           }

           privatefunction init3dObjects():void
           {
                var i:uint;
                var j:uint;
                var k:uint;
                var spacing:Number = 250;
                var quantity:uint = 3;
                var offset:Number = (quantity-1)*spacing/2;
                for(i = 0; i<quantity; i++)
                {
                     for(j = 0; j<quantity; j++)
                     {
                           for(k = 0; k<quantity; k++)
                           {
                                var cube:Cube = new Cube();
                                cube.x  = i*spacing - offset;
                                cube.y  = j*spacing - offset;
                                cube.z  = k*spacing - offset;
                                scene.addChild(cube);
                           }
                     }
                }
           }

           privatefunction renderScene(evt:Event):void
           {
                camera.x =  3*(mouseX - stage.stageWidth/2);
                camera.y =  3*(mouseY - stage.stageHeight/2);
                camera.lookAt(new Number3D(0, 0, 0));

                view.render();
           }
     }
}

You will need a Flickr API KEY , Adobe Flex Builder 3 or Eclipse with Flex Builder 3 plugin, and some basic knowledge of Flex and actionscript.

You can view the final application here (View Source is enabled).

All the source files are here .

Part 1 : Creating the Flex project.

Create a new Flex project called ‘FlickrViewer’, and choose ‘Web application’. Click on ‘Next’. Then, leave the output folder as default, it should be ‘bin’. Click on ‘Next’.

Part 2 : Design the user interface.

The project is now ready to go. We will first designing the application.

Open ‘FlexViewer.mxml’. Go to the Design Mode. Click on the application (it should be a blue square taking all the page) and go the Properties panel. Go to Layout and choose vertical in the comboBox. Then go to Components panel, and in ‘Layout’ select the ApplicationControlBar, then drag it in the Application. Go to Flex Properties and set a width of 100% and remove everything in height (the height of the ApplicationControlBar will be the height of its contents).

Drag a ‘TextInput’ component in the ApplicationControlBar and a ‘Button’ component just after the TextInput. Set the label of the button to ‘SEARCH FLICKR’, in the Flex Properties panel. Add a TileList component next of the ApplicationControlbar. Your application should look like that :

Now set up the ID parameter of the TextInput, Button and TileList components in the Flex Properties panel. TextInput should be set up to ‘txtSearch’, the Button should be set up to ‘btnSearch’ and the TileList to ‘picsList’.

The user interface is completelly designed, let’s add Flickr.

Part 3 : The libs.

First, you will have to download the compiled versions of 2 libraries :

as3FlickrLib and asCoreLib. Go to

http://code.google.com/p/as3flickrlib/ to get the first lib. Download

the package (featured downloads). Unzip the file, and the in the

expanded folder, go to bin/ and drag the file in Flex, inside your

project, in the src folder. Once it’s done, go to

http://code.google.com/p/as3corelib/ and repeat the operation. You

should see that in your project : and some other files of course.

So now your project has the 2 libs.I strongly recommands you to use that method in any projects. By doing that, you are sure that you always have a working library. If you want to make a big application using external libraries (which may evolve), I recommand you to use Flex Library projects and SVN synchronization, it will allow you to keep your code up to date.

To complete that part, you need to tell Flex that you will use those libs. Right-click on the project name, and then go to ‘properties’ -> ‘Flex Build Path’ and then -> ‘Library path’ and the ‘add SWC’. Choose corelib.swc and do the same for flickr.swc.

Part 4 : The code.

In Code Mode, add a line after the tag. Start typing “<> Mx:Script’. Press the Enter key. Now you should have a complete script tag. Inside of this Script tag, include the flickr functions we need :

import com.adobe.webapis.flickr.*;
import com.adobe.webapis.flickr.events.*;

Then, some variables :

private var flickr:FlickrService;
private var api_key:String = "enter you Flickr API key here";
private var maxResult:Number = 50;

After that, security parameters :

Security.allowDomain(["api.flickr.com", "flickr.com", "*"]);
Security.allowInsecureDomain(["api.flickr.com", "flickr.com", "*"]);

And set the dataProvider of the TileList :

import mx.collections.ArrayCollection;
[Bindable] public var photos:ArrayCollection;

‘Bindable’ means that the TileList will update each time the dataProvider change.

After that the function to call Flickr webservice. Basically, that means that we set up the api_key to send, an eventListener to know when the data comes back, and the request itself to search photos, based on the TextInput value.

private function getImages():void {
var service:FlickrService = new FlickrService( api_key );
service.addEventListener( FlickrResultEvent.PHOTOS_SEARCH, onPhotosSearch );
service.photos.search("", txtSearch.text, "any", "", null, null, null, null, null, "", maxResult,1 );
}

Now that the code is done, we just need to connect the TileList to the data. Go to the TileList tag, and at the end of the parameters, just add ‘dataProvider={photos}’. The tag should now look like that :

<mx:TileList width="100%" height="100%" id="picsList" dataProvider="{photos}" itemRenderer="iconRenderer" >

If you run the application now, you wont see any images. It’s because we miss an itemRenderer for the image.

Part 5 : The necessary itemRenderer

Go to ‘File’ -> ‘New’ -> ‘MXML Component’. Type ‘iconRenderer’ as filename and choose ‘Box’ in ‘Based on’. Remove width and height.

Go to Design Mode. Drop an Image Component. In the Flex Properties panel, set the ID to ‘pic’.

Go to Code Mode. Add a script tag after the first Tag. In this script tag, add the following lines :

import com.adobe.webapis.flickr.Photo;
import mx.core.Application;
public function init():void{
pic.source = 'http://static.flickr.com/' + data.server + '/' + data.id + '_' + data.secret + '_m.jpg';
//trace("source : "+pic.source)
}

Then, add an updateComplete event listener to this init function in the Box tag. It should look like that :

The itemRenderer is not ready. The complete code should be this :

Part 6 : Linking the itemRenderer to TileList

Go back to FlickrViewer.mxml. In Code Mode, go to the TileList tag and add the itemRenderer parameter by typing :

itemRenderer=”iconRenderer”

The complete code for FlickViewer is done and should look like this :

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
<mx:Script>
<![CDATA[
//import mx.messaging.channels.StreamingAMFChannel;
import com.adobe.webapis.flickr.*;
import com.adobe.webapis.flickr.events.*;
private var flickr:FlickrService;
private var api_key:String = "enter you Flickr API key here";
private var maxResult:Number = 50;
private var service:FlickrService = new FlickrService( api_key );

Security.allowDomain(["api.flickr.com", "flickr.com", "*"]);
Security.allowInsecureDomain(["api.flickr.com", "flickr.com", "*"]);

import mx.collections.ArrayCollection;
[Bindable] public var photos:ArrayCollection;

private function getImages():void {
  var service:FlickrService = new FlickrService( api_key );
  service.addEventListener( FlickrResultEvent.PHOTOS_SEARCH, onPhotosSearch );
  service.photos.search(”", txtSearch.text, “any”, “”, null, null, null, null, null, “”, maxResult,1 );
}

private function onPhotosSearch( event:FlickrResultEvent ):void {
  var photoList:PagedPhotoList = event.data.photos;
  photoList.perPage = maxResult;
  photos = new ArrayCollection( photoList.photos );
}
]]>
</mx:Script>
<mx:ApplicationControlBar width=”100%”>
<mx:TextInput id=”txtSearch”/>
<mx:Button label=”SEARCH ON FLICKR” id=”btnSearch” click=”getImages()”/>
</mx:ApplicationControlBar>
<mx:TileList width=”100%” height=”100%” id=”picsList” dataProvider=”{photos}” itemRenderer=”iconRenderer” >
</mx:TileList>
</mx:Application>

And the final code for iconRenderer.mxml :

<?xml version="1.0" encoding="utf-8"?>
<mx:Box xmlns:mx="http://www.adobe.com/2006/mxml" updateComplete="init()">
<mx:Script>
<![CDATA[
import com.adobe.webapis.flickr.Photo;
import mx.core.Application;
public function init():void{
pic.source = 'http://static.flickr.com/' + data.server + '/' + data.id + '_' + data.secret + '_m.jpg';
//trace("source : "+pic.source)
}
]]>
</mx:Script>
<mx:Image id=”pic” width=”100″ height=”100″ />
</mx:Box>

Part 7 : click to enlarge

Now the users can watch a list of pictures. That’s ok but not very good.

To allow users to enlarge the pics, we will first create a new component, wich will contain the big pic. Go to File > New > MXML Component. Enter ‘bigPic.mxml’ as filename and ‘TitleWindow’ in ‘based on’. Enter ‘100%’ for both width and height. Now, change the first tag by this one :

<mx:TitleWindow xmlns="*" xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:controls="qs.controls.*" xmlns:smooth="imageControls.*"
    xmlns:eff="com.adobe.effects.*" xmlns:views="views.*"
    layout="vertical"
    height="100%" width="100%"
    title="CLICK ANYWHERE TO CLOSE" textAlign="center" color="#333333"
    backgroundColor="#000000" backgroundAlpha="0.9"
    borderThicknessLeft="0" borderThicknessRight="0" borderThicknessTop="0" borderThicknessBottom="0"
    headerHeight="25" verticalScrollPolicy="off" horizontalScrollPolicy="off"
    paddingBottom="0" paddingLeft="0" paddingRight="0" paddingTop="0"
    creationComplete="init()">

The ‘xmlns’  are references to libs we will use. There are some graphical stuff, like borderThickness, you can read Flex Documentations to know more, they are basically use to fit the browser’s window.

Go back to FlickViewer.mxml. To launch this component when the user clicks on an item in the list, add this code in the Script tag, at the end :

///// BIGPIC FUNCTIONS
            import mx.managers.PopUpManager;
            import mx.containers.TitleWindow;
            import bigPic;
            import mx.events.FlexMouseEvent;
            import mx.core.Application;

            public var fullWindow:bigPic;

            public function showBigPic(id:String):void {
                fullWindow = bigPic(PopUpManager.createPopUp(this, bigPic, true));
                fullWindow.selectedPhoto = id;
                fullWindow.selectedPhotoNum = picsList.selectedIndex;
            }

Then look in the mxml code, and find the TileList tag. in the tag, add the itemClick property to launch the big pic :

itemClick=”showBigPic(event.itemRenderer.data.id)”

The tag should now look like that :

<mx:TileList width="100%" height="100%" id="picsList"
        dataProvider="{photos}" itemRenderer="iconRenderer"
        itemClick="showBigPic(event.itemRenderer.data.id)" >

Now, let’s add some layout. Go back to bigPic.mxml, and between the two tags on the stage, add this code :

<mx:Canvas height="100%" width="100%">
        <mx:Canvas x="0" y="0" id="preload" width="100%" height="100%" click="removeMe()" >
                <mx:Box width="100%" height="100%" verticalAlign="middle">
                    <mx:ProgressBar id="preloadBar" source="daPic" mode="event" width="100%"
                        complete="preload.visible = false; img.visible = true;" labelPlacement="bottom"/>
                        <mx:Label id="imgTitle" width="100%" textAlign="center"
                            text="{Application.application.photos.getItemAt(Application.application.selectedPhotoNum).title}"
                            fontSize="25" color="#666666" />
                    <mx:Image id="daPic2" source="{photoUrl}" visible="false" width="1" height="1" />
                </mx:Box>
        </mx:Canvas>
        <mx:Canvas x="0" y="0" width="100%" height="100%" id="img"
            showEffect="{fadeAndBlurIn}" hideEffect="{fadeAndBlurOut}"
            verticalScrollPolicy="off" horizontalScrollPolicy="off">
            <mx:HBox width="100%" height="100%" horizontalAlign="center" verticalAlign="middle">
                <mx:Box id="prevBox" visible="true" width="100" height="100%" horizontalAlign="center">
                    <mx:Spacer height="50%" />
                    <mx:Button width="70" label="prev" click="changePic('prev')" />
                </mx:Box>
                <mx:Box width="100%" height="100%"
                    verticalAlign="middle" horizontalAlign="center" click="removeMe()">
                    <mx:Image id="daPic" source="{photoUrl}"
                        verticalAlign="center" horizontalAlign="middle"
                        width="100%" height="100%" cacheAsBitmap="true"  />
                </mx:Box>
                <mx:Box id="nextBox" width="100" height="100%" bottom="10%" horizontalAlign="center">
                    <mx:Spacer height="50%" />
                    <mx:Button width="70" label="next" click="changePic('next')" />
                </mx:Box>
            </mx:HBox>
        </mx:Canvas>
    </mx:Canvas>

It’s a canvas containing 2 Canvases. The first one contains a ProgressBar, which will show image loading progression. The ‘onComplete’ event in the tag set this canvas to invisible at the end of the loading. By being invisible, we will be able to see the second Canvas, which contains the image.

Inside the second Canvas, you can see 3 Boxes. The first one contains a Button, the next one the image, and the third one another Button. That’s how your application will look like : a big pic surrounded by two navigation buttons. We will see the code in part 9.

There is in each Canvas a ’showEffect’ and ‘hideEffect’ parameter. It’s made to make a nice fade between the preloader and the photo. But the effects are not here. We will add them right now.

Part 8 : Adding fade effect

Add the following code just after the first tag (TitleWindow ) :

<mx:Sequence id="fadeAndBlurIn" startDelay="0" >
        <mx:Fade id="fadeIn" duration="1200" alphaFrom="0.0" alphaTo="1.0" />
    </mx:Sequence>
    <mx:Sequence id="fadeAndBlurOut" startDelay="0">
        <mx:Fade id="fadeOut" duration="300" alphaFrom="1.0" alphaTo="0" />
    </mx:Sequence>

All effect needs to be set after the first tag, and it’s mandatory, as well as for Scripts and Style tags.

Part 9 : Adding code to load the big pic, and manage the navigation

After the first tag, add this code :

<mx:Script>
        <![CDATA[
            import mx.core.Application;
            import mx.rpc.soap.LoadEvent;
            import mx.managers.SystemManager;
            import mx.managers.PopUpManager;
            import mx.utils.ArrayUtil;
            import mx.collections.ArrayCollection;

            import com.adobe.webapis.flickr.methodgroups.People;
            import com.adobe.webapis.flickr.methodgroups.PhotoSets;
            import com.adobe.webapis.flickr.FlickrService;
            import com.adobe.webapis.flickr.*;
            import com.adobe.webapis.flickr.events.*;

            [Bindable] private var photos:ArrayCollection;
            [Bindable] private var photoUrl:String;
            [Bindable] private var photoFlickrUrl:String;
            [Bindable] public var selectedPhotoNum:Number;
            [Bindable] public var selectedPhoto:String;

            public function init():void
            {
                img.visible = false;
                this.width = stage.width;
                this.height = stage.height;
                getPhotoSize();
            }

            private function removeMe():void {
                PopUpManager.removePopUp(this);
            }

            private function getPhotoSize():void{
                trace(”getPhotoSize: “+selectedPhoto)
                preload.visible = true
                img.visible = false;
                var service:FlickrService = new FlickrService( Application.application.api_key );
                   service.addEventListener( FlickrResultEvent.PHOTOS_GET_SIZES, onPhotoSizeSearch );
                   service.photos.getSizes( Application.application.photos[selectedPhotoNum].id );
            }

            private function onPhotoSizeSearch( event:FlickrResultEvent ):void {
                var photoSize:PhotoSize = event.data["photoSizes"] as PhotoSize;
                imgTitle.text = Application.application.photos[selectedPhotoNum].title
                var result:Array = event.data.photoSize;
                photoUrl = event.data["photoSizes"][(event.data["photoSizes"].length-1)].source;
            } 

            public function changePic(operation:String):void{
                if(operation == “next”){
                    if(selectedPhotoNum < Application.application.photos.length-1){
                        selectedPhotoNum++;
                    }else{
                        selectedPhotoNum = 0;
                    }
                }else{
                    if(selectedPhotoNum > 0){
                        selectedPhotoNum–;
                    }else{
                        selectedPhotoNum = Application.application.photos.length-1;
                    }
                }
                getPhotoSize();
            }

        ]]>
    </mx:Script>

It sure looks quite long, but it’s really simple.

The init() function react to the ‘OnCreationComplete’ event in the first tag. The first line hide the ‘img’ canvas, so we dont see it during the loading. The two second lines simply fit the component to the browser window, and the last line launch the loading of the first image.

The getPhotoSize() function is the core of this component. It will search all the available sizes for the image.

The onPhotoSizeSearch() function is executed when the getPhotoSize() is done. The aim of this function is to set the text for the label in the preloader canvas, and - most important - get the URL of the biggest image available. It’s this line :

photoUrl = event.data["photoSizes"][(event.data["photoSizes"].length-1)].source;

‘photoSizes’ is an array retured by Flickr, which define the sizes from the smallest to the biggest.

And finally, the changePic() function simply handle the navigation. If you look closely in the mxml code, you will see two buttons. When clicked, this function is called and just add or remove 1 to selectedPhotoNum, a variable that getPhotoSize() use to know which image to load. Of course, we add some conditions to prevent errors due to undefined id (because if it happens, the application will sure crash :-)).

Part 10 : Launch your application and enjoy !

Click on the run application button, and in the browser, type a word in the search box. Normally, you should see images appearing. If you see them, you just manage to make your first Flickr / Flex mashup. Congrats !

Now, look further : you can do a lot with that. Flickr has a whole range of functions that you can discover here . You can also refer to the asflickrlib docs on google code . You can do almost everything that users do on the Flickr website.

Plus, you can add more effects, or even do crazy stuff with papervision, physics engines… The possiblities are unlimited. All you need to find now is the revolutionnary idea to do something with all those pictures !

You only need to consider one limitation : Flickr can be slow. And by doing that, you can’t really manage the speed of your application. So avoid to load too much photos on each request. Use the max_result parameter to limit this amount.

This concludes my first tutorial. Thank for reading that to the end. I hope that you enjoy reading it and that it will help you. To thank me, just drop a line in the comments, make a link on your website or, even better, send me a picture of you drinking a beer in your local pub

Requirements

Flex 3

Try/Buy

Sample files:

YouTube.zip
Let’s start by building the search user interface.

Searching YouTube

YouTube provides a set of RSS feeds that keep you up to date with the latest videos. These feeds take lots of parameters to refine what you are looking for, one of those is an arbitrary keyword search.
The Flex code below uses the YouTube search feed to request a set of videos based on the user’s search criteria. The code then uses the e4x language extensions in ActionScript 3 to parse the feed and present the video thumbnails in a TileList.

<?xml version="1.0" encoding="utf-8"?> 

  <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"  title="YouTube  Search"> 

  <mx:Script> 

  <![CDATA[ 

  import
 mx.rpc.events.ResultEvent; 

  import
 mx.rpc.http.HTTPService; 

namespace
 atom = "http://www.w3.org/2005/Atom"
; 

    namespace
 media = "http://search.yahoo.com/mrss/"
; 

private
 function
 onSearch() : void
 { 

    var
 search:HTTPService = new
 HTTPService(); 

    search.url = "http://gdata.youtube.com/feeds/api/videos/?vq="
+escape(txtSearch.text)+"&orderby=updated"
; 

    search.resultFormat = 'e4x'
; 

     search.addEventListener(ResultEvent.RESULT,onSearchResult); 

    search.send(); 

  } 

  private
 function
 onSearchResult( event:ResultEvent ) : void
 { 

    use
 namespace
 atom; 

    use
 namespace
 media; 

    var
 movies:Array = []; 

    for
 each
( var
 entry:XML in
 event.result..entry ) { 

      var
 group:XML = entry.group[0]; 

      movies.push( { 

         id:group.player.@url.toString(), 

         description:entry.content.toString(), 

         thumbnail:group.thumbnail[0].@url.toString() } ); 

    } 

    thumbList.dataProvider =  movies; 

  } 

  ]]> 

  </mx:Script> 

  <mx:HBox  width=”100%”> 

  <mx:TextInput  width=”100%” id=”txtSearch” /> 

  <mx:Button  label=”Search” click=”onSearch()” /> 

  </mx:HBox> 

  <mx:TileList  id=”thumbList” width=”100%” height=”100%”> 

  <mx:itemRenderer> 

  <mx:Component> 

  <mx:HBox  paddingBottom=”5″ paddingLeft=”5″ paddingRight=”5″  paddingTop=”5″> 

  <mx:Image  source =”{data.thumbnail}” height=”100″ width=”150″ horizontalAlign=”center” verticalAlign=”middle” toolTip=”{data.description}”> 

  </mx:Image> 

  </mx:HBox> 

  </mx:Component> 

  </mx:itemRenderer> 

  </mx:TileList> 

  </mx:WindowedApplication>

The onSearch method is called from the search button. It creates a new HTTPService on the fly with the URL of the YouTube feed for the search. It then registers onSearchResult as an event handler for the result.
The onSearchResult method uses e4x to parse through each ‘entry’ tag in the RSS feed. For each movie it builds an object with three fields. The ‘id’ field holds the URL of the HTML page for the video. The ‘description’ field holds the textual description of the video. And the ‘thumbnail’ field holds the URL of the thumbnail.
When I launch this MXML in an AIR project within Flex Builder 3 I see something like Figure 1.

Figure 1-1. Just the YouTube search

In this case I’ve typed in ‘super mario’ and pressed ‘search’ to get a list of the movies that matched that criteria.
From here we ne