Apple Developer Connection
Advanced Search
Member Login Log In | Not a Member? Contact ADC

Scripting the COM/ActiveX Control in QuickTime 7 for Windows

QuickTime 7 for Windows introduces a completely new COM/ActiveX control that is fully scriptable from Visual Basic, C#, JavaScript, C++ and other applications that can host COM objects. This means that its even easier for Windows programmers to build standalone Windows applications that use QuickTime without needing to master QuickTime's C/C++ API.

Important: This new COM control is included in addition to the QuickTime ActiveX browser plug-in. They are not the same thing

The new QuickTime COM control has an API that will be familiar to Visual Basic programmers and others used to working with COM objects. It is intended to make it easy to create stand-alone Windows applications that use QuickTime. The new COM control is not a browser plug-in, and will not run in a browser or other Web-based application.

For Web-based applications, use the QuickTime ActiveX browser plug-in; it is scriptable using JavaScript from most browsers using the same platform-independent API as the QuickTime browser plug-ins for Netscape and Safari. The QuickTime browser plug-in is the cross-platform solution for Writing Web pages that interact with QuickTime.

Note: The API for controlling the QuickTime ActiveX browser plug-in using JavaScript can be found in the JavaScript Scripting Guide for QuickTime.

The remainder of this article is intended for programmers who want to provide high-level QuickTime movie playback and control, including some import, export, and editing capabilities, to Windows applications written in Visual Basic and other languages.

Advantages For Developers

If you are a Visual Basic programmer or enterprise software developer doing in-house development, the COM control implementation offers a number of important advantages:

  • You can build Windows desktop applications more easily with Visual Basic or C#, combining QuickTime with the rich and powerful .NET Framework.
  • You can write useful utility scripts for working with QuickTime in either JavaScript or VBScript. These scripts can be run within the Windows Scripting Host environment by simply double-clicking the .js or .vbs script files, or from the command line using cscript.
  • You don't have to access the low-level functionality provided by the full QuickTime API in order to use QuickTime in your application development.

For example, if your Windows server can run a Visual Basic, C#, or script application that uses QuickTime, you have the possibility to create custom QuickTime content interactively, delivering that content over the Web. As long as your clients have QuickTime installed, your content will work with Windows and non-Windows clients, Internet Explorer and non-Internet Explorer browsers.

QuickTime Player itself uses the new QuickTime COM control for virtually all of its access to QuickTime.

Important: The QuickTime 7 ActiveX browser plug-in is not scriptable via Visual Basic. It is scriptable, however, in JavaScript using the same syntax as the Netscape-style plug-in, and works the same on all browsers for Windows or Macintosh.

How It Works

The new COM control is comprised of two separate DLLs:

  • An COM/ActiveX control (QTOControl.dll) that "knows" how to open a movie and manage the interaction with the operating system and the host application.
  • A library (QTOLibrary.dll) which provides a COM interface to a movie and other QuickTime objects, and to QuickTime itself.

The COM library is a very thin layer that sits on top of the low level QuickTime APIs and provides a COM wrapper object for each logical QuickTime object. Each COM object exposes the properties, methods, and notifications of the QuickTime object it wraps.

The object hierarchy is illustrated in Figure 1.

The COM/ActiveX control object hierarchy

Figure 1: The COM/ActiveX Control Object Hierarchy

If you are a Windows developer, you know that the Component Object Model (COM) specification defines how a host application accesses the component, how the component notifies the host application of events, standard data types for data exchange with the OS or other components. A COM control is a type of COM component that has a visual display of some kind, restricting its placement to visual containers such as a form or dialog box. COM controls typically manage their own window.

In the .NET environment, the new QuickTime COM control is accessed via the .NET Framework's COM Interop layer. Primary Interop Assemblies (.NET wrappers for COM objects) will be provided with the QuickTime 7 SDK.

Note: The COM control does not provide a native .NET managed code interface to QuickTime.

Visual Basic .NET and C#

You will use the QuickTime COM control and its various methods from Visual Basic .NET and C# as described in the following sections.

Basics

Once you instantiate the QuickTime COM control and load a movie into it, you can then get at the QTOLibrary object model via the control's Movie property, which returns a QTMovie COM object.

Constants and Enumerations

To use the constants and enumerations associated with the QuickTime COM control, you must either explicitly precede them with the QTOControlLib namespace identifier, or else include an import for the QTOControlLib.

In Visual Basic, you do this with an Imports directive at the beginning of your module.

An example of using an explicit namespace identifier is, as follows: 

AxQTControl1.Sizing = QTOControlLib.QTSizingModeEnum.qtControlFitsMovie
AxQTControl1.SetScale(2)
AxQTControl1.Sizing = QTOControlLib.QTSizingModeEnum.qtMovieFitsControl

The same example with imported namespace: 

Imports QTOControlLib
AxQTControl1.Sizing = QTSizingModeEnum.qtControlFitsMovie
AxQTControl1.SetScale(2)
AxQTControl1.Sizing = QTSizingModeEnum.qtMovieFitsControl

In C#, the namespace can be imported with the using directive: 

using QTOControlLib;

To use the constants and enumerations associated with the QuickTime COM library, you must either explicitly precede them with the QTOLibrary namespace identifier, or else include an import (C#: using directive) for the QTOLibrary.

Getting Started With QuickTime COM Control And Visual Basic 6

In the next few sections we'll build a simple movie player application in Visual Basic 6 which will include the following capabilities:

  • Simple Movie Playback using a Movie Controller
  • Open, Open from URL, Close
  • Cut/Copy/Paste/Undo
  • Export
  • FullScreen playback

The project will be built in a series of steps, starting with simple movie playback using a movie controller. Successive steps will add new capabilities to the project, each building on the previous step.

Project 1: Simple Movie Playback Using a Movie Controller

To get started with the new COM control in Visual Basic 6:

  1. Create a new Standard EXE project.
  2. Choose Project | Components and scroll down to the Apple QuickTime Control 2.0. Check the box beside this component in the list and click OK to add it to the Visual Basic 6 Toolbox.
  3. Add the QuickTime COM control (QTControl1) to Form1.
  4. The QuickTime COM control has a property page--that is, a dialog box that allows you to set some basic QuickTime control properties. You access the property page by clicking the QuickTime Control in Form1 then pressing Shift F4 or clicking the Property Pages menu item in the View menu. Do this now to bring up the property page dialog as shown in Figure 2:

The QuickTime COM Property Page Dialog

Figure 2: The QuickTime COM Property Page Dialog

  1. Select '2 - Movie Fits Control Maintain Aspect Ratio' in the Sizing popup because we want the movie to fit into the control but we also want to maintain the proper movie aspect ratio.
  2. Select the sample movie file \Program Files\QuickTime\Sample.mov installed by QuickTime for the Movie FileName/URL property. Note also the 'Movie Controller Visible' property is set—this will ensure that the movie controller is displayed along with the movie in the window.
  3. Verify your new settings as shown in Figure 3 below and click the OK button to save these properties for the control:

Updated QuickTime Control Property Settings

Figure 3: Updated QuickTime Control Property Settings

  1. Build and run the project. You will see the movie along with its associated movie controller displayed in the window as shown in Figure 4 below.

Simple Movie Player with Movie Controller

Figure 4: Simple Movie Player with Movie Controller

  1. Use the various controls in the movie controller to control movie playback.

As you can see, with just a few simple steps and no real coding we've created a simple movie player application which displays a movie along with a controller in a window.

Now we'll look at how to create some more sophisticated applications using the QuickTime COM Control.

Project 2: Movie Open, Open URL and Close

In this next step, we'll add to our application the ability to open and close movie files on disk and from a URL.

More specifically, we'll add a File->Open menu item to allow us to open any movie file on disk. Similarly, we'll add a File->Open URL menu item to allow us to open any movie URL. Finally, we'll add a Close menu item to allow us to close any opened movie.

Follow these steps:

  1. You must first add the Microsoft Common Dialog Control to your project. Choose Project | Components.
  2. Scroll down until you see the Microsoft Common Dialog Control 6.0.
  3. Check the box beside it and click the OK button to add the dialog control to the toolbox.
  4. Place the dialog control (CommonDialog1)on Form1.
  5. Choose View | Code to bring up the code window for Form1.
  6. Paste the code from Listing 1 below into the code window for Form1. The GetFileName function uses the Common Dialog Control to display a file browser dialog as shown in Listing 1:

Listing 1: The GetFileName function to display a file open dialog


Function GetFileName()
    CommonDialog1.ShowOpen
    GetFileName = CommonDialog1.FileName
End Function
  1. Close the code window for Form1.
  2. Choose Tools | Menu Editor (or press Ctrl+E) to bring up the Menu Editor for Form1.
  3. To Form1 add a File menu. Enter File in the Caption field, mnuBar in the Name field, and 0 in the Index field.
  4. To the File menu add a menu item for Open. Enter & Open in the Caption field, mnuFile in the Name field, enter 0 for the Index and select Ctrl+O as the shortcut.
  5. Add menu items for Open URL and Close in a similar fashion.
  6. Bring up the code window for Form1 and paste the code from Listing 2.

Listing 2: File Menu Handling Code

Private Sub mnuFile_Click(Index As Integer)

    Select Case Index

        Case 0 'Open
            Dim fname As String
            fname = GetFileName()
            If fname < > "" Then
                QTControl1.URL = GetFileName()
            End If

        Case 1 'Open URL
            Dim movieURL As String
            movieURL = InputBox("Enter a URL:", "URL",
"http://www.server.com/movies/sample.mov")
            If movieURL < > "" Then
                QTControl1.URL = movieURL
            End If

        Case 2 'Close
            QTControl1.URL = ""
    End Select

End Sub

After you have completed these steps, you can:

  1. Build and run the application.
  2. Choose File | Open to open a movie file on disk. Choose File | Open URL to open a movie URL and choose File | Close to close the current movie. Here's how it looks:

SimplePlayer with File Menu

Figure 5: SimplePlayer with File Menu

Project 3: Simple Editing

Now we'll add some simple editing capabilities to our project - the ability to perform Undo, Cut, Copy and Paste.

Follow these steps:

  1. Choose Tools | Menu Editor (or press Ctrl+E) to bring up the Menu Editor for Form1.
  2. To Form1 add an Edit menu. Enter Edit for the menu Caption field, mnuBar for the Name field and 1 for the Index.
  3. To the Edit menu add a menu item for Undo. Enter Undo in the Caption field, mnuEdit in the Name field and 0 for the Index.
  4. Add menu items for Cut, Copy and Paste in a similar fashion.
  5. Bring up the code window for Form1 and paste the code from Listing 3 to handle editing the movie.

Listing 3: Edit Menu Code


Private Sub mnuEdit_Click(Index As Integer)

    Select Case Index
        Case 0  'Undo
            If QTControl1.URL < > "" Then
                QTControl1.Movie.Undo
            End If
        Case 2  'Cut
            If QTControl1.URL < > "" Then
                QTControl1.Movie.Cut
            End If

        Case 3  'Copy
            If QTControl1.URL  < > "" Then
                QTControl1.Movie.Copy
            End If
        Case 4  'Paste
            If QTControl1.URL  < > "" Then
                QTControl1.Movie.Paste
            End If
    End Select
End Sub

After you have completed these steps, you can:

  1. Build and run the application.
  2. Choose any of the Edit menu items to perform editing operations on the movie (hold down the Shift key to select portions of the movie while it is playing, or drag the slider while holding down the Shift key). Here's how it looks:

SimplePlayer with File Menu

Figure 6: SimplePlayer with Edit Menu

Project 4: Movie Export

In this project, we'll show how to use the QuickTime movie exporters to display the export dialog and save our movie to a different format.

Follow these steps:

  1. In order to use the QuickTime COM object types in your Visual Basic 6 application you will need to add the QuickTime COM library to your project. Choose Project | References and add the Apple QuickTime Library 2.0.
  2. Choose Tools | Menu Editor (or press Ctrl+E) to bring up the Menu Editor for Form1.
  3. To the File menu add a separator menu item. Enter '-' for the menu Caption field, mnuFile for the Name field and 3 for the Index.
  4. To the File menu add an Export menu item. Enter Export for the menu Caption field, mnuFile for the Name field and 4 for the Index.
  5. Bring up the code window for Form1 and paste the code from Listing 4 into the mnuFile. Click routine to handle movie exporting.

Listing 4: Movie Export Code


Case 4 'Export'
 If QTControll.Movie Is Nothing Then Exit Sub
 If QTControll.Movie.canExport Then
    	Dim qt As QTOLibrary.QTQuickTime
    	Set qt = QTControl1.QuickTime
      	If qt.Exporters.Count = 0 Then
          	qt.Exporters.Add
       End If
       Dim exp As QTOLibrary.QTExporter
       Set exp = qt.Exporters(1)
       exp.SetDataSource QTControl1.Movie
       exp.ShowExportDialog
    End If

After you have completed these steps, you can:

  1. Build and run the application.
  2. Select the Export menu item to display the export dialog for the active movie and save it to another format as shown in Figure 7:

Movie Export Dialog

Figure 7: Movie Export Dialog

Project 5: Full Screen Movie Display

In this project, we'll show how to display QuickTime movies that fill the entire screen.

Follow these steps:

  1. Choose Tools | Menu Editor (or press Ctrl+E) to bring up the Menu Editor for Form1.
  2. To the File menu add a FullScreen menu item. Enter FullScreen for the menu Caption field, mnuFile for the Name field and 5 for the Index.
  3. Bring up the code window for Form1 and paste the code from Listing 5 onto the end of the mnuFile_Click function to turn on fullscreen playback mode for the movie when the FullScreen menu item is selected.

Listing 5: Turning on Movie Full Screen Playback

...

Case 5 'FullScreen
            QTControl1.FullScreen = True
  1. Lastly, paste the code from Listing 6 to handle movie window resizing when fullscreen movie playback is turned on and then later turned off.

Listing 6:Handling Movie Full Screen Begin/End

Private Sub QTControl1_StatusUpdate(ByVal statusCodeType As Long, ByVal statusCode As Long,
   ByVal statusMessage As String)

  Select Case statusCodeType
     Case qtStatusCodeTypeControl
        Select Case statusCode
          Case qtStatusFullScreenBegin
            Me.Hide  ' hide movie window

          Case qtStatusFullScreenEnd
            ' set movie back to a reasonable size
            QTControl1.SetScale 1  
            Me.Show	' show movie window again
        End Select
  End Select
End Sub
  1. Build and run the application
  2. Select Full Screen from the File menu. The movie should display full screen as shown in Figure 8.

Movie Fullscreen Playback

Figure 8: Movie Full Screen Playback

  1. Press the Esc key to return the movie back to its normal size.

Conclusion

As you can see, the new QuickTime 7 COM/ActiveX control is quite simple to use and gives developers convenient access to the underlying QuickTime framework. Now more than ever this makes it easier for Windows programmers to build standalone Windows applications that use QuickTime without needing to master QuickTime's extensive C/C++ API.

For More Information

Posted: 2005-09-12
tml>