ActionScript 3.0 Custom Components from Hell

Oh my god. Adobe have managed, once again, to create one of the most complicated systems in the universe. Components. A really nice feature if you are developing large complex flash sites/applications but for some odd reason they choose to leave the documentation at an absolute minimum.

I have only been able to find 2 useful pages about this subject on the web. The one written by a guy named Jeff Kamerer, is actually very good and informative but it is also very long and cumbersome. I suggest you visit his site and read thought it once you have the basics working. The other somewhat shorter article by (I think) Chris Sperry. The 2 articles in combination helped me through this nightmare. Recently I was made aware of this slightly more complex implementation at FlashGrind, check that out too 🙂

Usually I think there is far too many tutorials and how-to’s on the web about simple flash programming, but the lack of information on this subject have prompted me to write another one. I will try to make is as simple as possible and maybe with some different twists than the other two. If you are having a hard time understanding this then it’s defiantly good to go through similar tutorials even though they are covering the same subject. Subtle differences and different wording might help you see the light.

This is defiantly one of those bad flash experiences that cause you to consider switching to Microsoft’s Silverlight (ahh, c# ;-)).

When I have to learn something new, I usually try to get something working as quickly as possible and then go back and add/change stuff several times, improving the complexity with each iteration. So I’ll start out here with an extremely simple no-good-for-anything component, and then add and expand it several times, even adding solutions that I will remove again (just for the sake of understanding why the next solution is better), until I have a good standard component.

A. A simple bare-bone component.

When learning something new, I always find it easiest to figure out if I get a prototype up and running as fast as possible so that’s what I’m going to do here.

In this first section I will create the simplest form of a component possible, a piece of graphics that does absolutely nothing more than being a piece of graphics. I will add functionality and stuff like that in the later sections.

1. Create a ‘New Document‘.

   

   New Document

2. Create a sphere (or any other simple symbol) and set the size 100×100 (not important right now, but later it will be).

   

   Create a Sphere

   

   Set the size to 100×100

3. Select the sphere and convert it to a symbol.

   

   Convert the sphere to a symbol

4. The Symbol will afterwards be available in the library and you can delete it from the timeline. Name the new symbol ‘myFirstComponent‘ and leave the rest of the settings unchecked.

   

   Convert the sphere to a symbol in the library.

5. In the library, right-click on the symbol and select ‘component definition‘. This will set the basic definitions for the symbol as a component.

   

   Set the Component Definitions to convert the symbol into a component

6. In the component definitions window, set the name of the class to ‘myFirstComponent‘. Set the ‘display in components panel‘ to true. This will make sure that the symbol is visible in the components menu (on more complex components or packages of components you don’t want all the symbols to be visible in the menu) and write a silly comment for the tool-tip.

   

   The very basic settings that will enable the symbol in the components menu

7. Save the Document and call it ‘myFirstComponent.fla’.
8. Close Flash (grrr).
9. Copy the file ‘myFirstComponent.fla’ to either of these two directories:

   %USERPROFILE%\AppData\Local\Adobe\Flash CS3\en\Configuration\Components\
   %PROGRAMFILES%\Adobe\Adobe Flash CS3\en\Configuration\Components\

10. Open Flash and check out that you now have a component called ‘myFirstComponent’ in the component tree. One very annoying thing is that from now on you will have to close and open Flash each time you want to test the symbol after changes because Flash locks the file when loading it (seriously Adobe, you need to fix this asap. Take a look at XSI, here you can offload plugins without closing the program which makes plugin development a lot faster).

Your very first component (hopefully)

B. Adding simple functionality.

The simple component I just made is good if you re-use a lot of graphics in your websites, but the ability to add code to the component is where this feature becomes really powerful.

1. Load the ‘myFirstComponent.fla’ file you created just before.
2. Link the symbol ‘myFirstComponent’ to a class. At point 4, I converted the graphic sphere to a symbol and left all the settings unchecked. To be able to add code to the symbol we need to link it to a class. Check the option ‘Export for ActionScript‘, and you will see that it automatically receives the class name ‘myFirstComponent’ and the base-class ‘flash.display.MovieClip’. We have not created any code files yet so if you click on the green check mark next to the class name, Flash display an error telling you that the code file for the class could not be found so it will auto-create one for you.

   

   Flash displays an error if the source file for a class is not found.

   This is only useful if you have code elsewhere and you need to add the symbol to the stage with that code, but it can be a little confusing that you do something wrong and Flash fixes it for you (it creates an empty class derived from the MovieClip class). Leave the Class-Name ‘myFirstComponent’, that’s exactly what our class will be called.

3. Create a new source file for your class. Save the new (and empty) source file as ‘myFirstCompoenet.as’ next to your .fla file. When the .fla file is compiled and Flash is looking for the classname ‘myFirstComponent’ it will look for that .as file. Obviously it need to contain some code too.

   

   Create a new .as file for the Class’ source code

4. Create the basic class structure. Paste this source code into the ‘myFirstComponent.as’ file. You have now created the basic class definition for the class ‘myFirstComponent’. The class does absolutely nothing but if you go back to 2) and click the validation button, you will notice that Flash tells you that the class definition have been found. Nice. You can now start to add code. Notice that the class is extending Sprite and not MovieClip. This is just good flash-programming practise. The MovieClip class is derived from the Sprite class and have much the same functionality, so unless you specifically need a timeline for your class you should stick with the Sprite class. It’s smaller.

   package {
      import flash.display.Sprite;
   
      public class myFirstComponent extends Sprite {
         public function myFirstComponent() {
         }
      }
   }

5. Next I will add some functionality to the class; a simple eventListener that will enable you to drag the sphere around on the screen. Add the new lines of code to make the class definition look like this:

   package {
      import flash.display.Sprite;
      import flash.events.MouseEvent;
   
      public class myFirstComponent extends Sprite {
         public function myFirstComponent() {
            addEventListener(MouseEvent.MOUSE_DOWN, Down);
         }
   
         private function Down(e:MouseEvent):void {
            startDrag();
            addEventListener(MouseEvent.MOUSE_UP, Up);
         }
   
         private function Up(e:MouseEvent):void {
            stopDrag();
            removeEventListener(MouseEvent.MOUSE_UP, Up);
         }
      }
   }

6. If you drag the symbol ‘myFirstComponent’ into the stage and publish it you can now drag the sphere around and be very amused.
7. Close Flash and (again) copy both the .fla and .as files to the components directory as described in the previous section (A9).
8. Start Flash, create a new scene and drag the ‘myFirstComponent’ symbol from the components, publish the scene and be very disappointed when nothing happens when you try to drag the sphere around.
   This is one place where Flash is a bit shit. What happened is that although you copied the .as file together with the .fla file, Flash actually doesn’t know where to look for the .as file so it reverts to the good old ‘create my own empty class file’ solution without telling you about it. Now, there is an easy, and pretty lame solution for this.
   Go to the ‘Publish Settings‘ menu (File->Publish Settings), press the button ‘Settings‘ next to ‘ActionScript Version’ and in the menu that pops up press the ‘+‘ button and browse to the directory where you copied your component file. You have now told Flash where to look for extra class files. You might be amused that when you publish the scene again, that the code works, but at the same time annoyed that it isn’t a very elegant solution. If you want normal users to use your components this is definitely pretty fucking lame.
9. The solution comes with the very bizarre and ultra-secret ‘Component Shim’.. next section ..

C. Adding Component Shim.

The ‘Component Shim’, a weird sort-of empty .fla file that you will find if you dig around in Flash’s component directories. This is basically a file that is used to create compiled byte-code of your classes that you can embed directly in the .fla file so you can avoid copying the .as file (not good) and setting local paths so Flash can find it (super lame). The ‘Component Shim’ solution works well but it is a very questionable method, in Danish we would call it ‘temmelig fusket’.

1. Create a new .fla file in the same directory as your ‘myFirstComponent.fla’ file, and call it ‘myFirstComponent_shim.fla’.
2. In the library (of myFirstComponent_shim.fla) create a new empty symbol and call it ‘myFirstComponent’.
3. Select ‘Export for ActionScript’ and notice that Flash is able to find the class definition from the .as file.
4. Create another new symbol and call this one ‘ComponentShim‘. Make sure that the class name does not exist (calling it ‘ComponentShim’ should do the trick).
5. Right-Click on the symbol and select ‘Convert to Compiled Clip‘, and if everything goes to plan a new symbol called ‘ComponentShim SWF‘ of the type ‘Compiled Clip‘ will appear in the library. What you have here is actually a compiled version of the ‘myFirstComponent’ class library (and any other class libraries that you might have added in the same way). The trick is that the ‘ComponentShim’ symbol does not have a corresponding .as file for its class and therefore Flash will create one for it and in that process it compiles all other classes with it. WTF Adobe?! I can understand why this is undocumented because it is way more dirty than some of the worst close-to-release-candidate hacks that you will find in game-code 🙂
6. CopyPaste the ‘myFirstComponent SWF‘ symbol from the library of to the library of ‘myFirstComponent_shim.fla‘ to the library of the ‘myFirstComponent.fla‘ file to get the byte code transferred.
7. Now we need to make sure that the compiled class definition is following our component all the way into a new user-created stage, and the only way to do this is to actually insert it into the ‘myFirstComponent’ symbol in the ‘myFirstComponent.fla’ file. Do it. You will not be able to see the symbol after it is inserted because it does not contain any graphics.
8. Save and close Flash.
9. Copy the .fla file to the components directory and try point 8 from last section again. Herligt, nu virker lortet. As you can see we are getting closer to something useful, but it’s complicated.

A note on c.4). If you do not create a new ‘dummy’ symbol but convert the ‘myFirstComponent’ symbol directly to a compiled symbol, you will receive a warning when publishing the stage where the component is used:

**Warning** The linkage identifier 'myFirstComponent' was already assigned to the symbol 'myFirstComponent SWF',
 and cannot be assigned to the symbol 'myFirstComponent', since linkage identifiers must be unique.

The scene will run but because the class is now linked to two symbols you will receive this warning. Pray that it’s the ‘myFirstComponent’ symbol that gets to link with the class and not the one compiled with the shim, because then your component will not work. Therefore, you should create the dummy.

D. Extending the UIComponent Class

So far our component have been pretty simple. If you are aiming at making custom UI components like new buttons or fancy menus you should stop using the sprite class as a base and use the UIComponent class instead. This class is the foundation of all the nice components supplied with Flash like the Button (fl.controls.Button) or ComboBox (fl.controls.ComboBox) and provide very nice base functionality. Unless your component is really special or you really like doing things that have already been done, stick with the UIComponent Class.

In this section I will convert my simple component to extend the fl.core.UIComponent class instead of flash.display.Sprite. Actually UIComponent is extended from Sprite but that’s only means that you are not loosing anything (only gaining a few extra pounds af excess code ;-))

First we need to take the ‘myFirstComponent.fla’ file a bit apart and modify it to make it useful for the UIComponent’s so-called ‘2-frame structure’ (another rather spaghetti’ish construction by Adobe). The UIComponent class is also used for code driven components, so we have to reconstruct our sphere with code instead of just dragging it into the stage.

1. Start by loanding the ‘myFirstComponent.fla‘ file.
2. Delete the ‘ComponentShim SWF‘ symbol from the library.
3. Edit the ‘myFirstComponent‘ symbol (by double-clicking on it in the library), select the sphere graphic and convert it to a new symbol and name it ‘mySphere‘.
4. Delete the new symbol from the ‘myFirstComponent’ symbol (it now exists in the library so don’t worry).

   

   The library contains the component and the sphere converted to a symbol.

5. Edit the properties of ‘mySphere‘ and enable ‘Export for ActionScript’. Just leave the default classname suggestions.
6. Make sure that ‘Export in First Frame’ is UNCHECKED, as we want the symbol to be available in frame 2.

   

   The sphere is now a separate symbol, exporting for ActionScript bearing the classname ‘mySphere’

7. Now we need to prepare the timeline of the ‘myFirstComponent’ symbol for use with the UIComponent class. Re-name ‘Layer 1’ to ‘avatar’.
8. Create a rectangle in pos x:0 y:0 with the size 100×100, and make sure the line weight is ‘Hairline‘. It is very important that this frame contains only this symbol and that the lineweight is ‘Hairline’. It will define the extends of your component when it’s inserted into a new stage so thicker lines will make the size imprecise. The position is of course equally important. When the UIComponent class initializes, all content on frame 1 is deleted.
9. On the ‘avatar’ layer; Insert a Blank Keyframe at frame 2.

   

   Insert a blank keyframe on frame 2

10. Create a new layer and call it ‘assets‘. This layer will be used as a container for all symbols (and compiled class definitions) that the component uses.
11. On the ‘assets’ layer; Insert a Blank Keyframe at frame 2.
12. Insert the symbol ‘mySphere‘ from the library into frame 2 of the ‘assets’ layer. It is not important where it is placed but you might put it in the correct position just to keep things tidy. Placing the symbols inside the ‘myFirstComponent’ symbol ensures that they will follow the component when it is inserted into a new stage. The reason for putting them in frame 2 is that because the UIComponent class derives from sprite, it does not contain any timeline and therefore the symbol will never display frame 2, which makes it a safe place to dump all your junk.

    

    The basic 2-frame structure. The ‘Avatar’ layer defines the extends of the component and the ‘Assets’ carries all the assets used by the component.

13. Open the ‘myfirstComponent.as’ file containing the code for the class definition.
14. We need to extend the fl.core.UIComponent class instead of the flash.display.Sprite Class. As mentioned before, the UIComponent class deletes all content on frame 1 when the class is initialized and since it’s derived from Sprite it doesn’t have a timeline so our content on frame is never shown. Therefore we have to add our assets using code instead. Now, when we converted the sphere to a library symbol we also made sure it was ‘Exported for ActionScript’ with the classname ‘mySphere’. I declare and create a new instance of ‘mySphere’ called ‘mySphereInstance’.
    The UIComponent class contains a function called configUI(), which is called as soon as the class have been created. This is used to initialize the component (in our case adding the sphere to the stage so we can see it). I do that by overriding the configUI() function and adding my own ‘put stuff into the stage’ code. It is important the UIComponent class gets to call configUI() before I do, so the first think I do in my overridden function is to call super.configUI();. After that I simply add my sphere-instance as a child.
    Make the following changes:
    

package {
   import fl.core.UIComponent; //DELETE// import flash.display.Sprite;
   import flash.events.MouseEvent;

   public class myFirstComponent extends UIComponent { //DELETE// public class myFirstComponent extends UIComponent
      private var mySphereInstance:mySphere = new mySphere();    

      public function myFirstComponent() {
         addEventListener(MouseEvent.MOUSE_DOWN, Down);
      }

      override protected function configUI():void {
         super.configUI();
         addChild(mySphereInstance);
      }

      private function Down(e:MouseEvent):void {
         startDrag();
         addEventListener(MouseEvent.MOUSE_UP, Up);
      }

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

• In order for Flash to be able to find the class definitions for the UIComponent Class you need to add the following path to Flash;

  $(AppConfig)/Component Source/ActionScript 3.0/User Interface

  This can be done in 2 places. The most correct place to add the path is in the Publish-settings for the ‘myFirstComponent_shim.fla’ file so it travels with the file, but if you find yourself using this class all the time you can add the path directly in the Flash-Preferences.

  

  Setting the path for the UIComponent class via the Publish Settings-> ActionScript 3.0 Settings.

  

  Set the path for the UIComponent class via the global Flash Preferences if you are working alot with this class.

• Next, you need to re-visit the ‘myFirstComponent_shim.fla’ file. If you just try and ‘re-compile’ the class definition you will receive the error:

  1046: Type was not found or was not a compile-time constant: mySphere.

  This is because we now declare a new class inside the ‘myFirstComponent.as’ class definition, in line 6 where the sphere is created. This is easy to fix. Just create a new empty symbol, name it ‘mySphere’ and set it to export to actionscript. This way Flash will create the class definition for mySphere aswell.

• Re-create the Component_Shim SWF (C5 + C6) and copy it to ‘assets’ frame 2.
• As a last thing, on the properties of the ‘myFirstComponent’ symbol, set the ‘require minimum player version‘ option to ‘Flash 9‘ and the ‘require minimum actionscript version‘ to ‘ActionScript 3.0‘. Because the fl.core.UIComponent class is strictly AS3 we don’t want the component to be available to users of ActionScript 2.0 and older versions. These options ensure that the component is only visible when using AS3.
• Save, close Flash, copy the component to the component directory (A9) and check that it works when you restart Flash.

E. Exposing Parameters using metadata.

Another great feature in Flash is the ability to insert metadata into your source code to expose certain parameters to the editor.This great for dynamic components where you want the give the user the possibility to tweak or re-skin the component.

1. Let’s modify the class definition code. Open ‘myFirstComponent.as’.
2. First we will add some text on top of the sphere.By default it will be located in the upper left corner of the symbol. I will add code later for centering the text.

   package {
      import fl.core.UIComponent;
      import flash.events.MouseEvent;
      import flash.text.TextField;
   
      public class myFirstComponent extends UIComponent {
         private var mySphereInstance:mySphere = new mySphere();
         private var txtField:TextField = new TextField();
   
         public function myFirstComponent() {
            addEventListener(MouseEvent.MOUSE_DOWN, Down);
         }
   
         override protected function configUI():void {
            super.configUI();
            addChild(mySphereInstance);
            txtField.text = "Hejsa";
            addChild(txtField);
         }
   
         private function Down(e:MouseEvent):void {
            startDrag();
            addEventListener(MouseEvent.MOUSE_UP, Up);
         }
   
         private function Up(e:MouseEvent):void {
            stopDrag();
            removeEventListener(MouseEvent.MOUSE_UP, Up);
         }
      }
   }

3. By default the text is black, and I’ve been a moron and colored the sphere black too. So we have to change the color of the sphere in order to see the text. Edit the ‘mySphere‘ symbol and change the color of the circle to something brighter.
4. If you publish the flash file now you’ll see that the text is displayed in the upper left corner from the blue sphere.

   

   The code generated text is displayed non-aligned to the sphere.

5. I would like to be able to set the text directly on the inserted component so I will expose a parameter called ‘label’. Exposing parameters is done using metadata [Inspectable(name, type, default value)]. Metadata is text residing in the source code that is ignored by the compiler but used by other parts of the program (in this case, the Flash editor uses the metadata to pull out parameters form the source code and expose them for the user).
   I have only exposed 1 parameter here and it is a string that we’ll use to set the text and as you can see it just reads and writes directly to the textField object’s .text property. simple.
   Notice that I do not use a common variable to set the defaultValue for the text, I actually use the string “Hejsa” in two places. This is because the metadata is not a part of the actual source code and therefore you cannot use source-code defined symbols here.

   package {
      import fl.core.UIComponent;
      import flash.events.MouseEvent;
      import flash.text.TextField;
   
      public class myFirstComponent extends UIComponent {
         private var mySphereInstance:mySphere = new mySphere();
         private var txtField:TextField = new TextField();
   
         public function myFirstComponent() {
            addEventListener(MouseEvent.MOUSE_DOWN, Down);
         }
   
         override protected function configUI():void {
            super.configUI();
            addChild(mySphereInstance);
            txtField.text = "Hejsa";
            addChild(txtField);
         }
   
         [Inspectable(name="label", type= String, defaultValue= "Hejsa")]
         public function set label(s:String):void {
            txtField.text = s;
         }
   
         public function get label():String {
            return txtField.text;
         }
   
         private function Down(e:MouseEvent):void {
            startDrag();
            addEventListener(MouseEvent.MOUSE_UP, Up);
         }
   
         private function Up(e:MouseEvent):void {
            stopDrag();
            removeEventListener(MouseEvent.MOUSE_UP, Up);
         }
      }
   }

6. Save the new changed source-code and select the ‘Component Definition‘ of the ‘myfirstComponent’ symbol.
7. Press ‘OK‘, and you will notice a slight delay (flash is checking your metadata)
8. Open the ‘Component Definition‘ window again and notice that our ‘label’ parameter is now present in the parameters list for  the component. The parameters ‘enabled’ and ‘visible’ comes from the UIComponent class.

   

   The ‘label’ parameter is now exposed.

9. If you drag the ‘myFirstComponentSymbol’ to the stage and select it you will see that in the object parameters you are now able to change the label.

   

   You can change the label directly in the editor after the parameter have been exposed.

10. Great, more power to the users.

F. Adding The Live Preview.

The ‘Live Preview’ is a really cool feature in the Flash Components. It enables you to see the effect of changes in exposed parameters instantly in the Flash editor. It updates instantly without having to publish the file. Again, of course, this wonder comes at a prize, it’s a bit cumbersome to set up.

The principle is simple enough. When a component is loaded by Flash it looks to see if it contains a compiled clip (or a reference for one). If you have supplied a compiled clip, Flash will display that one in the editor instead of the un-compiled one (the ‘myFirstComponent’ symbol) in your .fla file.

Great, it works. But why the hell did they think this is better that simply just compiling the actual component? This way you constantly have to keep the embedded swf file in sync with your real component. This also reeks of rushed, unfinished code.

When enabling the livepreview I will also look at another of the base functions of the UIComponent class; the draw() function. The draw() function is called every time the component updates, which is what we’ll need when the user changes one of the exposed parameters.

1. Open ‘myFirstComponent.as‘.
2. Update the code to reflect the changes below. I have added an override to the draw() function that centers the text on the sphere using the pixel-length of the text. Notice that the class function super.draw() is called as the last thing in the overridden function.

   package {
      import fl.core.UIComponent;
      import flash.events.MouseEvent;
      import flash.text.TextField;
   
      public class myFirstComponent extends UIComponent {
         private var mySphereInstance:mySphere = new mySphere();
         private var txtField:TextField = new TextField();
   
         public function myFirstComponent() {
            addEventListener(MouseEvent.MOUSE_DOWN, Down);
         }
   
         override protected function configUI():void {
            super.configUI();
            addChild(mySphereInstance);
            txtField.text = "Hejsa";
            addChild(txtField);
         }
   
         override protected function draw():void {
   	 txtField.x = (width/2)-(txtField.textWidth/2);
            txtField.y = (height/2)-(txtField.textHeight/2);
            super.draw();
         }
   
         [Inspectable(name="label", type= String, defaultValue= "Hejsa")]
         public function set label(s:String):void {
            txtField.text = s;
         }
   
         public function get label():String {
            return txtField.text;
         }
   
         private function Down(e:MouseEvent):void {
            startDrag();
            addEventListener(MouseEvent.MOUSE_UP, Up);
         }
   
         private function Up(e:MouseEvent):void {
            stopDrag();
            removeEventListener(MouseEvent.MOUSE_UP, Up);
         }
      }
   }

3. Now, update your component_shim (C5 + C6) and deploy the component (A8+A9).
4. Open Flash and create a new document (File->New).
5. Drag your component to the stage and make sure it sits in pos 0,0.
6. Set the Document Class to ‘fl.livepreview.LivePreviewParent‘.

   

   Set the document class of the LivePreview.fla file to ‘fl.livepreview.LivePreviewParent’ before publishing

7. Save the file as ‘myFirstComponent_livePreview.fla’
8. Publish the file. A myFirstComponent_livePreview.swf’ file is created.
9. Open the ‘myFirstComponent.fla‘ file
10. Select the ‘Component Definitions‘ for the ‘myFirstComponent’ symbol and click on live Preview ‘Set‘.
11. Select the option ‘Live preview with .sfw file embedded in .fla file‘ and select the .swf file created in 7).

    

    Selecte the .swf file just created to act as your livePreview.

12. Save, close and deploy your component.

There is another way to set the live preview which I actually find more useful for the workflow but it’s defiantly not pretty. Instead of creating a LivePreview .fla file using the ‘fl.livepreview.LivePreviewParent’ document class, you simply select the ‘myFirstComponent’ symbol in your original .fla file and choose ‘Export SWC file…’. This is an old style component exporter. The .swc file just created is actually a .zip file that contains a compiled version of your component. Rename it to .zip and extract the file ‘library.swf’. Rename ‘library.swf’ to ‘myFirstComponent_livePreview.swf’ and use that one in11). It a matter of taste which way you want to use, no matter what there is certainly room for improvement by Adobe. Hopefully there is some real improvement in the next CS package other than new icons and another broken menu-system.

I hope you can use some of the information here. Feel free to post corrections and suggestions.