Volume Number: 19 (2003)
Issue Number: 9
Column Tag: QuickTime

QuickTime Toolkit

Revolution

by Tim Monroe

Revolution is a software development environment written and published by Runtime Revolution Ltd., a company based in Edinburgh, Scotland. Revolution is a rapid application development (RAD) tool that can build applications for a number of operating systems, including Mac OS X, classic Macintosh OS, Windows, and several versions of Linux and UNIX. In this article and the next, I want to take a look at using Revolution to build applications that can open and display QuickTime movies. Accordingly, we'll limit our attention to using Revolution on Mac OS X and Windows systems.

As usual in our recent articles, our goal is to build a multi-window movie playback and editing application. Let's call this application RunRevVeez. Ideally, the movie windows displayed by RunRevVeez should be indistinguishable in appearance and behavior from movie windows displayed by our other sample applications (such as the C-based application QTShell or our REALbasic application BasicMovie). And, ideally, RunRevVeez should be able to invoke any of the thousands upon thousands of QuickTime APIs.

I'm happy to report that Revolution performs quite nicely in both regards. It's extremely easy to use Revolution to open and display QuickTime movies, and to get them to behave as expected. Revolution provides a reasonable selection of built-in commands and functions for working with movies and movie properties. And Revolution provides a mechanism -- using plug-in code modules -- to access features of QuickTime that are not already built-in to Revolution.

In this article, we'll see how to set up a new Revolution project for a QuickTime player application. We'll add an About box to the application, and we'll see how to create new movie windows and load movies into them. We'll create the application's menus and add executable code to a few of those menus. By the time we reach the end of this article, we should have a pretty good understanding of what it's like to create a simple application with Revolution and of how to work with QuickTime movies in that application. And everything we do in this article should work as well on Windows as it does on Macintosh.

In the next article, we'll concentrate on implementing those features of RunRevVeez that are not at all (or not very easily) supported directly by Revolution. For instance, Revolution does not currently provide any methods or commands for editing a movie (cutting or copying the movie selection, pasting a previous cut or copy, and so forth); but it's easy enough to write a plug-in module that supports these capabilities, and it's easy to access that module from within Revolution code. In fact, writing and calling Revolution plug-ins is so easy that I can't imagine any serious programmer not wanting to use them as a matter of course. So it will be good to take a careful look at this technique. In that article, we'll focus primarily on development on Mac OS X.

The current released version of Revolution is version 2.0.2, and that's what I've used throughout these articles. This version incorporates a large number of improvements over previous versions.

Revolution, like any good RAD tool, unifies the development of an application's user interface and its executable code within a single environment. User interface elements (such as buttons, scroll bars, text-edit fields, pop-up menus, and so forth) are objects that can be placed into windows and dialog boxes; these objects have properties that we can get and (usually) also set. We do this, and other operations, by attaching code to objects that is executed when particular events occur to those or other objects. Revolution is not event driven, however, at least in the classic Mac sense of event-driven programming that involves a global event loop. Rather, Revolution is message driven: all executable code is contained in message handlers that are attached to objects in the application. There are, for instance, start-up and open messages that are sent when a window, dialog box, or even the application itself is opened.

So far, this is part of any standard RAD diet, and it is not terribly unlike the programming model we saw in AppleScript Studio or REALbasic (covered in earlier QuickTime Toolkit articles). Revolution is interesting in several ways. First, it uses a so-called fourth-generation language for its message handlers. This language is called Transcript and is a clear descendent of the HyperCard family of languages. In Transcript, there are no explicit type declarations; the values of all variables are treated as strings but are coerced to other types when necessary. For instance, we can add two values together like this:

put 8 + 11 into mySum

After this code is executed, the variable mySum contains the value "19" (a string). To concatenate two strings, we use the "&" operator, like this:

put 8 & 11 into mySum

After this line of code is executed, the variable mySum contains the value "811".

Revolution is interesting and distinctive also in the basic vocabulary it uses to describe the application and its interactions with a user. (Again, this is a holdover from HyperCard.) A window is a stack. Every application has one mainstack, and all other stacks in the application (that is, all other windows and dialog boxes) are substacks of the mainstack. Typically the mainstack serves as the application's main window. For document-based applications (like our sample application RunRevVeez), there might however be no such main window; in this case, it is still useful to have a mainstack, since messages targeted at a substack are redirected to the mainstack if the substack does not contain an appropriate message handler. In this case, the mainstack can just be invisible.

Stacks contain cards. A card occupies the entire content area of the stack that contains it. Cards, in turn, contain controls -- which are the basic user interface objects like buttons, scroll-bars, etc. A stack can contain more than one card, and a card can contain more than one control. (Only one card in a stack can be visible at a time.) Controls can be grouped, for easy reference. For our purposes, we'll need to work with only one group of controls, the menu bar menus.

Let's get started building our movie playback and editing application, RunRevVeez. First, launch Revolution. After the splash-screen disappears, two windows appear, a tools palette (Figure 1) and an application browser window (Figure 2). The application browser currently shows no stacks in the application.

The tools palette shows icons representing a number of controls that can be placed into cards, including push buttons, tabbed buttons, check boxes, radio buttons, text-edit fields, list boxes, scrollbars, pull-down and pop-up menus, and images. Of particular interest for us in this article is the player object in the lower-right corner (whose tool tip is "QuickTime Player").

The top two icons in the tools palette do not represent controls. Instead, they indicate which mode the IDE is in. When the arrow is active (as in Figure 1), the IDE is in edit mode: we can add stacks, place controls into cards, and edit the executable code in a message handler. When the little hand icon is active, the IDE is in browse mode: we can run scripts and interact with the objects in a card. By entering browse mode, we can test out the operation of our stacks and scripts without having to build the application or leave the IDE.

The first thing we need to do is add a new mainstack to the application. Select "New Mainstack" in the File menu. A new empty stack opens, as shown in Figure 3.

In earlier articles, we used the default new window provided by the programming environment as a template for the multiple movie windows our applications could open, and indeed it's tempting to just click the player object icon in the tools palette and then click-drag a new movie player in the new window. With Revolution, however, we're going to use a slightly different architecture in our application. It will be easiest to add another stack to the application and to use that substack as the template for our movie windows. The mainstack, for the moment, will serve merely to hold global handlers (as mentioned briefly above).

Let's change the name of the mainstack. Select the "Stack Inspector" item in the IDE's Object menu to open a properties inspector like the one shown in Figure 4.

Set the Name field to "RunRevVeez"; notice that the name of the mainstack in the pop-up menu also changes to "RunRevVeez".

Next let's take a look at how we can attach a message handler to the mainstack. In the properties inspector, press the button with the triangle icon near the top of the window; this pops up a selection menu. (See Figure 5.) Select the "Edit Script" item in that menu.

At this point, a script editor window will appear, as shown in Figure 6.

We can add message handlers in this window. For now, let's type in the code shown in Listing 1.

preOpenStack
on preOpenStack
   set the defaultmenubar to the name of group "MainMenu"
   set the defaultcursor to arrow
   if the QTVersion is "0.0" then
      answer error "QuickTime is not installed! "
      close stack "RunRevVeez"
   end if
end preOpenStack

Notice that a message handler is delimited by the keywords "on" and "end", each followed by the name of the message. The preOpenStack message is sent to a card before the card is drawn in its stack on the screen. In our case, we want to perform any one-time initialization of the mainstack and the application. We set the default menu bar and the default cursor, and we check to see whether QuickTime is installed. The built-in function QTVersion returns the version of QuickTime that is installed on the system. If QuickTime is not installed, then QTVersion returns the value "0.0". As you can see, we look for that value; if we find it, we use the answer command to display the alert box shown in Figure 7. (The error keyword indicates that we want the error icon to be displayed; other choices are information, question, and warning.)

If QuickTime is not available, we quit RunRevVeez by closing the mainstack, like so:

close stack "RunRevVeez"

In general we refer to stacks and objects by name.

Let's move next to set up our application's menus and menu bar. With Revolution, this is a bit trickier than with other RAD tools, owing largely to the fact that Revolution wants to target a variety of operating systems. Menus in Revolution are buttons, and the menu bar is a group of buttons. Each stack can have its own group of buttons -- that is, its own menu bar. On Macintosh operating systems, this isn't really what we want. So we'll create a single menu bar associated with the mainstack and then set the application's defaultmenubar property so that all the stacks in our application use that menu bar. (Look again at Listing 1.)

To create our menus, select "Menu Builder" in the Tools menu. The menu builder dialog box shown in Figure 8 appears.

Click the New button. In the dialog box that then appears (Figure 9), set the name to "MainMenu". Notice that three menus are already included in the new menu bar.

When we click the OK button, the menu builder dialog box now contains the three default menus. Click the "Set as Menu Bar on Mac OS" check box (as in Figure 10) to get the proper behavior on Macintosh systems.

The construction of menus is reasonably straightforward. Using the controls in the menu builder dialog box, add the appropriate menu items (together with the usual keyboard shortcuts) to the File and Edit menus. Add a new menu, the Movie menu, and add two items to that menu: "Hide Controller Bar" and "Hide Speaker Button". In the Help menu, add the item "About RunRevVeez". When we're done, the menu builder dialog box will look something like Figure 11.

Now we need to add some code to handle the various menu items. In turn, select each of the four menus in the menu builder dialog box (File, Edit, Movie, and Help) and click the "Auto Script" button. Each time we click that button, Revolution creates a default script for the selected menu. For instance, Figure 12 shows the default script for the Help menu.

Notice that the Menu Builder has created a menuPick message handler, replete with the necessary switch and case statements to handle all the items we added to the Help menu. All we need to do is add code to handle those items in the appropriate manner. In RunRevVeez, we'll simply ignore the Help item in the Help menu. To handle the "About RunRevVeez" menu item, we can insert the code in Listing 2 into the menuPick handler.

menuPick
   case "About RunRevVeez"
      open stack "AboutBox"
      set visible of stack "AboutBox" to true
      break
   end switch

This tells our application to open a stack named "AboutBox" and then to set its visible property to true.

It turns out that Revolution is smart enough to move the "About RunRevVeez" menu item from the Help menu into its proper place in the Mac OS application menu, as shown in Figure 13.

Of course, our application does not yet contain a stack named "AboutBox". So let's add one. Select the menu item "New Substack of RunRevVeez" in the IDE's File menu. A new stack (that is, window) will appear. Open the property inspector for the new stack and set its name to "AboutBox" and its title to "About RunRevVeez".

Next, click the "magic wand" icon next to the Controls field; a sheet will slide down allowing us to select the desired controls for the window's title bar, as shown in Figure 14.

Let's select the set of controls with the fewest buttons; since we are currently building RunRevVeez only for Mac OS, we can select the third set from the top. Click OK.

Select the "Colors & Patterns" item in the pop-up menu in the properties inspector for the About box and then choose the Aqua striping for the background pattern. Then select the "Size & Position" item and set the size of the stack as shown in Figure 15.

Now we need to add items to the About box so that it has the standard appearance shown in Figure 16. (Notice that I've added a one-pixel border around the image; as we'll see, this is easy to do, and it makes the box look a bit nicer.)

First, click the Image tool in the tools palette and then click-drag an image well in the About box stack. Set the size of the image as shown in Figure 17.

Set the image file to the standard penguin image, penguin.pct. In the properties inspector for the image, turn on the "Show Border" property but turn off the "Three D" option for that property. Finally, set the border width to 1. Set the tool tip for the penguin image to "Keep the lawyers happy!"

Apparently, the Revolution license requires any applications built using it to display the Revolution logo at some point. (Hey, I'm not a lawyer, so this might not be strictly correct.) So let's add a second image to the About box; this image will be initially invisible but will become visible when we click the penguin image. Add a second image using one of the logos distributed with the Revolution IDE, say "Runtime small.pct". Make that image initially invisible. Open the script editor for the penguin image and add the handler shown in Listing 3.

mouseUp
on mouseUp
   set the visible of me to false
   set the visible of image "RevIcon" to true
end mouseUp   

Once the user has clicked the penguin image, the About box will look like the box in Figure 18.

Just for fun, let's configure the Revolution icon image so that clicking it will turn it back into the penguin image. Of course the script would look like the code in Listing 4.

mouseUp
on mouseUp
   set the visible of me to false
   set the visible of image "Penguin" to true
end mouseUp   

The last control we need to add to our About box is the OK button. Select the button icon in the tools palette and then click-drag a button of the appropriate size in the appropriate spot. In the properties inspector, set the name of the button to OKButton and the label to OK. Check the "Default button" check box. Finally, we need to script the button so that clicking it causes the About box to disappear. This is easy enough: add a mouseUp message handler to the button with this single line of code:

close this stack

Our About box is now complete. It's time to move on to constructing a movie window.

Revolution provides a player object (or, more briefly, a player) that we can use to display QuickTime movies in a card. There are a large number of built-in messages and properties associated with a player object, and we can also define custom messages and properties. Of particular interest is the movieControllerID property, which is a pointer to the movie controller associated with the movie being displayed in a player object. As we'll see in more detail in the next article, we can use this property to extend Revolution's QuickTime capabilities beyond the built-in methods and properties.

These built-in properties include a number of properties associated with normal linear QuickTime movies: currentTime, timeScale, startTime, endTime, paused, playLoudness, playRate, playSelection, trackCount, looping, and so forth. For QuickTime VR movies, Revolution defines a handful of properties, including: currentNode, hotspots, nodes, pan, tilt, constraints.

Most of these properties are associated with numerical or Boolean values, but several of them return a list of values. Revolution provides easy ways to iterate through these lists looking for particular values. For instance, a player's mediaTypes property contains a comma-separated list of strings that describe the media types in a movie; this list can contain some or all of these words: video, audio, text, qtvr, sprite, flash. We can find movies with sound tracks, and operate upon them, like this:

if the mediaTypes of player "MoviePlayer" contains "audio" then
   incrementLoudness
end if

Revolution also defines eight messages that can be sent to a player object: currentTimeChanged, deletePlayer, hotspotClicked, newPlayer, nodeChanged, playPaused, QTDebugStr, and selectionChanged. For present purposes, however, we won't need to write any message handlers for these messages.

Let's begin by adding yet another substack to the mainstack. This new substack will serve as a template for new movie windows. When the user decides to open a movie file, we'll clone this stack and load the movie into the cloned stack. In this way, we'll have the ability to open an unlimited number of movie windows, all sharing the properties of this substack.

Name the new substack "MovieWindow". Then add a player object to it by clicking on the QuickTime icon in the tools palette and then click-dragging in the new substack. (If you prefer to use menus, you can select the Player item in the "New Control" hierarchical menu of the Object menu.) Don't worry about making the player exactly fill the movie window, as we'll take care of resizing the movie window when we load a movie into it. In the properties inspector for the player object, set the player's name to "MoviePlayer". Make sure that the Visible, Controller, and "Focus with keyboard" check boxes are checked. More importantly, make sure that the Buffer check box is unchecked. (Checking that box would turn on the alwaysBuffer property of the player object, which renders the controller bar ineffective.) Figure 19 shows the desired properties.

Notice two things here. First, the Border option is not selected; since the movie window will be sized to exactly contain the movie and its controller bar, we don't want a border around the movie. Second, notice that we've left the Source property blank. If we wanted to open a specific movie, we could specify its full pathname as the source. As usual, however, we want to give the user complete choice over which movies to open. So we'll need to specify the source movie programmatically in our script.

Now let's see how to open a movie file and display the movie it contains in a movie window. Obviously, we want to add some code to the menuPick handler for the Open menu item in the File menu. Revolution provides the "answer file" command that we can use to elicit a movie file from the user; we can call it like this:

answer file "Open: RunRevVeez" of type "MooVSWFL"

This line of code displays the standard file-opening dialog box, with the prompt string (here "Open: RunRevVeez") used as the title of the dialog box; in this case, only movie files and Flash files can be selected by the user.

When the user selects a file, the complete pathname of that file is placed into a special variable named "it". We can make sure that the user actually selected a file (and didn't just hit the Cancel button) by testing that it isn't the empty string:

if it <> "" then

And we can save that full pathname for later use by assigning it to a local variable:

put it into savedFilePath

Recall that we are going to make a copy of the MovieWindow substack to serve as a window to hold the new movie. We can do that quite easily:

clone stack "MovieWindow"

The new window is named "Copy of MovieWindow", and this will also be the title of the new window if we don't change it. As usual, we want the title of the movie window to be the file's basename (the portion of the full pathname that follows the rightmost path separator). We can get the basename quite easily like this:

set the itemDelimiter to "/"
put the last item of savedFilePath into newStackName

The itemDelimiter is the character that is used to delimit the chunks of a string. By default, a handler's itemDelimiter property is set to the comma (","), but it can be reset at will. Here we set it to the slash character ("/"), which delimits the parts of a pathname. Once we've executed these two lines of script, the local variable newStackName should contain the file's basename. We can then use that variable to set the name of the stack and the title of the new movie window:

set the name of stack "Copy of MovieWindow" to newStackName
set the title of stack newStackName to newStackName

Now we need to assign the movie in the file we just opened to the player object in the stack we just created. We can do that by setting the filename property of the player object in that stack, like this:

set the filename of player "MoviePlayer" of stack 
            newStackName to savedFilePath

The filename property can be set to any full or partial pathname; if the pathname is partial, then it's interpreted relative to the value of the defaultFolder global property. (When a Revolution application is launched, the defaultFolder property is set to the folder containing the application; we can programmatically set it to any other folder we wish.) The filename property can also be set to a URL. In RunRevVeez, however, we'll always use full pathnames, as returned by the "answer file" command.

Listing 5 shows our complete definition of the menuPick handler for the Open menu item.

menuPick
case "Open..."
   answer file "Open: RunRevVeez" of type "MooVSWFL"
   if it <> "" then
      put it into savedFilePath
      -- get the base name of the file
      set the itemDelimiter to "/"
      put the last item of savedFilePath into newStackName
      -- create a new movie window
      clone stack "MovieWindow"
      set the name of stack "Copy of MovieWindow" to 
            newStackName
      set the title of stack newStackName to newStackName
      set the visible of stack newStackName to false
      -- load the movie into the new window
      set the filename of player "MoviePlayer" of stack 
            newStackName to savedFilePath
      -- set the size of the movie window
      sizeStackToMovie newStackName
      set the visible of stack newStackName to true
      set the visible of player "MoviePlayer" of stack 
            newStackName to true
   end if
   break

You'll notice that we make the movie window invisible before setting its size and then make it visible thereafter. We also need to make sure the player object itself has its visibility state restored.

The last thing we need to do when opening a QuickTime movie is to resize the movie window so that it exactly contains the movie at its natural size and the movie controller bar, if present. In Listing 5, we called the message handler sizeStackToMovie, which is defined in the mainstack. The definition is straightforward and relies on the height and width properties of the player object (Listing 6).

sizeStackToMovie
on sizeStackToMovie theStack
   put the height of player "MoviePlayer" of stack theStack 
            into windowHeight
   put the width of player "MoviePlayer" of stack theStack 
            into windowWidth
   set the width of stack theStack to windowWidth
   set the height of stack theStack to windowHeight
   set the rectangle of player "MoviePlayer" of stack 
            theStack to 0,0,windowWidth,windowHeight
end sizeStackToMovie

We set the height and width of the movie window to the height and width of the player object, which is set to the movie's natural dimensions when the movie is first opened. Then we reset the rectangle of the player object so that its upper left corner is at the point 0,0 in the window's content area.

The amount of code we need to write in order to open a QuickTime movie in a window on the screen is surprisingly small. We clone the MovieWindow stack, set its filename property to a path elicited from the user, and then resize the movie window to exactly contain the movie at its natural size. Once we've done this, the movie appears, just like it should, in a window; Figure 20 shows a sample movie window displayed by our current version of RunRevVeez.

This window behaves exactly as we'd expect; we can drag it around on the screen by grabbing its title bar, minimize it by clicking on the yellow button in the title bar, and close it by clicking on the red button in the title bar. We configured the window so that it's not resizable, so the green button is inactive.

Moreover, the controller bar functions perfectly, and keyboard operations (such as starting and stopping the movie by pressing the space bar, or moving forward and backward by pressing the right and left arrow keys) work exactly as they should. In short, for normal linear QuickTime movies and for QuickTime VR movies, Revolution works flawlessly as far as normal movie playback is concerned.

Problems arise, however, when we open certain types of non-linear QuickTime movies, like movies containing wired sprites or zero-source QuickTime video effects. For instance, when we open the fire movie we created in an earlier article ("F/X" in MacTech, September 2001), we'll quickly notice that the fire does not burn by itself. (See Figure 21.) A few flames sputter up initially and then the fire freezes (if that's even possible). Oddly enough, if we open a linear movie and start it playing, the fire will join in and burn, but only for as long as the linear movie is playing. Even more oddly, if we open the About box, the fire starts burning, but (again) only for as long as the About box is open.

It's possible that I've got my movie stacks somehow configured incorrectly, but I'm inclined to doubt that, given that we've used such simple and natural code to get to this point. It seems more likely to me that the Revolution runtime engine is for some reason failing to call MCIsPlayerEvent or MCIdle often enough to keep these non-linear movies playing. I dunno.

Happily, the About box behavior described above suggests a simple and apparently effective workaround. Keep in mind that our mainstack is currently empty, visually speaking. It's serving only to hold handlers for application start-up and window sizing. I have discovered that if we place a default button on the mainstack, as shown in Figure 22, then the fire movie and wired sprite movies behave as they should. Something about that pulsating button seems to wake up the movie controllers. I dunno.

Of course we don't want the mainstack to be visible while our application is running, especially with its throbbing button. So let's just move it out of the way at application launch time. In the preOpenStack message handler we wrote earlier (see Listing 1), let's add one line at the bottom:

set the location of stack "RunRevVeez" to 5000,5000

This moves the stack sufficiently far offscreen that it shouldn't be visible.

As I said, this workaround seems to solve the problem entirely. There may be a better solution to the original problem, but this hidden-mainstack-with-throbbing-button will do fine until we find that better solution.

Recall that we added a couple of menu items to the Movie menu, one of which is supposed to toggle the visibility state of the controller bar. We can implement this item quite easily in Revolution by getting and setting the player object's showController property, as shown in Listing 7.

menuPick
case "Hide Controller Bar"
   if showController of player "MoviePlayer" of stack
                           theTopStack is true then
         set showController of player "MoviePlayer" of stack 
                           theTopStack to false
   else
         set showController of player "MoviePlayer" of stack
                           theTopStack to true
   end if
   sizeStackToMovie theTopStack
   break

Notice that we call sizeStackToMovie to make sure that the movie window is resized correctly to hold the movie and any associated controller bar.

Listing 7 raises an interesting question: how did we figure out the value of theTopStack? RunRevVeez can have more than one movie window open at a time, and we want to apply the menu item only to the frontmost movie window. So how do we figure out which movie window is in front of all others? Revolution provides the topStack function, which returns the frontmost stack window with the lowest mode. Since the mainstack and the movie window stack have the same mode, topStack ought to return the frontmost movie window.

The trouble is, I could never get topStack to work quite right. Fortunately, Revolution also provides the openStacks function, which returns a list of open stacks ordered according to their order on the screen. The first element in this list is the frontmost stack, and we can read that first line like this:

put first line of the openStacks into theTopStack

You can expect to see that line of code at the beginning of any handlers for menu items that apply only to a movie window. You will also often see the following line of code, which tests to see whether the frontmost window contains a player object:

if exists(player "MoviePlayer" of stack theTopStack) then

This allows us to distinguish a movie stack from the mainstack.

So far, so good. Revolution appears to be a simple yet powerful environment for creating applications. It provides support for opening and displaying QuickTime movies, and it's easy enough to get our application to support multiple open movies at once. We ran into a minor problem with playback of some kinds of movies, but we also discovered a simple and effective workaround to that problem.

Still, we've got a fair amount of work remaining in our quest to develop a multi-window movie playback and editing application. We need to tackle the movie editing operations, and we need a way to track the state of our movie windows so that we can enable and disable menus and menu items appropriately. For these enhancements, we need to move beyond what's built in to Revolution and explore the topic of Revolution plug-ins. We'll tackle all that in our next article.

Thanks are due to Kevin Miller and Tuviah Snyder at Runtime Revolution Ltd. for their unflagging assistance in improving my understanding of Revolution. A very special thanks is due to Geoff Canyon of Inspired Logic, LLC, for answering a number of questions about Revolution.

The Runtime Revolution web site (http://www.runrev.com) contains a wealth of information about Revolution as well as a free trial version of the development environment.

Tim Monroe is a member of the QuickTime engineering team at Apple. You can contact him at monroe@mactech.com. The views expressed here are not necessarily shared by his employer.