Any one have a better explanation?

One of the first things I hit was the term ‘elements’. What is an element? Is it the same thing as a child? Initially I concluded that elements where just another way of saying children (wrong). I figured that all elements where child components and vice versa. Then I noticed that some of the methods that I was expecting to find inside the new containers (as well as some of the existing ones) were missing. Where is getElements()? How do I find out how many elements I have? Can I just use getChildren() and treat the result like an IVisualElement (which itself was a mystery to me at the time).

So I started to really read the API docs, Flex source and blog postings about these topics. I also tried to decipher the slides shows that some bloggers posted about the great new features of Flex 4, but it turns out the slides do not make much sense if you do not have the audio of the presentation to go along with them.

Finally, I started to put together some very basic demos that would help me explore the new world of elements and help me figure out what I was really doing when it came to using the new Spark containers.

I’ll start by stating the questions I had at the time. Question number one was “How do I get the all the elements of a spark container?” I was expecting a getElements() method similar to the familiar getChildren() method from Flex 3. Instead, what you have are two properties: numElements and numChildren. To obtain all of the elements of a container, you can use a for-loop with the numElements count and call the getElementAt() method for each one. Pretty obvious after you realize there is no getElements convenience method. Question number two was: “what is the difference between an element and a child?”. Let’s look at the difference between elements and children….

An element is basically anything that implements the IVisualElement interface. A child is anything that extends from DisplayObject. When trying to determine if a component is an element or a child or both, remember that a UIComponent is a descendant of DisplayObject, so all UIComponents are DisplayObjects and therefore can be children. Also know that UIComponent implements IVisualElement so all UIComponents are considered ‘elements’. However, this does not mean that all DisplayObjects are elements. A DisplayObject that is parented by a container (ie, contained within that container) is a child of that container. But it is only an element of that container if it also implements IVisualElement. So when is a DisplayObject a child of a container and when is a DisplayObject an element of that container? Some examples showing different types of containers will answer this question.

In the first example, we look at the result when the container in question is an older Halo container (in this case, a Halo Panel). Because Panel is a descendant of DisplayObjectContainer, it has the addChild() method. In addition, because it descends from Container (which implements IVisualElementContainer), it also has the addElement() method. We will see that the Container’s implementation of the IVisualElementContainer interface is just a facade to the display list API but it is implemented here so that it will have the same methods that we find in the newer Spark containers that also implement IVisualElementContainer.

So we can add both children and elements to this container. However, we cannot add just any type of element to it. There is a difference between VisualElements and GraphicElements. VisualElements implement the IVisualElement interface, but GraphicElements implement an extension of IVisualElement called IGraphicElement which has some extra features that the container needs to know about. Therefore, some elements (such as the GraphicElement) cannot be added directly to the Halo Panel. The compiler will complain that it needs to be wrapped in a Group container first. More on why in a second….

The Panel in the following example contains several UIComponents including another Halo Panel, a Spark Panel, some Halo Buttons, some Spark Buttons and a SkinnableContainer with child components of its own. (Note that the components inside the SkinnableContainer will NOT be children of the Panel. They are children of the SkinnableContainer.) All of these components are DisplayObjects so they are all ‘children’. Clicking the ‘Show Children” button reveals as much. In addition, all of these components are UIComponents (which implements IVisualElement) so they are all ‘elements’ as well.

Now take a look at the next example. This time the container in question is a Spark Group. Like the Halo Panel in the previous example, Group is a descendant of DisplayObjectContainer so it has the addChild() method and because it implements IVisualElementContainer, we can add IVisualElements (‘elements’) to it as well using addElement(). The Group container can also handle GraphicElements such as a Rect (a Rectangle GraphicElement) which the Halo Panel could not. This is because, unlike the Halo Panel, the Group object knows how to display GraphicElements in an optimized manner. What does that mean? Read on…

GraphicElements require a little more involvement from their parent containers than do regular VisualElements. The key here is the IGraphicElement interface that GraphicElements implement. As I mentioned before, it is an extension of the IVisualElement interface (which is why GraphicElements can be added to the Group through the Group’s addElement() method). But GraphicElements are not DisplayObjects so they cannot be seen unless they get ‘drawn’ onto another DisplayObject by their parent. So if you add a Rectangle to a Group, the Group will also need to have a DisplayObject to draw the Rectangle on so it will show up in that Group. Just to optimize things a bit, the Group can actually reuse the same DisplayObject to draw multiple GraphicElements when possible. The container can use any DisplayObject that implements ISharedDisplayObject to draw the GraphicElement. In the first example, the Halo Panel could not do this so it could not draw GraphicElements in this optimized manner. Thus, the compiler gave an error saying you have to wrap it in a container that can deal with this. The Group container can do this so GraphicElements can be added to a Group.

One other thing to note: while some GraphicElements will allow the Group parenting them to create a DisplayObject for that GraphicElement to be drawn in, others will create their own DisplayObjects to be drawn in, and this interface (IGraphicElement) allows the parent Group to manage that DisplayObject even though the parent Group did not create it.(ie to add the DisplayObject as a child so the IGraphicElement can be drawn into it).

So what does this mean? It means that in our next example, the number of children is not the same as the number of elements. This example uses the same set of components from the first example, but it adds 4 rectangles which are GraphicElements. The children are all IVisualElements. However, they are not all children. The rectangles are GraphicElements which do not descend from DisplayObject. BUT, the Group knows that it needs to add DisplayObjects so that the GraphicElements can be drawn inside the container. The rectangles are different sizes and rotations so the Group decided to add two new DisplayObjects to draw the four rectangles on. Pretty cool, huh?

Now look at example 3. Instead of a Group, we are using a SkinnableContainer. The SkinnableContainer has the same set of components as the previous example. But, the SkinnableContainer uses a Skin for its visual representation and that Skin is the first and only child of the SkinnableContainer. The SkinnableContainer’s default Skin class is comprised of a Rectangle (for the border) and a Group called the ContentGroup which all skins for containers need so Flex know where to add children to the container.

So this example illustrates the fact that, while the SkinnableContainer has 10 elements, it only has one child: the Skin of the SkinnableContainer. In turn, that skin has only one child: the ContentGroup Group component. You may be asking “why are there not 2 children of the Skin: one being the ContentGroup and the other being the DisplayObject for the Rectangle (serving as the border) to be drawn in? The answer is because the Skin class descends from the Group class and Groups will add DisplayObjects when necessary to draw any GraphicElements they contain. In this case, no new DisplayObjects were required. The Skin class just drew the Rect GraphicElement directly onto itself. It can do this because the Skin’s ancestor, the Group class, also implements ISharedDisplayObject which means that it can serve as a shared DisplayObject used to draw GraphicElements when necessary. So the Skin manages the DisplayObjects used to render the GraphicElement, and the in this case, the DisplayObject it is using to draw on is itself! If you added other Rectangles to a custom skin and assigned that to the SkinnableContainer, the Skin might decide it needed more DisplayObjects to draw those other Rectangles and you would therefore see more children in the Skin’s child list.

One other thing to note is that the number of elements stays the same when you look at the element list for the SkinnableContainer, its Skin, and the Skin’s ContentGroup. If you look at the source for SkinnableContainer, you will see that it determines the numElements value by getting the corresponding numElements value from the currentContentGroup so basically it is just re-routing you to its content group when you query for elements. Likewise, the Skin of the SkinnableContainer does something similar. It extends from Group, which gets the numElements property from its internal mxmlContent property which is an array of visual content children for this Group. Both of these are analogous to the RawChildren property of the Panel container which you used to get ALL the children of the Panel rather than just the children that you added to the Panel which came from the getChildren() method.

After reading all of this, it may not seem any clearer than when you started. You basically have to familiarize yourself with the inheritance hierarchy and relationship between 7 different classes/interfaces:

1. DisplayObject
2. UIComponent
3. Container,
4. IVisualElement,
5. IGraphicElement,
6. IVisualElementContainer
7. ISharedDisplayObject

Once you know who these fit together, you’ll soon understand the difference between elements and children. I’m sure I’ve messed up some of the facts and gotten a few things wrong so feel free to put corrections in the comments section if you think I’m way off base on any of this. :)

UPDATE: Check out these links for more information on this and related topics:

• Article on the Gumbo DOM Tree API (this is full of great detail on this topic)
• Nice example on the the difference between the owner and parent of a component. Very nice.

So I decided to put something together myself. Nothing ground-breaking here, but this demo uses the Box2D 2.0 physics engine and combines it with Spark buttons using some ideas I’ve taken from Eugene Karataev (translated) and his demo using Flex 3 called FallenUI.

This demo shows some Spark buttons that become physics-enabled once you click the ‘Start Simulation’ button. You can also drag them around and toss them into each other. I’m sure there is a better way to integrate Flex 4 and Box2D, but this is just a quick and dirty attempt to see if I could get it working with no Halo components involved. Of course, the source is also available from the context menu. Let me know what you think. :)

I’ve made good use of a tip I picked up from McCune on generating a stacktrace in my logging statements so that I can not only see the method that was called but also from where it was being called.

In this particular case, I was trying to determine why my component was getting its maxWidth value changed at some point in the lifecycle. I overrode the maxWidth accessor using this snippet:

1
2
3
4
5
6
7

override public function set maxWidth(value:Number):void {
    trace("set maxWidth = " + value);
    var stackTrace:String = new Error().getStackTrace();
    var callStackString:String = stackTrace.substring(stackTrace.indexOf("\n"), 500);
    trace("---- call stack: " + callStackString + "... \n");
    super.maxWidth = value;
}

The result is a nice log statement showing me what led up to the call:

1
2
3
4
5
6

set maxWidth = 757
---- call stack:
at BaseContainer/set maxWidth()[/Users/white/dev/workspace/FlexContainerTesting/src/BaseContainer.as:45]
at layouts::HorizontalFlowLayout/updateDisplayList()[/Users/white/dev/workspace/FlexContainerTesting/src/layouts/HorizontalFlowLayout.as:96]
at BaseContainer/updateDisplayList()[/Users/white/dev/workspace/FlexContainerTesting/src/BaseContainer.as:85]
at mx.core::UIComponent/validateDisplayList()[C:\autobuild\3.2.0\frameworks\projects\framework\src\mx\core\UICompone...

Now this works great until you run into the issue that I did the other day. According to the Doug’s posted (at the bottom) and according to the docs, there is a gotcha that I wish I had paid attention to before hitting this problem. Doug’s post mentions that this only works in the debug player, but to get more specific, the docs point out that it returns a null value:

getStackTrace(): Returns the call stack for an error as a string at the time of the error's construction (for the debugger version of Flash Player and the AIR Debug Launcher (ADL) only; returns null if not using the debugger version of Flash Player or the ADL.

So this means that the stackTrace variable will be valid when I’m using the debug version of the Flash player. But in the normal player, the third line will throw a nullpointer exception. However, in my application, these null pointers were getting ‘eaten’ by the application and never being shown.

The result? The perfect bug. One that hides when you look for it. Because the getStackTrace() method of the Error object returns a valid object in the debug version of the Flash player and a null in the regular version, it was a real pain to figure out why my app worked great on my dev box (with the debug player) and would never finish loading in the regular version of the flash player. The answer, of course, would be to have runtime errors correctly bubble up to an error dialog in the application so non-debug flash players could indicate that something is wrong. Alternatively, something like this would also work:

1
2
3
4
5
6
7
8
9

override public function set maxWidth(value:Number):void {
    trace("set maxWidth = " + value);
    var stackTrace:String = new Error().getStackTrace();
    if (stackTrace != null) {
        var methodNameString:String = stackTrace.substring(stackTrace.indexOf("\n"), 500);
        trace("----> call stack method: " + methodNameString + "... \n");
    }
    super.maxWidth = value;
}

Just wanted to post this in case anyone else ever got bitten by the same issue.

• Flex Data Services / Live Cycle Data Services integration, providing real time updates to users.
• Instance messaging functionality so users could get notifications in real-time. This also allowed me to monitor which users were logged in and using the system.
• A library of comments which could be saved and then reused by the teachers to speed up the time it took to create reports.
• A report-creation wizard to generate blank reports in bulk so the teachers would not have click ‘new’ for each student in the class.
• PDF report generation (using the iText framework) combined with an iFrame overlay to make the resulting PDF files look like they are actually in the Flex application.

There are two parts to the application.  The Teacher Portal is where teachers create courses, enroll students and add grade and progress reports.  (I used the Flex Store demo as my inspiration for the animations.).  The Administrator Portal is where administrators could review the submitted reports and print out PDF files.

For this demo, I’ve taken out all the private info and used a bunch of stock photos of kids with made-up information. (These are NOT real students and the information is completely fabricated for demonstration purposes)

So take a look and let me know what you think. They are large so it takes a few seconds to download. Yes there are bugs and issues, but this was my first attempt from about 3-4 years ago so give me a break :)

Teacher Portal (select any teacher; no password required)

Administrator Portal (select any user; no password required)

So how did I make it work? Well, step one was to sift through the code from the PageFlip demo by Didier Brun and the FlexBook code from Ely Greenfield.  I used the PageFlip class from Didier to compute the flip graphic, and then I played around with the gradients and vectors based on what I learned from Ely’s code.  I found that I liked the flip effect from PageFlip, but not the gradients so I handled them separately.  Rendering the flip is easy.  Computing the gradients is not.  You have to make them follow the movement of the fold and I still do not have it down perfect.  I had to brush up on my geometry and trigonometry and I still had a hard time computing all the angles, so you will see a lot of brute force mathematics where I really should have used more established equations (if I knew what they were).

To finish it off, I incorporated TweenMax (very nice!) to get things to move smoothly and used Ben Stucki’s reflection logic along with one of Juan’s skins to make it look nice. So after ripping off the really good Flex programmers out there, the result is what you see above.  As usual, the source is provided. :)

You can basically use it by taking the code from the demo mxml, and plugging in your own components within the PeekPanel tag.  Just provide it with the TopPage and HiddenPage components and see what happens.  I have not tested this all that thoroughly so it might not work perfectly. I still need to touch up the gradients which do not always look smooth when the flip is moved at certain angles.  I also need to find a good way to handle components with rounded corners.  If anyone wants to suggest solutions, I’d love to hear them.

[Note: if you use dynamic rather than static values for the width and height settings, you have to set dynamic binding values for the foldOriginX/foldOriginY to make the animation work properly]

Update: I forgot to mention that I used Renaun Erickson’s Flex Logger on this as well.  I’ve heard from some of you that you need the .swc for this to compile the code so here is the one I used or you can go to Renaun’s site to get the code and compile it yourself.  You may have to right-click on the link and use ‘save as’ with a name of FlexLogger.swc to get the file to save to your local computer correctly. Of just remove all the reference to that swc and the logger in the code and go without the logging.

In case you missed it, here is day 1.

Day 2:

• Most of the developers here seem to favor macs over pc’s. My guess is that Apple has at least 60% of the flex-nerd market.  Nice.
• The axiis framework is really something special.  Once they get the transitions in place, it will really be a must-have library for anyone doing data visualization.  The way they are handling layouts and data binding is pretty slick.
• Flex 4 is looking better and better but I’m not going to really get into it until they solidify the api a little more. Jeremy Saenz’s presentation today pointed out that the way skins are implemented in the current pre-release of Gumbo is still somewhat fluid and you can easily find yourself having to go back and re-work your examples.  This is to be expected in code that is still in the early stages of development but it is also what is keeping me from really getting my feet wet.  Once the beta is released, I’m all over it.
• The Universal Mind guys have really put a lot of thought into their UX efforts.  I was surprised to find out that Adobe’s UX team is not the only game in town.
• I was not aware that Joe Johnson and merhl.com are one in the same.  I’ve been reading his blog posts for years and yet I never knew who he was.  Actually, I still don’t know him, but I do know what he looks like now.

• The folks here are really cool and very friendly. They seem to be genuinely excited to be here.
• I’ve gotten to meet several of the guys who are working on projects that I’m either very interested in or already use. This includes folks like Juan Sanchez, Doug McCune and Ryan Campbell just to name a few. It is cool to finally put faces with names after following their blogs for such a long time.
• Indianapolis seems to be a pretty clean city and the downtown area is much more lively than I expected. There are lots of steakhouses and brew pubs.
• Renaun’s presentation on structured log testing is something I can definitely use on my projects at work. I just hope I can keep the disciplined attitude that it takes to keep my tests up-to-date.
• The enhancements coming down the pipe for Flex 4 are even more substantial than I realized. They will make writing Flex apps much more efficient. Too bad they are so vague about its availability.
• So far, Michael Labriola’s ‘Any Which Array but Loose’ has been my favorite session. He really seems to know his stuff and I learned a lot about what is really going on in the different types of arrays, vectors, bytearrays and arraycollections.
• I think Adobe initially thought that Flash Catalyst would be a great way to create Flex/Flash applications without all the messing coding. Now that it has been in development for quite some time, I think they’ve figured out that it is much better to position it as a tool for prototyping and wireframing applications and leaving the rest of the work up to the developers who want to get into the code.
• The first night here, Obama was in town. His motorcade was supposed to pass right by the hotel but I never saw it. Too bad. Would have been cool to see the limo and the whole procession first-hand.
• Every night there is a reception at the Rock Bottom Brewery. It is fun to socialize with everyone over a beer after a day of sessions. The waitresses are pretty good looking too, except for the one that is short, portly, and a dude.
• The presentation I’m most looking forward to is the one on OpenFlux. The outside-the-box thinking that goes into a project like this is really something else. The impact that OpenFlux and Degrafa have had on the evolution of Flex 4 is really impressive.
• This hotel is also a functioning train station. The rooms shake when a locomotive rolls through. They try to pass it off as part of the experience. My bet is that they just didn’t think it through.