Flash Article

Defining Class Properties and Component Parameters

In the previous step, you turned the component into a UI component. The next step defines all the necessary properties used by the component. Then you can move on to defining the component parameters within the class file.

Before you go into the code, you need to be aware that there are two rather different types of variables.

The first variable type is just a plain old variable with the added flavor of now having a type. For the most part, you will use regular variable properties as private internal properties.

You define the second variable type with getter/setter methods and it appears on the outside as a simple property that you can read and write. You will use getter/setter properties primarily as public properties that you can even use as component parameters. This second species of variable already existed in Macromedia Flash MX, but it becomes much more important in Macromedia Flash MX 2004.

Getter/setter properties have several benefits. They are easy to access from the outside. Also, they are able to execute code so the component can immediately react to changes, for example, changing its appearance.

1. Add the private properties. Replace the previous class code with the following code:

   class FooterNav extends mx.core.UIComponent
   {
   	var className:String = "FooterNav";
   	static var symbolOwner:Object = FooterNav;
   	static var symbolName:String = "FooterNav";	
   	
   	private var __buttonStyles:Object = {
   		color       : 0x2B333C
   		,fontSize   : 9
   		,fontFamily : "Verdana"
   		,fontWeight : "bold" 
   	}
   	
   	private var __captionStyles:Object = {
   		color       : 0x2B333C
   		,fontSize   : 9
   		,fontFamily : "Verdana"
   		,fontWeight : "normal" 
   	}
   	
   	private var __borderWidth:Number = 2;
   	
   	private var __buttonAlign:String;
   	private var __labels:Array;
   	private var __links:Array;
   	private var __linkTarget:String;
   	private var __captionText:String;
   	private var __captionAlign:String;
   	
   	private var __margin:Number = 5;
   	private var __spacing:Number = 2;
   
   	private var captionLabel:MovieClip;
   	private var bg_mc:MovieClip;
   	private var bgBorder_mc:MovieClip;
   	private var container_mc:MovieClip;
   	
   	
   	function FooterNav() 
   	{
   		trace( "new FooterNav" );
   	}
   	
   }
   

   Notice that all of these private properties begin with a double underscore. That's not a necessity, it's simply to remind you as you program that you shouldn't call those variables from outside the class or subclass.

   It is important that you define all your properties at this point—all private storage properties as well as all movie clips you will use. Otherwise, if you haven't defined them, the compiler will give you error messages later when you are trying to use them. You can avoid some of that if you define your class as a dynamic class instead of just a simple class, which implies static class. Macromedia Flash allows a dynamic class to add properties at runtime, while a static class cannot.

   It is, however, good practice to define all your properties ahead of time. This actually lets the compiler check to make sure you use them correctly. This is very beneficial to you, although it may seem a burden at first. For example, the compiler can now show you an error message if you misspelled a property name.

2. Add the getter/setter methods after the FooterNav constructor (the FooterNav function with the trace statement), but before the closing curly bracket:

   // inspectable properties
   // give Flash additional info – possible values, default values
   // e.g. for use in component parameters
   	[ Inspectable( enumeration="left,center,right", defaultValue="left" ) ]
   	// define the setter method for the buttonAlignment property
   	// e.g. myComponent.buttonAlignment( "center" );
   	public function set buttonAlignment( align:String ):Void {
   		// store the setting in a private property
   		__buttonAlign = align;
   		// make sure the component updates itself
   		invalidate();
   	}
   	// define the getter method for the button alignment property
   	// e.g. trace( "buttonAlignment: " + myComponent.buttonAlignment );
   	public function get buttonAlignment():String {
   		// return the actual setting
   		return __buttonAlign;
   	}
   	
   	[Inspectable( type="Array", defaultValue="Macromedia,Google,Yahoo,Nirvana" )]
   	public function set buttonLabels( labels:Array ):Void {		
   		__labels = labels;	
   		invalidate();
   	}
   	
   	public function get buttonLabels():Array {
   		return __labels;
   	}
   	
   	[Inspectable(type="Array", defaultValue="http://macromedia.com,http://google.com,http://yahoo.com" )]				 
   	public function set buttonLinks( links:Array ) {
   		__links = links;	
   	}
   	
   	public function get buttonLinks():Array {
   		return __links;
   	}
   	
   	
   	[Inspectable(enumeration="_blank,_self,_top,_parent", defaultValue="_blank" )]
   	public function set buttonLinkTarget( tgt:String ) {
   		__linkTarget = tgt;
   	}
   	
   	public function get buttonLinkTarget():String {
   		return __linkTarget;
   	}	
   	
   	[Inspectable(type="String", defaultValue="caption goes here" )]
   	public function set captionText( caption:String ) {		
   		__captionText = caption;		
   		invalidate();
   	}
   	
   	public function get captionText():String {
   		return __captionText;
   	}
   	
   	[ Inspectable( enumeration="left,center,right", defaultValue="left" ) ]
   	public function set captionAlignment( align:String ) {
   		__captionAlign = align;
   		invalidate();
   	}
   	
   	public function get captionAlignment():String {
   		return __captionAlign;
   	}
   

   Each getter/setter method has the same structure. They each have:

   • A setter method with a specific type to store the setting that also calls invalidate()
   • A getter method to return the current value
   • The Inspectable statement, which displays the property within an inspector panel, such as the Component Parameters panel. The Inspectable settings are what you will see as default values later in the components parameters.

   Statements such as [Inspectable] are not "real" code. This is called metadata, which gives Macromedia Flash additional information about the code you write. In turn, Macromedia Flash can use metadata to automatically create the component parameters of your component. To learn more about what you can do with these settings, please read the component metadata section in Allen Ellison's article on Building and Testing Components in Macromedia Flash MX 2004.

3. Define which of the above properties show up as component parameters by adding the following code just above the FooterNav constructor:

   var clipParameters:Object = {  buttonLinks:1, buttonLabels:1, buttonLinkTarget:1, buttonAlignment:1, captionText:1, captionAlignment:1 };
   
   
   

It's important that you don't forget to update this array when you add or remove properties as you develop your own components. You only need this array for backward compatibility with the Macromedia Flash Player 6, however, you want to make sure this works. A great benefit of the new architecture is backward compatibility. Defining this array with new values is not too much of a disadvantage when the benefit is backward compatibility.

Note: Using this array is not something Macromedia Flash takes care of by itself. It is rather part of the component architecture. Left untreated, these properties are not defined properly in Flash Player 6. Some code in the component base classes ensure that the properties are defined in Flash Player 6 as well. Since there is runtime code taking care of this, Flash can’t take care this automatically for you; you must define this array.

Now it's time to check out the parameters in your component. Make sure to save your class file before you switch back to FooterNav.fla.

The component parameters may not show up immediately; you may have to open and close the Component Definition dialog box before the parameters show up in your instance on the stage. After doing so, they should all appear.

Note: You may be looking for the component in the Components panel. The Components panel is for finished and compiled components only. Your component will eventually make it there, but for now, work with it in the Library. The Components Inspector panel will work just fine, however. You can either use that or the Property inspector to check out your component parameters.

Note that the component parameters appear in alphabetical order. Unfortunately there is no way to specify a different order. To keep related parameters together, it is best to start them with the same prefix, such as captionAlignment and captionText.