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

VueScan 9.5.70 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
TextSoap 8.3.2 - Automate tedious text d...
TextSoap can automatically remove unwanted characters, fix up messed up carriage returns, and do pretty much anything else that we can think of to text. Save time and effort. Be more productive. Stop... Read more
ForkLift 3.0 - Powerful file manager: FT...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
Amazon Chime 4.0.5528 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
Sparkle 2.1.0 - $79.99
Sparkle will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more
Bookends 12.7.9 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Dash 4.0.0 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
TrailRunner 3.8.834 - Route planning for...
TrailRunner is the perfect companion for runners, bikers, hikers, and all people wandering under the sky. Plan routes on a geographical map. Import GPS or workout recordings and journalize your... Read more
Dash 4.0.0 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Bookends 12.7.9 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more

Fantasy MMORPG MU Origin’s receives a hu...
Developer Webzen are looking to take their highly popular fantasy battler MU Origin to the next level this month, with its most ambitious overhaul yet. The latest update introduces the long sought after Server Arena, new treasure dungeons, and much... | Read more »
RPG Djinn Caster (Games)
RPG Djinn Caster 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: SPECIAL PRICE 38% OFF(USD 7.99 -> USD 4.99)!!!A Fantasy Action RPG of far foreign lands! Summon the Djinns and rise to... | Read more »
Alto's Odyssey gets its first trail...
There's finally video evidence of Alto's Odyssey, the follow up to the 2015 App Store hit, Alto's Adventure. It looks just as soothing and atmospheric as Alto's last outing, but this time players will be journeying to the desert. Whereas Alto's... | Read more »
Last week on Pocket Gamer
What’s going on in the wider world of portable gaming? Each week we ask that question of our sister website Pocket Gamer. The PG team covers iOS gaming, just like 148Apps, but it also strays into the world of Android games and handheld consoles... | Read more »
Pokémon GO Generation 2 evolution guide
At long last, Niantic Labs finally unleashed the Generation 2 Pokémon into the wild. Pokémon GO trainers are scrambling to grab up this new set of 80 Pokémon. There are some special new tricks required to catch all of these new beasties, though.... | Read more »
The best new games we played this week
It feels as though the New Year got off to a creaking start as far as mobile games go, but that's changed over the past few weeks. The last few days alone have seen the debut of a number of wonderful games, so we thought we'd take the time to... | Read more »
Recruit more scallywags and discover new...
Get ready to show off your sea legs all over again in Oceans & Empires’ new grand update, which aims to make the act of rising to the role of seven seas ruler even more fresh and appealing, thanks to a richness of new content on both iOS and... | Read more »
Mage the Ascension: Refuge (Games)
Mage the Ascension: Refuge 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The groundbreaking roleplaying game Mage: The Ascension manifests in our turbulent present with Refuge, an... | Read more »
Vampire: Prelude (Games)
Vampire: Prelude 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The classic roleplaying game Vampire: The Masquerade returns to digital games with a Prelude of things to come. Experience a... | Read more »
Digby Forever Guide: How to dig to the d...
Digby Forever is a sparkling homage to arcade classics, and while you may be tiring of the number of arcade games being thrown at you, this endless digger finds many ways to stand out from the rest of the pack. The game manages to be challenging... | Read more »

Price Scanner via MacPrices.net

QuickerTek Announces 5TB Apple AC AirPort Tim...
QuickerTek Inc. has announced their new 5TB hard drive upgrade for Apple’s AC AirPort Time Capsule. By customer request, this upgrade also features six external antennas and offers the highest... Read more
Apple Certified Refurbished iMacs available f...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
Apple offering Certified Refurbished Series 1...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
1.4GHz Mac mini on sale for $449, save $50
B&H Photo has the 1.4GHz Mac mini on sale for $50 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP Read more
12-inch Retina MacBooks on sale for $200-$250...
Newegg has the 12″ 1.2GHz Space Gray Retina MacBook (sku MLH82LL/A) on sale for $1349.99 including free shipping. Their price is $250 off MSRP, and it’s the lowest price available for this model.... Read more
13-inch 2.0GHz Space Gray MacBook Pro on sale...
Adorama has the non-Touch Bar 13″ 2.0GHz Space Gray MacBook Pro in stock today for $100 off MSRP. Shipping is free, and Adorama charges NY & NJ sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray... Read more
13-inch Touch Bar MacBook Pros on sale for $1...
B&H Photo has select 2016 Apple 13″ Touch Bar MacBook Pros in stock today and up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.9GHz/512GB Touch Bar MacBook... Read more
KSI-1802R SX Disinfect-able Keyboard With Wav...
KSI has unveiled a new, innovative medical keyboard, the KSI-1802R SX, at HIMSS 2017, running February 19-22 in Orlando, Florida. KSI-1802R SX is the only keyboard that combines dual factor... Read more
15-inch Touch Bar MacBook Pros on sale for up...
Amazon has 15″ Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP including free shipping: - 15″ 2.7GHz Touch Bar MacBook Pro Space Gray: $2720.38 $79 off MSRP - 15″ 2.7GHz... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more

Jobs Board

*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
Manager *Apple* Systems Administration - Pu...
Req ID 3315BR Position Title Manager, Apple Systems Administration Job Description The Manager of Apple Systems Administration oversees the administration and Read more
*Apple* Technician - nfrastructure (United S...
Let’s Work Together Apple Technician This position is based in Portland, ME Life at nfrastructure At nfrastructure, we understand that our success results from our 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
Manager *Apple* Systems Administration - Pu...
Req ID 3315BR Position Title Manager, Apple Systems Administration Job Description The Manager of Apple Systems Administration oversees the administration and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.