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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Civilization VI 1.0.1 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
Google Chrome 55.0.2883.75 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Chromium 55.0.2883.75 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 55.0.2883.75: Security fixes: High CVE-2016... Read more
Luminar 1.0.2 - Powerful, adaptive, conf...
Luminar is the new full-featured image editor that adapts to the way you edit photos. Over 300 essential tools to fix, edit, and enhance your photos with comfort. The future of photo editing is here... Read more
Slack 2.3.3 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.3.3: Fixed window zoom jumping back-and-forth OS X 10.9... Read more
WhatRoute 2.0.10 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Luminar 1.0.2 - Powerful, adaptive, conf...
Luminar is the new full-featured image editor that adapts to the way you edit photos. Over 300 essential tools to fix, edit, and enhance your photos with comfort. The future of photo editing is here... Read more
WhatRoute 2.0.10 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Slack 2.3.3 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.3.3: Fixed window zoom jumping back-and-forth OS X 10.9... Read more
Lens Blur 1.4.3 - True out-of-focus boke...
Lens Blur transforms your existing photo into true SLR-quality out-of-focus bokeh effect! Everyone needs a gorgeous personalized background for a social profile, blog, Web/UI design, presentation, or... Read more

Latest Forum Discussions

See All

Amateur Surgeon 4 Guide: Become the worl...
It's time to wield your trusty pizza cutter again, as Amateur Surgeon has returned with a whole fresh set of challenges (and some old, familiar ones, too). Starting anew isn't easy, especially when all you have at your disposal is a lighter, the... | Read more »
Le Parker: Sous Chef Extraordinaire (Ga...
Le Parker: Sous Chef Extraordinaire 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Telltale Games really is working on a Gu...
Telltale Games' next episodic adventure is indeed Guardians of the Galaxy. A document tied to the voice actors strike suggested that the project was in the work, but now we have direct confirmation following an announcement at the Game Awards that... | Read more »
Amateur Surgeon returns to iOS and Andro...
Amateur Surgeon and its two sequels disappeared from the App Store some time and it was sad days for all. But now, just in time for the holidays, the Adult Swim favorite makes its joyous return in the shape of Amateur Surgeon 4, a remake with... | Read more »
The best board games on mobile
Sometimes you need to ditch all of the high speed, high action games in favor of something a little more traditional. If you don't feel like parting ways from your mobile device, though, there are still plenty of ways to get that old-school fix.... | Read more »
The best Facebook Messenger Instant Game...
Facebook's new Instant Games is now here, meaning you can play games with your friends directly via Facebook. It's a fun new way to connect with friends, of course, but it's also proving to be a solid gaming experience in its own right, with a... | Read more »
You can now play game's on Facebook...
Facebook launched its new Instant Games platform in an exciting new attempt to engage its user base. As a result, you can now play a number of different games directly through Facebook Messenger. All of these games run with HTML5, meaning you play... | Read more »
Apollo Justice Ace Attorney (Games)
Apollo Justice Ace Attorney 1.00.00 Device: iOS Universal Category: Games Price: $.99, Version: 1.00.00 (iTunes) Description: Court Is Back In Session Star as rookie defense attorney, Apollo Justice, as he visits crime scenes,... | Read more »
KORG iWAVESTATION (Music)
KORG iWAVESTATION 1.0 Device: iOS Universal Category: Music Price: $19.99, Version: 1.0 (iTunes) Description: A revolutionary new world of sound.The Wave Sequence Synthesizer for iPad - KORG iWAVESTATION | Read more »
Don't Grind Guide: Tips for becomin...
Don’t Grind is a surprising, derpy little one touch game with fun hand-drawn graphics. The goal is simple -- get the high score without being chopped to bits. That can be tough when you’re not used to the game, and that’s compounded by the fact... | Read more »

Price Scanner via MacPrices.net

Parallels Toolbox 1.3 for Mac Offers 25 Singl...
Parallels has launched Parallels Toolbox 1.3 for Mac, an upgrade that adds five new utilities to the stand-alone application which was released in August and is available exclusively online at http... Read more
OWC Mercury Elite Pro Dual mini Ultra-Portabl...
OWC has introduced the new OWC Mercury Elite Pro Dual mini, a powerful yet ultra-portable dual-drive RAID solution. The new Mercury Elite Pro Dual mini packs phenomenal performance into a small... Read more
Clearance 13-inch Retina MacBook Pros availab...
B&H Photo has clearance 2015 13″ Retina Apple MacBook Pros available for up to $200 off original MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $... Read more
Roundup of 2016 13-inch 2.0GHz MacBook Pro sa...
B&H has the non-Touch Bar 13″ MacBook Pros in stock today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (MLL42LL/A): $1449 $... Read more
New 13-inch 2.0GHz Space Gray MacBook Pro in...
Adorama has the new 13″ 2.0GHz Space Gray MacBook Pro (non-Touch Bar, MLL42LL/A) in stock for $1499 including a free 3-year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax... Read more
Finnair Adopts iOS Enterprise iPad Apps from...
Finnair and IBM have announced a first-of-its-kind agreement to utilize iOS enterprise apps from IBM to support the airline’s overall digital transformation. Finnair is focused on Asia-Europe traffic... Read more
Tech21 Launches Evo Go iPhone 7 Case Availabl...
Tech21 has announced the launch of the Evo Go case for Apple iPhone 7 and iPhone 7 Plus, exclusively at T-Mobile. Available online and at participating T-Mobile stores nationwide, Evo Go cases start... Read more
Apple Turns (RED) with More Ways to Join the...
In recognition of World AIDS Day, Apple is offering more ways than ever for customers to join (RED) in its mission to create an AIDS-free generation. Apple is the worlds largest corporate contributor... Read more
Deals on new 15-inch Touch Bar MacBook Pros,...
B&H Photo has new 2016 Apple 15″ Touch Bar MacBook Pro models in stock today with some available for $50 off MSRP, each including free shipping plus NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
12-inch Retina MacBooks on sale for up to $10...
12-inch Retina MacBooks remain on sale at B&H Photo with models available for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. B&H will also include a free copy... Read more

Jobs Board

*Apple* Retail - Multiple Positions- White P...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Automotive Detailer - *Apple* Used Autos -...
We are currently conductinginterviews and will be accepting applications for a part-time detailer. Apple Used Autos is a great place to work andstart a career. We Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
US- *Apple* Store Leader Program - Apple (Un...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on Read more
*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Dallas TX Introduction: We have immediate job openings for several Desktop Support Technicians with one of our most Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.