Aug 00 QTToolkit
Volume Number: 16
Issue Number: 8
Column Tag: QuickTime Toolkit
The Informant
By Tim Monroe
Getting and Setting Movie Information
In the previous QuickTime Toolkit article, we saw how to create a QuickTime movie
file that contains a single video track. We also learned a fair bit about the structure of
QuickTime movies (as collections of tracks) and QuickTime movie files (as collections
of atoms). In this article, we'll continue on with the general topic of creating and
configuring QuickTime movie files. We'll see how to get various pieces of information
about QuickTime movies and movie files; we'll also see how to add information to a
QuickTime movie to help the user determine what's in a movie.
To get an idea of what we're going to accomplish here, let's suppose that we're running
some version of the MoviePlayer application (the predecessor to the current
QuickTime Player application). MoviePlayer's Movie menu contains the item "Show
Copyright...". If we select that item immediately after having opened the movie file we
created in the previous article, we'll see the movie information dialog box shown in
Figure 1.
Figure 1. The movie information dialog box for our new movie
As you can see, this is not particularly helpful. The only real "information" visible to
the user is the first frame of the movie, which happens to be a solid white rectangle. It
would be better to display some other frame of the movie and to add some descriptive
information to the other panes of the dialog box. Figure 2 shows a much more useful
movie information dialog box.
Figure 2. The revised movie information dialog box for our new movie
Part of our task here will be to see how to modify the movie file so that selecting
"Show Copyright..." displays the dialog box in Figure 2 rather than the one in Figure 1.
In a nutshell, this involves setting the movie poster to some frame other than the first
frame, which is the default poster frame; it also involves attaching three new pieces of
movie user data to the movie file. Along the way, we'll also learn how to set the
preview that is contained in the file-opening dialog boxes displayed by calls to the
StandardGetFilePreview and NavGetFile functions. Figure 3 shows a typical
file-opening dialog box with a preview.
Figure 3. A preview contained in a file-opening dialog box
Our sample application this time around is called QTInfo. As usual, it's based directly
on the QTShell sample application that we've developed previously. QTInfo is just
QTShell with one additional source code file (QTInfo.c) and some additional resources.
Figure 4 shows the Test menu supported by QTInfo.
Figure 4. The Test menu in QTInfo
As you can see, QTInfo provides the "Show Copyright..." menu item, as well as a
number of other items that allow us to get and set various kinds of movie information.
It turns out that we can handle the "Show Copyright..." item with a single line of code:
ShowMovieInformation(myMovie, gModalFilterUPP, 0L);
The ShowMovieInformation function was introduced in QuickTime version 2.0, but has
(to my knowledge) never been documented. ShowMovieInformation simply displays the
movie information dialog box, which includes the movie poster image, the name of the
movie, the movie's copyright information, and some other information. If you pass a
universal procedure pointer to a modal dialog event filter function in the second
parameter, you'll get a movable modal dialog box; otherwise, you'll get a standard
non-movable modal dialog box, as shown in Figure 5.
Figure 5. A non-movable movie information dialog box
Movie Posters
A movie poster image (or, more briefly, a movie poster) is a single image that
represents a QuickTime movie. The images in the top-left panes of Figures 1, 2, and 5
are movie posters, suitably resized to fit into the available space in the movie
information dialog box. A movie poster is defined by specifying a movie poster time and
one or more movie poster tracks. The movie poster time specifies the time in the
movie at which the image is to found, and the movie poster tracks specify which tracks
in the movie are to be used to create the movie poster. Typically a single track is used
as the movie poster track, but in theory two or more video tracks (or other tracks
with visible data) could contribute to the final movie poster image. If a movie has no
track designated as a movie poster track, then the movie won't have a poster, no matter
what the movie poster time is set to. Let's see how to work with poster times and
tracks.
Getting and Setting Movie Poster Times
The default movie poster time is 0, which picks out the first frame in the movie. As we
saw earlier, it's sometimes useful to designate some other time as the movie poster
time. The function QTInfo_SetPosterToFrame, defined in Listing 1, sets the
currently-displayed movie frame to be the movie poster image. (QTInfo calls
QTInfo_SetPosterToFrame in response to the "Set Poster Frame" menu item.)
Listing 1: Setting the movie poster time to the current movie time
QTInfo_SetPosterToFrame
OSErr QTInfo_SetPosterToFrame
(Movie theMovie,
MovieController theMC)
{
TimeValue [TOKEN:28025]Time;
ComponentResult myErr = noErr;
// stop the movie from playing
myErr = MCDoAction(theMC, mcActionPlay, (void *)0L);
if (myErr != noErr)
goto bail;
myTime = GetMovieTime
(theMovie, NULL);
SetMoviePosterTime
(theMovie, myTime);
myErr = MCMovieChanged
(theMC, theMovie);
bail:
return((OSErr)myErr);
}
As you can see, QTInfo_SetPosterToFrame first calls MCDoAction to set the movie play
rate to 0, which effectively stops the movie from playing. (If the movie is already
stopped, this call has no effect.) Then QTInfo_SetPosterToFrame retrieves the current
movie time by calling the GetMovieTime function and sets the movie poster time to the
current movie time by calling the SetMoviePosterTime function.
QTInfo_SetPosterToFrame finishes up by calling the MCMovieChanged function, which
informs the movie controller that we've made changes to the movie using the Movie
Toolbox. As we've seen in past articles, there are often two ways to change some
characteristic of a movie: using Movie Toolbox functions and using movie controller
functions. When a movie is associated with a movie controller and when we make a
change to the movie using the Movie Toolbox, it's usually necessary to keep things in
sync by calling MCMovieChanged. For example, if we change the size of the movie by
calling SetMovieBox, we'd need to call MCMovieChanged so that the movie controller
can update itself appropriately.
In the present case, there is no movie controller action to set the poster frame, so we
used the Movie Toolbox function SetMoviePosterTime. Then we called MCMovieChanged
on the offhand chance that the movie controller might actually care about the poster
time. I've tried running QTInfo without the call to MCMovieChanged here and no harm
appears to result, but it's better to be safe than sorry. As a general rule, if you have a
movie controller associated with a movie and you use the Movie Toolbox to effect some
change in the movie, call MCMovieChanged to inform the movie controller of the