(Please open the article to see the flash file or player.)

This was also a chance to get to grips with the new Motion Editor in Flash CS4.  I’ve made that and a CS3 version available for download if you’d like to have a look.

Download the .fla (CS4)
Download the .fla (CS3)

Have a look at www.imageafter.com if you’re looking for more texture images.

As seemingly exhaustive as Adobe’s gigantic article by Jeff Kamerer is, many answers were not to be found there. I wanted to make an SWC-based component that did not rely on the UI Component framework — after all, not every component is a UI gadget! I wanted to write a simple class to draw something to the stage, with a few options I could control with my own control panel and see updated with a live preview right on the stage.

Along the way to a solution, I encountered a host of problems getting the control panel to communicate with the authoring tool, and for the authoring tool to communicate properly with the component and the control panel… and then even with all of those problems cleared up, there was still the problem of parameter settings being retained in the finished compiled product. It seems quite clear that several aspects of component creation do not work as they should–at least not when you add a custom control panel into the mix. However, in spite of all the problems, there is a reasonable workaround to make this possible.

Eventually, after a lot of googling about, and a whole lot of trial and error, I managed to piece together this jigsaw puzzle, and can now present to you a method for creating your very own components with custom control panels, all in Actionscript 3, which works for both Flash CS3 and CS4.  In this article, I’ll give you a tour of the code for a simple component and its control panel, with notes on how to make your own components.

CLICK HERE to download the complete source files.

THE COMPONENT

Defining Parameters

First, let’s take a look at the source code for the component. Open up “MyComponent.as”  …In order to inform Flash what the parameters for this component will be, we have to include [Inspectable] metadata tags in the class code.

 [Inspectable (name = "color", variable = "color", type = "Color", defaultValue = "FF0000")]
 [Inspectable (name = "radius", variable = "radius", type = "Number", defaultValue = "10")]

I’ve placed them right at the top of the class, for easy reference. Both parameters–radius and color–are going to call getter/setters which you’ll find near the end of the file. There are a few important things to notice here:

• The name and variable for each parameter MUST be the same
• All of the parameters MUST be in alphabetical order
• The default values must be set BOTH in the meta-data and the code

Of course these are hardly official requirements for writing a component, and I’m sure there are plenty of components out there that were not written following these rules. However, in order to create this component with a custom user interface in the Component Inspector and with live preview… all three of these rules must be observed.

Note also that the default value for color is represented as a hex string without the leading “#” or “0x”

The setSize() Method

Moving on, the setSize() method is where we handle resizing of the component. The Flash authoring tool will automatically call this function for live preview, so it must be defined as public, and with parameters for width and height.

public function setSize(w:Number, h:Number):void {
	_width = w;
	_height = h;
	draw();
}
 
private function draw():void {
	_background.graphics.clear();
	_background.graphics.beginFill(_color, 1);
	_background.graphics.drawRoundRect(0, 0, _width, _height, _radius, _radius);
	_background.graphics.endFill(); 
 
	_tf.text = Math.floor(_width) + " x " + Math.floor(_height);
	_tf.x = (_width - _tf.width) * 0.5;
	_tf.y = (_height - _tf.height) * 0.5 + 2;
}

Some component source examples I’ve come across have defined a draw() method as protected, with a drawNow() method to provide public access. I have found no requirement for this, except perhaps when working with the UIComponent framework.

Parameter get/set functions

Next, the getter/setter functions for our parameters, color and radius. We need to use getter/setter rather than public properties so that whenever these values change, we can redraw the component.  This will keep the component updated both for live preview and at runtime.

public function get radius():Number { return _radius; }
public function set radius(value:Number):void {
	_radius = value;
	draw();
}
 
public function get color():int { return _color; }
public function set color(value:int):void {
	_color = value;
	draw();
}

Override width and height

Finally, we must override the getter/setter functions for width and height. If we don’t, then when an actionscript call is used to change the dimensions of our component, it would merely be stretched or squashed.  What we want is to redraw the component with the new size.

override public function get width():Number { return _width; }
override public function set width(value:Number):void {
	_width = value;
	draw();
}
 
override public function get height():Number { return _height; }
override public function set height(value:Number):void {
	_height = value;
	draw();
}

Compile and Test

Let’s compile the component and try it out without any custom control panels, just for starters.  Open up “Make a Component.fla”  You’ll find just one library item, a MovieClip called “MyComponent.”  It’s not quite ready to be compiled as it is.  Double-click the item to open it up on the stage.  You’ll find just one object, called “avatar” which the component code will use for default dimensions and as a simple means of setting font format properties as well as embedding the font.  All right let’s compile…

1. In the Library, right click “MyComponent” and click on “Properties”
2. Tick the box: “Export for ActionScript”  Since the class box will have automatically set itself to “MyComponent” it will use our component code.
3. Click OK, and again, right click “MyComponent” in the Library and click on “Component Definition…”
4. As redundant as it is, type “MyComponent” into the Class box here also, and then click OK.
5. Again, right click “MyComponent” in the Library and click on “Component Definition…”

NOTE: The parameters part of this dialog will now show our parameters, radius and color.  Frankly, this dialog was built backwards:  it ought to have filled in the Class from the Properties dialogue, and from that the Parameters.  But that’s not how it works.  What’s more, don’t bother trying to rearrange your parameters using the buttons provided–those changes will be lost.  You see, as soon as you click OK in this dialog, Flash reads in the Class file, searching for meta-data and rebuilds the parameters table…!

6. Tick the box: “Display in Components Panel” and click OK.
7. Now right click “MyComponent” one more time and click on “Export SWC File…”
8. Make a new folder in: “C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\Components” called “My Components” or “Test Components” or whatever you like.
9. Export the SWC file to this foler.
10. Open up the Components panel (ctrl-F7 / -F7)
11. Click the panel options button (the tiny black triangle in the upper right corner of the panel) and click on “Reload”

NOTE: Whenever you re-compile your SWC file, you must reload the Components panel for Flash to load in the updated version.

12. You should see the name of the folder you created your component in, so open that and you’ll find your new component.
13. Make a new Flash document where we’ll give the component a try out.
14. Drag the MyComponent from the Library panel onto the stage.  You should see something like this:



Tthe avatar has been replaced.  Our component code has been run, right on the stage.

15. With the component selected, click on the Parameters tab of the Properties panel.
16. Try changing the parameter values.  Immediately as you change the values, the component updates itself.
17. Save this file as “Test Component.fla” and we’ll come back to it later.

CUSTOM CONTROL PANEL

Something to keep in mind is that our custom control panel will not communicate directly with the component instance. Rather, the control panel adjusts parameter settings in the authoring tool, and the authoring tool in turn modifies the component instance. The component instance receives information via the setSize() method and property setters, and has no means of its own to communicate with either the authoring tool or the control panel. Keeping our parameters in alphabetical order, rather than trying to arrange them in some logical order, allows us to avoid a minefield of problems.

Reading Parameter Values

Let’s have a look at the source code for our control panel.  Open up “ControlPanel.as”  Once again, right near the top of the file are references to our parameters:

private const PARAMETER_COLOR:String = "fl.getDocumentDOM().selection[0].parameters[0].value";
private const PARAMETER_RADIUS:String = "fl.getDocumentDOM().selection[0].parameters[1].value";

These instructions refer to parts of the Flash authoring tool’s user interface using the JSFL language–specifically, the parameters panel of the selected object.  (See below under Further Reading for more details about JSFL.) Notice that the numbering of the parameters follows the alphabetical order we’ve maintained.  Although it’s not required to set these constants, it makes the rest of the code considerably more readable.

public function ControlPanel() {
 
	color.text = MMExecute(PARAMETER_COLOR);
	if (color.text.substr(0, 1) != "#") color.text = "#" + dec2hex(uint(color.text));
	color.addEventListener(Event.CHANGE, setColorFromText, false, 0, true);
	colorPicker.addEventListener(ColorPickerEvent.CHANGE, setColor, false, 0, true);
 
	radius.text = MMExecute(PARAMETER_RADIUS);
	radius.addEventListener(Event.CHANGE, setRadiusFromText, false, 0, true);
	radiusSlider.addEventListener(SliderEvent.CHANGE, setRadius, false, 0, true);
 
	addEventListener(Event.ENTER_FRAME, setControls, false, 0, true);
}
 
//......................
 
private function setControls(e:Event):void {
	setColorFromText();
	setRadiusFromText();
	removeEventListener(Event.ENTER_FRAME, setControls);
}

In the class constructor function, we read the current control panel values and apply them to our controls.  Using the MMExecute() function (which is made available by importing the package: adobe.utils.MMExecute) allows us to execute our JSFL code defined in those two constants above.

The slider and the color picker components’ default parameter values will be applied right after our control panel is instantiated.  Hence, the code to set those controls had to be called from an ENTER_FRAME event listener, so that it would occur after those components had been initialized.

Setting Parameter Values

Whenever parameters are changed, either with the handy slider & color picker, or with the text fields, setting the parameters in the authoring tool requires another simple call to MMExecute():

MMExecute(PARAMETER_RADIUS + "=" + value);
 
	// Which, assuming value is 20, is equivalent to...
 
MMExecute("fl.getDocumentDOM().selection[0].parameters[1].value = 20");

That’s really there is to it.  The remainder of the ControlPanel.as code works like any other Flash form, updating text and components to work together, and using l to MMExecute() to update the authoring tool. The authoring tool in turn sets variables in our component instance to update the live preview.  Now let’s add this control panel to our component…

Compile the Component with Custom UI

1. Compile the control panel (Shift-F12) creating “Component Control Panel.swf”
2. Now, re-open “Make a Component.fla” and right-click MyComponent in the Library panel, then click “Component Definition…”
3. Across from “Custom UI:” click on the Set button.
4. Select “Custom UI in external .swf file”
   • Select “Display in Component Inspector panel”
   • Assign the Custom UI .swf file by clicking on “Browse…” and selecting ”Component Control Panel.swf” which we just created.
   • Click OK
5. Click OK
6. We’re ready to re-compile the component.  Right-click MyComponent and click on “Export SWC File…” and overwrite the older SWC file we created
7. Update the Component panel by clicking the panel options button (the tiny black triangle in the upper right corner of the panel) and click on “Reload”
8. Re-open your test file: “Test Component.fla”
9. Click and drag the updated component from the Coponents panel, into the Library panel.  You should see the dialog: “One or more library items already exist in the document.”  Select “Replace existing items” to update your test file.
10. Now when you click on a component instance on the stage, the Parameters panel will no longer allow parameters to be set there, but will give you a button to launch the Component Inspector, which is where our control panel will appear.

NOTE: By choosing “Display in Property Inspector” in step 4, you can get your control panel to appear in the Parameters tab.  However, in this example case, the color picker demands more space than is available there.

11. Try making a few variations of the component on stage and compile your test movie.

CONCLUSION

Thanks for reading!  I hope you’ve found this tutorial helpful.  Check out the file “Use the Component.fla” and its base class “UseComponent.as” for various tests which helped me to refine this method and write this tutorial.  There is also an illustration of the one issue, described below, that I have as yet been unable to resolve.  If you should come up with a solution, please be sure to post about it here!

Known Issue:

If I rotate the component on the stage in the authoring tool, its width and height are incorrectly reported as an unrotated bounding box, which will inevitably be larger than the correct dimensions, as shown below:

The selected component shows its correct dimensions as 83 x 17, while the authoring tool shows the incorrect dimensions 70.2 x 70.2.  At runtime, the component is initialized with those incorrect dimensions:

[UPDATE]  A solution to this problem is presented by Juan Carlos in a comment that follows this post.

Further Reading:

Read about the [Inspectable] meta-data tag:
http://livedocs.adobe.com/flex/3/html/help…
http://livedocs.adobe.com/flash/9.0/main/…
It seems this information does pertain to AS3 as compiled by Flash CS3+, but I have never found documentation except as it pertains either to Flex or to AS2.

To find out more about JSFL and what you can do with MMExecute(), take a look at this excellent video by Lee Brimelow about creating panels to extend the Flash IDE:
http://gotoandlearn.com/play?id=66

This reference to extending Flash provides full details of JSFL support in Flash:
http://livedocs.adobe.com/flash/9.0/main/flash_cs3_extending.pdf

…and a tutorial on creating FLA-based components:
http://www.flashbrighton.org/wordpress/?p=31

The problem lies in a small javascript file: brwsniff.js, a handy dandy browser sniffer that checks for the installed Flash Player version number. The bit of code written for non-IE browsers wasn’t expecting a player with a version number of more than one digit; so, seeing only the one’s place digit, if you’ve got Flash Player 10 installed, the script comes up with a version number of ZERO!

Unfortunately, the author of this otherwise delightful script has not updated the file since before Flash Player 10 was released. Having made the minor repair necessary, I’m making my updated version available for download HERE.

Please note: If for some reason you needed this script to detect the browser software in use, I’m afraid you’re still out of luck. The script seems to see everything as either IE or Firefox.

[UPDATE]
Got a message from Pau Garcia i Quiles, author of jsbrwsniff.  He’ll publish a bugfix soon—until he does, download the version posted here.  I’ll announce when an official bug fix becomes available.  New features he’s planning to add in the coming months:

My new portfolio site is finally ready for public viewing. The design of the site is an homage to one of my favorite artists, the Belgian surrealist René Magritte. Even if you’ve never heard the name, you’ve probably seen his most famous image somewhere: A man in a bowler hat, with the sea behind him… and a green apple floating mysteriously right in front of his face. Monsieur Magritte is responsible for numerous iconic images like this one, and in my design of this site (as with the background image for this blog) I’ve created various sorts of references to his style, some spoofs of his most famous paintings… with the addition of animation!

Another point of interest is that this site is the first project I’ve completed using my new Actionscript 3 framework: MORFsite. Although there’s still a fair bit more functionality yet to be added to it before it’s complete, MORFsite already covers these features…

• handles overall site architecture and navigation events
• manages media and data resources
• maintains the visual layout of the site

I still need to integrate SWFaddress and tie up some loose ends. When I do, my plan is to release MORFsite as an open source project.

Anyway, enough babble! Go visit my new portfolio site: http://studio.barliesque.com

[UPDATE] The site was just awarded a PickA Gold Award!  (21 January 2009)

http://www.pv3d.org
http://papervision2.com
http://www.dehash.com/?page_id=202
http://www.flashbookmarks.com/PV3D-Beta2-DOC
http://blog.zupko.info/?cat=8
http://www.madvertices.com

…and here’s a little 3D experiment I’ve been tinkering with as I learn how to use this exciting library:

(Please open the article to see the flash file or player.)

I’ll post some source code eventually for PV3D experiments soon… 

A tiny object being masked by a huge shape will cause getBounds() to return the extents of… the mask, not the visible object.  It gets even better if your object happens to move beyond the masked area–thus making it totally invisible.  Now getBounds() exapands to include the area of the giant mask plus that of the tiny object, which is no longer being drawn to the screen at all.

In fact, there appears to be no built-in method for reliably determining the actual screen area a MovieClip is occupying.  Do we call this a bug, or was it really meant to work this way???

I decided to try writing a handy dandy function to remedy this problem, and in so doing discovered another serious limitation involving masks.  When you create an arrangement of layers in the Flash IDE with, let’s say three or four objects being masked by one mask, you’ve done something that apparently is only possible with the Flash IDE, and not with AS3.  If you have a look at the .mask property of each of those masked objects, they’ll all be set to NULL.  There’s no sign of any masking going on, as far as ActionScript is concerned.  Suppose you manually set the .mask property of one of those three or four masked objects?  The result is that all the other objects will be unmasked.  Using the .mask property strictly pairs one mask to one display object.  So now you’ve got to find a way of duplicating your mask, so each object has its own mask…! 

Well, nonetheless I wrote my own routine: getVisibility() which reliably tracks down whatever is actually visible, and nothing more.  It’s reliable, that is, as long as you manually set your masks in code–one mask for each object.  If a better solution exists, I’d like to know about it.  For now, here’s a little demo of my function versus AS3’s native functions…

(Please open the article to see the flash file or player.)

There’s only one error I can detect in the result of getVisibility() …When objects are rotated, their visibility is based upon a rotated bounding box, rather than the precise shape of the object.  Still, this gets us considerably closer to a solution.

The .fla can be downloaded HERE.  Here’s the code for my getVisibility() function…

function getVisibility(obj:DisplayObject):Rectangle {
 
	var vis:Rectangle;
 
	if (obj.parent == null) return new Rectangle();
 
	if (obj is DisplayObjectContainer) {
		vis = getChildVisibility(obj, obj.parent);
	} else {
		vis = obj.getBounds(obj.parent);
	}
 
	// Is the DisplayObject masked?
	if (obj.mask != null) {
		vis = vis.intersection(obj.mask.getBounds(obj.parent));
	}
 
	// Is the DisplayObject partly or completely off-stage?
	vis = vis.intersection(obj.stage.getBounds(obj.parent));
 
	return vis;
}
 
function getChildVisibility(obj:*, target:DisplayObjectContainer):Rectangle {
 
	var vis:Rectangle = new Rectangle();
	var child:DisplayObject;
	var childRect:Rectangle;
	var i:uint;
 
	for (i = 1; i <= obj.numChildren; i++) {
		child = obj.getChildAt(i-1);
 
		if (child != null) {
			if (child.visible) {
				if (child is DisplayObjectContainer) {
					childRect = getChildVisibility(child, target);
				} else {
					childRect = child.getBounds(target);
				}
				if (child.mask != null) {
					childRect = childRect.intersection(child.mask.getBounds(target));
				}
				vis = vis.union(childRect);
			}
		}
	}
	return vis;
}

All these years of designing and developing and I’ve never had a blog to call my own.  The shame of it!  Well, through the magic of WordPress I’ve finally rectified this. Thanks also go to TheBuckmaker for the Aeros theme, to which I’ve added my own Magritte-inspired background image and a few minor modifications.

I’ll be posting about my travails with Adobe Flash and ActionScript3 in particular, but who knows what else may find its way onto this blog?

Sometime soon, I plan to release a proper announcement of my AS3 framework, MORFsite.  At present, I’m using it to complete a new website for myself–finally an up-to-date portfolio!  I’ll post about MORFsite soon, which I plan to release as an OpenSource project.  But not until it’s had a chance to mature with a couple of real live projects.

Well… on with the blog!