When a user action occurs over one of TreeView's nodes you can choose to have a message sent to a callback handler. The callback handler for each event must use the designated name for that event's handler and can reside in a sprite, frame, cast member or movie type of script. When a TreeView event occurs, such as "single click" it is sent to the script levels in the following order, until it hits a level containing a callback handler for it.
sprite --> cast member --> frame --> movie
The designated callback handlers are as follows:
on treeViewSingleClick refcon, nodeId, whichPart, spriteChannel
end
Called when the user clicks within the bounding box of a node. Detects event on icon or name.
on treeViewDoubleClick refcon, nodeId, whichPart, spriteChannel
end
Called when the user double-clicks within the bounding box of a node. Detects event on icon or name.
on treeViewMouseEnter refcon, nodeId, whichPart, spriteChannel
end
Called once when the mouse enters the bounding box of the node, if the mouse is up. Detects events on expander, icon, name and whitespace.
on treeViewMouseExit refcon, nodeId, whichPart, spriteChannel
end
Called once when the mouse leaves the bounding box of the node, if the mouse is up. The whichpart parameter is not used and always reports whitespace.
on treeViewMouseMove refcon, nodeId, whichPart, spriteChannel
end
Called while the mouse is within the bounding box of a node. Detects events on expander, icon, name and whitespace.
on treeViewMouseDown refcon, nodeId, whichPart, spriteChannel
end
Called when the user mouses down within the bounding box of a node. Detects events on expander, icon, name and whitespace.
Each callback handler receives the same information about the user event:
refcon: custom number that is not a sprite number but is used to distinguish between TreeView sprites
id: node ID of node user action happened on
whichPart: 0: expander area of node 1: icon area of node, 2: text area of node 3: whitespace within node bounding box
The SingleClick and DoubleClick events only report icon or text for whichpart.
channel: sprite number of the treeview sprite the action happened on
To customize which handlers should be activated, use setAllNodesMouseStatusRequestXTV to set event-handling tree-wide, or setMouseStatusRequestXTV to set it per individual node. Both SingleClick and DoubleClick are initially on by default. Note that the mouseEnterFlag argument of those methods turns on both the MouseEnter and MouseExit callback handlers.If both SingleClick and DoubleClick are enabled, the first click of a user's double-click action triggers the SingleClick callback.
All of the programming of TreeView sprite interactivity happens inside of a callback handler. You can use the information passed in to the handler to read or change tree properties in response to user actions.
USING CALLBACK HANDLERS IN BEHAVIORS
When a TreeView callback handler is included in a behavior, it passes back a parameter in the first position that is a refcon reference, not a reference to the behavior.The parameter that is usually "me" instead contains a reference to the TreeView refcon that is receiving the event. That means that a TreeView callback handler inside a behavior will not know about the behavior's properties. They will all come up as Void. To work around this, call another method inside the behavior, and pass it any information it may need that came from the TreeView callback handler. Do something like this:
property myProp
on beginSprite me
myProp = 8
end
on treeViewSingleClick refcon, nodeID, whichpart,spriteChan
-- myProp will be Void
sendSprite(spriteChan,#anotherHandler,refcon,nodeID,whichpart)
end
on anotherHandler me,refcon,nodeID,whichpart
-- "me" the first param, refers to behavior again
-- so myProp will be recognized, and we still have the values returned
-- from the callback handler
--
if myProp = 8 then
alert(string(nodeID))
end if
end
IMPORTANT NOTE
You cannot do a "go frame" from inside a callback handler to a new frame that does not have the same TreeView sprite in the same channel or Director will crash. The same thing will happen with "go movie". One workaround is to keep the TreeView sprite in the same channel throughout the movie and move it offstage in the frames where it should not show. Another workaround is to set a flag in the callback handler and have an exitframe handler execute the "go" when the flag changes.
EXAMPLE
Here is a simple example of callback handling code:
on treeViewDoubleClick refcon, id, whichPart,channel
nodeID = id
treesprite = channel
-- Retrieve the path to an application stored in the node's
-- user storage area previously, with setUserStringXTV,
-- and launch it
--
programLaunchPath = sprite(treesprite).getUserStringXTV(nodeID,0)
open programLaunchPath
end