TreeView is an Asset Xtra. Unlike Scripting Xtras, Asset Xtras can be manipulated using the score and cast windows, and their properties can be adjusted through scripting, just like Director's built-in media types. You create a new TreeView cast member by highlighting an empty cast slot and choosing Insert -> Tabuleiro Xtras -> TreeView from Director's menu. If you drag the newly created cast member onto the stage you will see a TreeView tree sprite with one default node called the root node. Resize the sprite to the size you want the viewable area of the tree to be. Create an approximately 200 x 200 pixel sprite to practice.
Initial appearance of a TreeView sprite:
In TreeView terms, nodes are the branches of the tree. A parent node contains other nodes. A child node is contained by a parent node. A node can be the child of a higher-up parent node, and have children of its own at the same time. The only node that is not a child node of some other node is the root node because it is at the top of the tree.You fill a tree by adding nodes to it, one at a time and specifying their properties, such as the node text and icon. When a node is created it is assigned a nodeID, which is a unique number.
This is the code that created the tree above, written as a behavior attached to the TreeView sprite:
on beginSprite me
makeSmallTree()
end
on makeSmallTree
root = sprite(me.spritenum).getRootNodeXTV( )
sprite(me.spritenum).setNameXTV(root,"Animals")
birdsNodeID = sprite(me.spritenum).addChildXTV( root, 1, 0)
sprite(me.spritenum).setNameXTV(birdsNodeID,"Birds")
fishNodeID = sprite(me.spritenum).addChildXTV( root, 1, 0)
sprite(me.spritenum).setNameXTV(fishNodeID,"Fish")
tunaNodeID = sprite(me.spritenum).addChildXTV( fishNodeID, 1, 0)
sprite(me.spritenum).setNameXTV(tunaNodeID,"Tuna")
bassNodeID = sprite(me.spritenum).addChildXTV( fishNodeID, 1, 0)
sprite(me.spritenum).setNameXTV(bassNodeID,"Bass")
end
The setNameXTV method sets the text of the node. The addChildXTV method creates a new node. Note that by specifying the fishNodeID as the parent in the last two addChildXTV lines, new nodes were created under node "Fish" instead of directly under the root node "Animals".
The simple tree above uses the default red box node icon. To assign graphics from your Director cast to nodes, see the Icon Section. The background of a TreeView sprite is transparent, and the sprite has no bounding outline, which allows you to place graphics behind it and to frame it any way you like.You can also add scrollbars, configure the tree layout and change the font.
When the user rolls over or clicks on a node's icon, the action generates a callback message. You trap and act on the callback message in your code by creating a movie script with a designated name to handle the type of message you want to trap. For instance if you wanted to be informed of the user's single clicks on tree nodes you would create the following handler in a movie script:
on treeViewSingleClick refcon, nodeid, whichPart, spriteChannel
-- refcon: internal treeview id of tree sprite that was clicked
-- id: nodeID of the node that was clicked
-- whichPart: area of node that was clicked
-- 1 = icon area, 2 = text area
-- spriteChannel: sprite number of tree sprite
--
-- Your code below
--
put sprite(spriteChannel).getNameXTV(nodeid) into field "choice"
end
Note: the refcon is an internal TreeView number assigned to the TreeView sprite. It is not the same as the sprite number. You can use it to distinguish between different trees assigned to the same sprite channel in different frames of the movie:
sprite(3).setRefconXTV (5)
TREEVIEW BEHAVIORS
The TreeView demonstration movie contains drag and drop behaviors that can build a tree from a hierarchy specified in a field, build a tree from a folder on the user's hard drive or build thumbnails from a folder of images. Using the behaviors does not require any Lingo scripting. Simply drag one of the behaviors to a TreeView sprite and fill out the parameters. Each behavior contains full documentation at the top of the script that explains how to fill out any parameter you may not understand.
The TreeView behaviors were intended for use by Lingo novices. In order to be as general-purpose as possible they offer the ability to customize every TreeView property that exists. The trade-off for this degree of flexibililty is slower performance when creating the tree, since all possible properties must be set for each tree node.
If you are an experienced Lingo programmer, and you are interested in displaying the tree initially as quickly as possible, you should use the makeSmallTree example as a starting point and keep the following perfomance tips in mind:
- Lingo repeat loops lock user interaction out. If you are creating a very large tree (1000's of nodes) you may want to temporarily increase the frame rate and use an exitFrame handler that adds one node per frame, rather than a repeat loop.This method allows the user to continue working while the tree is being generated. If you do not want the user to interact with the tree until it has finished building, keep the tree sprite off stage (negative locV) until it has completely built, and then move the sprite onto the stage.
- If you do choose to use a repeat loop, remove any Lingo lines from the loop that do not have to execute every time a node is created. Avoid doing any text manipulation if possible such as altering strings, or the text inside fields or text members. These are the slowest operations in Lingo and will bog down the loop.
- Set the least number of properties possible at the node level. Take advantage of treewide commands like getGlobalIconIDXTV and setAllNodesIconIDXTV to set properties that will be the same for all nodes. If you are going to take the default for a property, for instance if you are going to use the system font for every tree node, do not set that property when creating the node.
- Do not set a variable to the result of addChildXTV unless you need the variable farther down in the handler to add properties or children to the node. The functions getNumChildrenXTV , getNthChildXTV , findChildXTV , getParentXTV and getNameXTV will help you find any node by name later on. In particular, do not create a global variable for each nodeID of the tree. This is unnecessary and may use up all of your variable space.
REGISTRATION
The unregistered version displays a registraton warning, and is fully functional for evaluation purposes.
If you have purchased TreeView Xtra you received a serial number that can be used to remove the warning. Make the following registration call once the first time that each TreeView sprite appears in the score. Make sure you do it before using any other TreeView commands on the sprite. Put the code in a sprite script on theTreeView sprite on stage::
on beginSprite me
sprite(me.spritenum).setMagicXTV("48dkd2929")
-- your registration number is the second parameter
end