Alert.show("Alert message", "Alert title", Alert.OK | Alert.NO | Alert.CANCEL);

The code above generates an alert with 3 buttons (ok, no and cancel), but how it works exactly? Well, I don’t want to rewrite the article I read, but I would like to synthesize it and focus on an Actionscript usage, in order to give the basic information required to create custom classes which will accept multiple parameters an unique argument. So… what Alert.OK, Alert.NO and so on are? They are basically numbers (uint), and the result of the bitwise or operator still returns an integer, so the Alert class will receives a number as the third argument. The | operator, in practice produces a “binary sum” of the given numbers. A good way I figured out to understand what is going on when using that operator is to trace the binary representation of every number passed and then the result after the bitwise operation. To convert a “normal number” (base 10) into a binary one (base 2… only 1 or 0 sequence), we can use the toString() method by passing 2 as the radix argument:

var myNumber:uint = 3560;
trace(myNumber.toString(2));

The code above will trace: 110111101000.

So, let’s create a dummy class to do some tests:

package {

    public class BitwiseTest {

        public static const FLAG_1:uint = 1;
        public static const FLAG_2:uint = 2;
        public static const FLAG_3:uint = 4;
        public static const FLAG_4:uint = 8;
        public static const FLAG_5:uint = 16;
        public static const FLAG_6:uint = 32;

        public function BitwiseTest() {

            trace("BitwiseTest.FLAG_1: " + BitwiseTest.FLAG_1.toString(2));
            trace("BitwiseTest.FLAG_3: " + BitwiseTest.FLAG_3.toString(2));
            trace("BitwiseTest.FLAG_5: " + BitwiseTest.FLAG_5.toString(2));
            trace("BitwiseTest.FLAG_6: " + BitwiseTest.FLAG_6.toString(2));

            this.test(BitwiseTest.FLAG_1 | BitwiseTest.FLAG_3 | BitwiseTest.FLAG_5 | BitwiseTest.FLAG_6);

        }

        private function test(flags:uint):void {

            trace("flags: " + flags.toString(2));

        }

    }

}

The trace output will be:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 100
BitwiseTest.FLAG_5: 10000
BitwiseTest.FLAG_6: 100000
flags: 110101

To check for a specific flag’s presence inside flags argument, we can use the bitwise “and” operator (&):

if ((flags & BitwiseTest.FLAG_1) > 0) {

    trace("BitwiseTest.FLAG_1 passed - (" + String(flags & BitwiseTest.FLAG_1) + ")");

}

By using the & operator on flags it will returns the flag’s value if passed to the method and 0 otherwise. By updating the test method in this manner:

private function test(flags:uint):void {

    trace("flags: " + flags.toString(2));

    if ((flags & BitwiseTest.FLAG_1) > 0) {

        trace("BitwiseTest.FLAG_1 passed - (" + String(flags & BitwiseTest.FLAG_1) + ")");

    }

    if ((flags & BitwiseTest.FLAG_2) > 0) {

        trace("BitwiseTest.FLAG_2 passed - (" + String(flags & BitwiseTest.FLAG_2) + ")");

    }

    if ((flags & BitwiseTest.FLAG_3) > 0) {

        trace("BitwiseTest.FLAG_3 passed - (" + String(flags & BitwiseTest.FLAG_3) + ")");

    }

    if ((flags & BitwiseTest.FLAG_4) > 0) {

        trace("BitwiseTest.FLAG_4 passed - (" + String(flags & BitwiseTest.FLAG_4) + ")");

    }

    if ((flags & BitwiseTest.FLAG_5) > 0) {

        trace("BitwiseTest.FLAG_5 passed - (" + String(flags & BitwiseTest.FLAG_5) + ")");

    }

    if ((flags & BitwiseTest.FLAG_6) > 0) {

        trace("BitwiseTest.FLAG_6 passed - (" + String(flags & BitwiseTest.FLAG_6) + ")");

    }		

}

We will obtain this output:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 100
BitwiseTest.FLAG_5: 10000
BitwiseTest.FLAG_6: 100000
flags: 110101
BitwiseTest.FLAG_1 passed - (1)
BitwiseTest.FLAG_3 passed - (4)
BitwiseTest.FLAG_5 passed - (16)
BitwiseTest.FLAG_6 passed - (32)

We have successfully “intercepted” what flags has been passed to the method.
Is important to know that flag’s values can’t be progressive numbers, but they must be multiples of 2, otherwise when using the bitwise “or” operator we will obtain a “ones overlap” resulting in an entity we won’t be able to properly manage. If we replace the flags values used in the previous example in this way:

public static const FLAG_1:uint = 1;
public static const FLAG_2:uint = 2;
public static const FLAG_3:uint = 3;
public static const FLAG_4:uint = 4;
public static const FLAG_5:uint = 5;
public static const FLAG_6:uint = 6;

We will get the following output:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 11
BitwiseTest.FLAG_5: 101
BitwiseTest.FLAG_6: 110
flags: 111
BitwiseTest.FLAG_1 passed - (1)
BitwiseTest.FLAG_2 passed - (2)
BitwiseTest.FLAG_3 passed - (3)
BitwiseTest.FLAG_4 passed - (4)
BitwiseTest.FLAG_5 passed - (5)
BitwiseTest.FLAG_6 passed - (6)

As we can see our test method is unable to understand what flags it has received due to “ones overlap” (looks at te first 5 lines).

In conclusion… using bitwise operators for flags are pretty simple, however bitwise operators can do much more but understanding the real power of these operators and how to properly use them is not so easy (at least to me :-))

Fundamentally there are two ways to realize custom Flex’s components: one (and the easiest) is to create an MXML file, the second is to create an Actionscript class.

MXML component

The MXML file will contains a components like a Canvas (which is an excellent class to start to build on) as the root node, instead of the classic Application and it will be filled by others several small components already available in Flex (Label, TextField, Button…), realizing a new complex object which can will be used inside MXML Applications by simply writing a tag with the same name of the MXML file. Another step required is to create an XML name space for the custom component created, this can be accomplished simply by insert an xmlns attribute inside the Application node, similarly to the default mx name space from adobe (xmlns:mx=”http://www.adobe.com/2006/mxml“), it must report a name after the colons and a path to the package containing the component. This is an example of a name space declaration for my own custom tag:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:dz="com.daveoncode.controls.*" layout="vertical">

It creates a name space called “dz” for all the classes (the “*” wildcard means “all”) inside the package “com/daveoncode/controls”. This is instead how a simple MXML based component could be (this is only a basic example, a such component is pretty useless):

<?xml version="1.0" encoding="utf-8"?>
<mx:Panel xmlns:mx="http://www.adobe.com/2006/mxml" title="Login" width="400" height="300">
    <mx:Form>

        <mx:FormItem label="UserName:">
            <mx:TextInput width="200" />
        </mx:FormItem>

        <mx:FormItem label="Password:">
            <mx:TextInput width="200" displayAsPassword="true" />
        </mx:FormItem>

        <mx:FormItem>
            <mx:Button label="Login" />
        </mx:FormItem>

    </mx:Form>
</mx:Panel>

Now, supposing that we save the example above as LoginPanel.mxml, under “com/oursite/components”, we can use it in a mxml Application in this way:

<mx:Application xmlns:cc="com.oursite.components.*" xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <cc:LoginPanel />
...

This is pretty cool, because lets us separate defined areas of a GUI (like a login panel) and reuse them everywhere with no efforts… although this is an useful thing, is not so much exciting as creating a real custom component (something that is not made of other existent Flex components), whit its own properties, methods and style support!
To create such object, we should write it entirely in Actionscript.

Actionscript component

We can start from extending an existent Flex class, in order to inherit all the necessary methods to interact properly with the framework. The most important thing to know, is how to handle our class configuration, in fact in Flex we can’t put configuration logic inside constructor, because it will be automatically called by Flex every time a tag with the components name is encountered and there is no way to pass arguments to the constructor from the MXML tag, so such approach:

public function MyCustomComponent(param1:String, param2:Number) {

    this.param1 = param1;
    this.param2 = param2;

}

cant’ be used! We have instead to write getter and setter which will be automatically called by Flex when required. This kind of getter/setter must use Actionscript’s get and set keywords, in order to get/set a property. So, we have to forget classic getter/setter methods like:

public function setMyParam(value:String):void {
    myParam = value;
}

public function getMyParam():String {
    return myParam;
}

and adopt these:

public function set myParam(value:String):void {
    myParam = value;
}

public function get myParam():String {
    return myParam;
}

The get/set key is a really cool feature of Actionscript language, because it lets to set an object property in a declarative manner (myObject.property = X), without renunce to encapsulation. In this way when in MXML file we will declare tag’s attributes:

<cc:MyCustomComponent myParam="Hello!" /> 

Those setters will be used… but when exactly? Good question, another thing to understand, in order to realize custom and good components, is in fact the creational procedure adopted by the framework, which is divisible in these steps (in execution order):

1. Construction: in this step the component is instantiated and code inside the constructor is executed (typically the code will consist of a calling to super() and optionally event listeners configuration and few more)
2. Configuration: getters methods are invoked by Flex to configure class’ instance
3. Attachment: this step occours only when the component is added to the display list. This is an automatic task if the component is called from an MXML (with the relative tag) and occours through Actionscript when addChild() or addChildAt() are invoked
4. Initialization: this is the most intense phase, because during initialization a lot of tasks are performed and several methods invoked. The first thing that happens is the dispatching of preinitialize event (FlexEvent.PREINITIALIZE), then the protected method createChildren() is called (we have to override this method in order to populate our custom components with desired content), after its execution another event is dispatched, this time is the initialize (FlexEvent.INITIALIZE). After these, a series of invalidations and validations operations occours and finally creationcomplete is dispatched (FlexEvent.CREATION_COMPLETE)

I realized a custom component called StarPicker, it is a control which can be used to rate objects (songs,  movies, books…) by selecting (with a click) among N stars (N is one of the several parameters that can be configurated by the user, such color, size, space between stars and so on),  it is bindable (we can bind another control to StarPicker’s value) and finally it support CSS styles… yes, with Flex we can create extreme custom components that will support custom user-defined properties (such “power”, “coolness”…). Although I’m quite embarrassed (because I’m not already so confident with Flex), I’m going to show you how I realized my first Flex component.

My first step was create an Actionscript class (under my package “com.daveoncode.controls”) which extends Canvas, then I defined several public constants for default settings, by using the Flex naming convenction “DEFAULT_MY_SETTING_NAME”, several private variable to handle settings values and as many private variables to track settings changes. So, before the constructor I’ve such stuff (every prameter has 3 types of variables/constants related to it):

public static const DEFAULT_STARS:uint = 5;
// ...more constants

private var _stars:uint;
// ...more vars

private var starsDefined:Boolean;
// ...more booleans

The constructor contains a call to super and some listeners creation (and I enable the doubleclick over the component):

public function StarPicker() {

    super();

    // This component allows double click in order to deselect stars
    this.doubleClickEnabled = true;

    // Listens for preinitialize event
    this.addEventListener(FlexEvent.PREINITIALIZE, this.preInitializeHandler);

    // Listens for the click event over the stars
    this.addEventListener(MouseEvent.CLICK, this.clickHandler);

    // Listens for the double click event over the stars
    this.addEventListener(MouseEvent.DOUBLE_CLICK, this.doubleClickHandler);

}

The only thing I want to analize in the code above is the listener for FlexEvent.PREINITIALIZE… why I used this listener? The answer is: I use it to set default values if they are not provided by the user (with user I mean who use the component in the MXML file, not the Application’s user), because I want to handle default settings only after all the setters are called by Flex in order to set properly the boolean flags “myparamDefined”, which I use to grant the right precedence between style and inline tag’s attribute. If a flag is setted (myparamDefined == true) then when CSS assign a value to the same parameter this is not used, because inline attribute have the precedence and win. So the handler has several ternary operators like:

this._stars = this._stars == 0 ? StarPicker.DEFAULT_STARS : this._stars;

In order to populate the picker with stars I override  createChildren() method, into which I use addChild() to insert N Star object (which is a Class in the same package, which basically draws a star shape and has methods to change colors and size), I also override  measure() method which is used by Flex to know the exact size of the components (typycally when it must calculates clipping and resizing):

override protected function measure():void {

    super.measure();

    // StarPicker's height will be the same as the stars
    this.measuredHeight = this.measuredMinHeight = this._starSize + this._starBorderSize;

    // StarPicker's width will be the same as the sum of the stars width + space
    this.measuredWidth = this.measuredMinWidth = (this._starSize + this._starSpace) * this._stars;

}

In practice I’m telling Flex that my component should be never clipped and is larger as the sum of the stars width it contains. Oh… I also override the styleChanged() method, which is called by Flex every time a component’s style parameter changes:

override public function styleChanged(styleProp:String):void {

    super.styleChanged(styleProp);

    this._stars = this.stars;
    // ... other (re)settings

}

And style metatags? Yes, I putted them before class declaration:

[Style(name="stars", type="uint", inherit="no")]
// ... more styles

With style metatag we can declare the name of styles properties that our components will suport, so with the previous declaration will be possible to create CSS like:

.myCustomComponent {
    stars: 4;
}

Ok, I wrote too much, this is an example of the custom component that I realized (you can download, use and view source code by selecting “Flex components” on blog’s menu):

The example above is not a screenshot… you can test it ;-)

1. Initialize an ArrayCollection and then use its addItem() method (which accepts any Object type)
2. Initialize an ArrayCollection, access its “embedded” Array by using the source property (ie: myArrayCollection.source) an then push objects inside this one
3. Initialize an Array, populate it and then initialize an ArrayCollection by passing the Array to its constructor (ie: myArrayCollection:ArrayCollection = new ArrayCollection(myPreviousDefinedArray))

Last technique is (as far I saw) absolutely the fastest , I did a test in which I populated a collection with 300,000 objects and it taken about 9 seconds instead of 32 (350% slower) of first one! The second technique is also faster than the first, but the third is better.

So, what I learned is that addItem() should used only to add few items, instead for huge collection should be avoided in favor of the third technique described in order to obtain better performances.

How it works?

First we have to create a new array (arr2) which will contains the elements from the base ordered array (arr), then we use a while loop, which can be translated into english as: “do this until base array is not empty”. Inside the loop, we push into the second array a random element from the first array and, at the same time, we remove that element from its array. Array’s method splice() in fact, removes one or more elements from an array and returns an array containing the deleted elements, that in our case is only one (as specified in the second argument). The first argument of the method represent the starting index from which to start to delete, this is dynamically calculated by using the Math.random() method (which returns a number between 0 and 1), then multiplied by the length of the base array minus 1, because array length is always 1 greater than elements array contains (cause array indexing starts from zero), finally this number is rounded to the nearest integer by Math.round(), in order to access an exact index.

I think this is the best and shorter way to implement a shuffle functionality :)

package {

    public class MyClass {

        private var myVar:uint;

        public function MyClass(myVar:uint) {

            this.myVar = myVar;

        }

    }

}

However there are 3 valid reasons to (always) use  the “this” keyword:

1. Is an excellent way to visually differentiate between static and dynamic variable (static variables can’t use the “this” keyword, otherwise you get a compile error)
2. When invoking methods is immediately evident which is the class owner/target of the method itself
3. Faster typing and developing thanks to Flex Builder hints (after typing “this.”, I can select all the applicable methods, which is faster and error free than type the entire method name)