Progress Functions

Some Movie Toolbox functions can take a long time to execute. For example, creating a movie file that contains all of its data may be quite an involved process for a movie that has many large media structures. During these operations, your application should give the user some indication of the progress of the task. The Movie Toolbox allows you to monitor its progress on long operations with a progress function.

The Movie Toolbox calls your progress function at regular intervals during long operations. The Movie Toolbox determines whether to call your function based on the duration of the operation; your function will not be called unnecessarily. When it calls your function, the Movie Toolbox provides information about the operation that is underway and its relative completion. You can use this information to display an informational dialog box to the user.

You assign a progress function to a movie by calling the SetMovieProgressProc function. You should assign your progress function when you open the movie; the Movie Toolbox will call your function when it is appropriate to do so. One progress function may support more than one movie. When the Movie Toolbox calls your function, it provides you with the movie identifier so that you can discriminate between various movies.

Cover Functions

The Movie Toolbox allows your application to perform custom processing whenever one of your movies covers a screen region or reveals a region that was previously covered. You perform this processing using cover functions.

There are two types of cover functions: those that are called when your movie covers a screen region, and those that are called when your movie uncovers a screen region, revealing a region that was previously covered. You can use a cover function to detect when a movie changes size.

Cover functions that are called when your movie covers a screen region are responsible for erasing the region; you may choose to save the hidden region in an offscreen buffer. Cover functions that are called when your movie reveals a hidden screen region must redisplay the hidden region.

The Movie Toolbox sets the graphics world before it calls your cover function. Your function must not change the graphics world.

The Movie Toolbox provides default cover functions. When your movie uncovers a region, the default function that is called erases the movie’s image by displaying the graphics port’s background color and pattern. You can set the port’s characteristics by calling the SetMovieGWorld function. When your movie covers a region, the default function that is called does nothing.

Use the SetMovieCoverProcs function to set both types of cover functions.

Error-Notification Functions

The Movie Toolbox lets your application perform custom error notification. Your application must identify its custom error-notification function to the Movie Toolbox. Error-notification functions are particularly helpful when you are debugging your program.

The SetMoviesErrorProc function allows you to identify your application’s error-notification function in the errProc parameter.

Movie Callout Functions

The PlayMoviePreview function plays a movie’s preview. You provide a pointer to a movie callout function in the callOutProc parameter.

The Movie Toolbox calls your movie callout function repeatedly while the movie preview is playing. You can use this function to stop the preview. If you do not want to assign a function, set the callOutProc parameter to nil.

File Filter Functions

A file filter function filters the files that are displayed to the user in a dialog box. You specify this function in the fileFilter parameter of the SFGetFilePreview, StandardGetFilePreview, and CustomGetFilePreview routines. If this parameter is not nil, SFGetFilePreview calls the function for each file to determine whether to display the file to the user. The SFGetFilePreview function supplies you with the information it receives from the File Manager’s GetFileInfo routine.

Custom Dialog Functions

A dialog hook function handles user selections in a dialog box. A custom dialog function lets you support the template in the custom dialog template that you specified with the CustomGetFilePreview routine. This function corresponds to the File Manager’s CustomGetFile routine.

You specify your dialog function in the dlgHook parameter of CustomGetFilePreview. You can use this parameter to support a custom dialog box function you have supplied by specifying a dialog template resource in your resource file. You specify the dialog template’s resource ID with the dlgID parameter. If you are not supplying a custom dialog function, set this parameter to nil.

Modal-Dialog Filter Functions

The CustomGetFilePreview routine presents an Open dialog box to the user and allows the user to view file previews. This function differs from StandardGetFilePreview in that you can provide a custom dialog template and functions to support your template. This function corresponds to the existing CustomGetFile routine.

You specify your modal-dialog filter function in the filterProc parameter. Your modal-dialog filter function gives you greater control over the interface presented to the user.

Standard File Activation Functions

The CustomGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews. This function differs from the StandardGetFilePreview function in that you can provide a custom dialog template and functions to support your template. The CustomGetFilePreview function corresponds to the File Manager’s CustomGetFile routine.

You specify your activation function in the activateProc parameter. An activation function controls the highlighting of any items whose shape is known only by your application.

Callback Event Functions

The CallMeWhen function schedules a callback event. You specify the callback event in the callBackProc parameter.

Text Functions

You can use the MyTextProc function described in this section to pass a handle to a specified sample containing formatted text, along with the movie in which the text is being displayed, a pointer to a flag variable, and your reference constant. You specify the desired operations on the text and return an indication of whether you want to display the text in the displayFlag parameter.