TweetFollow Us on Twitter

Feb 02 QT Toolkit

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

Introduction

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.

Wired Actions Targeted at Flash Tracks

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).

Wired Actions in Flash Tracks

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;
}

Conclusion

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.

Credits

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.

 
AAPL
$518.58
Apple Inc.
+0.62
MSFT
$40.13
Microsoft Corpora
+0.38
GOOG
$549.88
Google Inc.
+13.44

MacTech Search:
Community Search:

Software Updates via MacUpdate

PDFpenPro 6.2 - Advanced PDF toolkit for...
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Create... Read more
PDFpen 6.2 - Edit and annotate PDFs with...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
Monolingual 1.5.9 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. It requires a 64-bit capable Intel-based Mac and at least... Read more
Maya 2015 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
Starcraft II: Wings of Liberty 1.1.1.180...
Download the patch by launching the Starcraft II game and downloading it through the Battle.net connection within the app. Starcraft II: Wings of Liberty is a strategy game played in real-time. You... Read more
Sibelius 7.5.0 - Music notation solution...
Sibelius is the world's best-selling music notation software for Mac. It is as intuitive to use as a pen, yet so powerful that it does most things in less than the blink of an eye. The demo includes... Read more
Typinator 5.9 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
MYStuff Pro 2.0.16 - Create inventories...
MYStuff Pro is the most flexible way to create detail-rich inventories for your home or small business. Add items to MYStuff by dragging and dropping existing information, uploading new images, or... Read more
TurboTax 2013.r17.002 - Manage your 2013...
TurboTax guides you through your tax return step by step, does all the calculations, and checks your return for errors and overlooked deductions. It lets you file your return electronically to get... Read more
TrailRunner 3.8.769 - Route planning for...
Note: While the software is classified as freeware, it is actually donationware. Please consider making a donation to help support development. TrailRunner is the perfect companion for runners,... Read more

Latest Forum Discussions

See All

Hearthstone: Heroes of Warcraft is Avail...
Hearthstone: Heroes of Warcraft is Available on the U.S. App Store Right Now – Gogogogo! Posted by Rob Rich on April 16th, 2014 [ permalink ] | Read more »
Groundskeeper2 Review
Groundskeeper2 Review By Nadia Oxford on April 16th, 2014 Our Rating: :: SLICE THOSE ALIEN SLIMEUniversal App - Designed for iPhone and iPad Putting aside some minor control issues, Groundskeeper2 is a fun and furious action/... | Read more »
Pinnacle Studio for iPhone (Photography...
Pinnacle Studio for iPhone 5.0 Device: iOS iPhone Category: Photography Price: $9.99, Version: 5.0 (iTunes) Description: | Read more »
Season 3 of Zombies, Run! Starts Right N...
Season 3 of Zombies, Run! | Read more »
Snupps Review
Snupps Review By Jennifer Allen on April 16th, 2014 Our Rating: :: USEFUL LISTINGUniversal App - Designed for iPhone and iPad Got a huge collection that you need to organize, or just want to share with others? Snupps has it covered... | Read more »
Toad Rider Goes Free for a Limited Time,...
Toad Rider Goes Free for a Limited Time, Starting This Week Posted by Tre Lawrence on April 16th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Knights of Pen & Paper is Free for a...
Knights of Pen & Paper is Free for a Limited Time – Don’t Wait for a Natural 20, Get it Now! Posted by Rob Rich on April 16th, 2014 [ permalink ] | Read more »
R.B.I. Baseball 14 Review
R.B.I. Baseball 14 Review By Blake Grundman on April 16th, 2014 Our Rating: :: RETRO REVIVEDUniversal App - Designed for iPhone and iPad What was old is new again, as the MLB attempts to taking baseball gaming back to its retro... | Read more »
Noodlecake Studios Places Mikey Hooks on...
Noodlecake Studios Places Mikey Hooks on Sale, Releases Sneak Peek Trailer for Upcoming Sequel Mikey Boots Posted by Tre Lawrence on April 16th, 2014 [ | Read more »
Cosmic Mechanic Review
Cosmic Mechanic Review By Blake Grundman on April 16th, 2014 Our Rating: :: SLIGHTLY CREDIBLE MACHINEUniversal App - Designed for iPhone and iPad Creatives folks love the opportunity to have their wits tested, but there isn’t... | Read more »

Price Scanner via MacPrices.net

Microsoft Blinks – Drops Microsoft Office 365...
Microsoft has dropped the annual subscription fee for Microsoft Office 365 Personal – which is needed in order to create and edit documents in Microsoft Office for iPad. However, Apple’s iOS and OS X... Read more
New AVG Vault Apps for iOS and Android Help K...
AVG Technologies N.V. an online security company for 177 million active users, has announced the launch of its latest mobile application, AVG Vault. The free app introduces an innovative user... Read more
Free Local Carrot iPhone App Helps Find Fresh...
I love fresh vegetables. I’m not a vegan, although I was for several years in the 1980s, but fresh vegetables and other whole foods are still my dietary mainstays as a matter of taste rather than... Read more
Apple refurbished iPad Airs available startin...
Apple is now offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. The following Airs are available today: -... Read more
21-inch 2.7GHz iMac on sale for $1179, save $...
B&H Photo has the 21″ 2.7GHz iMac on sale for $1179 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Add an iMac to your shopping cart, and B&H will offer an... Read more
Download our app, iTracx, for iOS and Android
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Education discounts shave up to $300 off the...
Purchase a new Mac at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and all... Read more
Save $50 on Mac mini Server
B&H Photo has the 2012 Mac mini Server on sale for $949 including free shipping plus NY sales tax only. Their price is $50 off MSRP. Read more
PhatWare’s “Ultimate Writing App For iOS” Ren...
PhatWare Corp. has announced it has renamed its new WritePro word processing app for iPhone and iPad: WritePad Pro. The decision to change the app’s name to leverages the strong brand awareness and... Read more
Full Resolution Photo Editor Tint Mint 1.0 Re...
California based independent developer, Jeffrey Sun, creator of the iOS app Modern Editor, has released Tint Mint, a new photography app for editing enthusiasts. The app costs a dollar, and it packs... Read more

Jobs Board

*Apple* Retail - Manager - Apple (United Sta...
Job SummaryKeeping an Apple Store thriving requires a diverse set of leadership skills, and as a Manager, you're a master of them all. In the store's fast-paced, dynamic Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Retail - Market Leader - Cincinnati...
…challenges of developing individuals, building teams, and affecting growth across Apple Stores. You demonstrate successful leadership ability - focusing on excellence Read more
*Apple* Retail - Manager - SoHo - Apple (Uni...
Job SummaryKeeping an Apple Store thriving requires a diverse set of leadership skills, and as a Manager, you're a master of them all. In the store's fast-paced, dynamic Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** Every day, business customers come to the Apple Store to discover what powerful, easy-to-use Apple products can do for them. As a Business Leader, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.