Volume Number: 20 (2004)
Issue Number: 3
Column Tag: Programming

QuickTime Toolkit

by Tim Monroe

Strange Brew

In the two previous QuickTime Toolkit articles (in MacTech, January and February 2004), we took a look at using Apple's QuickTime for Java classes to build a simple Java-based Macintosh application that can manipulate QuickTime movies. Our application -- called "JaVeez" -- can open movie files and display their movies in windows on the screen. Figure 1 shows a typical movie window displayed by JaVeez.

JaVeez supports all the standard editing operations on linear movies and can save edited movies into their original files or into new files. If the user tries to close an edited movie file, JaVeez displays the dialog box shown in Figure 2, which gives the user the opportunity to save or discard those edits.

In this article, I want to investigate what needs to be done to get JaVeez to run on Windows operating systems as well as on Mac OS X. In other words, I want to see how to turn the window in Figure 1 into the window in Figure 3.

And I want to see how to turn the dialog box in Figure 2 into the similar dialog box in Figure 4.

The good news is that we don't really need to do very much work at all to get JaVeez running on Windows, thanks to its Java underpinnings and to the platform-independent graphical toolkits AWT and Swing. We need to add a small amount of platform-specific code to adjust the placement of the Quit and "About JaVeez" menu items, and we need to make a few adjustments to our Xcode project. But ultimately, and indeed fairly quickly, we'll have a single executable file that can be launched on both Mac OS X and Windows computers.

Once we've got JaVeez running on Windows, we'll take a look at extending it on both platforms by allowing the user to resize its movie windows. To do that, we'll need to install a movie controller action filter procedure. As we've had some trouble doing that with a few of the development environments we've considered in recent articles, it will be interesting to see how easy it is to do this using QuickTime for Java.

Let's begin by considering the code changes we need to make to get JaVeez running properly on Windows, all of which are related to the creation and handling of menus. On Mac OS X, the "About JaVeez" and Quit menu items are contained in the Application menu. On Windows, those items need to be moved into the File menu and the Help menu, respectively. Figure 5 shows the File menu on Windows. Notice that the Quit item is labeled "Exit" on Windows.

Figure 6 shows the Help menu on Windows.

First we need to create the new menu and menu items; then we need to attach actions to those new menu items.

It's easy enough to add a separator line and the Exit menu item to our existing File menu. The only mildly interesting hoop we need to jump through is to figure out whether JaVeez is running on Macintosh or Windows. There are in fact at least three ways we can do this.

The standard way to check whether a Java application is running on Macintosh is to look at the mrj.version property, like this:

if (System.getProperty("mrj.version") != null)

"MRJ" stands for "Macintosh Runtime for Java", which was the official name of earlier versions of the Java support on Macintosh computers. If the mrj.version property exists, then the string object returned by the System.getProperty method is non-null and hence our application is running on some version of Mac OS.

While this way of determining that our application is running on Mac OS is still supported in JS2E version 1.4.1 and later, it is no longer the recommended way of doing so. A better way is to look at the os.name property, like this:

if (System.getProperty("os.name").equalsIgnoreCase(
                                                         "Mac OS X"))

This expression evaluates to true just in case our application is running on some version of Mac OS X.

There is yet a third way to determine the current system our application is running on, using the QTSession class we encountered in the two previous articles:

if (QTSession.isCurrentOS(QTSession.kMacOSX))

We'll use this third way throughout our application. For instance, Listing 1 shows the code we'll add to the addFileMenuItems method to add the Exit menu item to the bottom of the File menu.

addFileMenuItems
if (!(QTSession.isCurrentOS(QTSession.kMacOSX))) {
   fileMenu.addSeparator();
   miExit = new MenuItem(resBundle.getString("exitItem"));
   miExit.setShortcut(new MenuShortcut(KeyEvent.VK_Q, 
                                                         false));
   fileMenu.add(miExit).setEnabled(true);
   miExit.addActionListener(exitAction);
}

And Listing 2 shows the complete revised version of the addMenus method.

addMenus
public void addMenus () {
   editMenu = new Menu(resBundle.getString("editMenu"));
   fileMenu = new Menu(resBundle.getString("fileMenu"));
   movieMenu = new Menu(resBundle.getString("movieMenu"));
   
   addFileMenuItems();
   addEditMenuItems();
   addMovieMenuItems();
   
   if (!QTSession.isCurrentOS(QTSession.kMacOSX)) {
      helpMenu = new Menu(resBundle.getString("helpMenu"));
      addHelpMenuItems();
   }
   setMenuBar(mainMenuBar);
}

The addHelpMenuItems method, which is called by this new version of addMenus, is defined in Listing 3.

addHelpMenuItems
public void addHelpMenuItems () {
   miAbout = new MenuItem(resBundle.getString("aboutItem"));
   helpMenu.add(miAbout).setEnabled(true);
   miAbout.addActionListener(aboutAction);
      
   mainMenuBar.add(helpMenu);
}

All that remains is to define two new action classes and to create instances of those two classes (which, as we saw in Listings 1 and 3, we add as listeners to the Exit and "About JaVeez" menu items). Listing 4 shows how we can handle the Exit menu item on Windows. As you can see, we simply call the existing method attempQuit, which inspects all open movie windows and gives the user the chance to save or discard any unsaved changes.

ExitActionClass
public class ExitActionClass extends AbstractAction {
   public ExitActionClass (String text, KeyStroke shortcut) {
      super(text);
      putValue(ACCELERATOR_KEY, shortcut);
   }
   public void actionPerformed (ActionEvent e) {
      attemptQuit();
   }      
}

Similarly, Listing 5 shows how we can handle the "About JaVeez" menu item on Windows; again, we just call an existing method, about.

AboutActionClass
public class AboutActionClass extends AbstractAction {
   public AboutActionClass (String text) {
      super(text);
   }
   public void actionPerformed (ActionEvent e) {
   about();
   }
}

Finally, we need to add a few lines of code to the createActions method to create instances of these two classes; Listing 6 shows the code we need to add.

createActions
if (!(QTSession.isCurrentOS(QTSession.kMacOSX))) {
   exitAction = new ExitActionClass(
                        resBundle.getString("exitItem"), KeyStroke.getKeyStroke(
                                    KeyEvent.VK_Q, shortcutKeyMask));
   aboutAction = new AboutActionClass(
                        resBundle.getString("aboutItem"));
}

When this is all done, the File and Help menus will have the appearance shown earlier in Figures 5 and 6. Selecting the Exit menu item performs the standard application shutdown operations. And selecting the "About JaVeez" item displays the dialog box shown in Figure 7.

Note that we haven't changed any of the code called by the new actions. Our About box looks pretty much the same as its Macintosh counterpart, thanks to the wonders of Java and Swing.

Recall that we started building JaVeez by creating a new Xcode project based on the "Java AWT Application" template. The target built by Xcode is a double-clickable Macintosh application named JaVeez.app. This application responds appropriately to the basic Apple events OpenApplication, OpenDocuments, and QuitApplication. This means, in particular, that JaVeez automatically opens QuickTime movie files and Flash files dropped onto its icon in the Finder or in the Dock.

In fact JaVeez.app is just a directory that holds some special items. We can inspect those items by option-clicking on the JaVeez icon and selecting the "Show Package Contents" item. A Finder window opens that holds a folder named Contents. The Contents folder contains a folder named Resources, which in turn contains a folder named Java. Figure 8 shows the contents of the Java folder:

JaVeez.jar is a Java archive file, also called a jar file. It contains the executable code of the application along with any images or other resources used by the application. Jar files are the standard distribution containers for Java applications. In theory, we should be able to move this jar file to a Windows machine, double-click it, and have JaVeez launch and run. In practice, we need to make a couple of minor tweaks to our project for this to work correctly.

Indeed, double-clicking this existing JaVeez.jar file won't even launch JaVeez on Mac OS X. If we try it, we'll see the warning shown in Figure 9.

The Console log contains this message:

Failed to load Main-Class manifest attribute from
/Users/monroe/JaVeez/build/JaVeez.app/Contents/Resources/java/JaVeez.jar

The problem is that the default jar file's manifest (a special file in the archive that contains information about the other files in the archive) does not indicate which class in the jar file is the main class. To fix this, let's add to the project a new file called JaVeez.mf that contains these lines:

Main-Class: JaVeez

(There is a newline character at the end of the first line; it needs to be there in order for our new manifest to work correctly.) Then we can set this file as the project's manifest file by specifying its name in the target settings panel, as shown in Figure 10. When we build JaVeez, the lines in the file JaVeez.mf will be appended to the default manifest data.

While we're here, let's adjust one other project setting, to prevent an annoying but harmless warning from being issued each time we launch JaVeez. Select the "Cocoa Java-Specific" pane and uncheck the "Needs Java" box, which is shown in Figure 11.

Leaving that setting at its default value will result in this warning appearing on the console whenever we launch JaVeez:

-[NSJavaVirtualMachine initWithClasspath:] cannot 
                           instantiate a Java virtual machine:

Let's rebuild JaVeez so that these changes take effect. Now double-clicking the jar file will launch the application, as desired. That's very cool. What's perhaps not so cool is that when we launch JaVeez by double-clicking the JaVeez.jar file, we lose the Finder interaction we got when we launched it by double-clicking the JaVeez.app file; in particular, we can't drop files onto the JaVeez.jar file or into its Dock icon.

Can we now move the jar file to a Windows machine and run it? Not quite, but almost. Recall that JaVeez uses the Application class in the com.apple.eawt package to handle the basic application-related Apple events. This package is not implemented on Windows, so we need to do a little bit of work to keep the Windows Java runtime engine happy.

There are several ways to work around this issue. The easiest way is to add some stub classes to our project that provide empty implementations of the classes and methods in com.apple.eawt. Fortunately, Apple provides a set of stubs that can be used for this purpose. Look for the sample code package called AppleJavaExtensions on the Apple developer site. This package consists of a file called AppleJavaExtensions.jar. We need to unpack that jar file; in a Terminal window, execute this command:

jar -xf AppleJavaExtensions.jar

When this command completes successfully, you'll see two new directories named META-INF and com. Copy the com directory into the JaVeez folder that contains the application project files and source code. Add that folder to the project; the project file now looks like Figure 12.

Build the project and copy the JaVeez.jar file to a computer running Windows that has Java and QuickTime installed on it. Double-click the jar file and behold the new empty movie window that appears (Figure 13).

Use the Open menu item in the File menu to open a QuickTime movie file and then spend a few minutes verifying that the movie and its window behave as expected. (See Figure 3 again.)

Let's pause to consider our progress so far. We now have a fully-functional Windows application, and we did that with just a couple of easy adjustments to our existing project and source code. We added some code to handle the different locations of the Quit/Exit and About menu items on Mac and Windows, and we tweaked the jar file's manifest to specify the application's main class. Also, we added a few stub classes to our project to provide empty implementations of the com.apple.eawt package for Windows. Everything runs fine. We're done, right?

Wrong. To be honest, I'd be very happy to consider our porting work done and then move on to add some features to JaVeez that show off the interesting capabilities of QuickTime for Java. After all, we do now have a single jar file that runs on both Mac OS X and Windows and that has all the features we originally planned. But in fact we're not quite finished. The reason is that the stub-class solution described above, though technically impeccable in terms of getting the job done, has a decidedly non-Java flavor. The generally-preferred solution to the problem of classes being implemented on one platform but not on another is to use a feature of the Java language known as reflection. If you're happy using the stub classes, skip to the next section. Otherwise, read on....

Here's the crux of the issue: JaVeez currently contains the following line of code, which creates an instance of the com.apple.eawt.ApplicationAdapter class and attaches it to fApplication.

fApplication.addApplicationListener(
                  new com.apple.eawt.ApplicationAdapter() {

When the Java runtime engine loads a package, it looks for all classes referenced in the package. Even though this line of code won't actually be executed on Windows, the runtime loader still wants to find some code for the ApplicationAdapter class.

Rather than solve this problem by providing no-op implementations of the classes in com.apple.eawt, which is what the stub classes provide, we can factor the relevant code into a new package and then load that package only if JaVeez is running on Mac OS X. The Windows runtime engine never sees the references to com.apple.eawt, so the stubs are no longer necessary. Very nice.

Let's begin by defining a new package, called "osxadapter", which imports the com.apple.eawt classes and the JaVeez application classes:

package osxadapter;
import com.apple.eawt.*;
import javeez.*;

The osxadapter package contains a single class, OSXAdapter, which defines three public methods: handleAbout, handleQuit, and registerMacOSXApplication. (The code upon which this class is based defines two additional methods for handling an application's preferences; since JaVeez does not support user-selectable preferences, I've taken the liberty of removing those methods.) Listing 7 shows the complete definition of the OSXAdapter class.

OSXAdapter
public class OSXAdapter extends ApplicationAdapter {
   private static OSXAdapter    theAdapter;
   private static com.apple.eawt.Application
   theApplication;
   private JaVeez    mainApp;
   
   private OSXAdapter (JaVeez inApp) {
      mainApp = inApp;
   }
   
   // handle the About menu item
   public void handleAbout (ApplicationEvent ae) {
      if (mainApp != null) {
         ae.setHandled(true);
         mainApp.about();
      } else {
         throw new IllegalStateException("handleAbout: JaVeez 
         instance detached from listener");
      }
   }
   
   // handle the Quit menu item
   public void handleQuit (ApplicationEvent ae) {
      if (mainApp != null) {
         ae.setHandled(false);
         mainApp.attemptQuit();
      } else {
         throw new IllegalStateException("handleQuit: JaVeez instance 
         detached from listener");
      }
   }
   
   public static void registerMacOSXApplication (JaVeez inApp) {
      if (theApplication == null) {
         theApplication = new com.apple.eawt.Application();
      }         
      
      if (theAdapter == null) {
         theAdapter = new OSXAdapter(inApp);
      }
      
      theApplication.addApplicationListener(theAdapter);
   }
}

The first two methods, handleAbout and handleQuit, simply call the existing about and attemptQuit methods in JaVeez. They also both call the setHandled method of the ApplicationEvent class to indicate whether or not the event has been handled. Notice that handleQuit needs to pass false to setHandled since we want to allow the user to cancel the application shut-down operation.

The interesting method in the OSXAdapter class is registerMacOSXApplication, which creates an instance of the Application class, creates an instance of the OSXAdapter class, and then adds the adapter object as a listener for the Application object. The registerMacOSXApplication method is the only method that JaVeez needs to call explicitly at run-time. Of course JaVeez cannot invoke that method by name (since it references classes that do not exist on Windows machines); rather, it invokes that method indirectly, using Java's reflection APIs. Listing 8 shows the definition of the macOSXRegistration method that we need to add to JaVeez.

macOSXRegistration
public void macOSXRegistration () {
   if (QTSession.isCurrentOS(QTSession.kMacOSX)) {
      try {
         Class osxAdapter = 
                  Class.forName("osxadapter.OSXAdapter");
                        
         Class[] defArgs = {JaVeez.class};
         Method registerMethod = 
                        osxAdapter.getDeclaredMethod(
                              "registerMacOSXApplication", defArgs);
         if (registerMethod != null) {
            Object[] args = {this};
registerMethod.invoke(osxAdapter, args);
         }
      } catch (Exception e) {
         e.printStackTrace();
      }
   }
}

As you can see, macOSXRegistration calls Class.forName to find the class named "OSXAdapter" in the package osxadapter. If it finds it, macOSXRegistration executes that method by calling the invoke method.

So JaVeez now runs on both Macintosh and Windows computers. We can open one or more QuickTime movies, play them back or interact with them, edit them, and save or discard those edits as desired. JaVeez currently meets or exceeds all our original requirements, using nothing more than standard Java or QuickTime for Java classes and methods.

Let's consider briefly how to extend JaVeez. In particular, let's see how to install a movie controller action filter procedure to receive and respond to movie controller actions. For the moment, we'll handle only the mcActionControllerSizeChanged action, which lets us know that the controller has changed size. We'll use that action to support resizing of movie windows.

You may recall from our first article on Java and QuickTime that we initially configured our movie windows so that they cannot be resized by the user; we did that by adding this line of code to the JaVeez class constructor:

setResizable(false);

Now you might think that part of what we need to do in order to allow resizable windows is to change that false to true. Unfortunately, doing that would lead to problems, because AWT would want to draw its own grow box in the lower-right corner of a movie window, as shown in Figure 14.

Instead, we want to use the grow box provided by the QuickTime movie controller, which you can see in Figure 15.

To accomplish this, we'll continue to pass false in the call to setResizable. We'll get the movie controller to draw its grow box in the standard way, by defining a non-empty grow box rectangle. In the createNewMovieFromFile method, we'll execute these lines of code:

QDRect rect = new QDRect(32000, 32000);
mc.setGrowBoxBounds(rect);

Once we've done this, the movie controller will draw the grow box in the appropriate location and allow the user to resize a movie by click-dragging in that box.

Now we need to resize the Java frame (that is, window) when the user resizes the movie using the grow box. As usual, we do this by suitably responding to the mcActionControllerSizeChanged action. First, we need to define a movie controller action filter method. Listing 9 shows the code we'll add to JaVeez.

execute
public class MCActionFilter extends ActionFilter {
   public boolean execute (MovieController mc, int action) { 
     if (action == 
                  StdQTConstants.mcActionControllerSizeChanged) {
         pack();
     }
      return false; 
   }
}

As you can see, we simply call the pack method when we receive the appropriate action. We also need to implement the getPreferredSize method, which is called by pack. Listing 10 shows our getPreferredSize method.

getPreferredSize
public Dimension getPreferredSize () {
   Dimension frameDim = new Dimension(0, 0);
   
   try {
      QDRect rect = m.getBox();
      if (mc.getVisible())
         rect = mc.getBounds();
       
      // make sure that the movie has a non-zero width;
      // a zero height is okay (for example, with a music movie with 
         no controller bar)
      if (rect.getWidth() == 0)
         rect.setWidth(this.getSize().width);
       
      // resize the frame to the calculated size, plus window borders
      frameDim.setSize(
               rect.getWidth() + (getInsets().left + 
                                                getInsets().right),
               rect.getHeight() + (getInsets().top + 
                                                getInsets().bottom));       
   } catch (QTException err) {
      err.printStackTrace();
   }
   
   return(frameDim);
}

There's nothing much new here. In fact, this method is based on the sizeWindowToMovie method that appeared in the first article in this series. Using getPreferredSize is by far better Java code.

Finally, we need to install the action filter method, like this:

mc.setActionFilter(new MCActionFilter(), false);

With these changes, the movie windows displayed by JaVeez should resize as expected.

QuickTime for Java provides a very nice set of capabilities for building QuickTime applications with Java. The support for displaying and controlling movies using movie controller components is extensive and easy to use. And, as we've seen in detail in this article, it's extremely easy to write our applications in such a way that they are easily portable to Windows computers running QuickTime and Java. Whether we use Java's reflection APIs or resort to the stub classes, we can get our OS X application running on Windows in a matter of minutes. Cross-platform portability is of course one of the key promises of Java, and it's refreshing to see that promise realized so fully in this case.

Thanks are due once again to Anant Sonone for his assistance and support. The OSXAdapter class is based upon sample code by Matt Drance, who also graciously provided advice on these issues.

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.