Volume Number: 18 (2002)
Issue Number: 02
Column Tag: QuickTime Toolkit

The Flash II: Revenge of the Trickster

by Tim Monroe

Using Wired Actions with Flash Tracks

In the previous QuickTime Toolkit article, we got a general overview of Macromedia's Flash multimedia development environment and saw some ways to work with Flash content inside of QuickTime applications. We learned that QuickTime 4 and later provide a Flash movie importer and a Flash media handler that allow us to import and display Flash movies as Flash tracks in QuickTime movies. We developed a simple parser that allows us to read through a Flash file to get some useful information about the Flash movie contained in the file, such as whether it's an autoplay movie and whether the movie should be played full-screen. Finally, we got a taste for working with the public APIs provided by the Flash media handler.

In this article, we're going to see how to work with wired actions and Flash tracks. There are two general sorts of capabilities we want to explore here. First, we want to see how to embed wired actions in a Flash track, so that (for instance) clicking a button in the Flash track sends one or more wired actions to some other track in the QuickTime movie. Recall that QuickTime provides well over a hundred different wired actions, which can be targeted variously at sprite tracks, at individual sprites within sprite tracks, at QuickTime VR tracks, at hotspots within QuickTime VR tracks, at text tracks, at the QuickTime movie itself, and indeed at external movies and objects within those external movies. So it's very useful to know how to trigger those actions with the interactive behaviors of the Flash track. Indeed, this ability is a necessity for the kind of Flash and QuickTime integration that is all the rage nowadays: using a Flash track and its panoply of interactive elements (buttons, menus, sliders, text boxes, and so forth) to control the operation of a QuickTime track. Figure 1 shows a simple example of using buttons in a Flash track to control the pan, tilt, and zoom parameters of a QuickTime VR movie.

Figure 1: A Flash track controlling a QuickTime VR track

The second way of using wired actions with Flash tracks is essentially the reverse of the first: instead of sending wired actions from a Flash track to some other kind of track, we might want to send wired actions from other tracks to a Flash track. For instance, user actions in a QuickTime VR node (say, rolling the mouse over a hot spot) might trigger a wired action that tells a Flash track to create a new movie clip. In a simple case, the movie clip might be a rectangle with some text in it whose bottom right corner is anchored at the current mouse location. This would give a nice pop-up label (or "tool tips") capability to the QuickTime VR movie, as illustrated in Figure 2.

Figure 2: A pop-up label provided by a Flash track

In this article, we're going to investigate these two techniques — embedding wired actions in Flash tracks and sending wired actions to Flash tracks. Our sample application once again is called QTFlash, and its Test menu is shown in Figure 3.

Figure 3: The Test menu of QTFlash

In the previous article we saw how to handle all of these menu items but the last one, which we'll focus on here.

Let's begin by taking a look at the QuickTime wired actions that can be targeted at a Flash track. When the Flash media handler was first introduced, in QuickTime 4, five new wired actions were added:

enum {
   kActionFlashTrackSetPan                        = 10240,
   kActionFlashTrackSetZoom                       = 10241,
   kActionFlashTrackSetZoomRect                   = 10242,
   kActionFlashTrackGotoFrameNumber               = 10243,
   kActionFlashTrackGotoFrameLabel                = 10244
};

The first three actions allow us to zoom in on a Flash track and to pan around inside a zoomed Flash track. The kActionFlashTrackSetZoom action takes one parameter, which specifies the percentage of the current movie window to zoom. This parameter is identical to the parameter passed to the FlashMediaSetZoom function (which we discussed in the previous article): to double the magnification, we pass a factor of 50. To halve the magnification, we pass a factor of 200. If, instead of zooming in on the center of the Flash track, we want to zoom in on some other portion of the Flash track, we can use the kActionFlashTrackSetZoomRect action. This action needs four parameters, which are (in order) the left, top, right, and bottom of the rectangle to zoom. Once we're zoomed in on some portion of the Flash track, we can use the kActionFlashTrackSetPan action to pan it horizontally and vertically. This action takes two parameters, which (just as with the FlashMediaSetPan function) specify the percentages of the movie window width and height to pan.

The final two original Flash track wired actions set the current movie time to correspond to a particular frame in the Flash track (that is, to go to that frame in the Flash track). The kActionFlashTrackGotoFrameNumber action jumps to the movie time that corresponds to the Flash track frame number specified in the single parameter atom in the action atom. The kActionFlashTrackGotoFrameLabel action jumps to the movie time that corresponds to the Flash track frame whose frame label is specified in the single parameter atom; in this case, the parameter atom contains a C string.

QuickTime 5 introduced an updated Flash media handler (capable of handling Flash files up to version 4) along with two new wired actions:

enum {
   kActionFlashTrackSetFlashVariable           = 10245,
   kActionFlashTrackDoButtonActions            = 10246
};

QuickTime 5 also added one new wired action operand:

enum {
   kOperandFlashTrackVariable                  = 9216
};

We can use the kActionFlashTrackDoButtonActions action to execute the actions associated with a particular state transition for a button in a Flash track. (See the previous article for a discussion of button state transitions.) This action takes three parameters, which specify the path to the button, the button ID, and the desired button state transition. We know how to specify a button state transition, using constants like kOverDownToOverUp, which we encountered previously. The button ID is simply the character ID stored in the button data in the Flash file. The tricky part here is the button path. Objects in a Flash file are arranged in a hierarchical structure, beginning with the root object, which is driven by the main timeline. The root object can also contain movie clips, which (as we've seen) are essentially Flash movies embedded within Flash movies. Movie clips can be embedded within movie clips, to an arbitrarily deep level.

To refer to an object in a Flash file, we must provide a path to that object. The button path specified as the first parameter to the kActionFlashTrackDoButtonActions action must be an absolute path beginning with the root object and containing the names of any movie clips the button is embedded within. In the simplest case, we can pass an empty path (that is, the string "") to refer to the root object. If a button is contained in the movie clip whose name is "buttonClip", we could pass the path "/buttonClip". If the buttonClip movie clip contained yet another movie clip named "yellow", we could target a button in that second movie clip using the path "/buttonClip/yellow".

We can use the kActionFlashTrackSetFlashVariable wired action to set the value of a Flash variable in a Flash track, and we can use the kOperandFlashTrackVariable operand to get the value of a Flash variable. A Flash variable consists of two parts: a name and a value. The name is a string, and the value can be either a string or a number. To specify a variable, we need to provide its name and the path to the object it is attached to. (A variable can be attached to any object, including the root object.) The kActionFlashTrackSetFlashVariable action requires four parameter atoms: (1) the path to the object to which the variable is attached, (2) the variable name, (3) the new variable value, and (4) a Boolean value that indicates whether to change the focus to the object attached to the variable.

Getting and setting Flash variables using wired actions is a simple and efficient way to establish interactions between Flash tracks and other QuickTime tracks that can be wired (currently, sprite, text, and QuickTime VR tracks). For instance, the hot spot in Figure 2 can be wired to trigger a kActionFlashTrackSetFlashVariable action that sets some variable to a particular value; an ActionScript in the Flash track can then periodically test that variable to see which text box to pop up.

Here's a particularly nice trick with Flash variables: when you create a text box in a Flash movie, you can configure it as a dynamic text box, which displays text that can change dynamically (without the user having to type into the text box). A dynamic text box is automatically associated with a variable, which we specify in the Text Option panel (shown in Figure 4).

Figure 4: The Text Options panel for a dynamic text box

As you can see, the topmost pop-up menu sets the text box to be dynamic, and the name of the variable associated with the text box is set to "textVar1". Now here's the fun part: we can get and set the text displayed in the text box by getting and setting the value of the variable textVar1. Listing 1 shows a simple function that builds an atom container with an event atom that changes the text to "Caffe Macs" on a hot spot roll-over.

Listing 1: Setting Flash text with a hot-spot rollover

OSErr QTFlash_CreateVarAction (QTAtomContainer *theActions)
{
   QTAtom          myActionAtom = 0;
   char            myPath[] = "";
   char            myVarName[] = "textVar1";
   char            myVarValue[] = "Caffe Macs";
   Boolean         myFocus = false;
   OSErr           myErr = noErr;

   myErr = QTNewAtomContainer(theActions);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddQTEventAndActionAtoms(*theActions, 
            kParentAtomIsContainer, kQTEventMouseEnter, 
            kActionFlashTrackSetFlashVariable, &myActionAtom);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddTrackTargetAtom(*theActions, 
            myActionAtom, kTargetTrackType, 
            (void *)FlashMediaType, 1);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddActionParameterAtom(*theActions, 
            myActionAtom, 1, strlen(myPath) + 1, myPath, NULL);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddActionParameterAtom(*theActions, 
            myActionAtom, 2, strlen(myVarName) + 1, myVarName, 
            NULL);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddActionParameterAtom(*theActions, 
            myActionAtom, 3, strlen(myVarValue) + 1, myVarValue, 
            NULL);
   if (myErr != noErr)
      goto bail;

   myErr = WiredUtils_AddActionParameterAtom(*theActions, 
            myActionAtom, 4, sizeof(myFocus), &myFocus, NULL);

bail:
   return(myErr);
}

QTFlash_CreateVarAction uses a few of the wired action utility functions we developed in earlier articles to set the event and action types, to set the target track (namely, to the first Flash track in the movie), and to set the four action parameters. It returns an atom container that can be inserted into the appropriate track. We don't yet know how to wire QuickTime VR movies, however, so you'll have to wait a bit to test this code out or else attach it to a sprite or text object (which we have learned to wire).

Let's turn now to our second main task, learning how to insert wired actions into a Flash track. The basic idea is quite simple: we can add QuickTime wired actions to a Flash data stream (that is, the data in a Flash track or a Flash file) by adding an action of type sactionWiredActions to an action list in that stream. Recall that actions can be found in two locations in a Flash file: (1) in the action list associated with a button state transition; and (2) in the action list associated with a tagged data block of type stagDoAction. Let's call these button actions and frame actions, respectively. A button action list is executed immediately when the specified state transition occurs. A frame action is executed immediately after the specified frame is rendered. For button actions and frame actions alike, we add a wired action by adding an action of type sactionWiredActions to the associated action list. The data in that action is simply an atom container that holds the appropriate event, action, target, and parameter atoms.

It turns out, however, that this simple recipe is a tad complicated to actually implement. We need to parse through the Flash data stream to find the button or frame that we want to wire, and then we need to parse through the button data or frame data to find the associated action list. Finally, we need to insert a new action into the list and then update all the relevant offsets and block sizes stored in the data stream. No one of these tasks is very complicated by itself, but accomplishing them all will occupy us for a while. For the moment, we'll focus on adding some wired actions to a button in a Flash track. The source code for QTFlash also shows how to add wired actions to a frame.

Handling the Menu Item

Let's begin at the highest level. When the user selects the "Add Wiring To Button" menu item, QTFlash calls the QTFlash_AddWiredActionsToFlashMovie function, passing in the identifier for the movie in the topmost movie window. This function starts off by calling GetMovieIndTrackType to get the first Flash track in the movie, and then it calls GetTrackMedia to retrieve the media for that track. Our current goal is to get the media data, which is the Flash data stream. We do this by calling GetMediaSample. Before we can call GetMediaSample, however, we need to find the media time at which the Flash track begins, like this:

myTrackOffset    = GetTrackOffset(myTrack);
myMediaTime      = TrackTimeToMediaTime(myTrackOffset, myTrack);

So we can get the Flash data stored in the Flash track like this:

myErr = GetMediaSample(myMedia, mySample, 0, NULL, 
            myMediaTime, NULL, &mySampleDuration, 
            (SampleDescriptionHandle)myFlashDesc, NULL, 1, NULL, 
            &mySampleFlags);

If we happen to know the character ID of the button that we want to wire, we can then call the application function QTFlash_SetWiredActionsToButton to attach an existing wired atom container (myActions) to that button:

myErr = QTFlash_SetWiredActionsToButton(mySample, myButtonID, myActions);

QTFlash, however, assumes that we want to attach the wired actions to the first button in the Flash track, so we'll call the LocateFirstButton function to find the ID of that button. LocateFirstButton is defined in Listing 2.

Listing 2: Finding the first Flash button in a data stream

OSErr LocateFirstButton (Handle theStream, long *theButtonID)
{
   if ((theStream == NULL) || (theButtonID == NULL))
      return(paramErr);

   *theButtonID = 0;

   InitParser();

   gFlashParserData.m_theData = theStream;

   gFlashParserData.m_fileBuf = (U8 *)*theStream;
   
   SkipHeaderBlock();
      
   gFlashParserData.m_fileStart = gFlashParserData.m_filePos;
   
   ParseTags(false, theButtonID);
   
   return(noErr);
}

There's nothing very intricate about LocateFirstButton; it simply sets initializes our Flash parser and then traverses the data stream looking for a tagged data block of type stagDefineButton2. (Flash also supports buttons of type stagDefineButton, but they respond only to mouse clicks and cannot be configured to trigger actions on any of the other state transitions.) The main work here is accomplished by the ParseTags function, defined in Listing 3.

Listing 3: Walking the data stream for a button

void ParseTags (Boolean isSprite, long *theButtonID)
{
   BOOL         isAtEnd;
   U16          myCode;
   U32          myTagEnd;

   if (isSprite) {
      U32 myTagId = (U32)GetWord();
      U32 myFrameCount = (U32)GetWord();
   } else {
      // set the position to the start position
      gFlashParserData.m_filePos = 
            gFlashParserData.m_fileStart;
   }

   // initialize the end of frame flag
   isAtEnd = false;

   // loop through each tagged data block
   while (!isAtEnd) {
      // get the current tag and tag-end position
      myCode = GetTag();
      myTagEnd = gFlashParserData.m_tagEnd;

      switch (myCode) {
         case stagEnd:
            // we reached the end of the file
            isAtEnd = true;
            break;

         case stagDefineButton2:
            *theButtonID = (U32)GetWord();
            isAtEnd = true;
            break;

         case stagDefineSprite:
            ParseTags(true, theButtonID);
            break;

         default:
            break;
      }

      // increment past the tag.
      gFlashParserData.m_filePos = myTagEnd;
   }
}

Once we've called QTFlash_SetWiredActionsToButton, we want to replace the original media sample in the Flash track with our updated media sample. This is code we've seen before, so we don't need to investigate it in detail. Listing 4 shows our complete definition of QTFlash_AddWiredActionsToFlashMovie.

Listing 4: Adding wired actions to a Flash track

void QTFlash_AddWiredActionsToFlashMovie (Movie theMovie)
{
   Track                            myTrack = NULL;
   Media                            myMedia = NULL;
   TimeValue                        myTrackOffset;
   TimeValue                        myMediaTime;
   TimeValue                        mySampleDuration;
   TimeValue                        mySelectionDuration;
   TimeValue                        myNewMediaTime;
   FlashDescriptionHandle           myFlashDesc = NULL;
   Handle                           mySample = NULL;
   short                            mySampleFlags;
   Fixed                            myTrackEditRate;
   QTAtomContainer                  myActions = NULL;
   long                             myButtonID = 0L;
   OSErr                            myErr = noErr;

   if (theMovie == NULL)
      return;

   // get the first Flash track from the movie
   myTrack = GetMovieIndTrackType(theMovie, 1, FlashMediaType, 
            movieTrackMediaType);
   if (myTrack == NULL)
      goto bail;

   // get first media sample in the Flash track
   myMedia = GetTrackMedia(myTrack);
   if (myMedia == NULL)
      goto bail;

   myTrackOffset = GetTrackOffset(myTrack);
   myMediaTime = TrackTimeToMediaTime(myTrackOffset, myTrack);

   // allocate some storage to hold the sample description for the Flash track
   myFlashDesc = (FlashDescriptionHandle)NewHandle(4);
   if (myFlashDesc == NULL)
      goto bail;

   mySample = NewHandle(0);
   if (mySample == NULL)
      goto bail;

   myErr = GetMediaSample(myMedia, mySample, 0, NULL, 
            myMediaTime, NULL, &mySampleDuration, 
            (SampleDescriptionHandle)myFlashDesc, NULL, 1, NULL, 
            &mySampleFlags);
   if (myErr != noErr)
      goto bail;

   // add button actions; find the first button
   myErr = LocateFirstButton(mySample, &myButtonID);
   if ((myErr != noErr) || (myButtonID == 0))
      goto bail;

   // create an action container for button actions
   myErr = QTFlash_CreateButtonActionContainer(&myActions);
   if (myErr != noErr)
      goto bail;

   // add button actions to sample
   myErr = QTFlash_SetWiredActionsToButton(mySample, 
               myButtonID, myActions);
   if (myErr != noErr)
      goto bail;

   // replace sample in media
   myTrackEditRate = GetTrackEditRate(myTrack, myTrackOffset);
   if (GetMoviesError() != noErr)
      goto bail;

   GetTrackNextInterestingTime(myTrack, nextTimeMediaSample | 
            nextTimeEdgeOK, myTrackOffset, fixed1, NULL, 
            &mySelectionDuration);
   if (GetMoviesError() != noErr)
      goto bail;

   myErr = DeleteTrackSegment(myTrack, myTrackOffset, 
            mySelectionDuration);
   if (myErr != noErr)
      goto bail;

   myErr = BeginMediaEdits(myMedia);
   if (myErr != noErr)
      goto bail;

   myErr = AddMediaSample(   myMedia,
                     mySample,
                     0,
                     GetHandleSize(mySample),
                     mySampleDuration,
                     (SampleDescriptionHandle)myFlashDesc, 
                     1,
                     mySampleFlags,
                     &myNewMediaTime);
   if (myErr != noErr)
      goto bail;

   myErr = EndMediaEdits(myMedia);
   if (myErr != noErr)
      goto bail;

   // add the media to the track
   myErr = InsertMediaIntoTrack(myTrack, myTrackOffset, 
         myNewMediaTime, mySelectionDuration, myTrackEditRate);
   if (myErr != noErr)
      goto bail;

bail:
   if (myActions != NULL)
      (void)QTDisposeAtomContainer(myActions);

   if (mySample != NULL)
      DisposeHandle(mySample);

   if (myFlashDesc != NULL)
      DisposeHandle((Handle)myFlashDesc);
}

So our work will be finished once we've defined the function QTFlash_SetWiredActionsToButton.

Finding Actions for Button State Transitions

As we'll see in greater detail later, the button actions contained in a data block of type stagDefineButton2 are grouped into lists according to the button state transitions that trigger them. However, a wired atom container (such as the one created in QTFlash by a call to QTFlash_CreateButtonActionContainer) might contain several event atoms. The event IDs of these atoms can be any of the nine button state transition constants we encountered in the previous article:

#define kIdleToOverUp               (1L << bsIdleToOverUp)
#define kOverUpToIdle               (1L << bsOverUpToIdle)
#define kOverUpToOverDown           (1L << bsOverUpToOverDown)
#define kOverDownToOverUp           (1L << bsOverDownToOverUp)

#define kOverDownToOutDown          (1L << bsOverDownToOutDown)
#define kOutDownToOverDown          (1L << bsOutDownToOverDown)
#define kOutDownToIdle              (1L << bsOutDownToIdle)

#define kIdleToOverDown             (1L << bsIdleToOverDown)
#define kOverDownToIdle             (1L << bsOverDownToIdle)

For each of these nine button state transitions, we need to extract from the wired atom container the event atoms of that type and then add the extracted atoms into the action list for the specified button. This is precisely what QTFlash_SetWiredActionsToButton accomplishes, as you can see in Listing 5.

Listing 5: Finding actions by event type

static OSErr QTFlash_SetWiredActionsToButton 
      (Handle theSample, long theButtonID, 
            QTAtomContainer theActions)
{
   short                  myIndex;
   QTAtomContainer      myActionContainer;
   QTAtom                  myEventAtom = 0;
   QTAtomID               myEventID;
   OSErr                  myErr;

   myErr = QTNewAtomContainer(&myActionContainer);
   if (myErr != noErr)
      goto bail;

   for (myIndex = 0; myIndex < (sizeof(gFlashConditions) / 
            sizeof(long)); myIndex++) {
      myEventID = gFlashConditions[myIndex];

      myEventAtom = QTFindChildByID(theActions, 
            kParentAtomIsContainer, kQTEventType, myEventID, 
            NULL);
      if (myEventAtom != 0) {

         myErr = QTFlash_CopyChildren(theActions, myEventAtom, 
            myActionContainer, kParentAtomIsContainer);
         if (myErr != noErr)
            goto bail;

         QTFlash_SetWiredActionToButton(theSample, theButtonID, 
            myEventID, myActionContainer);

         myErr = QTRemoveChildren(myActionContainer, 
            kParentAtomIsContainer);
         if (myErr != noErr)
            goto bail;
      } else {
         QTFlash_SetWiredActionToButton(theSample, theButtonID, 
            myEventID, NULL);
      }
   }

   myErr = QTDisposeAtomContainer(myActionContainer);

bail:
   return(myErr);
}

We won't dissect this function in detail. Essentially, it looks into the atom container theActions for actions to be triggered by the nine distinct button state transitions. For any button state transitions that have actions, it extracts the appropriate event and action atoms into a new atom container and calls QTFlash_SetWiredActionToButton. Note that, if theActions does not contain an action for a specific button transition state, then QTFlash_SetWiredActionsToButton calls QTFlash_SetWiredActionToButton with the last parameter set to NULL; this is a signal to QTFlash_SetWiredActionToButton to remove any wired actions of that kind from the target Flash data stream.

Reading the Button Data

QTFlash_SetWiredActionToButton is the real workhorse here. Its job is to parse the data associated with a specific button and to add an action of type sactionWiredActions that is to be triggered by a specific button state transition. So, to understand QTFlash_SetWiredActionToButton, we need to understand the format of the data in a tagged data block of type stagDefineButton2. Figure 5 gives a picture of how the data in that block is arranged.

Figure 5: Data for a block of type stagDefineButton2

The tagged data block begins with a tag header, of course, whose tag ID is stagDefineButton2. Immediately following the tag header we find a 16-bit character ID and an 8-bit menu flag (which determines whether the button operates as a push button or a menu button). Then we encounter a 16-bit integer that is the offset from the current location in the data stream to the first button action condition. Each button action condition specifies one or more actions that are to be executed on a specific button state transition. Between the offset word and the button action conditions are one or more button records, which specify the images to be used for each of the three button states. For present purposes, we don't need to know the structure of these button records, since we'll just be skipping over them (using the offset word) when we process the tagged data block.

So let's get started. QTFlash_SetWiredActionToButton is passed four pieces of information, which are the Flash track media sample (that is, the Flash data stream), the character ID of a button, an event ID (that is, a button state transition constant), and an atom container of wired actions for that button and button state transition. First we want to tell our parser what data to use:

gFlashParserData.m_theData = theSample;

Then we want to find the byte offset in that data stream of the beginning of the tagged data block that holds the information about the specified button. We'll call another QTFlash function to get that offset:

myOffset = GetOffsetForButton(theButtonID);

GetOffsetForButton is easy enough to write; once again, it uses the parsing code we developed in the previous article (Listing 6).

Listing 6: Finding a button in a Flash data stream

U32 GetOffsetForButton (long theButtonID)
{
   BOOL       isAtEnd = false;
   U16         myCode;
   U32         myTagEnd;
   U32         myTagID;

   gFlashParserData.m_fileBuf = 
            (U8 *)*gFlashParserData.m_theData;

   // set the position to the start position
   SkipHeaderBlock();

   // loop through each tagged data block
   while (!isAtEnd) {
      // get the current tag and tag-end position
      myCode = GetTag();
      myTagEnd = gFlashParserData.m_tagEnd;

      switch (myCode) {
         case stagEnd:
            // we reached the end of the file
            isAtEnd = true;
            break;

         case stagDefineButton2:
            myTagID = (U32)GetWord();
            if (myTagID == theButtonID)
               return(gFlashParserData.m_tagStart);
            break;

         default:
            break;
      }

      // increment past the tag
      gFlashParserData.m_filePos = myTagEnd;
   }

   return(0);
}

Once we've determined the starting position of the button data block, we need to pass that information to our parser and then read past the tag header:

gFlashParserData.m_fileBuf = (U8 *)*theSample;
gFlashParserData.m_filePos = myOffset;
(void)GetTag();

At this point, gFlashParserData.m_filePos points to the first byte in the button data. Let's skip over the character ID and the menu flag, to position our data pointer at the offset field. We'll need to remember the location of this field for later, so we'll store it in the variable myOffsetLocation.

gFlashParserData.m_filePos += sizeof(U16);   // step over character ID
gFlashParserData.m_filePos += sizeof(U8);    // step over menu flag

myOffsetLocation = gFlashParserData.m_filePos;
myButtonRecordLength = 0;
myActionCount = 0;

We also want to retrieve the value in the offset field, so we know how far ahead in the data stream to jump to reach the first button action condition:

myOffset = (U32)GetWord();

Now let's reposition the data pointer to point to the first button action condition:

gFlashParserData.m_filePos += myOffset - sizeof(U16);

Notice that we jump ahead by myOffset but then back up 16 bits; this is because the call to GetWord advances the pointer 16 bits, but myOffset is the offset from the beginning of the offset field.

For simplicity, let's assume that the existing button data does not contain a button action condition for the specified state transition that already contains a wired action. This means that we can just insert a new button action condition at the head of the existing list of button action conditions. (The code to handle the general case is fairly complicated but not terribly enlightening; but don't fret: the source code for QTFlash contains the full definition of QTFlash_SetWiredActionToButton.) So we're going to move the existing list of button action conditions down in the data stream to make room for our new condition. Let's get a few sizes:

myActionHandleSize = GetHandleSize((Handle)theAction);
myMoveAmount = myDataHandleSize - myStartActionOffset;
myIncreaseAmount = sizeof(U16) + sizeof(U16) + sizeof(U8) + 
         sizeof(U16) + myActionHandleSize + sizeof(U8);
myDataHandleSize += myIncreaseAmount;

Now we need to resize the handle that holds the Flash data stream and move all the existing button action conditions down:

SetHandleSize(theSample, myDataHandleSize);
myErr = MemError();
if (myErr != noErr)
   goto bail;

BlockMove(*theSample + myStartActionOffset, *theSample + 
         myStartActionOffset + myIncreaseAmount, myMoveAmount);

At this point, we want to construct a new button action condition. Let's set myPtr to the first byte of the new button action condition:

myPtr = *theSample + myStartActionOffset;

A button action condition begins with a 16-bit offset to the next action condition. If, on entry to QTFlash_SetWiredActionToButton, we determined that there were no actions in the button data (which is possible but not very useful), then we'll set that offset to 0; otherwise, we'll set that offset to the length of the new button action condition:

if (myActionCount > 0) {
   INSERT_U16_AT_LOC(myIncreaseAmount, myPtr);
} else {
   *(U16 *)myPtr = 0;
   myPtr += sizeof(U16);
}

The macro INSERT_U16_AT_LOC inserts the specified 16-bit value at the specified location, making sure that that value is written in little-endian form; INSERT_U16_AT_LOC is defined like this:

#define INSERT_U16_AT_LOC(val,loc)                  \
                     *(U8 *)loc++ = (val & 0xff);      \
                     *(U8 *)loc++ = ((val >> 8) & 0xff)

We continue writing data into our new button action condition. Next we patch in the condition:

INSERT_U16_AT_LOC(theCondition, myPtr);

And then we patch in the action type (namely sactionWiredActions) and the length of the action data (which is of course the length of the atom container):

*(U8 *)myPtr = sactionWiredActions;
myPtr += sizeof(U8);
INSERT_U16_AT_LOC(myActionHandleSize, myPtr);

We're finally ready to insert the atom container that holds the wired actions. Each button action condition must end with an 8-bit field whose value is 0, so we'll write that too.

BlockMove(*theAction, myPtr, myActionHandleSize);
*(myPtr + myActionHandleSize) = 0;

To finish this off, we need to patch in the original offset to the button action conditions, if that offset was originally 0 (that is, if originally there were no actions in the button data).

if (myActionCount == 0) {
   myPtr = *theSample + myOffsetLocation;
   INSERT_U16_AT_LOC(myButtonRecordLength, myPtr);
}

Adjusting Length Tags

We are almost finished attaching a QuickTime wired action to a Flash button. We've spliced a new button action condition into the button's data block and we've updated (if necessary) the offset to the list of button action conditions. So the actual data in the button's tagged data block is now complete and correct. There remain, however, two length fields that we need to reset: (1) the data length field in the tag header, and (2) the file length field in the file header. We need to add myIncreaseAmount (the length of the new button action condition that we added) to each of the values currently in those fields. We do that by calling the application function SetNewHeaderAndTagLength, like so:

SetNewHeaderAndTagLength(myIncreaseAmount, myIncreaseAmount);

Listing 7 shows our definition of SetNewHeaderAndTagLength. On the whole this function is straightforward; the only real complication arises from the fact that a tagged data block header can occupy 2 or 6 bytes, depending on the size of the data in the block.

Listing 7: Adjusting the file and tag lengths

void SetNewHeaderAndTagLength (U32 theFileDifference, 
            U32 theTagDifference)
{
   U8               *s;
   U16              myCode, myNewCode;
   U32              myLength, myFileLength;
   long             myHandleSize;
   Boolean          myIsLongTag = false;
   OSErr            myErr = noErr;

   // point at the first byte of the 4-byte file-length field in the header block;
   // it’s at offset 4 in the header block
   s = (U8 *)*gFlashParserData.m_theData + 4;

   // read the current file length
   myFileLength = (U32)s[0] | ((U32)s[1] << 8) | 
                        ((U32)s[2] << 16) | ((U32)s[3] << 24);
   
   // increment the file length
   myFileLength += theFileDifference;
   s[0] = (myFileLength & 0xFF);
   s[1] = ((myFileLength >> 8) & 0xff);
   s[2] = ((myFileLength >> 16) & 0xff);
   s[3] = ((myFileLength >> 24) & 0xff);

   // point at the first byte of the current tag
   s = (U8 *)*gFlashParserData.m_theData + 
            gFlashParserData.m_tagStart;

   // get the combined code and length of the tag
   myCode = (U16)s[0] | ((U16)s[1] << 8);

   // the length is encoded in the tag
   myLength = myCode & 0x3f;

   // remove the length from the code
   myCode = myCode >> 6;

   // determine whether another long word must be read to get the length
   if (myLength == 0x3f) {
         s += sizeof(U16);

   myLength = (U32)s[0] | ((U32)s[1] << 8) | ((U32)s[2] << 16) 
                        | ((U32)s[3] << 24);
   myIsLongTag = true;
   }

   myLength += theTagDifference;

   if (myLength >= 0x3f) {
      myNewCode = (myCode << 6) | 0x3f;

      if (!myIsLongTag) {      // need more space
         myHandleSize = 
               GetHandleSize(gFlashParserData.m_theData);

         myHandleSize += sizeof(long);

         SetHandleSize (gFlashParserData.m_theData, 
            myHandleSize);
         myErr = MemError();
         if (myErr != noErr)
            goto bail;

         // now shift the data up
         BlockMove(
   *gFlashParserData.m_theData + gFlashParserData.m_tagStart, 
   *gFlashParserData.m_theData + gFlashParserData.m_tagStart + 
            sizeof(long), 
   (myHandleSize - sizeof(long)) – 
            gFlashParserData.m_tagStart);

         myFileLength += sizeof(long);
      }

      s = (U8 *)*gFlashParserData.m_theData + 4;
      s[0] = (myFileLength & 0xff);
      s[1] = ((myFileLength >> 8) & 0xff);
      s[2] = ((myFileLength >> 16) & 0xff);
      s[3] = ((myFileLength >> 24) & 0xff);

      s = (U8 *)*gFlashParserData.m_theData + 
                        gFlashParserData.m_tagStart;

      s[0] = (myNewCode & 0xff);
      s[1] = ((myNewCode >> 8) & 0xff);

      s += sizeof(U16);
      s[0] = (myLength & 0xff);
      s[1] = ((myLength >> 8) & 0xff);
      s[2] = ((myLength >> 16) & 0xff);
      s[3] = ((myLength >> 24) & 0xff);

   } else {
      myNewCode = (U16)(myCode << 6) | (U16)(myLength & 0x3f);

      if (myIsLongTag) {
         myHandleSize = 
            GetHandleSize(gFlashParserData.m_theData);
         myHandleSize -= sizeof(long);

         // shift the data down
         BlockMove(
   *gFlashParserData.m_theData + gFlashParserData.m_tagStart + 
            sizeof(long), 
   *gFlashParserData.m_theData + gFlashParserData.m_tagStart,
    (myHandleSize - sizeof(long)) – 
            gFlashParserData.m_tagStart);

         SetHandleSize(gFlashParserData.m_theData, 
            myHandleSize);
         myErr = MemError();
         if (myErr != noErr)
            goto bail;

         myFileLength -= sizeof(long);
      }

      s = (U8 *)*gFlashParserData.m_theData + 4;
      s[0] = (myFileLength & 0xff);
      s[1] = ((myFileLength >> 8) & 0xff);
      s[2] = ((myFileLength >> 16) & 0xff);
      s[3] = ((myFileLength >> 24) & 0xff);

      s = (U8 *)*gFlashParserData.m_theData + 
                              gFlashParserData.m_tagStart;

      s[0] = (myNewCode & 0xff);
      s[1] = ((myNewCode >> 8) & 0xff);

   }

bail:
   return;
}

In this article, we've investigated some ways to use QuickTime's wired actions in conjunction with Flash tracks. We've seen that QuickTime provides a handful of actions that we can send to Flash tracks, along with a single operand that we can use to get information from a Flash track. Perhaps the most useful wired action that can be targeted at a Flash track is kActionFlashTrackSetFlashVariable, which allows us to interact with ActionScripts attached to Flash elements. We can also use this wired action to dynamically set the text of a text item in a Flash track, without any assistance from Flash ActionScripts.

We've also seen how to embed wired actions in Flash files. We've walked through the steps involved in adding wired actions to a button, and similar code can be used to add wired actions to a frame in a Flash animation.

The code for adding wired actions to Flash movies is based heavily on some code written by Bill Wright.

Tim Monroe is a member of the QuickTime engineering team. You can contact him at monroe@apple.com.