Validation/Invalidation Mechanism

It's been quite a while since I blogged last--for that I apologize. When you create a UI component in Flex, there are 4 main methods we ask that you implement: createChildren, commitProperties, validateSize, and updateDisplayList. The Flex framework then calls these methods at the appropriate times, but if you get into component development, you need to understand not only how these mechanisms work, but why we have these mechanisms in the first place. As a new member to the Flex SDK team, this was one of the first questions I had. To help answer this, let's take a look at something I'm currently implementing. Note that whatever I show may or may not end up being the final implementation, but it's a good example to look at. In AIR (Adobe Integrated Runtime), they added NativeMenu's, which are menus native to each operating system and sit at the top of the screen for a window. The API for this is centered around instantiating Menus, MenuItems, and adding them all together. A typical example would look like:

var mainMenu:NativeMenu = new NativeMenu();


var fileMenu:NativeMenu = new NativeMenu();
var printItem:NativeMenuItem = new NativeMenuItem("Print");
printItem.keyEquivalent = "P";
printItem.keyEquivalentModifiers = [Keyboard.CONTROL];
printItem.mnemonicIndex = 0;
...


var saveItem:NativeMenuItem = new NativeMenuItem("Save");
...

   
var newItem:NativeMenuItem = new NativeMenuItem("New");
...


fileMenu.addItem(printItem);
fileMenu.addItem(saveItem);
fileMenu.addItem(newItem);


var fileMenuItem:NativeMenuItem = new NativeMenuItem("File");
fileMenuItem.subMenu = fileMenu;
mainMenu.addItem(fileMenuItem);


// repeat for Edit, View, etc...
               

This can be a really long process. If there's anything Flex has taught us, it's that declarative markup can be a lot easier. If you look at the Flex interface, we use dataProviders to drive our menu. We want to do the same thing here for NativeMenus. So the idea would be:

[Bindable]
private var myMenuData:XMLList =
<>
     <menuitem label="_File">yy
         <menuitem label="_Save" keyEquivalent="F10" />
         <menuitem label="P_rint" mnemonicIndex="4" mnemonicIndexOverride="true" />
         <menuitem type="separator" />
         <menuitem label="E_xit" />
     </menuitem>
     <menuitem label="_Edit">
         <menuitem label="_Copy" toggled="true" type="check" />
         <menuitem label="C_ut"/>
         <menuitem label="_Paste" />
     </menuitem>
 </>;

<mx:Desktopmenu id="desktopMenu" dataProvider="{myMenuData}" labelField="@label" showRoot="false"/>
               

Don't worry much about the XML format specified above (the underscores, how shortcuts are specified, etc...). That interface is up in the air, but the idea is what's important, and that is it's a lot easier to use XML to declaratively create the menu. One of the odd things about this component is that it's not a UIComponent. What I mean by that is it won't extend UIComponent because we're not actually adding it to the underlying Flash display list. We're just creating NativeMenuItems, where AIR ends up using the underlying operating system menu API (atleast that's what I think happens). Yet, despite not being a UIComponent, we can still discuss why validation/invalidation is an important concept. Let's say someone wants to change the dataProvider for this menu. When they do this, we need to recreate the NativeMenu objects underneath. So let's say we have something like this:

public function set dataProvider(value:Object):void
{
 _dataProvider = value;
 createNativeMenu();
}

Where createNativeMenu loops through our dataProvider and recreates the underlying NativeMenu. Well we also need to do this if someone changes the labelField, iconField, dataDescriptor, or a few other properties (for many Flex classes, this list is even longer). However, when you change the dataProvider, you oftentimes need to change other properties as well. For example, our new dataProvider might use a different field for it's label and icon. If after every setter, we re-created the menu, we'd be doing it too many times. What we really want is something like a commit() function, where after making all the changes one wants, we then recreate the menu. We could do this, and in fact, we thought about doing this, but instead, let's do something really simple so that the programmer doesn't have to remember to do this. Let's just set a flag called invalidatePropertiesFlag and then wait 50 ms to re-create the menu.

public function set dataProvider(value:Object):void
{
 _dataProvider = value;
 invalidateProperties();
}


private invalidatePropertiesFlag:Boolean = false;
           

private function invalidateProperties()
{
 if (!invalidatePropertiesFlag)
 {
     invalidatePropertiesFlag = true;
     var myTimer:Timer = new Timer(100, 1);
     myTimer.addEventListener(TimerEvent.TIMER, validateProperties);
     myTimer.start();
 }
}



private function validateProperties(event:TimerEvent)
{
 if (invalidatePropertiesFlag)
 {
     invalidatePropertiesFlag = false;
     createNativeMenu();
 }
}                

All right, so with this approach, we've successfully solved our problem. Now when multiple properties are set that invalidate our menu, we only end up recreating the menu once (not 3 times). If this approach was applied throughout the framework, though, we'd have a few problems. Individual components would be validated at different times. However, the truth is that components are dependent on each other. For example, if the DateField component changes, it causes the underlying DateChooser component to change as well, so really we need a coordinated effort of validation. This is especially true for UIComponents that are drawn on the screen, where changing the size of one component affects all the other components around it as well as all it's children. This is why we have LayoutManager. It coordinates this whole process I won't get into the complete lifecycle here, but in a gist, LayoutManger calls validateProperties() on all the components in a top-down fashion. Then validateSize() is called bottom-up, essentially asking everyone how big they want to be. Lastly, validateDisplayList() is called which tells everyone how big they are going to be (they don't always get what they want), and this happens top-down. Underneath the hood, UIComponent and Container are base classes that implement these three methods. They do some extra work for you, and then they call commitProperties(), measure(), and updateDisplayList(unscaledWidth, unscaledHeight) respectively. One thing to note is how validateProperties() and validateDisplayList() are top-down, while validateSize() is bottom-up. This is because properties usually propagate top-down (Example is DateField properties changing the underlying DateChooser component). validateSize() is bottom-up because we need to know how big our children are before we can determine our size. Lastly, validateDisplayList() is top-down because ultimately the parent decides how big each children gets to be (it usually tries to respect basic principles, like always listening to the children's minWidth/minHeight). Besides these inter-dependencies between properties, there's another reason why we coordinate this effort. Underneath, the Flash Player essentially uses a timeline with frames. The player doesn't actually update it's display list until the next frame passes. So if I say myComponent.x = 50; the object doesn't actually move until this frame finishes. Here's an example that shows this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="init()" layout="absolute" >
<mx:Script>
 <![CDATA[
     private function init():void
     {
         stage.frameRate = 1;
     }

     private function width50():void
     {
         myCanvas.width = 50;

         var myTimer:Timer = new Timer(500, 1);
         myTimer.addEventListener(TimerEvent.TIMER, width200);
         myTimer.start();
     }

     private function width200(event:TimerEvent):void
     {
         myCanvas.width = 200;
     }
 ]]>
</mx:Script>

<mx:Canvas id="myCanvas" backgroundColor="red" width="100" height="100" />
<mx:Button label="Click Me" click="width50()" x="200" y="200" />

</mx:Application>

We change the framerate to 1 per second. Now, when you click the button, sometimes you'll see it shrink to a width of 50 before growing to 200, or sometimes you'll see it just go to 200. It depends on exactly when you click on the button with respect to where in the current frame we are.

There are a few reasons the flash player does this as it helps with performance, but the important point is that Flex ties into this and does validation/re-measuring only when it'll actually affects the screen by tying in to the ENTER_FRAME event. So, in this DesktopMenu component, we should do the same thing and validate ourselves when all other components do (to be honest, I'm not sure if the native menu, since it's using the operating system API underneath can update itself in between frames or not). To do this, we need to implement ILayoutManagerClient, like UIComponent does, and then attach ourselves to the LayoutManager's queue by calling UIComponentGlobals.mx_internal::layoutManager.invalidateProperties(this);. Since we're not a display object, we don't need to do anything in validateSize or validateDisplayList. One thing to note is that despite it's name, LayoutManger should really be though of as a ValidationManager because it doesn't just deal with layouts. One other reason we do this is because sometimes the order of properties matters, and if it's represented as MXML, this order can be lost. So for example, in a List component, we might do something like:

myList.dataProvider = ["a", "b", "c"]; // gets promoted to an ArrayCollection
myList.selectedIndex = 1;

But in MXML, you have:

<mx:List id="myList" dataProvider="{['a', 'b', 'c']}" selectedIndex="1" />

or:

<mx:List id="myList" selectedIndex="1" dataProvider="{['a', 'b', 'c'}" />

You can see that the order actually matters here, but in XML we don't really have an order of operations. commitProperties() sorts all this out for us, and sets dataProvider before setting selectedIndex. All right, that was a lot of code. I'm sure I could be missing some reasons, but to re-cap, why we have LayoutManager and this invalidation/validation scheme:

• Properties tend to change at the same time, and we don't want to re-do the same work because of this.
• Property changes often cascade and affect many other properties (changing my position, would affect lots of other elements). This exacerbates the point made above.
• The Flash Player uses delayed rendering, so changing a UI property doesn't actually display until the next frame
• MXML representations of objects don't take into account order of operations.

So I hope this helps explain the why behind the Flex scheme and not just the how.