Using the Tree Component in Director
Unfortunately the use of Flash Components in Director is a bumpy road at best, the Director documentation is light on its description of each component and the properties and methods that are to be used. In general the best approach to using the items is to keep a copy of both documentation sets handy, whether that be paper or electronic copies. For those that don't own Flash, you can use the LiveDocs online version of Flash MX 2004 documentation and in this case specifically the documentation on the Tree View Component. In particular I'm going to give a quick description as to the basic steps required to populate an empty tree component sprite on stage in Director, for this purpose I'll be using the version of the component as delivered with every installation of Director MX 2004.
Note: sorry but at this time the write-up here will be very brief indeed, hopefully I can come back to this later.
1. Get Your XML String
Obtain an XML string where each branch or node has a "label" property that provides the string label used in the tree view display. In the example movie I've created the XML string being used is very simple:
The XML you use can be more complicated than that, but for our purposes here it's best to keep things simple.
2. Prepare Your XML Data (optional)
Soon we will be feeding our XML data to the Tree component and there are two ways to do that, one of them is to use an ActionScript XML object to parse the string ahead of time. This is an optional step as you can actually feed the XML string directly to the Tree component, but preparing it ahead of time lets you better handle error checking and ensuring that the XML parses properly. In order to do this step you must create a XML object in the sprite that's rendering the Tree component, and provide it the XML string to parse. Here is some example Lingo that can achieve that goal (I'm assuming that the Tree component is being shown by sprite 1 in the code below):
Where in the above I'm assuming that tSprite is a reference to the sprite showing the tree component and tString is a variable containing the XML string shown in step 1 above. It's important to set the ignoreWhite property of the XML object to true so that all white-spaces in your XML string are ignored (generally the best option). Please be aware that this is only one way to have your XML object load and parse XML string data, you can provide the string when creating the XML object via the newObject() method, you can also call the XML object's parseUrl() method to have it load and parse an external XML file, for more details on that please check the Flash documentation for XML objects.
GOTCHA: it is very important to remember that in order for your Tree component to use the XML object you must create the XML object in the same sprite that is showing the Tree component. You cannot share Flash objects between either Flash sprites or Flash sprites and global Flash objects. This is why in this case I was required to create the XML object in the sprite containing the tree component.
3. Set the Tree Component's Data Provider
Now that we have our XML data we need to provide it to our tree component in order for it to be rendered on stage, and that is done is by setting the tree component's dataProvider property. This property will take two different data types, you can set it to be a reference to a XML object you've already created or you can set it to a string that contains the XML you would like the to have rendered. As mentioned above there are benefits to using a separate XML object, most notably the additional parser error checking available, but in reality it's up to the developer and the specific situation to make that choice. Here are syntax examples for both options:
-- set the data provider to a XML string directly
tSprite.dataProvider = tString
-- set the data provider to a XML object
tSprite.dataProvider = tXMLObject
Where again, I'm assuming that tSprite is a reference to the sprite showing the tree component and tString is a variable containing the XML string shown in step 1 above. Once you've done that your tree component should now be rendering the XML data we've provided on stage.
GOTCHA: it is very important to remember something about Flash components and that's that you'll typically need to wait through at least one frame of rendering the sprite before you can get/set various properties. In the case of the tree component the sprite won't know it's a tree view until the first rendering is made, if you attempt to set the dataProvider property before that occurs then you'll get a script error ("property not found"). This means that the earliest you can set the dataProvider property is on the first enterFrame event for that sprite, you cannot set this property on beginSprite nor on the first prepareFrame event. In my example file I set this property on exitFrame but only the first time through.
4. Add/Remove Branches and Leaves as Needed
Once you have a working tree component using the steps above you can then also add and remove branches and leaves at run-time as needed. Once again I'm only going to discuss a few of the simpler ways of doing this, if you're interested in further details then please consult the Flash documentation for the Tree View component.
To add a new branch we simply call the addTreeNode() method off the sprite reference we've already used. For example, imagine that we want to add another top-level branch to our example case above, say another state like Utah. To do this we must first add the new tree node then make sure to set that node to be a branch so that it can contain sub-nodes which I've also referred to as "leaves". Here is a code example that does this:
The above has now created a new branch in the XML display with a label of "Utah", but please note than when using addTreeNode() you will add the new node at the end of the display. If you want to insert a new node in a particular location then you must use the addTreeNodeAt() method instead. Also worth noting is that in this example case we've created the branch at the top-level because we called the addTreeNode() method off the sprite, but sub-branches can also be created by continuing to call addTreeNode() off deeper level branches, for example:
The above will then create yet another new branch below the first one ("Utah") created above. The point being that once you reference a particular node within your structure you can begin adding other branches or leaves below it. Similarly we can also add new "leaves" to a node, for example:
tNewLeaf = tNewNode.addTreeNode("Salt Lake City")
This would then add a new "leaf" (or "city") underneath the branch that was referenced. In this case please notice that setIsBranch() is never called, that's because all nodes default to being "leaves" and not "branches" so that's not necessary in this case as we're not expecting the "Salt Lake City" entry to be expandable itself. Finally it's good to understand that there are also multiple ways to get a reference to a particular node in your structure, simply referring to the sprite references the top-level node, you can trap references to newly created nodes after calling addTreeNode() and addTreeNodeAt(), or ultimately you can use the getTreeNodeAt() method to get the Nth sub-node of any other node. For example, we would use getTreeNodeAt() if we wanted to add a new entry under California:
