Overview of Application-Defined Functions
This section describes the functions your application can provide when interacting with the Movie Toolbox, including some functions that your application must provide to make use of certain services. These functions allow you to monitor, customize, and extend the behavior of the Movie Toolbox by executing functions you create at various points in the operation of the Movie Toolbox.
In this section:
Progress Functions
Cover Functions
Error-Notification Functions
Movie Callout Functions
File Filter Functions
Custom Dialog Functions
Modal-Dialog Filter Functions
Standard File Activation Functions
Callback Event Functions
Text Functions
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.
Note: A modal-dialog filter function controls events closer to their source by filtering the events received from the Event Manager. The Standard File Package itself contains an internal modal-dialog filter function that maps keypresses and other user input onto the equivalent dialog box items. If you also want to process events at this level, you can supply your own filter function.
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.
© 2005, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-01-10)