The following example is found in the text_nodes_and_strings.fla source file and begins with the explicit creation of an XML instance called las3Data, in lines 1 through 15.

1    var las3Data:XML = <book>
2                          <publisher name="O'Reilly"/>
3                          <title>Learning ActionScript 3.0</title>
4                          <subject>ActionScript</subject>
5                          <authors>
6                             <author>
7                                <firstname>Rich</firstname>
8                                <lastname>Shupe</lastname>
9                          </author>
10                         <author>
11                            <firstname>Zevan</firstname>
12                            <lastname>Rosser</lastname>
13                         </author>
14                         </authors>
15                       </book>;
16
17    trace("- name of title node:", las3Data.title.name());
18    //- name of title node: title
19
20    trace("- data returned from title node:", las3Data.title);
21    //- data returned from title node: Learning ActionScript 3.0
22
23    var txtFld:TextField = new TextField();
24    txtFld.width = 300;
25    txtFld.text = las3Data.title;
26    addChild(txtFld);

Now take a look at line 17. This illustrates a simple example of working with a node object by using the name() method to return the node’s name. The rest of the segment demonstrates working with data returned when querying a node. Line 20 traces the value to the Output panel, and lines 23 through 26 show a text field populated with the String returned.

Line 28 in the following code block further demonstrates the difference between these two concepts by showing that the title node, itself, is still an element node. Like an element node, a text node is also XML and can be accessed using the text() method shown in line 31. This, too, will return a String for your convenience, but line 34 shows that the node itself is a text node.

27    //node kind
28    trace("- kind of title node:", las3Data.title.nodeKind());
29    //- kind of title node: element
30
31    trace("- text node child of title:", las3Data.title.text());
32    //- text node child of title: Learning ActionScript 3.0
33
34    trace("- kind of text node:", las3Data.title.text().nodeKind());
35    //- kind of text node: text

var fruit:Array = ["apple", "orange"];
fruit.push("banana");
trace(fruit.push("grape"));
//4

When your goal is to work with text, you are most likely to use the String data returned when querying a text node or an element node that contains text. However, it’s occasionally convenient to work with the text node instead because it’s still XML. For example, you can use XML syntax to collect all occurrences of a particular node in an XML object. This is accomplished with the XMLList class, the real heart of E4X. We’ll demonstrate the power of this class using element nodes.

An XMLList instance is a list of all occurrences of a node at the same hierarchical level in the XML object—even if there is only one of those nodes. Let’s start right away by pointing out that all XML nodes are of the XMLList data type. The following example is found in the element_nodes_and_xmllist.fla source file, and lines 1 through 15 again create a basic instance of the XML class. Lines 17 and 20 show that both element and text nodes are typed as XMLList.

1    var las3Data:XML = <book>
2                          <publisher name="O'Reilly"/>
3                          <title>Learning ActionScript 3.0</title>
4                          <subject>ActionScript</subject>
5                          <authors>
6                             <author>
7                                <firstname>Rich</firstname>
8                                <lastname>Shupe</lastname>
9                             </author>
10                            <author>
11                               <firstname>Zevan</firstname>
12                               <lastname>Rosser</lastname>
13                            </author>
14                         </authors>
15                      </book>;
16
17    trace("- XMLList element node:", las3Data.title is XMLList);
18    //- XMLList element node: true
19
20    trace("- XMLList text node:", las3Data.title.text() is XMLList);
21    //- XMLList text node: true

Now let’s take a closer look at how wonderful XMLList can be. First, you can isolate a segment of your XML object to make it easier to parse. Lines 23 and 24 show that you can place a subset of las3Data into an XMLList instance (<authors>, in this case).

22    //isolation of XML subset
23    var authors:XMLList = las3Data.authors;
24    trace("- authors:
" + authors);
25    /*- authors:
26    <authors>
27      <author>
28        <firstname>Rich</firstname>
29        <lastname>Shupe</lastname>
30    </author>
31    <author>
32        <firstname>Zevan</firstname>
33        <lastname>Rosser</lastname>
34        </author>
35    </authors>
36    */

But that’s just the beginning. What XMLList excels at is pulling together all occurrences of a node at the same hierarchical level. We’ll first show this at work by collecting both <author> nodes within the <authors> node.

37    //collecting siblings into an XMLList instance
38    trace("- author:
" + las3Data.authors.author);
39    /*- author:
40    <author>
41       <firstname>Rich</firstname>
42       <lastname>Shupe</lastname>
43    </author>
44    <author>
45       <firstname>Zevan</firstname>
46       <lastname>Rosser</lastname>
47    </author>
48    */

Note that line 38 references simply <author>, but two of these nodes are returned, evidenced by the trace() output. This is XMLList collecting the relevant nodes for you. If an additional <author> node appeared on another level, perhaps as a parent, child, or grandchild, it would not be included.

Collecting siblings for you is great, because you don’t have to loop through the siblings and build an array yourself. Using XMLList, for example, you could automatically generate a list of all sibling news items from an XML news feed. What’s really great, however, is that XMLList will traverse nodes for you to collect all nodes at the same hierarchical level. Continuing the news feed example, you could collect all headline nodes from each parent news node.

Using our book example, line 50 of the following script collects both <firstname> nodes, even though they are in separate <author> parent nodes. Furthermore, you can use bracket syntax to retrieve specific data from the list. For example, line 56 retrieves only the first <firstname> node.

49    //collecting nodes at the same level into an XMLList instance
50    trace("- firstname:
" + las3Data.authors.author.firstname);
51    /*- firstname:
52    <firstname>Rich</firstname>
53    <firstname>Zevan</firstname
54    */
55
56    trace("- firstname[0]:
", las3Data.authors.author.firstname[0]);
57    //- firstname[0]: Rich

Two more powerful tools make traversing XML and XMLList instances easier: the descendant accessor operator and the wildcard. The descendant accessor operator is a pair of dots (..) and allows you to query a node or nodes in any hierarchical level at or below the specified node, without using a complete path to that element. This is convenient for retrieving deeply nested nodes, as long as no other nodes bear the same name. (Again, this would probably be bad XML design, and all nodes of the same name would be collected.) The following is an alternate way to retrieve only the <firstname> nodes that reside within separate parent nodes, anywhere in the las3Data instance.

58    //descendant accessor operator
59    trace("- ..firstname:
" + las3Data..firstname);
60    /*- ..firstname:
61    <firstname>Rich</firstname>
62    <firstname>Zevan</firstname>
63    */

The wildcard is an asterisk (*) that allows you to include every node at one hierarchical level. The following will retrieve both <firstname> and <lastname> nodes, even traversing multiple parent nodes.

64    //wildcard operator
65    trace("- author.*:
" + las3Data.authors.author.*);
66    /*- author.*:
67    <firstname>Rich</firstname>
68    <lastname>Shupe</lastname>
69    <firstname>Zevan</firstname>
70    <lastname>Rosser</lastname>
71    */

Finally, on a related note, using a method to retrieve all nodes of a specified type can also be used to retrieve element nodes with illegal names. This is seen in line 24 of the following code, which has been appended to the xml_attributes.fla source file for side-by-side comparison.

Note, however, that there is an inconsistency here. The attributes() (plural) method collects all attributes in a given scope, while the attribute(), (singular) method is used to query a single attribute. The elements() (plural) method, however, is used for both purposes.

1    //querying node names illegal in AS3
2    trace("- elements(name):", example.elements("modified-date"));
3    //- elements(name): 20100829

Another important thing to know about the aforementioned @ versus attribute() choice is that filtering content using @ works only if all of the queried elements have the attribute. Note, in the following example, found in the xml_attributes_filtering_issue.fla source file, that one of the element nodes is missing the price attribute. Matching nodes using @price will generate an error, but using attribute("price") will not.

1    var catalog:XML = <stock>
2                         <product name="one" price="100" />
3                         <product name="two" price="200" />
4                         <product name="three" />
5                         <product name="four" price="100" />
6                      </stock>;
7
8    //trace(catalog.product.(@price == 100));
9    //error
10
11    trace(catalog.product.(attribute("price") == 100));

This example is nearly identical to the load_xml.fla source file discussed in the preceding Loading External XML Documents section. All we need to do is substitute the following eight lines of code for line 7 of that example. These lines both create XML to send, and customize the URLRequest instance to send data, as well as load it.

Lines 7 through 9 create the XML object to send to the server. Like ActionScript, our PHP script does not require the XML declaration tag in line 7 but, for maximum flexibility, it’s not a bad idea to prepend this to any XML you send to a server. You may find that it’s required in a future configuration of your project and, since it makes no difference in ActionScript, there’s no good reason not to include it.

Lines 11 through 14 create a URLRequest instance for submitting the data. Note that you’ll need to put the correct path to your server in line 11. As discussed in Chapter 13, line 12 assigns the outgoing XML to the data property of the request, and lines 13 and 14 specify “text/xml” as the contentType, and POST as the method, of the request object, respectively.

7    var str:String = "<?xml version='1.0' encoding='utf-8'?>";
8    str += "<value>Sent from ActionScript</value>";
9    var xmlToSend:XML = new XML(str);
10
11    var req:URLRequest = new URLRequest("save_xml.php");
12    req.data = xmlToSend;
13    req.contentType = "text/xml";
14    req.method = URLRequestMethod.POST;

The next code block is the server-side PHP script. This is the server destination of your simple XML data and, as specified in line 11 of the ActionScript code, should be called save_xml.php. The script first checks to be sure POST data has been received (line 3), and then populates the $data variable with that data (line 4). In lines 6 through 8, it creates and opens for writing a file called data.txt, writes the data to the file, and then closes the open file instance. Lastly, it checks to make sure the file was written successfully and sends a simple XML object back to ActionScript.

If successful, you’ll see the message “File saved.” in the text field. If not, you’ll see “Server unable to create file.” There may be a permissions issue on the server preventing write access to the directory in which the PHP script has been placed, for example, or another error preventing file creation.

1    <?php
2
3    if (isset($GLOBALS["HTTP_RAW_POST_DATA"])){
4        $data = $GLOBALS["HTTP_RAW_POST_DATA"];
5
6        $file = fopen("data.txt", "wb");
7        fwrite($file, $data);
8        fclose($file);
9
10        if (!$file) {
11            echo("<stuff>Server unable to create file.</stuff>");
12        } else {
13            echo("<stuff>File saved.</stuff>");
14        }
15    }
16
17    ?>

You can look at the XML document any time, but the following excerpt is representative of the data:

<nav>
    <menus>
        <button label="MOTION">
            <project label="flocking" path="projects/motion/worm.swf">
              Flocking with Zeno's paradox
            </project>
            <project label="point at" path="projects/motion/point.swf">
              Pointing at the mouse position
            </project>
        </button>
    </menus>
</nav>

The root node, <nav>, has a child node, <menus>, which contains the data for all menus. Each menu is delineated by a <button> node, which corresponds to the main menu button. This node has a label attribute, which holds the text used for the main menu button text label.

Within each <button> node are multiple child nodes called <project> (two are shown in the excerpt for brevity). Collectively, these make up the submenu for each menu. Each <project> node corresponds with one button in the submenu, and has an attribute called label. This is used to populate the text label of the submenu button. It also has a path attribute, used to load the corresponding content, and a text node, which we’ll use in Chapter 15 to display a brief blurb about the loaded asset.

The document class is pretty straightforward. It loads the XML data, creates a SafeLoader for loading content and a mask for masking the content to an area below the menus, and initializes the menus.

Lines 1 through 10 declare the package and import required classes, including SafeLoader, and two custom classes, CustomURLLoader and NavigationBarXML. Line 12 declares the class, including extending MovieClip so it can easily be used as a document class. Finally, lines 14 through 16 create three private properties for the CustomURLLoder, XML, and SafeLoader instances, respectively.

1    package {
2
3        import flash.display.Graphics;
4        import flash.display.MovieClip;
5        import flash.events.Event;
6        import flash.filters.DropShadowFilter;
7        import flash.net.URLRequest;
8        import fl.display.SafeLoader;
9        import com.learningactionscript3.loading.CustomURLLoader;
10        import com.learningactionscript3.ui.NavigationBarXML;
11
12        public class LAS3Main extends MovieClip {
13
14            private var _menuLdr:CustomURLLoader;
15            private var _xml:XML;
16            private var _loader:SafeLoader;

The class constructor occupies lines 18 through 22 and creates an instance of the CustomURLLoader class to load the external data. Discussed in Chapter 13, this class does all the loading work for us and dispatches an Event.COMPLETE event when the loading is finished. Line 20 adds an event listener to trap this event and call onLoadXML().

Once the XML is loaded, the onLoadXML() method uses a try..catch block to attempt to parse the XML. It retrieves the data from the data property of the CustomURLLoader instance and tries to instantiate an XML object using that data (line 26). If successful, it calls the initLoader() and initMenus() methods (lines 27 and 28, respectively). If the data can’t be parsed as XML, it traces an error (lines 30 and 31).

17            //constructor and xml load
18            public function LAS3Main() {
19                _menuLdr = new LoadURL("data/nav.xml");
20                _menuLdr.addEventListener(Event.COMPLETE, onLoadXML,
21                                          false, 0, true);
22            }
23
24            private function onLoadXML(evt:Event):void {
25                try {
26                _xml = new XML(_menuLdr.data);
27                initLoader();
28                initMenus();
29            } catch (err:TypeError) {
30                trace("Can't parse loaded content as XML:",
31                    err.message);
32            }
33        }

The initLoader() method creates an instance of the SafeLoader class (line 36), positions it below the future location of the menus (line 37), and adds it to the display list (line 38). It also draws a 750 × 450 pixel movie clip (lines 40 through 44), adjusts its y position to 100, the same location as the SafeLoader instance (line 45), and uses it to mask the loaded content (line 46).

34        //loader and mask
35        private function initLoader():void {
36            _loader = new SafeLoader();
37            _loader.y = 100;
38            this.addChild(_loader);
39
40            var loaderMask:MovieClip = new MovieClip();
41            var g:Graphics = loaderMask.graphics;
42            g.beginFill(0x000000, 1);
43            g.drawRect(0, 0, 750, 450);
44            g.endFill();
45            loaderMask.y = 100;
46            _loader.mask = loaderMask;
47        }

The initMenus() method creates an instance of the NavigationBarXML class (lines 50 and 51) and adds it to the display list (line 52). In doing so, it passes the scope of the document class into the constructor, as well as the <menus> XMLList. This makes all of the menu XML data available to the class so it can create the necessary buttons. The method also creates a DropShadowFilter instance (line 54), sets its alpha to 25 percent, and adds it to the _navBar instance. This will give the entire menu system, including the submenus that appear interactively, a drop shadow.

48            //navigation menu bar
49            private function initMenus():void {
50                var _navBar:NavigationBarXML =
51                    new NavigationBarXML(this, _xml.menus);
52                this.addChild(_navBar);
53
54                var ds:DropShadowFilter = new DropShadowFilter();
55                ds.alpha = 0.25;
56                _navBar.filters = [ds];
57            }
58
59            public function get assetLoader():SafeLoader {
60                return _loader;
61            }
62        }
63    }

Finally, a getter is provided to return the SafeLoader instance when required. Despite not processing the information returned, a getter is used here instead of a public property because the value should be read-only. By contrast, we’ll use public properties later on in the MenuButtonSub class, to give you more experience with both approaches to controlling information access in classes. For more information, see the Encapsulation section in Chapter 6.

The NavigationBarXML class is the longest class in the project, and the real workhorse. Although its functionality isn’t particularly complex, a little more detail is warranted to cover some of its inner workings.

Lines 1 through 15 declare the package and import the necessary classes. In this case, note that three TweenLite classes that we haven’t discussed before are imported: TweenPlugin, ColorTransformPlugin, and VisiblePlugin. We’ll discuss those when we go over the constructor. Also, note that MenuButtonMain and MenuButtonSub are imported. It’s in this class that we’ll be using both button types.

Line 17 declares the class and extends MovieClip so the navigation bar instance inherits the accessible properties and methods of the MovieClip class. Lines 19 through 21 create three private properties, preventing access from outside the class. The first property (line 19) will hold an instance of the document class (remember that it extended MovieClip, as well) passed into the constructor during instantiation. This will allow us to get the SafeLoader instance when one of the menu buttons needs to load content.

The second property (line 20) will hold an XMLList of all the button data loaded in the document class—also passed into the constructor during instantiation. The last property (line 21) will contain the currently active submenu when the user rolls his or her mouse over a menu button. This will allow us to reference the same menu in another method when the user rolls the mouse away and we must hide the menu.

1    package com.learningactionscript3.ui {
2
3        import flash.display.Graphics;
4        import flash.display.MovieClip;
5        import flash.events.Event;
6        import flash.events.MouseEvent;
7        import flash.geom.Matrix;
8        import flash.net.URLRequest;
9        import flash.text.TextField;
10        import com.greensock.TweenLite;
11        import com.greensock.plugins.TweenPlugin;
12        import com.greensock.plugins.VisiblePlugin;
13        import com.greensock.plugins.ColorTransformPlugin;
14        import com.learningactionscript3.ui.MenuButtonMain;
15        import com.learningactionscript3.ui.MenuButtonSub;
16
17        public class NavigationBarXML extends MovieClip {
18
19        private var _app:MovieClip;
20        private var _navData:XMLList;
21        private var _subMenu:MovieClip;

The class constructor occupies lines 23 through 41. It accepts two arguments: the movie clip in which the navigation bar was instantiated (to allow us to get a reference to the SafeLoader instance), and the button data loaded from XML. This information is immediately stored in the aforementioned private properties, in lines 25 and 26, so we can use the references in multiple methods within the class.

Line 28 calls the addMenus() function, which builds the menu system and which we’ll discuss in just a moment. Lines 30 through 37 dynamically draw the thick black line that serves as the lower bound of the main menu tabs. This improves upon the original version of the menu system in Chapter 6, which used a symbol for this purpose, because the code can easily be altered without having to create new artwork in the FLA.

The last two lines in the constructor activate the TweenLite plugins. The TweenLite tweening package is kept staggeringly small by only integrating the bare animation essentials. It doesn’t skimp on bells and whistles, however, because it allows you to add individual features as needed by activating plugins. This project uses two TweenLite plugins: VisiblePlugin, which turns an asset invisible after a tween, and ColorTransformPlugin, which allows us to tween color values. The uses of both plugins will be explained in context. This is a one-time process. Once the plugins are activated, their features will be available throughout your SWF, and any SWFs loaded from the same domain.

22        //constructor
23        public function NavigationBarXML(app:MovieClip,
24                                     navData:XMLList) {
25            _app = app;
26            _navData = navData;
27
28            addMenus();
29
30            var line:MovieClip = new MovieClip();
31            var g:Graphics = line.graphics;
32            g.beginFill(0x000000);
33            g.drawRect(0, 0, _app.stage.stageWidth, 4);
34            g.endFill();
35            line.y = 100;
36            line.mouseEnabled = false;
37            this.addChild(line);
38
39            TweenPlugin.activate([VisiblePlugin]);
40            TweenPlugin.activate([ColorTransformPlugin]);
41        }

The addMenus() method is the workhorse of this class, and it’s responsible for parsing the XML data, instantiating each main menu button, creating their submenus, and instantiating all submenu buttons. Line 44 uses the XML length() method to determine how many main menu buttons are included in the XML. (The project source XML contains five menus.)

The remainder of the function is inside a loop that iterates five times, once for every menu. Line 46 starts the process by excerpting only the XML relevant to the current menu. Lines 49 through 59 then initialize the main menu button. Lines 49 and 50 create a MenuButtonMain instance, passing the label attribute from the XML into the class constructor to create the button’s text label.

Line 51 positions the button horizontally, beginning at 20 pixels and then offsetting a distance equivalent to the buttons width and a 2-pixel space, for each button in the loop. As the button is 120 pixels wide, this means the first button is placed at an x position of 20 pixels (20 + 0 * (120 + 2)), the second at 142 (20 + 1 * (120 + 2)), and so on. Line 52 positions each button at a y coordinate of 75.

Lines 53 through 58 create two event listeners, one for the MOUSE_OVER event and another for the MOUSE_OUT event. When these events occur, they call the methods starting at lines 83 and 90, respectively. We’ll discuss these methods in a few minutes. Finally, line 59 adds each main menu button to the display list.

42        //building the menus
43        private function addMenus():void {
44            var mainButtonLength:uint = _navData.button.length();
45            for (var i:int; i < mainButtonLength; i++) {
46                var buttonXML:XML = _navData.button[i];
47
48                //main button
49                var mainBtn:MovieClip =
50                    new MenuButtonMain(buttonXML.@label);
51                mainBtn.x = 20 + i * (mainBtn.width + 2);
52                mainBtn.y = 75;
53                mainBtn.addEventListener(MouseEvent.MOUSE_OVER,
54                                         onMainBtnOver,
55                                         false, 0, true);
56                mainBtn.addEventListener(MouseEvent.MOUSE_OUT,
57                                         onMainBtnOut,
58                                         false, 0, true);
59                this.addChild(mainBtn);

Still within the primary loop that iterates once for each main menu button, lines 61 through 64 create the subMenu MovieClip instance to hold all submenu buttons. The submenu is added as a child to the main button (line 64), so their locations start out at the same point. In line 62, the submenu’s y coordinate is set to the bottom of the main button (using the button’s height plus a 2-pixel margin to account for the black line that will lay on top of the navigation bar).

Line 67 next determines the number of project nodes in the current menu. This will determine how many submenu buttons are required. Lines 68 through 79 make up a loop that iterates once for every submenu button. Line 69 parses the current project node from the parent menu XML data.

var buttonXML:XML = _navData.button[i];

var projectNode:XML = buttonXML.project[j];

Lines 70 and 71 create an instance of the MenuButtonSub class, passing the label attribute of the <project> node into the constructor to serve as the button’s text label. Line 72 sets the button’s public property projectPath to the path attribute of the project, and Line 73 sets the button’s public property projectDescription to the text within the <project> node.

Lines 75 through 77 add an event listener for the CLICK event so the submenu button will load the asset at the path associated with the button. Note that no other mouse event listeners are created. The ROLL_OVER and ROLL_OUT behavior of the button is cosmetic and is not customizable, so we’ll build it in the MenuButtonSub class.

The last line of the loop, line 78, adds the button to the submenu.

60                //sub menu
61                var subMenu:MovieClip = new MovieClip();
62                subMenu.y = mainBtn.height + 2;
63                subMenu.visible = false;
64                mainBtn.addChild(subMenu);
65
66                //sub buttons
67                var subButtonLength:uint = buttonXML.project.length();
68                for (var j:int = 0; j < subButtonLength; j++) {
69                    var projectNode:XML = buttonXML.project[j];
70                    var subButton:MovieClip =
71                        new MenuButtonSub(projectNode.@label);
72                    subButton.projectPath = projectNode.@path;
73                    subButton.projectDescription = projectNode;
74                    subButton.y = ((subButton.height) * j);
75                    subButton.addEventListener(MouseEvent.CLICK,
76                                               onSubBtnClick,
77                                               false, 0, true);
78                    subMenu.addChild(subButton);
79                }
80            }
81        }

Called each time the main menu button is rolled over, the onMainBtnOver() method shows the submenu. Line 84 first determines which button was rolled over by checking the currentTarget property of the event. Next, the button must show its submenu. Because the main menu button contains both a sprite background and a text field (explained in the next section), line 85 references the submenu by querying the third child of the button. Line 86 sets the visibility of the menu to true, and then line 87 uses TweenLite to fade from an alpha of 0 (transparent) to 1 (opaque), in one-quarter of a second.

Rolling off the main menu button calls the onMainBtnOut() method so we can again hide the menu. The first line of the method uses the relatedObject property of mouse events to determine if the mouse has rolled onto anything but a submenu button. We don’t want to hide the menu if one of its buttons is in use. If that’s not the case, the submenu’s visible property is set to true so you can see the submenu when it fades in. TweenLite is used to fade the submenu up to an alpha of 1 over one-quarter second.

Also, the visibility of the menu is set to false using TweenLite’s VisiblePlugin. When the visible property of the TweenLite object is set to false, this plugin automatically sets the visibility of the target to false after the tween is complete. In other words, the menu fades out and then becomes invisible. This is vital to the success of the menu because we can’t rely solely on alpha to hide our menus.

Despite being transparent, display objects with an alpha value of 0 can still receive mouse events. If we just faded the submenu out, rolling the mouse over its prior location would cause it to fade back into view without ever going near its main menu button. Instead, the menus must be invisible because invisible assets won’t respond to mouse events. So, the menus must start as invisible, become visible but tween their alpha property from 0 to 1 when rolled over, tween their alpha back to 0 and become invisible again upon mouse out.

_subMenu.visible = false;

82        //menu button mouse roll behavior: appearance
83        private function onMainBtnOver(evt:MouseEvent):void {
84            var mainBtn:MovieClip = MovieClip(evt.currentTarget);
85            _subMenu = mainBtn.getChildAt(2);
86            _subMenu.visible = true;
87            TweenLite.to(_subMenu, 0.25, {alpha:1});
88        }
89
90        private function onMainBtnOut(evt:MouseEvent):void {
91            if (!(evt.relatedObject is MenuButtonSub)) {
92                TweenLite.to(_subMenu, 0.25, {alpha:0, visible:false});
93            }
94        }

The last method in the class is called when a submenu button is clicked. Line 97 determines which button was clicked and retrieves the values from its public properties projectPath and projectDescription. The path is used to load the content associated with that button, and the description (included here only as an example) might be used to show information about the asset in a caption field, if you thought it necessary.

Line 100 or 101 will unload any content from the SafeLoader instance (retrieved from the document class assetLoader getter), depending on which platform you’re targeting. As discussed in Chapter 13, unloadAndStop() is preferable because it closes all sound and video streams, stops all timers, and removes all relevant listeners, so the asset can be properly unloaded. This method, however, requires Flash Player 10 or later. If you must target Flash Player 9, you must use the unload() method and take all necessary steps yourself to close open streams, stop timers, and remove listeners within the loaded asset. After any content is unloaded, line 102 then loads the content at the path contained in the local path variable.

95            //menu button click behavior: loading
96            private function onSubBtnClick(evt:MouseEvent):void {
97                var subBtn:MovieClip = MovieClip(evt.target);
98                var path:String = subBtn.projectPath;
99                var description:String = subBtn.projectDescription;
100                //_app.assetLoader.unload(); //FP 9
101                _app.assetLoader.unloadAndStop(); //FP 10
102                _app.assetLoader.load(new URLRequest(path));
103            }
104        }
105    }

This actually concludes the main functionality of the navigation bar, including the XML loading and parsing, and the content loading triggered by using the system. However, we must still discuss the classes that create the main menu buttons and submenu buttons.

The MenuButtonMain class works hand in hand with the corresponding movie clip symbol in the main FLA’s Library. The movie clip contains artwork resembling a tab, and a linkage class of com.learningactionscript3.ui.MenuButtonMain. This class resides in that location and creates the button’s text field and text format.

Lines 1 through 8 declare the package and import the required classes. Line 10 declares the class and extends MovieClip to work with the aforementioned symbol. Line 12 opens the class constructor, and receives a String as its only argument to serve as the text label for the button. It has a default value of an empty String, so an instance of the class can still be created even without passing in any text.

Line 13 sets the buttonMode property of the button to true, so the cursor will change from a pointer to a finger when rolling over the button.

Lines 15 through 22 initialize the button’s text field, and lines 24 through 31 initialize and apply a text format. Much of this is self-explanatory, but a few things are worthy of note. Lines 17 and 18 set the width and height of the text field to fill the button. This exposes the possibility that the button will cease working because the text field will trap incoming mouse events. To prevent this, line 21 disables mouse interaction with the field.

Also of note, line 19 sets the field to use embedded fonts, allowing us to use the font symbols in the library of the FLA. Line 24 instantiates the ArialBold symbol, line 26 ensures that we’re using the embedded font, and, finally, line 31 applies the text format using the setTextFormat() method, after the text has been added to the field.

1    package com.learningactionscript3.ui {
2
3        import flash.display.MovieClip;
4        import flash.text.Font;
5        import flash.text.TextField;
6        import flash.text.TextFieldAutoSize;
7        import flash.text.TextFormat;
8        import flash.text.TextFormatAlign;
9
10        public class MenuButtonMain extends MovieClip {
11
12            public function MenuButtonMain(labl:String="") {
13                this.buttonMode = true;
14
15                var btnLabel:TextField = new TextField();
16                btnLabel.y = 5;
17                btnLabel.width = this.width;
18                btnLabel.height = 20;
19                btnLabel.embedFonts = true;
20                btnLabel.text = labl;
21                btnLabel.mouseEnabled = false;
22                this.addChild(btnLabel);
23
24                var btnFont:Font = new ArialBold();
25                var labelFormat:TextFormat = new TextFormat();
26                labelFormat.font = btnFont.fontName;
27                labelFormat.size = 12;
28                labelFormat.bold = true;
29                labelFormat.color = 0xFFFFFF;
30                labelFormat.align = TextFormatAlign.CENTER;
31                btnLabel.setTextFormat(labelFormat);
32            }
33        }
34    }

The MenuButtonSub class is responsible for creating a submenu button and controlling only its appearance when the mouse rolls over or out of the button. The click behavior is controlled from the NavigationBarXML class. This makes the button more flexible and reusable. It also uses two public properties to store the path and description of the asset the button will load.

Lines 1 through 13 declare the class package and import the required classes, including TweenLite. Line 15 declares the class and extends MovieClip to inherit its accessible properties and methods. Lines 17 through 19 declare the class properties. Note that both projectPath and projectDescription are public, meaning they can be both set and retrieved from outside the class. As a result, no getter or setter is used.

1    package com.learningactionscript3.ui {
2
3        import flash.display.GradientType;
4        import flash.display.Graphics;
5        import flash.display.MovieClip;
6        import flash.display.Sprite;
7        import flash.events.MouseEvent;
8        import flash.geom.Matrix;
9        import flash.text.Font;
10        import flash.text.TextField;
11        import flash.text.TextFormat;
12        import flash.text.TextFormatAlign;
13        import com.greensock.TweenLite;
14
15        public class MenuButtonSub extends MovieClip {
16
17            private var _background:Sprite;
18            public var projectPath:String;
19            public var projectDescription:String;

Lines 21 through 30 contain the class constructor. The String that will serve as the button label is passed into the constructor, and the argument uses an empty String as a default value so the button can still be instantiated even without text input. Lines 22 and 23 call functions to draw the button’s background and create its text label, both of which we’ll look at in a moment. (Note that the String passed into the constructor is passed on to the addTextLabel() method.)

Line 24 disables mouse interaction with the button’s children. This is not only an alternative to disabling mouse interaction directly on the text field (as seen in MenuButtonMain class); it also disables interaction with the background sprite. Finally, lines 26 through 29 add event listeners for mouse roll over and roll out events.

20            //constructor
21            public function MenuButtonSub(labl:String="") {
22                addBackground();
23                addTextLabel(labl);
24                this.mouseChildren = false;
25
26                this.addEventListener(MouseEvent.ROLL_OVER,
27                                      onOver, false, 0, true);
28                this.addEventListener(MouseEvent.ROLL_OUT,
29                                      onOut, false, 0, true);
30                }

The addBackgound() method in lines 32 through 43, create the button’s background sprite using the gradient fill technique discussed in Chapter 8. The colors used in the gradient both have alpha values of 80 percent, making the buttons translucent. The addTextLabel() method receives the button’s label String from the constructor, and uses the same technique seen in the MenuButtonMain class to create and format a text field.

31            //background and text label
32            private function addBackground():void {
33                _background = new Sprite();
34                var g:Graphics = _background.graphics;
35                var matrix:Matrix = new Matrix();
36                matrix.createGradientBox(120, 25, deg2rad(90));
37                g.beginGradientFill(GradientType.LINEAR,
38                                    [0x64788C, 0x2C4054],
39                                    [0.8, 0.8], [0, 255], matrix);
40                g.drawRect(0, 0, 120, 25);
41                g.endFill();
42                addChild(_background);
43            }
44
45            private function addTextLabel(btnLabelText:String):void {
46                var btnLabel:TextField = new TextField();
47                btnLabel.x = btnLabel.y = 2;
48                btnLabel.width = this.width;
49                btnLabel.height = 20;
50                btnLabel.embedFonts = true;
51                btnLabel.text = btnLabelText;
52                this.addChild(btnLabel);
53
54                var btnFont:Font = new ArialRegular();
55                var labelFormat:TextFormat = new TextFormat();
56                labelFormat.font = btnFont.fontName;
57                labelFormat.size = 12;
58                labelFormat.color = 0xDDDDEE;
59                labelFormat.align = TextFormatAlign.LEFT;
60                btnLabel.setTextFormat(labelFormat);
61            }

Although the actions invoked by a button click are invoked from the NavigationBarXML class, each MenuButtonSub instance updates its own appearance based on mouse interaction. Specifically, TweenLite is used to tint the button a slate blue using TweenLite’s ColorTransformPlugin (activated earlier in the NavigationBarXML class). When rolling over the button with the mouse, TweenLite changes the tint from 0 to 100 percent, tinting it blue. When rolling off the button, the tint changes from 100 to 0 percent.

62            //submenu button mouse behavior
63            private function onOver(evt:MouseEvent):void {
64                TweenLite.to(_background, 0.3, {colorTransform:
65                             {tint:0x223355, tintAmount:1}});
66            }
67
68            private function onOut(evt:MouseEvent):void {
69                TweenLite.to(_background, 0.3, {colorTransform:
70                             {tint:0x334466, tintAmount:0}});
71            }
72
73            private function deg2rad(deg:Number):Number {
74                return deg * (Math.PI/180);
75            }
76        }
77    }

Finally, the deg2rad() method in lines 73 through 75 supports the createGradientBox() method in line 36, allowing us to convert degrees to radians so we can rotate the gradient.

When you tie it all together, you end up with Figure 14-1. The document class creates the loader, loader mask, and navigation bar, and loads the XML. The NavigationBarXML class instantiates each MenuButtonMain instance, submenu, and MenuButtonSub instance based on the XML data. It also sets the click behavior of the submenu buttons to load content into the SafeLoader instance in the document class. The result is that new content is loaded every time the user clicks a submenu button.

Figure 14-1. A simple navigation system that loads button properties from an external XML file

This simple navigation system brings a lot of power to a project because it allows you to quickly and easily change the main and submenu button names, modify project descriptions, and update what’s loaded from each button—all by configuring an external XML file. In other words, you don’t have to edit and republish the SWF every time you want to make a change.