The QTSimpleApplet Example

A good starting point for understanding QuickTime for Java is the QTSimpleApplet program from the QuickTime for Java SDK. The code listing for QTSimpleApplet.java is given below:

/*
 * QuickTime for Java SDK Sample Code

   Usage subject to restrictions in SDK License Agreement
 * Copyright: © 1996-1999 Apple Computer, Inc.

 */
import java.applet.Applet;
import java.awt.*;
import java.io.*;

import quicktime.*;
import quicktime.io.QTFile;

import quicktime.app.QTFactory;
import quicktime.app.display.*;
import quicktime.app.image.ImageDrawer;	// for exceptions

public class QTSimpleApplet extends Applet {
	private Drawable myQTContent;
	private QTCanvas myQTCanvas;
	
	public void init () {
		try {
			// this is a workaround required by a bug in the loading
			// mechanism of applets using the JavaPlugin on Netscape on Win
			if (QTSession.isInitialized() == false)
				QTSession.open();

				// set up a QTCanvas which will disply its content 
				// at its original size of smaller and centered in the space given
				// to the QTCanvas when the applet is layed out
			setLayout (new BorderLayout());
			myQTCanvas = new QTCanvas (QTCanvas.kInitialSize, 0.5F, 0.5F);
			add (myQTCanvas, "Center");		
			
			QTFile file = new QTFile (getCodeBase().getFile() + getParameter("file"));
			myQTContent = QTFactory.makeDrawable (file);
		} catch (QTException qtE) {
				// something wrong with the content but QT itself is OK
			if (QTSession.isInitialized())
				myQTContent = ImageDrawer.getQTLogo();
			else
				throw new RuntimeException (qtE.getMessage());		
		} catch (FileNotFoundException fnfE) {
			myQTContent = ImageDrawer.getQTLogo();
		
		} catch (IOException ioE) {
				// the IOException would occur as a violation of
				// java security settings on the user machine - throw it again
			throw new SecurityException (ioE.getMessage());
		}
	}	

	public void start () { 
		try { // if QT was not successfully initialized the QTCanvas will be null
			if (myQTCanvas != null)
				myQTCanvas.setClient (myQTContent, true);			
		} catch (QTException e) {
			e.printStackTrace();
		}
	}
	
	public void stop () { 
		if (myQTCanvas != null)
			myQTCanvas.removeClient();
	}
	
	public void destroy () {
		QTSession.close();
	}
}

The out of QTSimpleApplet running in an applet viewer is shown in Fig. 9.1.

{\tt QTSimpleApplet} Output

The things to note about this program are:

• We can display multimedia content (On Internet or locally) in less than a dozen lines of Java code.
• The media may include video, audio, text, timecode, music/ MIDI, sprite animation, tween, MPEG, or even movies that let you use Apple's QuickTime VR and QuickDraw 3D capabilities.
• You can control with the standard QuickTime movie controller buttons, uses the media as specified in the applet tag -- in this example, sample.mov:

  <applet code="QTSimpleApplet.class" width=200 height=100>
  		<param name="file" value="sample.mov">
  	</applet>
  

The basic operation of the code is as follows:

• The QTCanvas, QTDrawable, and QTFactory classes that belong to the quicktime.app package and are discussed in greater detail. These are typically used in all Quicktime presentations.
• QTCanvas, QTDrawable create objects where media can be presented:
  • QTCanvas is the object responsible for handling the integration from the java.awt side between Java and QuickTime.
  • The QTCanvas also has parameters that let you control the resizing of the client that it presents -- here we tell the canvas to center the client within the space given by the applet's layout manager.This ensures that the client is only as big as its initial size (or smaller if you make the canvas smaller).
  • The QTSession.open() call performs a gestalt check to make sure that QuickTime is present and is initialized. Note that this is a required call before any QuickTime for Java classes can be used.
  • To set up a QTCanvas object that displays its content at its original size or smaller and is centered in the space given to the QTCanvas when the applet is laid out, we do the following:

    setLayout (new BorderLayout());
    myQTCanvas = 
      new  QTCanvas (QTCanvas.kInitialSize, 0.5F,
                     0.5F);
    add (myQTCanvas, "Center");
    QTFile file = new QTFile (getCodeBase().getFile() +
    getParameter("file"));
    myQTContent = QTFactory.makeDrawable (file);
    } catch (Exception e) {
    e.printStackTrace();
    ...
    }
    }
    

• QTFactory() methods are used to manufacture a wide variety of multimedia objects that QuickTime supports.
  • The QTFactory.makeDrawable() method is used to create an appropriate QuickTime object for the media that is specified in the <PARAM> tag in the call from the HTML file.
  • If a QTException is thrown in the init() method, an appropriate action should be taken by the applet, depending on the error reported. In the start() method shown in the next code snippet, you set the client of the QTCanvas. This QTCanvas.client is the QuickTime object (i.e., an object that implements the QTDrawable interface) that draws to the area of the screen that the QTCanvas occupies. This is the QuickTime side of the integration between Java and QuickTime:

    public void start () {
    try { my QTCanvas.setClient (myQTContent, true);
    } catch (Exception e) {
    e.printStackTrace();
    }
    }
    

  • You use the stop() method to remove the client from the QTCanvas. It will be reset in the start() method if the applet is restarted. destroy() is used to close the QTSession. This protocol enables the applet to be reloaded, suspended, and resumed -- for example, if the user is leaving and returning to the page with the applet. The init()/de-stroy(), and start()/stop() methods are reciprocal in their activities.

    public void stop () {
    my QTCanvas.removeClient();
    }
    public void destroy () {
    QTSession.close();
    }
    

  • You need to call QTSession.close() if you have previously called QTSession. open() in order to shut down QuickTime properly.
• The init() method may throw exceptions because the required file was not found or the applet does not have permission from Java's security manager to read that file. Alternatively, the required version of QuickTime may not be installed. The applet should deal with these issues appropriately.