Playing a Movie Using HIMovieView

An HIMovieView is a specialized human interface object that displays QuickTime movies. It is a subclass of HIView, which is a subclass of HIObject. HIMovieView includes a movie controller component, a set of display coordinates, and more.

HIView is an object-oriented view system. Using the HIView model, every item within a window is a view: the root control, all embedded controls, the close, zoom, and minimize buttons, the resize control, and so on. Current Control Manager function calls are layered on top of this HIView model, so you can also control a view using existing Control Manager functions.

Some benefits of the HIView model include the following:

• Core Image (Quartz) is the native drawing system, but you can still use QuickDraw if desired.

• Coordinate system is not limited by the 16-bit space of QuickDraw. Floating point coordinates are valid.

• Simpified coordinate system for view bounds and view position within its parent.

• Views can be layered; you can easily place controls in front of, or behind, other controls.

• Views can be attached to, and detached from, parent windows, allowing you to move a view between windows.

Because HIMovieView is a subclass of HIView, it inherits these benefits over traditional controls.

Creating an HIMovieView

An HIMovieView can be created in Interface Builder by dragging an icon from a palette; you can then use the inspector window to set most of the viewing parameters without writing any code at all. In this case, you set the parent window, initial position of the movie within the window, and the initial size of the movie’s display area, all in Interface Builder. There are attribute buttons to select whether the movie control bar is visible, whether the system automatically grants time to the movie as needed, whether the controller accepts keyboard input, whether the movie is editable, and whether the controller should enable its editing user interface as shown in Figure 1-1. All this information is stored in the nib file that specifies the parent window.

Alternatively, you can create and configure an HIMovieView entirely in code, in which case you must also set the various parameters, such as height and width, from your code when you instantiate the view. An example would look like this:

HIViewRef theHIMovieView;

// create an HIMovieview

HIObjectCreate(kHIMovieViewClassID, NULL, &theHIMovieView);

// set the movie attributes for the HIMovieView

HIMovieViewChangeAttributes(theHIMovieView, kHIMovieViewStandardAttributes, 0);

// attach my movie to the HIMovieView

HIMovieViewSetMovie(theHIMovieView, myMovie);

As a third alternative, you can create a generic HIView using Interface Builder, setting some of the view parameters there, then subclass it as an HIMovieView and configure it further from your code at runtime.

If you create a generic HIView in Interface Builder (in this case with an ID of 'moov',0, in a window named MovieWindow), your code would look something like this:

HIViewID kMovieViewID = {'moov', 0};

HIViewRef theHIMovieView;

...

// get the window

CreateWindowFromNib(nib, CFSTR("MovieWindow"), &window);

// find our HIMovieView

HIViewFindByID(HIViewGetRoot(window), kMovieViewID, &theHIMovieView);

// set some attributes and a movie for the HIMovieView

HIMovieViewChangeAttributes(theHIMovieView, kHIMovieViewAutoIdlingAttribute |

kHIMovieViewControllerVisibleAttribute,

kHIMovieViewEditableAttribute |

kHIMovieViewHandleEditingHIAttribute |

kHIMovieViewAcceptsFocusAttribute);

HIMovieViewSetMovie(theHIMovieView, aMovie);

// install some event handlers

InstallWindowEventHandler(window, &MainWindowEventHandler,

GetEventTypeCount(windowEvents), windowEvents, window, NULL);

InstallHIObjectEventHandler((HIObjectRef)theHIMovieView, &HIMovieViewEventSniffer,

GetEventTypeCount(viewEvents), viewEvents, window, NULL);

// on with the show

ShowWindow(window);

...

kHIMovieViewDataMovieController       (read-only MovieController)

kHIMovieViewDataControllerBarHeight   (read-only UInt32)

kHIMovieViewDataMovie                 (Movie)

kHIMovieViewDataControllerVisible     (Boolean)

kHIMovieViewDataLocateTopLeft         (Boolean)

kHIMovieViewDataEditable              (Boolean)

kHIMovieViewDataHandleEditingHI       (Boolean)

kHIMovieViewDataKeysEnabled           (Boolean)

kHIMovieViewDataManualIdling          (Boolean)

Playing a Movie Using a Carbon Movie Control

QuickTime 6 for Mac OS X introduced the Carbon movie control. The CreateMovieControl function takes a movie and a window as arguments and creates a control containing a standard movie controller component. The movie control can then act as a Carbon event target, receiving Carbon events and dispatching them to its movie controller.

In other words, the Carbon movie control is implemented as a custom control that includes an event handler that handles any Carbon events sent to controls. When a Carbon movie control is created for a movie, a movie controller component instance is also created. The movie control then directs user interface events to its movie controller.

Your application can install additional event handlers on the Carbon movie control to handle such things as contextual menu clicks or to intercept events to do special processing. Control Manager calls can be made as well.

The movie controller is automatically idled by means of an event loop timer, using the Idle Manager to optimize idling frequency.

Playing a Movie Using a Movie Controller Component

If you are working in Windows OS or compiling for a version of QuickTime prior to QuickTime 6, you do not have access to either HIMovieView or Carbon movie controls. Consequently, you need to work with movie controller components directly. This is more complicated than playing a movie with an HIMovieView or a Carbon movie control, but it is still relatively straightforward; there’s just more housekeeping.

You need to decide where your visual output should appear in the parent window and how much space to give it. This defines the movie controller’s bounding box, the rectangle that encompasses the movie display area, and the movie control bar. You can get the movie’s natural bounds and set the size of the display area to match, or choose an arbitrary display area and scale the movie to fit. If the movie is too large for the bounding box, it will be scaled down automatically, but it will only be scaled up to fill the display area if you request this behavior.

Once you’ve decided where your movie should appear, you open a movie controller component and attach it to your movie. You then provide time to the movie controller from within your application run loop.

Listing 1-5 is an example of opening a movie controller component and using it to play a movie.

Listing 5-1  Using a movie controller component to play a movie

  WindowPtr     myWindow = NULL;

  Rect          myBounds = {50, 50, 100, 100};

  Rect          myRect;

  StringPtr     myTitle = QTUtils_ConvertCToPascalString(kWindowTitle);

  OSErr         myErr;

  MovieController         gController;

// Initialize QuickTime

  myErr = EnterMovies();

  if (myErr != noErr)

goto bail;

// Create a display window

  myErr = memFullErr;

  myWindow = NewCWindow(NULL, &myBounds, myTitle, false, 0, (WindowPtr)-1, false, 0);

  if (myWindow == NULL)

    goto bail;

  myErr = noErr;

// Align the movie bounding box with the display window

GetMovieBox(theMovie, &myRect); /* Get the movie box. */

OffsetRect(&myRect, -myRect.left, -myRecct.top); /* topleft=0 */

SetMovieBox(theMovie, &myRect);

// Get a movie controller component and attach it to the movie

// Pin the movie to the top left corner

 gController = NewMovieController (theMovie, &myBounds, mcTopLeftMovie);

        if (gController == nil)

goto bail;

// Get the movie controller's bounds and resize the window accordingly

 myErr = MCGetControllerBoundsRect (gController, &myRect);

 SizeWindow (myWindow, myRect.right, myRect.bottom, true);

 ShowWindow (myWindow);

// Enable the controller to accept keyboard focus

 myErr = MCDoAction (gController, mcActionSetKeysEnabled,(Ptr)true);

// Check for unforeseen errors

  myErr = GetMoviesError();

  if (myErr != noErr)

    goto bail;

// Application event loop goes here

// Idle the movie controller component inside your application event loop

// ...

  myErr = MCIdle(gController);

// ...

// On error or exit, dispose of the controller, movie, window (in that order)

bail:

  free(myTitle);

  if (gController != NULL)

DisposeMovieController(gController);

  if (theMovie != NULL)

    DisposeMovie(theMovie);

  if (myWindow != NULL)

    DisposeWindow(myWindow);

Note that you should not call MCIsPlayerEvent in Mac OS X, even though you may see this in some older sample code. Instead, use MCIdle or MoviesTask to grant time to the controller, or MCKey to have the movie controller handle a keystroke.

Working Directly with Movie Controller Components

Regardless of whether you play your movie using an HIMovieView, a Carbon movie control, or a naked movie controller component, your application can call the movie controller component instance directly and give it commands.

You obtain the component instance if you open the component directly using NewMovieController. If you use an HIMovieView, you can obtain the component instance by calling HIMovieViewGetMovieController. If you use a Carbon movie control, you can obtain the component instance by calling GetControlData with kMovieControlDataMovieController.

The following commands to the movie controller component are available to your application:

• MCActivate

• MCAdjustCursor

• MCAddMovieSegment

• MCClear

• MCClick

• MCCopy

• MCCut

• MCDoAction

• MCDraw

• MCDrawBadge

• MCEnableEditing

• MCGetClip

• MCGetControllerBoundsRect

• MCGetControllerBoundsRgn

• MCGetControllerInfo

• MCGetControllerPort

• MCGetCurrentTime

• MCGetDoActionsProc

• MCGetIndMovie

• MCGetInterfaceElement

• MCGetMenuString

• MCGetVisible

• MCGetWindowRgn

• MCIdle

• MCInvalidate

• MCIsControllerAttached

• MCIsEditingEnabled

• MCIsPlayerEvent (deprecated)

• MCKey

• MCMovieChanged

• MCNewAttachedController

• MCPaste

• MCPositionController

• MCPtInController

• MCRemoveAllMovies

• MCRemoveAMovie

• MCRemoveMovie

• MCSetActionFilter

• MCSetActionFilterWithRefCon

• MCSetClip

• MCSetControllerAttached

• MCSetControllerBoundsRect

• MCSetControllerCapabilities

• MCSetControllerPort

• MCSetDuration

• MCSetIdleManager

• MCSetMovie

• MCSetUpEditMenu

• MCSetVisible

• MCTrimMovieSegment

• MCUndo

The MCDoAction function is of particular importance. MCDoAction can perform dozens of different operations, including starting and stopping the movie, setting the movie rate (playback speed), setting the audio volume, and so on. MCDoAction takes a selector as an argument. The selector tells MCDoAction which action to perform. For details, see Movie Controller Actions.

Obviously, all these functions allow you to do far more than just play a movie. They enable you to programmatically edit the movie, associate new movies with the controller, and configure the controller in various ways (enable editing, make the controller visible or invisible, and so on).

You can augment or override any controller function by installing a callback function, using MCSetActionFilterWithRefCon. See also “Using Movie Controllers” in the Programming Summary of QuickTime API Reference.

You will probably see references to MCIsPlayerEvent in sample code. In the past, MCIsPlayerEvent served two purposes: It granted processing time to the movie controller, and it allowed the movie controller to handle events such as mouse clicks and keystrokes. Both these features were based on the Apple Event Manager and event records, which are no longer used in Mac OS X.

If you use a Carbon movie control or an HIMovieView, processing time and event handling are taken care of automatically, so calls to MCIsPlayerEvent serve no purpose.

If your target system does not support Carbon movie controls or HIMovieView, you can call MCIdle to grant processing time to the movie controller, MCClick to have the movie controller handle a mouse click, and MCKey to have the movie controller handle a keystroke.

Bypassing the Movie Controller

It is possible to control a movie directly, without using an HIMovieView, a Carbon movie control, or a movie controller component. This is not recommended practice, however.

The low-level functions that allow you to work directly with movies can also be used when a movie controller of some sort is attached. This requires you to notify the controller that the movie has changed, and is also not recommended practice.

The low-level functions that work directly on movies are described in Appendix A, Playing a Movie Using Low-Level Commands.