What does [Bindable] mean in ActionScript?

You can either read my answer here or over on Stack Overflow.

[Bindable] is a one of several meta tags that you can use in flex ActionScript code. It can be applied to properties, or methods that are marked in any scope. It cannot be used with static class members.

The key to useing the [Bindable] meta tag is understanding what is going on under the hood when you use it. Essentially using data binding is a type of short hand for adding event listeners and dispatching events.

There are two basic forms of the [Bindable] tag. The first is just [Bindable] followed by a var/property declaration. The Second is [Bindable(event="eventname")] followed by either a var/property declaration, a function/method declaration or one half of a getter/setter declaration.

I’ll explain the longer notation first since the other builds on the same concept but with even more short hand.

When you use [Bindable(event="eventname")] you are essentially telling the compiler that this var/property/function/method (call this the instance member) is ‘available’ to be used as the source for data binding. You are also telling it that when the value of the instance member has been invalidated/changed and it needs to be re-read that the “eventname” event will be dispatched.
In this longer form this all you are doing. You the developer are responsible for actually dispatching the “eventname” event whenever the value needs to be updated in the binding subscribers.

The real efficiency of using data binding comes on the subscribing side. The typical notation you will see in MXML is value=”{instance.propertyName}” When you use the notation { } you are telling the compiler to do the following:

1. Create an event listener that listens to the event named in the bindable meta tag
2. In that event listener re-read the instance.propertyName and update this value

If you use the shorter form [Bindable], and you add the tag before a property/var, the compiler fills in the blanks and adds some additional functionality to make the property bindable. Essentially you are telling the compiler “add the events and methods you need to make this property bindable”
Now the way to think of what the compiler will do under the hood is this.

1. make a private version of your var
2. create an “event” to trigger the binding
3. create a getter function with scope and name of your original var that returns the private verson of the var when called.
4. create a setter function with scope and name of your original var that sets the private version of the var when called AND dispatches the triggering event.

In essence the compiler will do much of the work for you.

[Bindable]
public var xyz

is equivalent to

private var _xyz:String;

[Bindable(event="updateXYZValue")]
public function get xyz():String{
return _xyz;
}

public function set xyz(newxyz:String):void{
_xyz = newxyz;
dispatchEvent(new Event("updateXYZValue"));
}

The only functional differences in these is that in the first instance;

1. you do not know the name of the event that will be dispatched to trigger the binding
2. there is no way to update the underlying value without triggering the data binding

This second example also demonstrates one special case of the [Bindable] meta tag. This is that when you are applying it to a getter/setter pair defined for the same variable name you need only apply it to one or the other, it will apply to both. Typically you should set it on the getter.

You can use either notation on a function/method however if you do not specify an event the binding will never be triggered so if you are trying to bind to a function you should alway specify an event. It is also possible to specify more than one triggering event by stacking the tag. eg.

[Bindable(event="metaDataChanged")]
[Bindable(event="metaObjectUpdated")]
public function readMyMetaData():MetaDataObject{
var myMetaDataObject:MetaDataObject;
.
.
.

return myMetaDataObject;
}

This would presume that somewhere else you your class you will dispatch this metaDataChanged event or the metaObjectUpdated event when you want trigger the binding.

Also note that with this notation you can tie the binding of any instance member to any event that the instance will dispatch. Even inherited events that you yourself do not generate such as FrameEnter, OnChange, etc…

Data bindings can also be setup and destroyed during runtime. If you are interested in this take a look at the mx.binding.utils classes.

http://stackoverflow.com/questions/3959546/what-does-bindable-mean-in-actionscript/5183839#5183839

http://en.wikipedia.org/wiki/Don’t_repeat_yourself

There are not many mentions of another common feature.  This feature prevents a battery from charging unless the battery is below 90%.  This means that if you battery meter says 91% and “plugged in, not charging” you might not need to be concerned.

To test if your system is one of these, unplug and use your laptop till it gets down to say 85%, then plug it in.  Wait a minute or two before you check the status.  If your laptop is one that has this feature you should now see “plugged in charging”.

Oddly enough you should consider yourself lucky, this means that your laptop is taking special care of your battery to make it last longer.  The more you charge and discharge a battery the more you degrade it’s performance over time.  This is particularly true of small discharges and recharges. By not charging unless the battery is below 90% you won’t wear out your battery when you unplug your laptop for a short period of time, like moving it from one room to another.

I just wanted to share this because I had this happen and everything I read online talks about hardware problems or windows driver problems.  Just try this out first to see if you even need to be worried.

Since Servoy is eclipse and FlashBuilder is eclipse the process is almost exactly the same.  The only difference being that instead of the Servoy Solution explorer you use the Project Explorer.

If you are curious as to why I decided to migrate to Subclipse; it mostly has to do with the failing of Subversive to properly integrate refactoring changes (moves) into the SVN repository.   I use the eclipse automated refactoring frequently in the initial stages of a projects as I play with different package structures.  The Subversive method of handling a move is to post two  distinct SVN actions a delete and an add.  This looses any history attachment and is not ‘proper’ in my opinion.  (You can get around this by doing the SVN move outside of eclipse and then doing the refactor, but IMO this is just lame. )   I haven’t tried it yet but apparently Subclipse integrates closer to eclipse so that it will properly handle refactoring.  (Most people suggest that you do an update before and commit after the re-factor. )

When you look at the way each of these came about it makes sense.  Subversive was written by eclipse people to connect to SVN while Subclipse was written from the SVN perspective.  If you are primarily concerned with SVN then move is a really important function (to maintain history)  where as if you are coming at it from the IDE side of things it might not be as important and the easier delete/add would be sufficient.

I am in no way putting down Subversive, it is a great tool, and works well particularly if you don’t plan on doing any refactoring, then again who “plans” on refactoring

A couple of months ago I was working on a project using the ExtJS framework in JavaScript. I came to appreciate one particular feature in JavaScript that is commonly used there and while somewhat available in ActionScript is not as commonly used here in the AS world.  This is the use of anonymous functions and method injection.  Now back in the days of pre OO, AS2  Anonymous functions actually were rather common. However with the advent of AS3 and classes no longer being dynamic by default the use of things like anonymous functions and method injection has really gone away.  With the move toward a real OO language it can be argued that this is a good thing.  I’m never one to strictly stick with a prescribed architecture or pattern, and this include things like these that might make some OO purists wince.  However living in the real world I have to go with what works and makes my life easier. Sometimes that means crossing the street where there is not a crosswalk.

So the particular problem I was having was fairly straight forward and easy to understand particularly if you

A. use bindings in your ActionScript

and

B. if you understand how the AS events model relates to binding.

If you are using bindings but don’t understand the event model relationship, I recommend doing some research into into it and getting familiar with how it works.

Now to restate the problem.  You have an object that exposes a public property that is bindable.   You have a second object that uses this bindable property to provide it’s own bindable property (or method).  How do you simply and easily bind a UI element to this property on the second object, so that when the first object’s property updates, the displayed value updates.

The easy way to do this is to create the binding to object 1 in the UI (MXML in this case)  in such away that you pass the first object’s property as a parameter to a method of the second object. This method then returns the value you seek.  If this is then defined in a binding  i.e. “{obj2.someMethod(obj1.prop)}” then the binding will update when the first object’s property updates, but the value will come from object 2 (obj2.method may or may  not actually use the obj1.prop as part of the result)

Now this is all well and good however it’s not very clean in my opinion.   If you are familiar with how bindings work with events, you are aware that bindings simply execute when events are dispatched. Therefore if there is a binding, there is a corresponding event that is causing the binding-destination to fetch the new value from the binding-source.

You could then easily create a  method inside of obj2, attach that method using addEventListener to the event that corresponds to the binding on the obj1 property.  This method in obj2 could then create and fire a new event (or rebroadcast the event from obj1)  for which a property on obj2 would have it’s binding event set too.  (If that didn’t make any sense go read up on how bindings and events work.)

Now again nothing wrong with that approach.  Only thing that bothers me about that is every time I want to do this, all of my obj2 type classes have to have this one method that basically does nothing other than rebroadcast an event from obj1.  In my case I might end up with hundreds of classes that would be in this situation which means this same stupid method duplicated hundreds of time.  Anytime I get the wiff of code duplication, I start looking for a more efficient way of doing things.

The solution is an anonymous function provided by the originator of the event (obj1) and added to the dependent object (obj2).    To do this, I created an addDelgate method to the originator, for each event that I want chain.  This event takes as a parameter an object that implements IEventDispatcher and returns a handle to an anonymous function.  Here is an example of that method.

public function addDelegate_NewLoaded(that:IEventDispatcher):Function
{
   var f:Function = function(e:NewLoadedEvent):void {
                         that.dispatchEvent(new NewLoadedEvent());
                    }

   this.addEventListener(NewLoadedEvent.NEW_LOADED,f,false,0,true);
   return f
}

Now if you notice all this does is create an object f of type function. The function f does only one thing, create a new instance of NewLoadedEvent and dispatch it using the provided IEventDispatcher object that.  We then attach this function f as a listener to NewLoadedEvent of this. Then, just so we don’t loose it, we return a handle to the function to the caller.  (The caller can either keep or discard the handle as needed.)   So in the caller (obj2) we would call this like this:

[Bindable(event="newLoaded")]
public class ObjectTwo extends EventDispatcher
{
   private var obj1:ObjectOne
   private var fProxy:Function
   public var property1:String = '';
   public var property2:Number = 0;
   public function ObjectTwo()
   {
     obj1 = new ObjectOne();
     fProxy = obj1.addDelegate_NewLoaded(this);
   }
   public function someMethod():Number
   {
      return obj1.someMethodReturnsANumber() + this.property2;
   }
}

Notice that in the constructor of ObjectTwo we are creating an instance of ObjectOne.

(This  is just for demonstration purposes most likely this object would come from somewhere else, i.e.: a singleton, a factory or be passed into constructor.)

We are then calling the addDelegate_NewLoaded method on the instance of ObjectOne and passing in a reference to this instance of ObjectTwo.  We keep a handle to the resulting anonymous function as fProxy.   The other thing you should notice is that the entire class is marked as Bindable on the event newLoaded.  This means that anytime this (i.e. this instance of object2) dispatches the newLoaded event, all bindings that use properties or methods of this object as the source of the binding will be re evaluated.  This is where the magic happens.  Notice that object2 doesn’t actually have any code to dispatch this particular event.  This is because thanks to that addDelegate_NewLoaded method on ObjectOne, the obj1 will dispatch the event for us, but using obj2 as the source / eventDispatcher.

Now I’ve left out a bunch of stuff out here; import statements,   Event Meta Tags , but you should get the picture.  Just in case there is any confusion about what this accomplishes.  You would now be able to write your binding simply as “{obj2.method()}” or you could bind to any other property or method on obj2 and know that these bindings would update whenever obj1 throws the newLoaded event.

Now I’m not going to get into why you should use an event architecture… there are lots of articles on that and I’m sure by this time most developers are using events.  I will lay out my preference on how to set up events.

So if you are not familiar with it there is this neat little meta tag for attaching events to the a dispatcher.  The tag looks something like this:

[Event(name="someEventName",type="com.some.thing.fooEvent")]

Now as meta tags go this one is NOT required by the compiler (as opposed to say [Bindable] ) so it is completely optional. However if you are using FlashBuilder let me tell you what magic happens when you do use it correctly.

First let me talk a bit about how I like to create events.   I’ve become quite fond of creating individual event classes for each event type of event I want to dispatch.  Confused?  Well there are two approaches to creating custom event classes that I’ve seen floating about.  The first creates a custom event class that has a number of constant values that can be passed into the constructor for the event type.  It looks something like this:

package com.some.thing.foo {
	import flash.events.Event;
	public class FooEvent extends Event	{
		public static const OPEN_FOO_EVENT:String = "openFooEvent";
		public static const CLOSE_FOO_EVENT:String = "closeFooEvent";
		public function FooEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=false)
		{
			super(type, bubbles, cancelable);
		}
	}
}

Now to create an event of this type you call  it something like this.  (from inside of your class that extends event dispatcher):

import com.some.thing.foo.FooEvent
dispatchEvent(new FooEvent(FooEvent.OPEN_FOO_EVENT));

Now there is nothing really wrong with this…. except it doesn’t do much for you and here is why.

First imagine that you have 50 different events you want to dispatch that do not include any additional data other than the fact that the event was dispatched.  Ok so you create an event class like the above FooEvent class, add 50 different constants and there you go.   Great, but what a waste.  You could have done basically the same thing by simply putting the constants in your dispatcher class and creating a generic event.  Ala…

import flash.events.Event;
public static const OPEN_FOO_EVENT:String = "openFooEvent";
public static const CLOSE_FOO_EVENT:String = "closeFooEvent";
dispatchEvent(new Event(OPEN_FOO_EVENT));

Didn’t really do much except for add a new class that does nothing.  Either way you have to pass the constant in to the event to make sure it gets the right type.

Now imagine the other scenario.  This is the situation where you want to include some data along with the event.  Your event might look like this.

package com.some.thing.foo {
       import flash.events.Event;
       public class BarEvent extends Event
       {
          public static const OPEN_BAR_EVENT:String = "openBarEvent";
          public static const CLOSE_BAR_EVENT:String = "closeBarEvent";
          public var phooy:String = "";
          public function BarEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=false)
          {
              super(type, bubbles, cancelable);
          }
       }
}

or this

package com.some.thing.foo {
       import flash.events.Event;
       public class Bar2Event extends Event
       {
          public static const OPEN_BAR_EVENT:String = "openBarEvent";
          public static const CLOSE_BAR_EVENT:String = "closeBarEvent";
          private var _phooy:String = "";
          public function Bar2Event(phooy:String, type:String, bubbles:Boolean=false, cancelable:Boolean=false)
          {
             this._phooy = phooy;
             super(type, bubbles, cancelable);
           }
           public function get phooy():String{
               return this._phooy;
           }
       }
}

Now you would dispatch these like this:

import com.some.thing.foo.BarEvent
import com.some.thing.foo.Bar2Event

   //For BarEvent
   var b:BarEvent = new BarEvent(BarEvent.OPEN_BAR_EVENT);
   b.phooy = "iphoney";
   dispatchEvent(b);

   //or for Bar2Event
   dispatchEvent(new Bar2Event("iphone home",Bar2Event.CLOSE_FOO_EVENT));

The question you have to ask yourself is;  Does either of these really help things, or do these methods make your code harder to read?

There is a better way…..Create individual event classes for each of your events.

Now before I go down that path I will say there is one benefit of doing things like the foo class above.  You have the ability to use the is operator to check for a common class type.  Which can come in handy somewhere in your code.  You might want your event handler to handle both foo open event and file open event and branch execution by type.  Ok so  to keep that ability (and just to make things clean) I’ll do the same thing.  The way I like to handle this is by creating a directory  and package structure like this.

com.some.thing.foo

com.some.thing.foo.FooBarDispatcher.as

com.some.thing.foo.events

com.some.thing.foo.events.FooEvent.as (extends flash.events.Event)

com.some.thing.foo.events.FooOpenEvent.as     (extends  FooEvent)

com.some.thing.foo.events.FooCloseEvent.as (extends FooEvent)

Now since we don’t have abstract classes in AS you just have to restrain yourself from directly creating the FooEvent or implement some sort of abstract enforcer at runtime.  For this I don’t bother since I might at some point want to directly dispatch a FooEvent.  (seems unlikely but who knows)

So now all my events will be FooEvents by inheritance.    If  I want to throw errors  I will also create a FooErrorEvent class  (extending flash.events.ErrorEvent )  and use that as the parent class for error events.

The FooEvent class here looks almost exactly like the first foo event class in this post except there are no constants in it.    Instead we define one and only one constant in each sub-class.

package com.some.thing.foo.events
{
    public class FooOpenEvent extends FooEvent
        {
         public static const FOO_OPEN_EVENT:String = "fooOpenEvnet";
         public function FooOpenEvent()
         {
             super(FOO_OPEN_EVENT);
         }
    }
}

Dispatched like this:

import com.some.thing.foo.events.*
dispatchEvent(new FooOpenEvent());

There are a couple of ways this makes the code cleaner.  First in the event class itself, no import statement is needed since the parent class is in the same package.  A small difference but small differences add up.

The next point of clarity  is that the line needed to dispatch the event is very clear.  All I need to know is right in front of me.  I don’t need to know where to get the constant.  I don’t need to know what constants are permissible.  I just create and dispatch the event.

Also in the event class you will notice that the event type that is passed to the parent class constructor’s type argument is fixed.  The type of this event will ALLWAYS be “fooOpenEvent”   This makes the code else where easy to read.  When you  have a listener that is getting an event of type  ”FooOpenEvent”, it is always a “fooOpenEvent”.    The the first example, a FooEvent could be either a “fooOpenEvent” or a “fooCloseEvent”.   This distinction isn’t so important for the compiler, internally it looks at the type string to determine event type, however for you in reading your code  think about this….

public function handleFooOpen(e:FooEvent){
   //Am I handleing the right event?...   e.Type?
   //the compiler won't throw an error if I'm wrong.
}
public function handleFooClose(e:FooEvent){
   //Am I handleing the right event?... e.Type?
   //the compiler won't throw an error if I'm wrong.
}
//versus the clarity of
public function handleFooOpen(e:FooOpenEvent){
   //I'm sure I have the right event or it won't compile.
}
public function handleFooClose(e:FooCloseEvent){
   //I'm sure I have the right event or it won't compile.
}

So think a bit about the above code.   The first two handlers would be what you would use with the first foo event class listed at the beginning of this post.   Notice how since they both take the same type (FooEvent) that if you were to accidently set up your addEventListener incorrectly you wouldn’t know it.  For example, considering the first two event handlers above.

//This is what you want....
fooBarInstance.addEventListener(FooEvent.OPEN_FOO_EVENT,handleFooOpen);
fooBarInstance.addEventListener(FooEvent.CLOSE_FOO_EVENT,handleFooClose);
//But this would be valid too... the compiler would be just happy
fooBarInstance.addEventListener(FooEvent.OPEN_FOO_EVENT,handleFooClose);
fooBarInstance.addEventListener(FooEvent.CLOSE_FOO_EVENT,handleFooOpen);

In contrast, the last two handlers use different types, so if you try to attach them as event listeners to the incorrect type of event, the pre-compiler in FlashBuilder will report a problem.  For example… (considered with the last two event handlers from above)

//This would work....
fooBarInstance.addEventListener(FooOpenEvent.FOO_OPEN_EVENT,handleFooOpen);
fooBarInstance.addEventListener(FooCloseEvent.FOO_CLOSE_EVENT,handleFooClose);
//But the compiler wouldn't like this....
fooBarInstance.addEventListener(FooOpenEvent.FOO_OPEN_EVENT,handleFooClose);
fooBarInstance.addEventListener(FooCloseEvent.FOO_CLOSE_EVENT,handleFooOpen);

Where this really helps code readability is when you want to include some sort of payload data with the event.   I won’t write the revised event classes out but think of the bar events from before.  If you rewrite them to include the constant in the event and the type is fixed to that constant.  This is what you end up with to dispatch the event .

import com.some.thing.foo.events.*

   //For BarEvent
   dispatchEvent(new BarEvent("iphoney"));

   //or for Bar2Event
   dispatchEvent(new Bar2Event("iphone home"));

Now that is much easier to read and understand.  Plus the advantage that I just mentioned above about the compiler catching incorrectly assigned event listeners comes into play even more when you have events that carry data.  For example; Imagine that you have an event with a “status” property, “status” would have quite a different meaning for an open event, close event and a delete event.  You would want to ensure that it is handled correctly.

Ok…. so this post has gotten pretty long and I haven’t even gotten to the meta data tag I mentioned before…. ok now I’m getting to that.

Basically it comes down to this.  You want to add the following meta data tag before the class definition for each event that your class will dispatch.  For example in my FooBarDispatcher class :

...
[Event(name="fooOpenEvent",type="com.some.thing.foo.events.FooOpenEvent")]
[Event(name="fooCloseEvent",type="com.some.thing.foo.events.FooCloseEvent")]
public class FooBarDispatcher Extends EventDispatcher
{
...

Now where this comes into play in FlashBuilder is in the auto sense type thingy.

FlashBuilder uses the information in the meta tag above to do a couple of things.  First it uses it to help you auto fill events that an object can dispatch.   So if I opened another class and created an instance of FooBarDispatcher named foosball (of type FooBarDispatcher)  as soon as I then typed the “(“ in “foosball.addEventListener(”    a list of the available events that could be dispatched by the object (fooOpenEvent, fooCloseEvent) would be displayed.

If I then select one of these events the other bit of magic happens.   Provided I have named my event name, event class, and event type constant correctly defined in the meta tag and the event class, FlashBuilder will automagically enter the correct class and constant value for me.  ie.    “FooOpenEvent.FOO_OPEN_EVENT” thus I then just have to type in the name of the event handler and all is done.    For reference ….

...
private var foosball:FooBarDispatcher = new FooBarDispatcher();
foosball.addEventListener(FooOpenEvent.FOO_OPEN_EVENT, handleFooOpen);
...

Now the rules for naming the event class, the event name and event type constant are the tricky bit  they are as follows.

• The type in the meta tag must be point to the class that contains the constant.  This should also be the class of the event type itself.
• The name in the meta tag must be the same as the name of the constant in the above class converted to all upper case where  an upper case letter is preceeded by an underscore as in…
  fooOpenEvent ->  FOO_OPEN_EVENT
  fooCloseEvent -> FOO_CLOSE_EVENT
• To keep things simple and consistent, the string contained in the constant in the event class should be the reverse
  FOO_OPEN_EVENT = “fooOpenEvent”

That’s it.  Now I should mention that the above method of using the meta tag WILL work just fine with the method of having more than one event type defined in a single event class.  However I hope you see there are other very good reasons to define separate events for each event type.

The extra time it takes to create individual event classes and the time it takes to add the meta tag to your event dispatchers for all the events it dispatches does pay off.   First when you are coding by having the correct event types automatically appear and second by reducing debugging time since bone-headed event handling errors will be caught by the pre-compiler.

PS.  Another  thing this does, is show your events when you use your components in MXML. (If you swing that way.)

PSS.  Almost forgot (this is even more goodness)   By specifying the event meta data you can also add an ASDoc comment to  the event.   Maybe I’ll write a post about that too someday.

From a bit of googleing   I was able to determine that the problem was basically that my atom-xml request content was not formed properly.  In particular that the xml content was preceded in the request by “something”    Using Charles I was able to easily determine that the offending piece of data was my oauth signature and other oauth bits.  The problem could best be summed up as the following:

• I had been doing oAuth requests to the Picasa API using a POST request.
• Because there are issues with the Authentication header in Flex/Flash I was sending all oAuth values in the post request.
• This was all well and good EXCEPT if  the request needs to be of content type “application/atom+xml” because then you get this aforementioned error.
• However… you can’t make the API call without passing all of the oAuth “stuff”
• Since I can’t use the Authentication header (which would be ideal) to pass the oAuth stuff, but I need to get the oAuth stuff out of the body of the POST, how then to do it?….

Solution, Ah  oh so simple….

Leave the request type as a POST (with the content being the atom xml payload), set the content type to “application/atom+xml” but pass all of the oAuth as a GET, i.e. as escaped (urlEncoded) values on the URL query string.

Voila!  Request completes and is signed properly etc. etc.

Now just have to get past the fact that Flex thinks a 201 response code is an error and we should have that bit working.

“SetSlate returned error. FjSetSlt is exiting”

After some looking around at  tabletpcreview.com and some trial and error I found a solution.

Originally I tried the procedures outlined by a number of people to uninstall the button utility, reboot, uninstall driver, reboot, delete the buttons directory under the program files/fujitsu directory, reboot then reinstall the driver, reboot, reinstall the utility…..

unfortunately this didn’t work.

However, I noticed that during the installation process, Windows7 as usual would ask the typical UAC question… “This program is attempting to make changes to the system…. “  (or whatever it normally says) and the install program opened a couple of command windows.  These windows would then generate a couple of errors.  This got me to thinking about some issues I was having with some other software on my new development machine at work… and I had an idea……

I turned off User Access Control and rebooted.

now… with UAC turned off I followed the directions..

• Uninstall the button utility
• Reboot
• Uninstall the button drivers
• Reboot
• Re-install the button drivers
• Reboot
• Re-install the button utility
• Reboot

….. it worked!   The buttons started to work……

I suspect that because UAC was enabled (even though I gave permission to the installation program) the command files that it used did NOT have elevated (admin) permissions and therefore failed to perform whatever actions they were supposed to carry out.   (hence the error messages)

Now the next thing I need to try is to see if this idea might help me fix the blue-tooth problem I was having a couple months ago  (which again happened after an system update)

Adobe makes available but does not include by default many framework localization resource bundles in the form of collections of property files. These files provide localization settings for the Flex framework components including; number and currency formats, month and day names, internal error messages etc…

To localize the framework components it is necessary to download these property files and recompile the framework resource bundle library (framework_rb.swc) for each locale. (see attachment) These libraries can then be compiled into our localization files.

Setting up basic standard localization for the Flex environment.

This post does not cover how to apply localization to your application when I have a chance I’ll post one on how to do that. Also, this information is made regarding the Flex SDK 3.4 but should apply with minor modifications to most other versions of the SDK. These steps should apply to the command line or any version of Flex/Flash Builder with minor variation.

For reference, I am using Flash Builder 4 installed in the default install directory, with the 3.4.0.9271 SDK loaded as an alternative SDK.
The process to setup basic Flex localization can be broken into the following steps.

1. Create the localization component libraries in the SDK
2. Localize the component librariesfor the SDK
3. Recompile the component libraries for the SDK

Before you can localize you must set up the localization component libraries in the SDK. By default only en_US is installed. To install the others follow the following steps.

1. Create the localization component libraries in the SDK.

To do this you must first copy the en_US stub to your new localization. There are several standard localization names most take the form of two letter language code + underscore + two letter country code. However there is no rule that you must follow this convention. Adobe includes a utility to make a copy of localizations. You must navigate to your SDK bin directory via the command line. Since I am using Flash Builder 4 with the additional SDK loaded in it, that means this directory for me is:

 C:\Program Files\Adobe\Adobe Flash Builder 4\sdks\3.4.0.9271\bin\

You then want to run the program copylocale (if you need to find your bin directory you can do a file search for copylocale.exe)

This is a very simple program it takes two arguments source and destination locales. You don’t worry about directories, it knows where to do it’s business. I will be creating a generic Spanish locale (es) and a Mexico specific locale (es_MX). So I will run the following two commands.

copylocale en_US es
copylocale en_US es_MX

These commands will do a number of things but basically they copy:

 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\projects\framework\bundles\en_US\

To:

 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\projects\framework\bundles\es\
 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\projects\framework\bundles\es_MX\

And at the same time they compile the contents of those directories to several swc files located in:

 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\locale\es\
 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\locale\es_MX\

2. Localize the component libraries for the SDK

Now you need to modify the source files located in the first set of directories

 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\projects\framework\bundles\es\
 C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\projects\framework\bundles\es_MX\

You can modify these by hand if you want to and happen to have the knowledge.  But there is an easier way.

Adobe has made available a set of basic localization files for over a dozen languages online.  (Why they just don’t just include these… I don’t understand) You can download the files at:

http://opensource.adobe.com/svn/opensource/flex/sdk/trunk/frameworks/projects/framework/bundles/

For my purpose I will get the es_ES directory and copy all of the *.property files to the two directories above. I will make a further change to a few of the files I copy into the es_MX directory, but other than that, that is it.

Note: There is a “docs/” directory in the resource directories on the download site. I don’t think you need it unless you want to localize the context help for your installation of Flex/Flash Builder.

3. Recompile the component libraries for the SDK

You are not quite done yet. If you were to attempt to localize an application at this time you would find that everything is still using en_US.   (‘January’ ‘Monday’,$, etc..)  The reason is that when flex compiles your application,  it uses the SWC files located in these directories:

C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\locale\es\
C:\...\Adobe Flash Builder 4\sdks\3.4.0.9271\frameworks\locale\es_MX\

These were created in step 1, before you downloaded the localized files from Adobe. To recompile these files I use the following command, but first I must change my command console directory to the root of the sdk. In my case that is:

C:\Program Files\Adobe\Adobe Flash Builder 4\sdks\3.4.0.9271

(Note: the next commands are all on one line. I broke it out so you could read it easier.  I also boldfaced the command line options.)

Now I run the following command

bin\compc -locale=es
-source-path+=
frameworks/projects/framework/bundles/es/src/
-include-resource-bundles=
collections,containers,controls,core,effects,formatters,logging,SharedRe
sources,skins,states,styles
-output=frameworks/locale/es/framework_rb.swc


I run it again for Mexico variant


bin\compc -locale=es_MX
-source-path+=
frameworks/projects/framework/bundles/es_MX/src/
-include-resource-bundles=
collections,containers,controls,core,
effects,formatters,logging,SharedResources,skins,states,styles
-output=frameworks/locale/es_MX/framework_rb.swc

These last two commands compile the property files into the framework_rb.swc file.  This library is then in turn used by the compiler when you compile your application or can be dynamically loaded as a localization into your app.

Now you are set to localize your project swf or compile dynamic locale swf files with all of the base flex components being localized.    (‘Enero’ ‘de lunes’, peso, euro etc..)

/** Takes a series of UI components, sets all widths to the widest width */
private function setToGreatestWidth(...args):void{
   args.sortOn(['width'], Array.NUMERIC | Array.DESCENDING);
   for(var i:uint = 0; i < args.length; i++) {
        args[i].width = args[0].width;
   }
}

I would typically call it like this in the on creation complete handler for my UI container:

private function onCreationComplete():void{
   setToGreatestWidth(this.button_upload,this.button_cancel);
   setToGreatestWidth(this.label1,this.label2,this.label3,this.label4);
}

By calling it from the creation complete handler you ensure that all localization strings have loaded and layout has already occurred and therefore the controls have all adjusted to their content width.

(I’m not sure there may be  a really cool and efficient way to accomplish this in the new Spark architecture but I’m working on some older 3.4 code so I don’t have access to those components anyway.)