Subject: Thunderdome: FW: Good citizen LiveTabs
Date: Thu, 6 Dec 2001 09:47:58 -0800
From: "Henry Y. Lee" <monkeyboy@adobe.com>
To: "External Thunderdome" <external_thunderdome@adobe.com>

This is a good read for anybody making Live Tabs right now.

-----Original Message-----
From: Ralf Berger
Sent: Thursday, December 06, 2001 7:46 AM

For a LiveTab to play nice with the rest of LM it needs to do a few things.

In general you want to have a single function in your _root that executes
the automation scripts on the current composition. We'll call this function
the "doit()" function.

Check to see if there is a composition.

Before your doit() function does anything it should check that there is in
fact a composition available to doit on.

This will do the trick;

if (application.compositions.length) {

Colin can tell us if

if (application.currentComposition) {

would work also.

Your LiveTab action should work on multiple object selections.

You want to get the list of currently selected objects into an array and
then walk that array and process each object.

var objects = application.currentComposition.selection;

for (i=0; i < objects.length; i++)
    {
    var object = objects[i];
        // do stuff to object
    }

Don't deselect the objects in the process.

In the process of walking the selected objects and modifying stuff you will
end up changing the object selection that the user sees. To prevent this you
need so save and then restore the selection in your doit() function.

application.currentComposition.saveSelection();

    // do my stuff

application.currentComposition.restoreSelection();
Add it's action to the undo stack.

You're LiveTab action should be undoable. This doesn't come for free. You do
this by calling beginUndoAction and completeUndoAction in your doit()
function.

beginUndoAction(application.currentComposition);

     // do my stuff

completeUndoAction(application.currentComposition);

Update your controls based on the currently selected object.

If your LiveTab modifies an attribute of an object it's usually a good idea
to read the current value of that attribute for the selected object and
update your controls to reflect this. This is how all the LM palette
controls work and you're controls should work the same way.

To do this you should add code to the _root.onEnterFrame event handler to
get the currently selected object (or first selected object) and test the
attribute your controls care about.

 if (application.compositions.length)
    {
    objects = application.currentComposition.selection;

    if (objects.length)
        {
        var object = objects[0];

            // check the objects attributes that you care about and update
your controls

This code can be throttled back so that it doesn't check on every frame
time, as that's pretty wasteful, by adding a counter that only does this
every second or so. The counter is declared in _root.onLoad as counter = 0;
and then incremented and tested in the _root.onEnterFrame.

- Ralf