Russ Back » Adobe Flex

Creating an image asset library

Russ — Thu, 27 Aug 2009 16:38:10 +0000

The problem

When you compile your Flex projects there will come a time when you realise that some classes just aren’t getting compiled into the bin-release folder, perhaps because you have some conditional ActionScript code that instantiates a class according to some logic and the Flex compiler assumes that your class isn’t required.

This is an annoying quirk of the compiler and there are a common workaround is to instantiate a ‘dummy’ instance of one of these uncompiled classes to ensure that it gets included. I prefer to avoid this by creating an external asset library that compiles into its own SWC library file as follows…

Creating a Library project

A Flex Library project can be created in the same way as any other project: just choose Flex Library Project in the New menu instead of Flex Project.

At first glance nothing has changed other than the icon in the Flex Navigator view (shown below) but the benefit of this approach will become apparent very shortly.

Create a Class

First we need to create at least one class. For this example I’ve chosen to use the excellent FamFamFam Silk Icon library – a collection of 700+ 16px x 16px images that are used for many online interfaces. For this article we’ll add all the icons from this library to our Flex Library Project and then expose two of them for use in an external application.

Import the assets

This is easy – just download the icon library, extract it and drag all of the images into the Library Project. For my example these live at /assets/images/famfamfam/silkicons/. They can live anywhere but this structure makes it easy it easy to add assets from other sources to our library.

Exposing the assets

For this example we just need two of the icons and to expose these we create a new class called IconLibrary (mine’s in the package com.russback). This is a straight-forward bindable class that has a public static constant of type Class for each of the assets we want to expose:

package com.russback
{
	/**
	 * Class containing constants for each icon image available for use in the application
	 */
	[Bindable]
	public final class IconLibrary
	{

		/**
		 * Displays the accept icon from the FamFamFam Silk Icons library
		 */
		[Embed(source="assets/images/famfamfam/silkicons/accept.png")]
		public static const ACCEPT:Class;

		/**
		 * Displays the bomb icon from the FamFamFam Silk Icons library
		 */
		[Embed(source="assets/images/famfamfam/silkicons/bomb.png")]
		public static const BOMB:Class;

		/**
		 * Constructor
		 */
		public function IconLibrary()
		{
		}

	}
}

Compiling the Library

Now all we need to do is compile the Library and this is where the benefit of using this approach kicks in. If you right-click on the Flex Library Project in the Flex Navigator view and choose Properties, you’ll get your compiler options. Click on Flex Library Build Path and you’ll see a view with a button bar (Classes, Assets, Source path, Library path). In the Classes view you can select which classes you want the compiler to compile into the library. The beauty of this is that you take control – the compiler will compile whatever you choose regardless of whether you’ve used the class anywhere so we go ahead and make sure our IconLibrary class gets included.

Next, click on the Assets button and make sure that all the images in the library are included. We could just include the two assets we’re exposing and that would create a very small SWC file but the great thing about SWC files is that only the classes and assets it references will get included in any release build (which paradoxically caused the initial problem we’re solving…). So as we only have two references to these assets (in our IconLibrary class) we know don’t need to worry about our SWC footprint.

I should at this point credit Ronald Ferguson for this as he has already walked this path and his free library works great. It has constants for every icon in the library; however this creates a large SWC file and with 700+ icons in the library, it’s hard to justify this footprint. The trade off is that every time you want to use an icon that’s not referenced in the IconLibrary class we need to go back to it and add a new constant.

I’ve used the Silk Icon library as an example here but you could easily extend this Library to include other image sets as required; the approach is exactly the same, just make sure that any new class you add to the Library project gets compiled by following the steps above.

Linking to the library in an external application

So we now have a library that by default will be compiled to a SWC file in the bin directory of our Library Project. To use that SWC library file in any other Flex Project we just need to reference it in each project as follows

Right-click on the project in the Flex Navigator view and choose Properties
Click on Flex Build Path and then hit the Library path button
Click the Add SWC… button and navigate to the SWC file your in your Library Project’s bin directory and hit Open
You should now have your SWC referenced as the screenshot below shows

Using the Library

Using the Library couldn’t be any easier: We simply bind the source property of an Image class to the constant in the Library that we want to use:

You can download and edit the source code for the example application and also the example Library, You can also right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

Using this method might seem like a pain at first but it keeps your code clean, your assets in one manageable location
, and you can say goodbye to those compiler problems.

One last note on compiler errors

Using this method you may find you get a compiler warning for each constant when you compile the Library, particularly if you compile documentation using Ant and asdoc.

There is nothing to worry about here; the compiler is simply telling you that you haven’t created an instance of the constant. If you want to get rid of these completely, you can add an additional line to the build.xml file used by Ant and your compiler will run happily silent:

Compiling documentation with Ant and asdoc

Russ — Fri, 21 Aug 2009 07:46:03 +0000

Documenting code for asdoc

Documenting your code for asdoc is easy and there’s plenty of help available on this and I’d suggest starting with the Flex help.

Installing Ant

You can run asdoc from the command line but I found it much easier to install Ant in Flex Builder, which is as simple as this:

In Flex Builder go to Help > Software Updates > Find and Install
Click on the option to Search for new features to install
Make sure The Eclipse Project Updates is selected and then hit Finish
Expand the tree Eclipse 3.3.2 or newer, select Eclipse Java Development Tools and install
Restart Flex Builder and then go to Window > Other Views
Expand the Ant directory, click on the Ant icon and hit OK
You should now have an Ant panel, though the position of it may vary according to your perspective settings (mine is alongside Console at the bottom)

Create a symbolic link to asdoc

A copy of asdoc lives in each SDK directory so if you’re using 3.3.0, you’ll find it at /Applications/Adobe Flex Builder 3/sdks/3.3.0/bin/asdoc. We’ll be using Ant to build our documentation and giving it the path to the asdocs progrm but asdoc has a problem with spaces in pathnames, which although not a problem on Windows, is a pain on Mac as the path above has spaces in it and attempting to use this in Ant throws an error. I first tried the approach in this excellent article but still had the same problem so instead I created a symbolic link (shortcut) to asdoc in my hard disc root.

You can do this in a number of ways, the easiest of which is perhaps using this little plugin.

Once you’ve created your symobolic link, name it something obvious with no funny characters. Mine is flex-sdk-330. When you click on this symbolic link in the Finder you’ll see the contents of the 3.3.0 directory and inside that, the bin directory and asdoc program. So far so good.

Create the Ant files

To compile our documentation we need an XML file called build.xml and a properties file called build.properties so we create these in the root of our Flex Project. If Ant has installed properly you’ll probably see a little Ant icon on your file.

The build.properties file

The properties file contains a set of values that the XML file will use.

We start with a reference to the symbolic link we created earlier.

# Path to SDK
SDK_PATH = /flex-sdk-330

Then we add something very important: the path to the Flash player we are using for this project. Setting the target player in Flex Builder will only tell the Flex compiler to target a specific player but Ant won’t know about that so if you’re targetting version 10, make sure you reference the version 10 player here.

One problem you may find if you don’t do this is you end up with compile errors. One that I got tripped up by was an error to do with the FileReference class. This was changed in Flash player 10 to include the ability to load files from the user’s environment without the need to load them to a server first. If you get errors to do with FileReference, make sure you have this set correctly.

# Path to target Flash Player library (relative to the SDK_PATH
PLAYER_PATH = /frameworks/libs/player/10/playerglobal.swc

The next property is where you reference any SWC library files your project uses. In the example I’m providing for download below I’m not including any so this is just blank:

# Paths to libraries to include
# LIBRARIES = ./libs/SomeLibrary.swc ./libs/SomeOtherLibrary.swc
LIBRARIES =

Next comes the path the the source files for the project, which are typically in the src directory:

# Source files
SOURCE = ./src

The next two settings are used for the documentation output – the TITLE appears in the title of the documents and the FOOTER text appears at the bottom of each page.

# Title for the documentation
TITLE = Compiling Documentation with Ant and asdoc

# Text to add to the footer of each page
FOOTER = Compiled using Ant and asdoc (build.xml and build.properties)

Finally we have a location to output our documentation to, in this case a directory called docs in the Flex Project:

# Output location
OUTPUT_PATH = ./docs

The build.xml file

Now we have our properties file we can go ahead and use them in our XML file. The properties file is referenced right at the outset and then we include a path to the flexTasks.jar file (note the properties throughout this file are called in as follows ${PROPERTY}).

Next we have our default Ant task which simply calls the two other tasks in the file Clean, and Build.

This is followed by a simple task that deletes the existing documentation if there is any:

	
		
		
		Clean task completed successfully

And finally the task that will build our documentation:

	
		
			
			
			
			
			
			
			
			
		
		Build taks completed successfully

Compile the documentation

Now everything is set up we simply need to drag the build.xml file onto the Ant panel and double-click on it or hit the Play button in the Ant panel.

If everything is set up correctly we should get a couple of confirmation messages in the Console panel and the documentation will be created in a /docs directory in the root of our Flex Project.

Download an example project

To see an example in action you can download and edit the source code here. This should work if you follow the steps above but obviously can be modified as required.

Disabling drag on an AdvancedDataGrid row

Russ — Tue, 18 Aug 2009 20:30:09 +0000

Drag and drop using an AdvancedDataGrid is just a case of setting a few properties (dragEnabled, dropEnabled are two of these) but this makes every row of your datagrid draggable, but what if you only want to enable the copy or move of particular items in the list?

In this article we’ll make this happen using a shop as an example. We’ll have a list of products that in the warehouse, and a list of products that are available to buy on the shop floor. To transfer stock from the warehouse to the store we’ll drag them and drop them from one list to the other but not everything in the warehouse is saleable – some of it has been recalled for safety reasons so we don’t want to be able to drag those.

So to start, we’ll set up a value object class for each of our products.

The Product value object

Nothing fancy here, just a name and availability properties and a couple of constants we use for the availability of each Product:

package com.russback.valueobjects
{
  /**
   * Value Object for a Product, containing a few basic properties
   */
  [Bindable]
  public class Product
  {

    /**
     * Used for Products currently available for sale
     */
    public static const AVAILABLE:String = "productAvailable";

    /**
     * Used for Products that have been recalled due to a fault
     */
    public static const RECALLED:String = "productRecalled";

    /**
     * Name of the Product
     * @default null
     */
    public var name:String;

    /**
     * Current availability status of this Product
     * @default AVAILABLE
     */
    public var availability:String = AVAILABLE;  

    /**
     * Constructor
     */
    public function Product()
    {
    }

  }
}

Extending the AdvancedDataGrid

Next we need somewhere to display each of Products and for this example I’m using the AdvancedDataGrid. This approach could equally apply to a List but the AdvancedDataGrid is something I tend to use time and again so I’m using this one here.

Our extended object is called ExtendedAdvancedDataGrid (pretty unimaginative to be fair) and it begins with the usual imports and a constructor that simply invokes the constructor of the super class:

package com.russback.extensions
{
  import com.russback.valueobjects.Product;

  import mx.controls.AdvancedDataGrid;
  import mx.core.DragSource;
  import mx.core.IUIComponent;
  import mx.events.DragEvent;
  import mx.managers.DragManager;

  /**
   * Extends the AdvancedDataGrid to allow for dragging of grid rows depending on data properties
   */
  public class ExtendedAdvancedDataGrid extends AdvancedDataGrid
  {

    /**
     * Constructor adds creation complete event listener
     */
    public function ExtendedAdvancedDataGrid()
    {
      super();
    }

Next we override the default dragStart() method of the super class. First we create a new Array object and then for each item the user has selected and dragged, we check if it’s availability property is AVAILABLE and if so, add it to our array.

Then if we have any data in our Array, we create a new DragSource object containing our array data and create a drag proxy that will indicate to the user which items are being dragged (we’ll look at this shortly). Finally we call the DragManager’s doDrag() method, passing it this as the drag initiator, our DragSource, event and drag proxy.

This approach allows you to select any row in the list but only those Products that are available will actually be added to the DragManager to move or copy.

    /**
     * Only adds product to the drag if they are available
     * Uses an instance of the CustomDragProxy class as it's drag proxy image
     */
    override protected function dragStartHandler(event:DragEvent):void
    {
      var dragData:Array = new Array();

      for each (var product:Product in this.selectedItems)
      {
        if (product.availability == Product.AVAILABLE)
        {
          dragData.push(product);
        }
      }

      if (dragData.length)
      {

        var dragSource:DragSource = new DragSource();
            dragSource.addData( dragData, "items" );

        var customDragProxy:ExtendedAdvancedDataGridDragProxy = new ExtendedAdvancedDataGridDragProxy();
            customDragProxy.owner = this;

        DragManager.doDrag(this as IUIComponent, dragSource, event, customDragProxy);

      }
    }

Our final two methods in this class override the dragDrop() and dragComplete() methods. The AdvancedDataGrid moves data from source and target objects out of the box but we typically don’t want to do this in a large application where a framework such as Cairngorm is in place, so all I’m doing here is effectively preventing that behaviour. In a real world application I’d fire events in this methods and then handle the data transfer in the controller but for this example we just have a couple of comments.

    /**
     * Custom drop behaviour. Prevents superclass' default behaviour
     */
    override protected function dragDropHandler(event:DragEvent):void
    {
      // custom code here to respond to a drop - firing an event to handle in an
      // MVC framework could be one example

      hideDropFeedback(event);
    }

    /**
     * Custom drag complete behaviour. Prevents superclass' default behaviour
     */
    override protected function dragCompleteHandler(event:DragEvent):void
    {
      // custom code here to respond to a completed drag - firing an event to handle in an
      // MVC framework could be one example
    }

  }
}

Creating a custom drag proxy

When you create your own dragStart() method and don’t define a drag proxy, Flex will visualise the drag by creating a box that matches the size of the drag source (ie the AdvancedDataGrid). This works fine but it doesn’t indicate which items are being dragged and this is important for us as although we can select all the items in our list, we can only drag the Products that are available and therefore we only want to see these in the drag proxy while we’re dragging.

So for this we have another class that extends the AdvancedDataGridDragProxy class. This starts with a few constants that will be used to configure the proxy. I’ve set these up as constants just to separate these display properties from the core logic so you could just as easily replace these with public variables that you set when you create a new instance of this class.

The proxy will be a VBox object containing an HBox for each Product in the dragged data. The constants we have are for the width and height of each row and also the X and Y offset which we’ll use to position the proxy in relation to the mouse cursor during the drag. The last part of this initial section of code is a private variable that we’ll use to hold the VBox and the constructor.

package com.russback.extensions
{
  import com.russback.valueobjects.Product;

  import mx.containers.HBox;
  import mx.containers.VBox;
  import mx.controls.AdvancedDataGrid;
  import mx.controls.Image;
  import mx.controls.Text;
  import mx.controls.advancedDataGridClasses.AdvancedDataGridDragProxy;
  import mx.core.ScrollPolicy;

  /**
   * Extends AdvancedDataGridDragProxy to display a proxy of the items that
   * the ExtendedAdvancedDataGrid has allowed to be dragged
   */
  public class ExtendedAdvancedDataGridDragProxy extends AdvancedDataGridDragProxy
  {

    /**
     * Width of each item in the proxy
     * @default 200
     */
    private static const ITEM_WIDTH:int = 200;

    /**
     * Height of each item in the proxy
     * @default 25
     */
    private static const ITEM_HEIGHT:int = 25;

    /**
     * Number of pixels to offset the proxy (against the mouse position) in the horizontal direction
     * @default -10
     */
    private static const MOUSE_X_OFFSET:int = -10;

    /**
     * Number of pixels to offset the proxy (against the mouse position) in the vertical direction
     * @default -10
     */
    private static const MOUSE_Y_OFFSET:int = -10;

    /**
     * VBox used as a wrapper for the items in the proxy
     * @default new VBox()
     */
    private var _vbox:VBox = new VBox();

    /**
     * Constructor
     */
    public function ExtendedAdvancedDataGridDragProxy()
    {
      super();
    }

Next we ovveride the createChildren() method of the super class to prevent the creation of that box object that the AdvanvedDataGridProxy class creates. First we create a reference to this proxy’s owner which will be an instance of our ExtendedAdvancedDataGrid class, and then we create a sorted array containing each selected item the user has selected.

Now we have this we can loop through each item and provided the Product is available, we call a method called createRowProxy which we’ll look at next. This method returns an HBox which we add to our VBox.

Finally we set the width and height of the VBox according to the number of rows we’ve created, add the VBox to the proxy and then position the proxy in relation to the mouse cursor. -10 for both X and Y constant values works nicely in this example but this is down to your design.

    /**
     * Grabs the selected items from the ExtendedAdvancedDataGrid, calls the createRowProxy()
     * method for each item that can be dragged and sets the proxy's position in line with
     * the current mouse position
     */
    override protected function createChildren():void
    {

      var grid:AdvancedDataGrid = this.owner as ExtendedAdvancedDataGrid;

      var products:Array = grid.selectedIndices;
          products.sort();

      for (var i:int = 0; i < products.length; i++)
      {
        var product:Product = grid.dataProvider[products[i]] as Product;

        if (product.availability == Product.AVAILABLE)
        {
          _vbox.addChild(createRowProxy(product));
        }
      }

      _vbox.width = ITEM_WIDTH;
      _vbox.height = _vbox.numChildren * ITEM_HEIGHT;
      _vbox.horizontalScrollPolicy = ScrollPolicy.OFF;
      _vbox.verticalScrollPolicy = ScrollPolicy.OFF;

      this.addChild(_vbox);

      this.x = grid.contentMouseX + MOUSE_X_OFFSET;
      this.y = grid.contentMouseY + MOUSE_Y_OFFSET;

    }

The final method in here is the createRowProxy() method which I mentioned above. Given a Product object, this creates an HBox containing an icon image and the name of the Product and returns the HBox. It's these HBoxes you will see when you drag data from our list.

    /**
     * Creates an HBox with an Image and text to act as a proxy for each row of
     * dragged data in the proxy object
     * @return An HBox
     */
    private function createRowProxy(product:Product):HBox
    {
      var hBox:HBox = new HBox();
          hBox.horizontalScrollPolicy = ScrollPolicy.OFF;
          hBox.verticalScrollPolicy = ScrollPolicy.OFF;

      var image:Image = new Image();
          image.source = "assets/images/package.png";

      var name:Text = new Text();
          name.text = product.name;

      hBox.addChild(image);
      hBox.addChild(name);

      return hBox;
    }

  }
}

An item renderer just for show

Before we go ahead and use our new classes, I've created an item renderer just to make the example clear. This is a straight-forward MXML component that extends HBox and shows an icon image and the name of the Product (very similar to our drag proxy we created, for obvious reasons). The only thing to note in here is that we use a move icon for the mouse cursor if you mouseover this object and the Product is draggable. This will indicate to the user that this item can be dragged.

Putting it all together

We now have all of our building blocks for the example so we dive into the MXML application. This a very simple application that has an ArrayCollection containing a set of Product objects, an instance of our ExtendedAdvancedDataGrid class, and then an out-of-the-box AdvancedDataGrid. I've included the latter just to demonstrate that you don't need a custom class as your target.

The first grid (our extended class) lists everything in our warehouse and uses our ProductRenderer component as the itemRenderer for it's only column. The second grid lists everything available in the shop (nothing initially) and has drop enabled.

Example in action

In the example below you can select multiple items in the warehouse list and drop them in the shop list and they'll be added to the shop list. The drag proxy for the drag should only show those items that are being dragged, which is not necessarily every item you selected before you started the drag.

You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

In this example we've prevented the dragDrop() and dragComplete() methods so the data doesn't get removed from the warehouse. We'd need to do some more work in our ExtendedAdvancedDataGrid class to do this as already discussed but I've not included that here in order to keep things simple. It's also possible to drag duplicate Products into the shop list, which is the default behaviour for the AdvancedDataGrid so again, we'd need to do some more work in this area to prevent dupes being added but hopefully this article provides enough information to start you on your road to customising your own drag and drop interfaces.

Hiding a Tab in a TabNavigator

Russ — Thu, 06 Aug 2009 12:56:50 +0000

You can easily disable a tab by disabling the associated child object in the TabNavigator, which is fair enough. So you might think that altering the child’s visibile and includeInLayout properties would impact the tab too, but it doesn’t and that’s because only the child that’s currently in view has its visible. The solution is simply to bind the visibility and includeInLayout properties to another property of the child. The enabled property is a good start but then you’re saying that all disabled elements are invisible, which you might not want. So we go with a custom property.

Create a custom property on the child

This is dead easy. The class below is simply a Box that has a public var added to it that defaults to true, and it’s this we’ll use for binding.

package com.russback
{
	import mx.containers.Box;

	public class ExtendedBox extends Box
	{

		/**
		 * Used for binding the visible and includeInLayout properties
		 * of the TabNavigator
		 */
		[Bindable]
		public var tabVisible:Boolean = true;

		/**
		 * Constructor
		 */
		public function ExtendedBox()
		{
			super();
		}

	}
}

Creating the Tab binding

All we need here is one method that creates the binding. We fire this method once the CREATION_COMPLETE FlexEvent has fird and it’s job is simply to bind the visibility and includeInLayout properties to the tabVisible variable we created in our custom Box:

package com.russback
{
	import flash.display.DisplayObject;

	import mx.binding.utils.BindingUtils;
	import mx.containers.TabNavigator;
	import mx.controls.Button;
	import mx.events.FlexEvent;

	public class ExtendedTabNavigator extends TabNavigator

	{

		/**
		 * Constructor adds event listener
		 */
		public function ExtendedTabNavigator()
		{
			super();
			addEventListener(FlexEvent.CREATION_COMPLETE, createTabBindings);
		}

		/**
		 * event handler binds each tab's visible and inludeInLayout properties to the
		 * custom "tabVisible" property of the related child
		 */
		private function createTabBindings(event:FlexEvent):void
		{
			for (var i:uint; i < childDescriptors.length; i++)
			{
				var tab:Button = getTabAt(i);
				var child:DisplayObject = getChildAt(i);

				BindingUtils.bindProperty(tab, "visible", child, "tabVisible");
				BindingUtils.bindProperty(tab, "includeInLayout", child, "tabVisible");
			}
		}

	}
}

Putting it all together

The MXML for this is simple. We simply create an instance of our ExtendedTabNavigator and populate it with some child objects, which are ExtendedBox objects. We can then set the visibility of each associated Tab by setting the tabVisible property on each.

The example below shows the four states you could have:

Enabled and tab visible
Enabled and tab hidden
Disabled and tab hidden
Disabled and tab visible

You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

Preventing click events on a Flex Accordion header

Russ — Fri, 31 Jul 2009 10:07:43 +0000

Flex takes care of switching the views in an Accordion when you click on the bars of the Accordion, but what if you want to detect that user activity and do something else? Maybe you want to disable the navigation if a form inside one of the accordion children has failed validation, or you want a user to confirm they don’t want to save the changes they’ve made in that form.

Below are two examples to achieve this. For both examples, we’ll simply enable and disable each item in the Accordion, which will enable or disable the navigation of the Accordion as appropiate.

Understanding the Accordion

Both of these examples make use of the Accordion’s headerRenderer class to achieve what we’re looking for. The default for an Accordion is a Button class and as Button is a subclass of Container, we know that it has a property called data which is a reference to the related object. In the case of the Accordion that related object is the child object you add to the Accordion. In other words if you add one VBox to an Accordion, that VBox is referenced in the data property of the header bar that appears in the Accordion.

A common way to disable a view is to set the enabled property to false, so what we’ll doing in both examples is setting the enabled property of each child object of the Accordion and our headerRenderer will follow suit. To test this I’ve created a little class just to toggle the enabled property of an object on click:

package com.russback.examples
{
	import flash.events.MouseEvent;

	import mx.controls.Button;
	import mx.core.Container;

	public class ExampleButtonControl extends Button
	{

		/**
		 * Target container linked to this ExampleButtonControl
		 */
		public var target:Container;

		/**
		 * Constructor
		 */
		public function ExampleButtonControl()
		{
			super();
		}

		/**
		 * Toggles the enabled property of the target Container
		 */
		override protected function clickHandler(event:MouseEvent):void
		{
			super.clickHandler(event);

			target.enabled = ! target.enabled;
		}

	}
}

Example 1: using BindingUtils

The first example is simple: we just need to bind the enabled property of each header to the related Accordion child so we have a class that extends the Button control. This overrides the default createChildren() method to bind the enabled property of the Button to the enabled property of it’s data object:

package com.russback
{
	import flash.events.MouseEvent;

	import mx.binding.utils.BindingUtils;
	import mx.controls.Button;

	public class BoundAccordionHeader extends Button
	{
		/**
		 * Constructor
		 */
		public function BoundAccordionHeader()
		{
			super();
		}

		/**
		 * Overrides default createChild() method
		 * Binds the enabled property to the data's enabled property
		 */
		override protected function createChildren():void
		{
			super.createChildren();

			BindingUtils.bindProperty(this, "enabled", data, "enabled");
		}

	}
}

Example 1 in action

The MXML for this couldn’t be simpler. We simply create an Accordion and set it’s headerRenderer property to be our BoundAccordionHeader class. The only other objects in this example are three of our ExampleButtonControl objects that simply toggle the enabled state of each child in the Accordion. Job done.

You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

Example 2: Events

Example 1 is great if you just need a simple binding but what if you need to handle those changes to the enabled property? This next example uses a custom event class to enable you to handle events at the Accordion level. A use for this might be to have the Accordion enabled but only to allow navigation in certain circumstances, such as if a form in one of the child objects has been validated successfully.

A custom event

For this example I’ve created a custom event, called AccordionHeaderEvent. This is a simple extension of the Event class that has a static constant for the event type and a container property. We’ll fire one of these events each time an Accordion child changes it’s enabled property and use the event’s container property to hold a reference to the child object involved.

package com.russback.events
{
	import flash.events.Event;

	import mx.core.Container;

	public class AccordionHeaderEvent extends Event
	{

		/**
		 * Event types
		 */
		public static const UPDATE_HEADER:String = "accordionHeaderEventUpdateHeader";

		/**
		 * Container object associated with this event
		 * NB event bubbles and can be cancelled
		 */
		public var container:Container;

		/**
		 * Constructor sets this event's container property
		 */
		public function AccordionHeaderEvent(type:String, container:Container, bubbles:Boolean=true, cancelable:Boolean=true)
		{
			super(type, bubbles, cancelable);
			this.container = container;
		}

	}
}

Custom headerRenderer component

This is a simple class that only has three methods. The first is the obligatory constructor that just invokes the super class, the next is an override of the createChildren() method that sets the enabled property of the button according to the enabled property of the button’s data property. This data property is assigned by the Accordion class and is a reference to the child object in the Accordion (a VBox for example).

package com.russback.extensions
{
	import com.russback.events.AccordionHeaderEvent;

	import flash.events.MouseEvent;

	import mx.controls.Button;

	public class StateEnabledAccordionHeader extends Button
	{
		/**
		 * Constructor
		 */
		public function StateEnabledAccordionHeader()
		{
			super();
		}

		/**
		 * Sets the enabled property according to the data's enabled property
		 */
		override protected function createChildren():void
		{
			super.createChildren();

			if (data.enabled is Boolean)
			{
				enabled = data.enabled;
			}
		}

Next we override the clickHandler() method. All we do here is stop the event from bubbling if the button has been disabled. And that’s it for this example.

		/**
		 * Prevents the CLICK MouseEvent propogating if this object is disabled
		 */
		override protected function clickHandler(event:MouseEvent):void
		{
			if (! enabled)
			{
				event.stopImmediatePropagation();
			}
		}

	}
}

This is enough to disable an Accordion item when it creates, but we should really extend this further so that we can enable and disable each item according to user behaviour or data values. For this we need to look at the child objects we’re going to add to the Accordion.

Child objects of the Accordion

For this example I’m just using three VBox objects but this approach applies to any class that extends the Container class. For now I’ve just created a custom class that extends VBox, called ExampleAccordionChild and it just has one override function.

package com.russback.examples
{
	import com.russback.events.AccordionHeaderEvent;

	import mx.containers.VBox;
	import mx.core.Container;

	public class ExampleAccordionChild extends VBox
	{
		/**
		 * Constructor
		 */
		public function ExampleAccordionChild()
		{
			super();
		}

		/**
		 * Fires an UPDATE_HEADER AccordionHeaderEvent after setting the enabled property,
		 * passing this class as the event's container property
		 */
		override public function set enabled(value:Boolean):void
		{
			super.enabled = value;

			var accordionHeaderEvent:AccordionHeaderEvent = new AccordionHeaderEvent(AccordionHeaderEvent.UPDATE_HEADER, this as Container);
			dispatchEvent(accordionHeaderEvent);
		}

	}
}

After the constructor we override the enabled() setter function to fire a new AccordionHeaderEvent with itself as the container argument. This will fire an event every time the enabled property of this object is changed and as our event is set to bubble, we’ll be able to capture this in the Accordion, which we can look at now.

The custom Accordion component

I’ve created an extension of the Accordion classs called StateEnabledAccordion. The constructor sets the headerRenderer property for the Accordion by setting up a new ClassFactory object which has the StateEnabledAccordionHeader class as it’s argument, and adds an event listener for the custom event we’ve created.

package com.russback.extensions
{
	import com.russback.events.AccordionHeaderEvent;

	import flash.display.DisplayObject;

	import mx.containers.Accordion;
	import mx.controls.Alert;
	import mx.core.ClassFactory;

	public class StateEnabledAccordion extends Accordion
	{

		/**
		 * Constructor adds headerRenderer and event listener
		 */
		public function StateEnabledAccordion()
		{
			super();

			headerRenderer = new ClassFactory(StateEnabledAccordionHeader);
			addEventListener(AccordionHeaderEvent.UPDATE_HEADER, accordionHeaderEventHandler);
		}

Then we have our event handler function that handles an UPDATE_HEADER AccordionHeaderEvent by using the container reference in the event to locate the child object that fired the event. We then get the Accordion’s header object for that child, set its enabled property, and cancel the event as we don’t need it to bubble any further. I’ve also added an Alert here just to demonstrate the fact that you can work with this here to do whatever you want.

		/**
		 * Event handler sets the enabled property of the header element associated
		 * with the event container object, and stops the event from bubbling further
		 */
		private function accordionHeaderEventHandler(event:AccordionHeaderEvent):void
		{
			var childIndex:int = getChildIndex(event.container);

			var child:DisplayObject = getChildAt(childIndex);
			Alert.show("Received from " + child, "AccordionHeaderEvent.UPDATE_HEADER received");

			getHeaderAt(childIndex).enabled = event.container.enabled;
			event.stopImmediatePropagation();

		}

	}
}

Example 2 in action

Creating the custom Accordion for this excample isn’t much more complex that exampl 1. We just create a new StateEnabledAccordion which contains as many ExampleAccordionChild child objects as we need. This method relies on having the child objects fire an event whenever their enabled property changes so you’d need to make sure you add that override to any child object you use.

You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

Creating a strongly typed ArrayCollection

Russ — Fri, 24 Jul 2009 08:04:16 +0000

The scenario

The ArrayCollection class’ addItem(), addItemAt(), getItem() and getItemAt() methods accept/return a generic Object which is great because we can use if for storing pretty much anything. But there is no way to ensure that the ArrayCollection only contains a specific class of Object, or to return an Object cast as a specific class.

Typically you just get your Object out of the ArrayCollection, cast it as the class you know it belongs to, and then carry on. But when you’re doing this over and over again it makes sense to override the get and add methods to work with specific Object classes.

Example data

To start with we need some data and for this example we have a number of ‘products’ to work with. So for this we have a simple Product Value Object with name and price properties:

package valueobjects
{
  public class Product
  {
    public var name:String;
    public var price:Number;

    /**
    * Constructor function sets up this Product object
     */
    public function Product(name:String, price:Number):void
    {
      this.name = name;
      this.price = price;
    }

  }

}

The strongly-typed ArrayCollection (ProductArrayCollection.as)

Next we need our new ArrayCollection class – which I’ve called ProductArrayCollection for this example – that extends the base ArrayCollection class:

package extensions
{
  import mx.collections.ArrayCollection;
  import valueobjects.Product; 

  public final class ProductArrayCollection extends ArrayCollection
  {

    /**
     * Private property used to prevent direct use of addItem and addItemAt methods
     */
    private var _itemOk:Boolean = false;

    /**
     * Constructor function simply calls the constructor function of the ArrayCollection super class
     */
    public function ProductArrayCollection(source:Array=null)
    {
      super(source);
    }

The only thing to note here is a private Boolean variable called _itemOk, which is defaulted to false. We’ll use this to protect our ArrayCollection from rogue addItem() and addItemAt() method calls, as we’ll see next, starting with overrides of the addItem() and addItemAt() methods…

These overrides both check to see if the _itemOK property is set to true. If it’s true then we call the super class’ addItem() (or addItemAt()) method which adds the supplied Object to the ArrayCollection. If it’s false, we throw an error. Doing this prevents us from calling the addItem() and addItemAt() methods directly as we can’t set the _itemOK value to false from outside the ProductArrayCollection class, we need to do that with an internal method.

    /**
     * Overrides the ArrayCollection's addItem() method
     * Adds an item only if the _itemOK property has been set by the addProduct() method
     * Resets the _itemOK property if the add is successful, or throws an error
     */
    override public function addItem(item:Object):void
    {
      if (this._itemOk)
      {
        super.addItem(item);
        this._itemOk = false;
      }
      else
      {
        throw new Error("Use addProduct() to add a Product to the ProductArrayCollection");
      }
    }

    /**
     * Overrides the ArrayCollection's addItemAt() method
     * Adds an item at the specified index only if the _itemOK property has been set by the addProductAt() method
     * Resets the _itemOk property if the add is successful, or throws an error
     */
    override public function addItemAt(item:Object, index:int):void
    {
      if (this._itemOk)
      {
        super.addItemAt(item, index);
        this._itemOk = false;
      }
      else
      {
        throw new Error("Use addProductAt() to add a Product to a specific location in the ProductArrayCollection");
      }
    }

To enable us to do that then, we need two new methods: addProduct() and addProductAt(). These simply set the value of _itemOK to true before calling the addItem() and addItemAt() methods:

    /**
     * Sets the _itemOK property and calls the addItem() method
     */
    public function addProduct(product:Product):void
    {
      this._itemOk = true;
      this.addItem(product);
    }

    /**
     * Sets the _itemOK property and calls the addItemAt() method
     */
    public function addProductAt(product:Product, index:int):void
    {
      this._itemOk = true;
      this.addItemAt(product, index);
    }

So now we can only add Product Objects to our ProductArrayCollection, the last thing we need to do is add a getProductAt() method that will return a Product rather than a generic Object:

    /**
     * Uses the ArrayCollection's getItemAt() method and returns the result as a Product
     */
    public function getProductAt(index:int, prefetch:int=0):Product
    {
      return this.getItemAt(index) as Product;
    }

  }
}

And that’s it – we now have a strongly-typed ArrayCollection that we can use for Products and can be extended for any other Object class.

The ProductArrayCollection in action

The example below is a simple one. Clicking on the each button calls the method on the button’s label. The addItem() and addItemAt() methods should should do nothing while the addProduct() and addProductAt() methods update the list. The core methods fail silently as this example is in release mode and the errors don’t display. However you can download and run the source code to generate these errors for yourself.

Clicking on the getProductAt(0) button should display name of the name of the item at position 0 in the list. An explanation of the source code is below and you can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

Example

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

The application (main.mxml)

In our application we begin with some basic layout properties, a call to a creationCompleteHandler() method, and a Script block with a private variable containing an instance of the ProductArrayCollection class:




  
    
Next we have our creationCompleteHandler() function that is called when the application is created. In this example, it simply adds event listeners to each of the buttons in the example. Each event listnener triggers the clickHandler() method and it’s this method that calls each of the ProductArrayCollection methods we’re concerned with: addItem(), addProduct(), addItemAt(), addProductAt(), and getProductAt().
The line that calls getProductAt() also grabs the returned Product and updates the view with the name of that Product. As the getProductAt() method returns a Product instead of a generic Object class, we don’t need to cast it as a Product and can therefore reference the properties of it directly.
      /**
       * Adds event listeners to each of the buttons in the example
       */
      private function creationCompleteHandler(event:FlexEvent):void
      {
        this.btnAddItemJeans.addEventListener(MouseEvent.CLICK, clickHandler);
        this.btnAddProductJeans.addEventListener(MouseEvent.CLICK, clickHandler);
        this.btnAddItemAtTeeShirt.addEventListener(MouseEvent.CLICK, clickHandler);
        this.btnAddProductAtTeeShirt.addEventListener(MouseEvent.CLICK, clickHandler);
        this.btnGetProductAt.addEventListener(MouseEvent.CLICK, clickHandler);
      }			

      /**
       * Creates two example products and handles click events on
       * each of the buttons in the example
       */
      private function clickHandler(event:MouseEvent):void
      {

        var jeans:Product = new Product("Jeans", 19.99);
        var teeShirt:Product = new Product("Tee Shirt", 54.99);

        switch (event.target.id)
        {
          case "btnAddItemJeans":
            this._products.addItem(jeans);
            break;
          case "btnAddProductJeans":
            this._products.addProduct(jeans);
            break;
          case "btnAddItemAtTeeShirt":
            this._products.addItemAt(teeShirt, 0);
            break;
          case "btnAddProductAtTeeShirt":
            this._products.addProductAt(teeShirt, 0);
            break;
          case "btnGetProductAt":
            this.txtLog.text = "Product at 0 = " + this._products.getProductAt(0).name;
            break;
        }
      }
The final part of our Script block is a simple label function that the list uses to display the properties of each Product in the list:
      /**
        * Returns a string containing the Product name and price
        */
      private function labelFunction(item:Object):String
      {
        var text:String = "";
        if (item is Product)
        {
          var product:Product = item as Product;
          text = product.name + ", £" + product.price;
        }
        return text;
      }

    ]]>
  
Our MXML view components are simple: A Vbox with some text and each of the buttons that will test our class, and a list to display the Products in our _products ProductArrayCollection variable.

Intercepting tab events in a Flex TabNavigator

Russ — Fri, 08 May 2009 07:03:43 +0000

Flex takes care of switching the views in a TabNavigator when you click on the tabs, but what if you want to detect that user activity and do something else? Maybe you want to update something else in your application. For this you need to extend the TabNavigator class and this example explains how to do that.

For this example, we’ll detect clicks on each tab, and also the mouseover, mouseout, mousedown and mouseup events. When any of these events occur, our example will update a TextArea element to indicate that the event has been captured and you can see this in the example below by mousing over and clicking on any of the tabs in the TabNavigator.
You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

A custom event

For this example I’ve created a custom event, called TabEvent. This is a simple extension of the Event class that has a couple of static constants and an event property. We’ll fire a TabEvent each time a tab is interacted with and use the event property to record which event actually took place.

The constants are there for us to use when we create a new TabEvent, which we’ll see when we look at our application MXML. For this example there are two constants that match the two types of event we want to capture: a mousevent (TAB_MOUSE_ACTIVITY) and a click event (TAB_ITEMCLICK_ACTIVITY):

package events
{
  import flash.events.Event;

  public class TabEvent extends Event
  {

    /**
    * Constants for each type of TabEvent
    */
    public static const TAB_MOUSE_ACTIVITY:String = "tabEventTabMouseActivity";
    public static const TAB_ITEMCLICK_ACTIVITY:String = "tabEventTabITemClickActivity";

Next we have public variable called event, which takes an Event object. We use this to record what type of event has occurred (a MouseEvent for example) and the constructor function assigns this property when a new TabEvent is created. We want the event to bubble up to the root of the application so we set the bubbles property to true.

    /**
    * event property to hold the event that occurred on the Tab
    */
    public var event:Event;

    /**
    * Calls the constructor class of the super class and assigns the received event to the event property
    */
    public function TabEvent(type:String, event:Event, bubbles:Boolean=true, cancelable:Boolean=false)
    {
      super(type, bubbles, cancelable);
      this.event = event;
    }

  }
}

The custom TabNavigator component

Next we have our custom component, which extends the TabNavigator class and is therefore called ExtendedTabNavigator. The first thing we have is the constructor function that simply calls the constructor of the super class (ie the TabNavigator class) and adds an event listener for the FlexEvent.CREATION_COMPLETE event).

package components
{
  import events.TabEvent;
  import flash.events.MouseEvent;
  import mx.containers.TabNavigator;
  import mx.controls.Button;
  import mx.events.FlexEvent;
  import mx.events.ItemClickEvent;

  public class ExtendedTabNavigator extends TabNavigator
  {
    public function ExtendedTabNavigator()
    {
      super();

      // add creation complete handler
      addEventListener(FlexEvent.CREATION_COMPLETE, creationCompleteHandler);
    }

That event listener triggers the creationCompleteHandler() function which itself adds two event listners to the tabBar property of the TabNavigator. We can’t do this in the constructor as it fires before the tabBar property is populated with an instance of the TabBar class, but deferring the event listener setup to this function gets around this nicely. In this example we’re going to listen for any click events (ItemClickEvent.ITEM_CLICK) and we then also add a listener for the the FlexEvent.UPDATE_COMPLETE event on the TabBar itself. We do this for the same reason we did with the creationCompleteHandler() function – we want to monitor each tab in the TabBar but until the TabBar has been updated with its dataProvider, we’re unable to do so.

    /**
    * Adds an event listener to monitor the ItemClickEvent.ITEM_CLICK on the tabBar
    * plus a listener to monitor the FlexEvent.UPDATE_COMPLETE event
    */
    private function creationCompleteHandler(ev:FlexEvent):void
    {
      tabBar.addEventListener(ItemClickEvent.ITEM_CLICK, itemClickEventHandler);
      tabBar.addEventListener(FlexEvent.UPDATE_COMPLETE, updateCompleteHandler);
    }

So when the creation of the TabBar is updated, we can add our event listeners for each mouse event we want to monitor. We could monitor as many different events as we wanted to here but for this example, we’ll just look at four common ones.

    /**
    * Adds event listeners for a selection of MouseEvents to each button in the tabBar
    */
    private function updateCompleteHandler(ev:FlexEvent):void
    {
      for each (var button:Button in tabBar.getChildren())
      {
        button.addEventListener(MouseEvent.MOUSE_OVER, mouseEventHandler);
        button.addEventListener(MouseEvent.MOUSE_OUT, mouseEventHandler);
        button.addEventListener(MouseEvent.MOUSE_DOWN, mouseEventHandler);
        button.addEventListener(MouseEvent.MOUSE_UP, mouseEventHandler);
      }
    }

We then have two event handler functions that are called by our event listeners. The first expects an ItemClickEvent and the second expects a MouseEvent but they both do exactly the same thing: create a new TabEvent, passing it the the received ItemClickEvent or MouseEvent as the event property, and then dispatching the TabEvent to be captured by the application. We could just as easily have one handler function that expected an Event and therefore could be used for any event but this example shows how to handle different types of event differently.

    /**
    * Dispatches a TabEvent.TAB_ITEMCLICK_ACTIVITY event containing the received MouseEvent
    */
    private function itemClickEventHandler(ev:ItemClickEvent):void
    {
      var tabEvent:TabEvent = new TabEvent(TabEvent.TAB_ITEMCLICK_ACTIVITY, ev);
      dispatchEvent(tabEvent);
    }

    /**
    * Dispatches a TabEvent.TAB_MOUSE_ACTIVITY event containing the received MouseEvent
    */
    private function mouseEventHandler(ev:MouseEvent):void
    {
      var tabEvent:TabEvent = new TabEvent(TabEvent.TAB_MOUSE_ACTIVITY, ev);
      dispatchEvent(tabEvent);
    }

Putting it all together – main.mxml

Now we have our extended class, we need to put it into action. Our application begins first by setting up some basic data to act as the dataProvider for our ExtendedTabNavigator. This is simply an ArrayCollection of generic Objects that each have a pageName property.




  

  
    
Next we have our creationCompleteHandler() function which is called when the application build has completed. This simply loops through our pages ArrayCollection, creates a new VBox using the createPage() function and adds that VBox to our ExtendedTabNavigator. It then adds event listeners for the two different types of TabEvent:
    /**
    * Sets up the example by calling the createPage() function for every
    * object in the pages Array, and adds event listeners
    */
    private function creationCompleteHandler():void
    {
      for each (var page:Object in pages)
      {
        var vBox:VBox = createPage(page.pageName);
        tabs.addChild(vBox);
      }

    addEventListener(TabEvent.TAB_ITEMCLICK_ACTIVITY, tabEventItemClickHandler);
    addEventListener(TabEvent.TAB_MOUSE_ACTIVITY, tabEventMouseHandler);

    }
Below this we have a createPage() function, whose job is to create a VBox with a Text object inside it. This is called by our creationCompleteHandler() function.
    /**
    * Creates a VBox with a Text object
    */
    private function createPage(pageName:String):VBox
    {
      var vBox:VBox = new VBox();
      vBox.label = pageName;

      var text:Text = new Text();
      text.text = pageName;

      vBox.addChild(text);
      return vBox;
    }
The last functions in our Script block are the event handler functions that are called by the event listeners. Both accept a TabEvent and then update the text property of one of the TextAreas in our example so we can see that an event has been received:
    /**
    * Responds to a TabEvent by sending the event details to the mouseEventDetails TextArea
    */
    private function tabEventMouseHandler(ev:TabEvent):void
    {
      var mouseEvent:MouseEvent = ev.event as MouseEvent;
      mouseEventDetails.text = mouseEvent.type + " on " + Button(mouseEvent.target).label;
    }

    /**
    * Responds to a TabEvent by sending the event details to the itemClickEventDetails TextArea
    */
    private function tabEventItemClickHandler(ev:TabEvent):void
    {
      var itemClickEvent:ItemClickEvent = ev.event as ItemClickEvent;
      itemClickEventDetails.text = "Clicked on " + itemClickEvent.label.toString();
    }

    >
  
All that’s left is to add our MXML components to the view and these are simply a couple of Text elements to label up what we’re looking at, an instance of our ExtendedTabNavigator class, and two TextArea components that display the events being received. Now when you perform a mouseover, mouseout, mouseup, mousedown or click event on any of the tabs, our TextAreas show us exactly what’s happening.

Binding the selectedChild of a ViewStack in a Flex MVC structure

Russ — Sun, 03 May 2009 07:25:25 +0000

The scenario

In any Flex application you’re likely to have a number of views (which I’ll call pages for this example), and some form of navigation that enables you to switch from one page to another.

Even if you application is tiny you’re still going to be splitting your application into components and the more you do this, the more valuable bindings become. If you have all your code in the application file for example, you can get away with writing ActionScript that directly references objects in the View and update them. But once you have split your code into components it becomes much more difficult to target component objects in lower down in your package structure (think "child.child.child.child" – not a good idea).

Of course, that’s not how MVC works and it’s exactly what we use data bindings for in Flex. In an MVC pattern, the Model stores the data of the application, the View contains the presentation interface, and the Controller takes care of communication between the two.

For this example, we have a simple application with a navigation bar (a ToggleButtonBar), a stack (ViewStack) of five pages and a set of five tab (TabNavigator)s, each containing a page.

When we click on the navigation bar, our example will update both the stack of pages and the tabs so that the page associated with the current navigation item is displayed. This is shown here and the code is explained in step-by-step detail below. You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

The problem

The TabNavigator and ViewStack components have selectedChild and selectedIndex properties so at first glance, it would seem reasonable to bind the selectedChild property to the Model so that as you update you click on your app’s navigation, the selectedChild changes.

However the selectedChild expects a Container as its value and you’re more likely to have a string value recorded in the Model (examples might be something like "sectionHome", "sectionProducts", sectionUsers"). The task therefore is to respond to changes to this string value in the Model and select the relevant child Container in the TabNavigator or ViewStack, so we need to be able to match the current value of that string with the relevant view (perhaps matching the string "checkout" to the view that displays the application checkout).

In a more complex application your View elements are going to be fairly complex, with numerous children objects that themselves have children, and so on. Although the structure in this example is very simple, the principle is the same as a very large project in that at the component level, the ViewStack and TabNavigator objects have no knowledge of the ToggleButtonBar and so communicating directly between the two isn’t going to work.

In Flex we use events to communicate throughout the application but these events only travel in one direction: they bubble upwards from the component to the application. But as the TabNavigator and ViewStack components may not be instantiated at the root of the application, we can’t simply work from the top down and communicate changes from the application down to each component. So for this, we’ll need to use data bindings on the ViewStack and TabNavigator.

A note before we start

This article isn’t intended to be an example of MVC as such – I’m simply building a simple MVC structure here as the theory could apply to any MVC framework, such as Cairngorm, Mate or pureMVC. However to plug in one of those frameworks in this example is perhaps a little overkill.

Jump straight to the solution if you want to skip the MVC section.

Example data

To start with we need some data and for this example we have a number of ‘pages’ in the application. So for this we have a simple Page Value Object with name and title properties:

package valueObjects
{
 /**
 * Basic Value Object for an example Page object
 */
 [Bindable]
 public class Page
 {
    /**
    * name and title properties
    */
    public var name:String;
    public var title:String;

    /**
    * Constructor function
    */
    public function Page()
    {
    }
  }
}

Events

To communicate the fact that a user has clicked on an item in the navigation bar, we need an event. And for this we have a custom event that bubbles up to the application root, taking with it an instance of the item that was clicked on. The object expected is Page Value Objects:

package events
  {
  import flash.events.Event;
  import valueObjects.Page;

  public class NavigationEvent extends Event
  {

    /**
    * A single event type that can be triggered
    */
    public static const DISPLAY_PAGE:String = "navigationEventDisplayPage";

    /**
    * The Page object associated with this event
    */
    public var selectedPage:Page;

    /**
    * Constructor function calls the super class constructor and assigns the ExampleItem to the event
    * NB > sets the bubbles property to true so that this event can be captured at the root
    * of the Application
    */
    public function NavigationEvent(type:String, selectedPage:Page, bubbles:Boolean=true, cancelable:Boolean=false)
    {
    super(type, bubbles, cancelable);
    this.selectedPage = selectedPage;
    }

  }
}

The Model

The place to store our data is the Model and for this example I’ve created a simple class called Model:

In the Model we have a constructor function and then a property which will contain an instance of the Model class, an ArrayCollection property that will hold our example data, and a String property that will contain a string value that represents the page that’s in view at any time:

package components
  {
  import mx.collections.ArrayCollection;
  import valueObjects.Page;

  [Bindable]
  public class Model
  {

    /**
    * Constructor function
    */
    public function Model()
    {
    }

    /**
    * Instance of the Model
    */
    public static var _instance:Model = null;

    /**
    * ArrayCollection to hold the list of pages in this example
    */
    public var data:ArrayCollection = new ArrayCollection();

    /**
    * Property to record the current selected view in the navigation
    */
    public var selectedPageName:String;

The only other code we have in this example is the getInstance() function. When this function is first invoked, a new instance of the Model is created and stored in the _instance property. If getInstance() is then called again, the existing instance is returned, which should mean that we only ever have one instance of our data.

    /**
    * Creates an instance of the Model class or
    * returns the existing instance
    */
    public static function getInstance():Model
    {
      if (_instance == null)
      {
        _instance = new Model();
      }
      return _instance;
    }

The Controller

Now we have our Model, we need a way to communicate with it and this is where the Controller comes in. In this class we have a constructor method, an instance property and a getInstance() function – to ensure that we only invoke one Controller in our application – and a reference to the Model. The Model reference is called in by using the Model’s getInstance function to ensure we use the one Model referenced throughout the application.

package components
  {
  import events.NavigationEvent;
  import components.Model;
  import valueObjects.Page;

  public class Controller
  {
    /**
    * Constructor function
    */
    public function Controller()
    {
    }

    /**
    * Instance of the Controller
    */
    private static var _instance:Controller = null;

    /**
    * A singleton instance of the Model
    */
    private var _model:Model = Model.getInstance();

    /**
    * Creates an instance of the Controller or returns the existing instance
    */
    public static function getInstance():Controller
    {
      if (_instance == null)
      {
        _instance = new Controller();
      }
      return _instance;
    }

We then have a function to add some data to the Model. In this example, this will create a new Page object and add it to the Model’s data property.

    /**
    * Creates a Page object and adds it to the model
    */
    public function createPage(name:String, title:String):void
    {
      var page:Page = new Page();
      page.name = name;
      page.title = title;
      _model.data.addItem(page);
    }

The final function is used to update the selectedPage property of the Model, which it does by receiving a NavigationEvent containing a Page object.

    /**
    * Updates the model when the navigation changes
    */
    public function updateModel(ev:NavigationEvent):void
    {
      var selectedPage:Page = ev.selectedPage;
      _model.selectedPageName = selectedPage.name;
    }

The View and the solution to our problem

The View is made up of a set of components shown in the diagram at the top of this page and in Flex that breaks down like this…

The application (main.mxml)

In our application we begin with a Script block which starts by intantiating singleton instances of our Model and Controller classes:

    /**
    * A singleton instance of the Model
    */
    [Bindable]
    private var _model:Model = Model.getInstance();

    /**
    * A singleton instance of the Controller
    */
    private var _controller:Controller = Controller.getInstance();

Next we have our creationCompleteHandler() function that is called when the application is created. In this example, this function calls the Controller’s createPage function a number of times to create five pages for our example. It then calls the addViews() function (see below) and finally adds an event listener to monitor any NavigationEvent.DISPLAY_PAGE events. This listener passes the event to the updateModel() function in the Controller.

    /**
    * Sets up the Application on load
    * For this example this involves adding some example pages to the model
    * and setting up the required event listeners
    */
    private function creationCompleteHandler():void
    {
    // add some example data to the model
    _controller.createPage("page1", "Page 1");
    _controller.createPage("page2", "Page 2");
    _controller.createPage("page3", "Page 3");
    _controller.createPage("page4", "Page 4");
    _controller.createPage("page5", "Page 5");

    // create some example views for each page in the model
    addViews(); 

    // add event listener for a NavigationEvent
    addEventListener(NavigationEvent.DISPLAY_PAGE, _controller.updateModel);
    }

Next we have two functions that create some views for us. addViews() recursively calls createView() and between them, they create a VBox with some text that is then assigned to our ViewStack and Tabnavigator objects so we have something to see in our example.

    /**
    * Adds a VBox object based on the Page data to the TabNavigator and
    * ViewStack used in this example
    */
    private function addViews():void
    {
      for each (var page:Page in _model.data)
      {
        createView(page, viewStack as ViewStack);
        createView(page, tabNavigator as ViewStack);
      }
    }

    /**
    * Creates a new VBox and child Text object based on a Page object
    * and appends it to the target ViewStack
    */
    private function createView(page:Page, target:ViewStack):void
    {
      var vBox:VBox = new VBox();
      vBox.name = page.name;
      vBox.label = page.title;

      var text:Text = new Text();
      text.text = page.title;
      vBox.addChild(text);

      target.addChild(vBox);
    }

Now we’re onto our MXML that begins with our application’s navigation: a simple ToggleButtonBar that’s been created as a component called NavigationBar. This gets its data from the data property of our Model class and uses the title property of the each Page object stored in the data property.

We then have a simple Text object and then our ViewStack, followed by another Text object and then our TabNavigator. However instead of instantiating the basic ViewStack and TabNavigator objects, here we’re using a custom component called BoundViewStack. The only thing we need to do for the second instantiation here is tell it to display as a TabNavigator, which we do by setting the isTabNavigator property to true.

NavigationBar.mxml

Our NavigationBar component simply extends the ToggleButtonBar class by adding an event listener that will monitor clicks on the navigation items, and an event handler to handle those click events.

The dataProvider of this component is set in main.mxml to be the data property of the Model class. That data property is an ArrayCollection of Page objects, so when the user clicks on an item in the navigation bar, they’re effectively clicking on a Page.

We take advantage of that in our event handler by creating a new NavigationEvent and passing it the selected Page object as its selectedPage argument and the event is then dispatched and caught in the event listener we set up in main.mxml.

So we now have our navigation bar communicating with the Model (via the Controller) each time the user clicks on the navigation bar. Now we need to tie our ViewStack and TabNavigator to the Model.

BoundViewStack.as

The TabNavigator is an extension of the ViewStack class so for our needs, we only need one component for both. We could create distinct TabNavigator and ViewStack components but we’d have to duplicate the code we’re about to write so it makes sense to create a new component that extends TabNavigator called BoundViewStack.

The first few lines of the this simple component takes care of our imports and the constructor function invokes the constructor class of the super class before adding an event listener that will detect when our component has been created. We do this by my monitoring the FlexEvent.CREATION_COMPLETE event:

package components
  {
  import flash.display.DisplayObject;
  import components.Model;
  import mx.binding.utils.ChangeWatcher;
  import mx.containers.TabNavigator;
  import mx.core.Container;
  import mx.events.FlexEvent;
  import mx.events.PropertyChangeEvent;

  public class BoundViewStack extends TabNavigator
  {
    /**
    * Class constructor function invokes the contructor of the TabNavigator class and adds
    * an event listener for the FlexEvent.CREATION_COMPLETE event
    */
    public function BoundViewStack()
    {
      super();
      addEventListener(FlexEvent.CREATION_COMPLETE, creationCompleteHandler);
    }

We then continue with a public property to determine if this component should display as a TabNavigator, and then singleton instances of our Model class:

    /**
    * Property to determine if this should be used as a TabNavigator
    */
    public var isTabNavigator:Boolean = false;

    /**
    * A singleton instance of the model object
    */
    private var _model:Model = Model.getInstance();

Then comes our creationCompleteHandler() function that does a couple of things. If the component is not to be displayed as a TabNavigator it hides the TabNavigator’s tab bar by setting its visibility and includeInLayout properties to false, and its height to 0.

Next is where we solve our problem with the ChangeWatcher class. The ChangeWatcher watches a property of an object and then calls a handler function when the property changes. We know that we have a property in our Model called currentPageName that holds the name of the Page the user clicked on in the navigation bar, so we set up a watch on that property.

    /**
    * Sets up the Class on creation complete
    * A ChangeWatcher is used to monitor the model and if this component is not to display
    * as a TabNavigator, the tabBar is hidden from view
    */
    private function creationCompleteHandler(ev:FlexEvent):void
    {
      if (! isTabNavigator)
      {
        tabBar.visible = false;
        tabBar.includeInLayout = false;
        tabBar.height = 0;
      } 

    // add a ChangeWatcher to monitor the model
    ChangeWatcher.watch(_model, "selectedPageName", modelChangeHandler);
    }

The final piece in the jigsaw is the handler function that the ChangeWatcher calls: modelChangeHandler(). This expects a PropertyChangeEvent in which both the old and new values of the _model.selectedPageName property is available.

As each page in our View has its name property set to match the name property of a Page object (we know this as we created our page views progromatically in the addViews() function of main.mxml), we need to get the child oject that corresponds to the Page the user has selected, which we do with the getChildByName function.

If this returns an object we then want to display it, which we do by updating the TabNavigator’s selectedChild property. This expects a Container so we need cast the DisplayObject we received in the previous step in order for it to work.

    /**
    * Responds to changes in the model by updating the selectedChild
    */
    private function modelChangeHandler(ev:PropertyChangeEvent):void
    {
      var itemToSelect:DisplayObject = getChildByName(ev.newValue as String);

      if (itemToSelect)
      {
        selectedChild = itemToSelect as Container;
      }
    }

And then bang, we’re done. We now have a very basic MVC application structure where everything is tied together with events and bindings, leaving us free to structure our component packages in any way our application demands.

The solution to our problem is very simple so this article is more in-depth than it needs to be, but I hope it explains a little about the advantages of an MVC pattern and that it will lead you on to looking at frameworks like Cairngorm that take care of a lot of the MVC side of things.

Displaying an image in a Flex tooltip

Russ — Thu, 02 Apr 2009 14:35:55 +0000

Demo and source code

This is a simple example that will display a panel with the details of an image as a tooltip, including a preview of the image itself.

This is shown here and the code is explained in step-by-step detail below. You can download and edit the source code, or right-click on the demo below and choose View Source to see how it all fits together.

You need Flash Player 10 to view this content. You can download this for free from the Adobe website. If you’re using a feed reader you could try loading this post in your web browser.

Data and assets

The first thing we need is some data, so for this we set up a Value Object that describes our photo object. For this we simpy need a few basic properties including the title, the photographer details and the filename of the preview image we’re going to display on our tooltip. In our example this is saved as Photo.as in the valueObjects directory.

package valueObjects
{
 /**
  * Basic Value Object for a photo
  */
 [Bindable]
 public class Photo
 {
   public var title:String;
   public var filename:String;
   public var photographer:String;
   public var website:String;

   public function Photo()
   {
   }
 }
}

We also need some assets for our demo, a simple stylesheet and the preview images we’ll be displaying for each photo. These are all stored in the assets directory of our demo.

To keep things nice and simple we’ll break our demo down into separate simple components, of which there are two: PhotoView.mxml and PhotoToolTip.mxml. But before we look at those, let’s dive into our Application file Main.xml.

The Application

As this is a very simple demo Main.mxml contains very little MXML as it’s simpler just to build the app with ActionScript when the application loads. The only MXML code in here is a call to load the stylesheet for the demo, and then a Script block which handles our application build, which we’ll go through step-by-step…

The first few lines take care of the imports for our PhotoView component and the Photo Value Object:

import components.PhotoView;
import valueObjects.Photo;

Next we have our two application methods. The first of these – createPhoto() – creates a new Photo Value Object and a new PhotoView component. The component is then added to the Application view.

/**
 * Creates a new Photo object and adds it to the sample data collection
 */
 private function createPhoto(title:String, filename:String, photographer:String, website:String):void
 {
   var photo:Photo = new Photo();
   photo.title = title;
   photo.filename = filename;
   photo.photographer = photographer;
   photo.website = website;
   _photos.addItem(photo);
 }

The createPhoto() method is called a number of times when the Application is first compiled, via our only other method in Main.mxml: creationCompleteHandler(). The job of this method is simply to create some demo objects by some data to the createPhoto() method.

/**
 * Sets up the demo when the application creation has been completed
 */
 private function creationCompleteHandler():void
 {
   // set up the sample data
   createPhoto("Tomatoes", "1163182_tomatoes.jpg", "Edmondo Dantes", "http://www.sxc.hu/profile/edmondo");
   createPhoto("Oranges", "1118482_oranges.jpg", "chamanit", "http://www.sxc.hu/profile/chamanit");
   createPhoto("Lemons", "1126699_lemon.jpg", "abcdz2000", "http://www.sxc.hu/profile/abcdz2000");
   createPhoto("Peppers", "1163181_peppers.jpg", "Edmondo Dantes", "http://www.sxc.hu/profile/edmondo");
   createPhoto("Courgettes", "1163183_courgette.jpg", "Edmondo Dantes", "http://www.sxc.hu/profile/edmondo");
 }

That takes care of our main Application. Next is the PhotoView component…

PhotoView.mxml

For each photo we want to show a simple red box with the title text in it. When you hover over this box, we want to show the rest of the information for the photo, along with the image, as a tooltip. So PhotoView.mxml is a simple VBox component with a Text object inside it. It expects a Photo Value Object for its data, so we bind the Photo.title property to the value of the Text object:

The only MXML object in here is a Script block, which takes care of our tooltip behaviour. The first few lines take care of our imports – the ToolTipEvent Class and our Photo Value Object.

import mx.events.ToolTipEvent;
import valueObjects.Photo;

We then create a public bindable variable to contain the Photo data and it’s this variable that’s populated in the createPhoto() mehod of Main.mxml each time a photo is added.

[Bindable]
public var photo:Photo;

Next we have two methods, the first of which is our creationCompleteHandler(). This is called when the PhotoView component is compiled and simply assigns a new event listener that will detect the creation of a tooltip and fire our second method: toolTipCreateHandler().

/**
 * Adds a TOOL_TIP_CREATE event on this component
 */
 private function creationCompleteHandler():void
 {
   addEventListener(ToolTipEvent.TOOL_TIP_CREATE, toolTipCreateHandler);
 }

Our toolTipCreateHandler() method follows and it’s purpose is to instantiate a new PhotoToolTip component, pass it the Photo Value Object for this particular photo, and then assign the component as to the tooltip event.

/**
 * Event handler method to create a new tooltip object
 */
 private function toolTipCreateHandler(ev:ToolTipEvent):void
 {
   var tooltip:PhotoToolTip = new PhotoToolTip();
   tooltip.photo = photo;
   ev.toolTip = tooltip;
 }

So what’s happening here? Basically when you hover your mouse over a instance of the PhotoView component, a ToolTipEvent.TOOL_TIP_CREATE event is fired and our toolTipCreateHandler() method intercepts this and assigns a PhotoToolTip component as the tooltip property of the event, effectively overriding the default text tooltip that you get out of the box. There is only one thing left to do here to make the ToolTipEvent fire: we need to set the tooltip property of the PhotoView component itself, which is done as follows in the properties of the PhotoView.mxml file:

PhotoToolTip.mxml

Our final piece of the jigsaw is the component we want to display as the tooltip and this is where PhotoToolTip.mxml comes in. This demo uses a simple Panel component containing Image and Text objects that display the photo data but you could use any component that extends the UIComponent Class. The important thing to note is that whatever component you choose, it must implement the IToolTip Interface and contain getter and setter methods for the text property, otherwise you’ll get errors when you compile your application.

The first line of our MXML file takes care of the implementation of the IToolTip Interface and adds a title to the Panel using the data from the Photo Value Object for this photo.

Next we have a Script block, the first part of which imports the Photo Value Object and declares a private bindable variable to hold the photo data.

import valueObjects.Photo;

/**
 * Variable to contain the Photo Value Object
 */
[Bindable]
private var _photo:Photo;

Then we have the text property and getter/setter methods that the IToolTip Interface requires:

/**
 * Required text property of the IToolTip interface
 */
private var _text:String;

/**
 * Getter method for text property, required for the IToolTip interface
 */
public function get text():String
{
  return _text;
}

/**
 * Setter method for text property, required for the IToolTip interface
 */
public function set text(value:String):void
{
  _text = value;
}

The last part of our Script consists of a setter method for the private variable _photo. We could avoid this by making the variable public but in the interests of keeping the way in which we get and set properties consistent, we have a setter method for this (we don’t need a getter for this example so this is left out).

/**
 * Setter method for photo property
 */
public function set photo(value:Photo):void
{
  _photo = value;
}

Finally we have the Image and Text objects within the Panel that will show the preview image and the photographer information stored in the photo’s Photo Value Object.

This technique should provide a simple foundation for tooltip usage beyond simple text descriptions and is one that you can expand upon for your own, perhaps more complex requirements.