ASTRA Aquarium Documentation

The Aquarium uses all ASTRA 1.0 Components, i.e. Tree, Menu, TabBar, AutoComplete, and Charts in a fun application. As such it shows how to integrate these components in a real application and how to customize these components for special use.

Highlights:

Custom skins for Buttons, TabBar, and Tree
Tree with custom CellRenderer featuring additional interaction and animation
AutoComplete integration with Tree by expanding the Tree via actionscript
Using Charts to display statistics

Structure

Flash File

The application has three main modes:

Aquarium	Add Fish	Settings

The different modes of the application are layed out on the time line.

Each component is added at the appropriate point on a layer. Actions for setting up the components (e.g. dataProviders, eventListeners) are kept on one layer. For example, the Menu component is added on it's own layer at frame "start", AutoComplete is added on its own layer starting at frame label "add Fish" etc. Except for the Menu, all components are dragged on stage and initialized through ActionScript in the main Flash file. We will comment on each component below. Please refer to the actions layer for taking a closer look at how we initialize each component.

Class Files

Apart from the initialization of the components we created a class hierarchy and separate class files for our aquarium to keep things organized. The class files used in this example are:

FishTank: This is our document class and can be seen as the main controller of the application
KineticObject: An abstract base class for moveable objects based on a physics model
Fish: Our main object we are adding and animating in our aquarium. It extends KineticObject
PhysicsModel: This class handles the 2D physics calculations used by our fish
FishCellRenderer: Our custom cellRenderer for the Tree to display our fish in the tree cells.
FishEvent: A custom event to propagate the addFish-event from our cellRenderer to the Tree.

Components

This is a very much standard use here: We are using ActionScript to create Menu as well as set it's position and with/height. A simple XML as dataprovider is used and an event listener defined that tints the frontGlass object of the aquarium to achieve the desired effect. Note that we also specify the icons for the menu entries as part of the XML. A Button is used to show the menu (see layer actions at frame label "start").

//----------------------------------------- // add menu button event handler modeButton.addEventListener(MouseEvent.CLICK, onButtonClick); function onButtonClick(event:MouseEvent):void { myMenu.show(); } //----------------------------------------- //XML to populate the control var dpMenu:XML = <root> <menuitem label="Fish tank mode" enabled="false" /> <menuitem label="daytime " icon="daytimeIcon" /> <menuitem label="nightime " icon="nighttimeIcon"/> </root>; //----------------------------------------- // create the menu and its settings // var myMenu:Menu = Menu.createMenu(this, dpMenu ); myMenu.x = 5; myMenu.y = 137; myMenu.width = 100; myMenu.height = 100; // add the event listeners myMenu.addEventListener(MenuEvent.ITEM_CLICK, onItemClicked);

TabBar

The TabBar is also used in a simple way. We initialize it with the label fields as well as the frame label to jump to when a tab is clicked. Note, that the same changeHandler function can be used when switching TabBars between "add Fish" and "settings" modes in our application. We also modified the skin - by copying the assets and assigning the new skins - to give the tabs some transparency and a different shape.

myTabBar.dataProvider = new DataProvider( [ {label:"Add Fish", frameLabel:"add", data:1}, {label:"Statistics", frameLabel:"stats", data:2} ] ) ; myTabBar.selectedIndex = 0; myTabBar.addEventListener( Event.CHANGE, tabBarChangeHandler ); myTabBar.setRendererStyle("upSkin", newTab_upSkin); myTabBar.setRendererStyle("overSkin", newTab_overSkin); myTabBar.setRendererStyle("downSkin", newTab_downSkin); myTabBar.setRendererStyle("selectedUpSkin", newTab_selectedUpSkin);

Tree

For Tree we define a simple XML dataprovider that lists all of our Fish. We also set a custom CellRenderer and define an eventListener for our custom Event "addFish" which the FishCellRenderer will create. The handler will then call the addFish Function from the document class (FishTank). Note that the cellRenderer does not have access to that class so creating this custom event allows this message to be passed. The Tree also has a customized skin, again by copying the assets and assigning the modied skins to the tree instance, i.e. adding rounded corners for background and cells, modify cell colors, modify the plus and minus icons.

var dp:XML = <node label="Root node"> <node label = "Domestic Fish"> <node label = "Goldfish"></node> </node> <node label = "Tropical Fish"> <node label = "Small Fish"> <node label = "Clownfish"></node> <node label = "Cute Fish" iconName="Cutefish"></node> <node label = "Butterflyfish"></node> </node> <node label = "Blue Fish"> <node label = "Moorish Idol" iconName="MoorishIdol"></node> <node label = "Snapper"></node> </node> <node label = "Fun Fish"> <node label = "Porcupinefish"></node> <node label = "Wahoo"></node> </node> </node> <node label = "Big Fish"> <node label = "Shark"></node> <node label = "Swordfish"></node> </node> </node> myTree.dataProvider = new TreeDataProvider(dp); myTree.setStyle("cellRenderer", FishCellRenderer); myTree.addEventListener("addFish", handleFishEvent); myTree.setRendererStyle("closedBranchIcon", newTreeCellRenderer_closedBranchIcon); myTree.setRendererStyle("openBranchIcon", newTreeCellRenderer_openBranchIcon); myTree.setRendererStyle("leafIcon", newTreeCellRenderer_leafIcon); myTree.setRendererStyle("upSkin", newTreeCellRenderer_upSkin); myTree.setRendererStyle("overSkin", newTreeCellRenderer_overSkin); myTree.setRendererStyle("downSkin", newTreeCellRenderer_downSkin); myTree.setRendererStyle("selectedUpSkin", newTreeCellRenderer_selectedUpSkin); myTree.setRendererStyle("selectedOverSkin", newTreeCellRenderer_selectedOverSkin); myTree.setRendererStyle("selectedDownSkin", newTreeCellRenderer_selectedDownSkin);

AutoComplete

We didn't want to create a separate dataprovider for AutoComplete in case we would modify our fish hierarchy or would add anything to it. Hence, we wrote a conversion function "parseTreeToLabelArry()" that creates the an array of the leaf-node labels and is used to initialize a new dataprovider for AutoComplete.

//-------------------------------- // set the autoComplete dataProvider var allFish:Array = []; var treeArray:Array = myTree.dataProvider.toArray(); parseTreeToLabelArray(treeArray, allFish); autoComplete.dataProvider = new DataProvider(allFish); // set the event listeners autoComplete.addEventListener(MouseEvent.CLICK, onClick); autoComplete.addEventListener(KeyboardEvent.KEY_DOWN, onEnterPressed); mySearchButton.addEventListener(MouseEvent.CLICK, onSearchButtonClicked); //-------------------------------- function parseTreeToLabelArray(data:Array, labelData:Array){ var n = data.length ; for ( var i:int = 0; i < n; i++ ) { var obj = data[i] ; if ( obj.nodeType == "branchNode" ) { parseTreeToLabelArray(obj.nodeChildren, labelData); } else if (obj.nodeType == "leafNode") { labelData[labelData.length] = obj.label; } else trace ("error on: " + obj.nodeType ); } }

There are three ways to expand the Tree to display the fish from AutoComplete: 1) Clicking on a proposed Fish from the Autocomplete Menu, 2) pressing Enter on in the Autocomplete field or menu, or 3) clicking on the "Fish Search" button. For each we need to do slightly different things. When clicking the button we also need to make sure we are displaying the Tree tab since we could be displaying the charts statistics when the button is clicked. Hence, we set the selectedIndex to "0". Once a fish is selected we would like to display the Tree in the appropriate expanded state. The Tree supplies a function exposeNode() and closeAllNodes() that makes this a simple task.

//-------------------------------- // expand Tree to specific Fish function select(name:String) { myTree.closeAllNodes(); var node:TNode = myTree.exposeNode("label", name); myTree.selectedItem = node; }

Charts

Charts in this example is very straight forward and mainly displays the current tally of fish in the tank. Note that it gets updated when you add a few fish and click back on the "Statistics" tab to display the chart again. The only small customization we did was creating a new toolTip function in order to display the toolTip on one line. In the future we like to add more visuals to charts and maybe showing the fish itself in the toolTip. One idea is to display the fishtype in the pieChart itself, however at the time of writing this would have required an extension to the Chart component itself.

// create new chart data myChart.data = []; myChart.categoryNames = []; var names:Array = new Array(); var nbFish:Array = new Array(); // initialize the data arrays (names, nbFish) for (var i:int = 0; i < fish.length; i++) { addType( fish[i].label.text ); } // set the chart data and categories myChart.data = nbFish; myChart.categoryNames = names; myChart.dataTipFunction = myDataTipFunction; //----------------------------------- // data tip function to render #fish and name on one line function myDataTipFunction(item:Object, index:int, series:ISeries):String { var n:Number = series.data[index]; var name:String = myChart.categoryNames[index]; return n + " " + name; }

Now that we described the main structure of the application and commented on how each of the ASTRA components has been integrated, let's now look at some more details of the FishCellRenderer and the PhysicsModel that we implemented:

Fish CellRenderer

This is probably the most complicated element of the entire application. We needed a custom CellRenderer in order to display the fish icons in the Tree. This gets achieved by choosing the right icon when the listData gets set. Here, for each fish name in the TreeDataprovider we have defined a corresponding symbol icon that we can retrieve through the getDefinitionByName() function.

// add the fish icon setStyle("icon", getDefinitionByName(fishName) );

We also need to size and position the icon in the drawLayout() function. Here we also position the "add" button that allows the user to actually add the fish. Note that we use the function setIconSize() to apply a heuristic for rescaling the fish sizes by keeping into account the limits of the cells. This way we still have differences in fish size but they all fit into the Tree cell.

//-------------------------------------------------------------------------- // normalize the size of the fish icon to displayable dimensions private function setIconSize(icon:Object) { var wMax = 50; var hMax = 17; var factorWidth:Number = Math.min(1, wMax/icon.width); var factorHeight:Number = Math.min(1, hMax/icon.height); var factor:Number = Math.min(factorWidth, factorHeight); icon.width *= factor; icon.height *= factor; } ... if ( data.nodeType == TreeDataProvider.LEAF_NODE ) { setIconSize(icon); // Add the "+add" button to cell addButton.x = width - 60; addButton.y = icon.y + 5; }

The last thing to do is adding the animation of the fish when the user clicks the add button. Here, we initiate a Tween and trigger our custom FishEvent "addFish" whenever the add button is pressed. This event gets then handled by the Tree.

//-------------------------------------------------------------------------- // Dispatches a FishEvent consumed by the Tree when the addButton gets clicked private function handleAddClick(ev:MouseEvent) { // set animation to true animate = true; // create and fire fishEvent (consumed by tree) var event:FishEvent = new FishEvent("addFish"); event.fishLabel = data.label ; listData.owner.dispatchEvent(event); }

However, due to the fact that the drawLayout() function is getting called immediately after a mouseUP event or when the user rolls-out of a cell, we do have to integrate the Tween into the drawLayout() function itself. So, when we "animate" we create a new Tween when none is current, hide fish, label, and add-button, and register a listener for the end of the Tween. Once the Tween finishes we re-display the fish icon, the label, and the add-button.

//-------------------------------------------------------------------------- // drawing the cell override protected function drawLayout():void { ... // play tween animation when add button has been clicked on if (animate) { // make elements invisible textField.visible = false; icon.visible = false; addButton.visible = false; // create a tween if not currently running if ( mytween == null || !mytween.isPlaying ) { // create icon for animation var fishName:String = data.iconName; if ( fishName == null ) { fishName = data.label; } var fishClass:Class = getDefinitionByName(fishName) as Class; animateFishIcon = new fishClass(); // set size and add to display list setIconSize(animateFishIcon); addChild(DisplayObject(animateFishIcon)); // start the animation, set event for end of animation mytween = new Tween(animateFishIcon, "x", Regular.easeInOut, icon.x, icon.x + 280, 1, true); mytween.addEventListener(TweenEvent.MOTION_FINISH, handleEndAnimation); } } // Size the background background.width = width; background.height = height; } //-------------------------------------------------------------------------- // Reset things to normal cell public function handleEndAnimation(event:TweenEvent) { animate = false; removeChild(DisplayObject(animateFishIcon)); // make elements visible again textField.visible = true; icon.visible = true; if ( mouseOnCell ) addButton.visible = true; }

Physics Model

For this example we implemented a simple force/acceleration model to animate the fish. We take into account that water has a drag coefficient and we create a repellent force with the wall coefficient. Each axis is handled separately for simplicity. Below we show the main function that calculates the forces at each frame:

//------------------------------------- // Calculate Friction and Boundary forces private function calcForces():Object { var force:Object = new Object(); // Drag force: Fd = c*v^2 // Gets larger the faster the object is moving (friction) var drag_ax:Number = - drag_coeff*speedx*speedx; if (speedx<0) { drag_ax = - drag_ax; } var drag_ay:Number = - drag_coeff*speedy*speedy; if (speedy < 0) { drag_ay = - drag_ay; } ... // calculatng repellent wall force: Fw = 1/max(1, (c*x)^2) ... // Calculate total acceleration force force.total_ax = ax*ax_mod + drag_ax + wall_ax; force.total_ay = ay*ay_mod + drag_ay + wall_ay; return (force); } }

A lot of additional things could be added here but we thought we leave this example very simple to highlight more the use of the components than sophisticated game physics. Adding some more animation to the fish (e.g. pedaling motion) and some more behaviors (less constant swimming speed) as well as interactivity on mouse-over would be fun to add at some time in the future.

credits:
application concept + implementation: michael hoch
tree component: allen rabinovich
menu + autocomplete components: alaric cole
charts + tabbar component: josh tynjala
interaction design: lucas pettinati
graphic design: stephan douris