Retired Documents Library

Developer

QuickTime Framework Reference Movie Controller Reference

Options
Deployment Target:

On This Page

Movie Controller Reference (Legacy)

Movie controllers provide a user interface for playing and editing movies, eliminating much of the complexity of working with movies. Movie controllers are implemented in QuickTime as components. This allows customized controllers to be plugged in to QuickTime for use by your application.

Functions

  • Lets your application to retrieve the movie reference for a movie that is associated with a movie controller.

    Declaration

    Movie MCGetIndMovie ( MovieController mc, short index );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    index

    Index for the movie. When set to 0, this call duplicates the action of the previous call to this function.

    Return Value

    The movie identifier for the movie that is assigned to the specified controller, or NIL if there is no movie assigned to the controller.

  • Associates a specified movie with a movie controller.

    Declaration

    ComponentResult MCNewAttachedController ( MovieController mc, Movie theMovie, WindowRef w, Point where );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    theMovie

    The movie to be associated with the movie controller.

    w

    A pointer to the window in which the movie is to be displayed. The movie controller component sets the movie's graphics world to match this window. If you set the w parameter to NIL, the component uses the current window.

    where

    The upper-left corner of the movie within the window specified by the w parameter. The movie controller component uses the movie's boundary Rect structure to determine the size of the movie. GetMovieBox returns this structure.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Associates a movie with a specified movie controller.

    Declaration

    ComponentResult MCSetMovie ( MovieController mc, Movie theMovie, WindowRef movieWindow, Point where );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    theMovie

    The movie to be associated with the movie controller. Set this value to NIL to remove the movie from the controller.

    movieWindow

    The window in which the movie is to be displayed. The movie controller component sets the movie's graphics world to match this window. If you set the w parameter to NIL, the component uses the current window.

    where

    The upper-left corner of the movie within the window specified by the movieWindow parameter. The movie controller component uses the movie's boundary Rect structure to determine the size of the movie. GetMovieBox returns this structure.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets a controller respond to activate, deactivate, suspend, and resume events.

    Declaration

    ComponentResult MCActivate ( MovieController mc, WindowRef w, Boolean activate );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the event has occurred.

    activate

    The nature of the event. Set this parameter to TRUE for activate and resume events. Set it to FALSE for deactivate and suspend events.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets a controller respond when the user clicks in a movie controller window.

    Declaration

    ComponentResult MCClick ( MovieController mc, WindowRef w, Point where, long when, long modifiers );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the event has occurred.

    where

    The location of the click. This value is expressed in the local coordinates of the window specified by the w parameter. Your application must convert this value from the global coordinates returned in the EventRecord structure.

    when

    Indicates when the user pressed the mouse button. You obtain this value from the EventRecord structure.

    modifiers

    Specifies modifier flags for the event. You obtain this value from the EventRecord structure.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Responds to an update event.

    Declaration

    ComponentResult MCDraw ( MovieController mc, WindowRef w );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the update event has occurred.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Performs idle processing for a movie controller.

    Declaration

    ComponentResult MCIdle ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Handles keyboard events for a movie controller.

    Declaration

    ComponentResult MCKey ( MovieController mc, SInt8 key, long modifiers );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    key

    The keystroke. You obtain this value from the event structure.

    modifiers

    Modifier flags for the event. You obtain this value from the EventRecord structure.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Removes the current movie selection from the movie associated with a specified controller.

    Declaration

    ComponentResult MCClear ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Returns a copy of the current movie selection from the movie associated with a specified controller.

    Declaration

    Movie MCCopy ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    A copy of the movie.

  • Returns a copy of the current movie selection from the movie associated with a specified controller and then removes the current movie selection from the source movie.

    Declaration

    Movie MCCut ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    A copy of the current movie selection.

    Discussion

    Your application is responsible for the returned movie. MCCut returns a movie containing the current selection from the movie associated with the specified controller. If the user has not made a selection, the returned movie reference is set to NIL.

  • Enables and disables editing for a movie controller.

    Declaration

    ComponentResult MCEnableEditing ( MovieController mc, Boolean enabled );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    enabled

    Specifies whether to enable or disable editing for the controller. Set this parameter to TRUE to enable editing; set it to FALSE to disable editing.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    Once editing is enabled for a controller, the user may edit the movie associated with the controller.

  • Retrieves the text string for a movie controller menu command.

    Declaration

    ComponentResult MCGetMenuString ( MovieController mc, long modifiers, short item, Str255 aString );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    modifiers

    The current modifiers from the mouse-down or key-down event to which you are responding.

    item

    One of the movie controller Edit menu constants (see below). See these constants:

    • mcMenuUndo

    • mcMenuCut

    • mcMenuCopy

    • mcMenuPaste

    • mcMenuClear

    aString

    On entry, pass a string of type Str255; on exit, this string is set to the text of the menu item specified by the item parameter.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    MCGetMenuString is used by MCSetUpEditMenu.

  • Determines whether editing is currently enabled for a movie controller.

    Declaration

    long MCIsEditingEnabled ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    Returns 1 if editing is enabled; set to 0 if editing is disabled or if the controller component does not support editing.

    Discussion

    Once editing is enabled for a controller, the user may edit the movie associated with the controller.

  • Inserts a specified movie at the current movie time in the movie associated with a specified controller.

    Declaration

    ComponentResult MCPaste ( MovieController mc, Movie srcMovie );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    srcMovie

    The movie to be inserted into the current selection in the movie associated with the movie controller specified by the mc parameter. If you set this parameter to NIL, the movie controller component retrieves the source movie from the scrap.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Correctly highlights and names the items in your application's Edit menu.

    Declaration

    ComponentResult MCSetUpEditMenu ( MovieController mc, long modifiers, MenuRef mh );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    modifiers

    The current modifiers from the mouse-down or key-down event to which you are responding.

    mh

    A menu handler for your current Edit menu. The first six items in your Edit menu should be the standard editing commands: Undo, a blank line, Cut, Copy, Paste, and Clear.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets your application discard the effects of the most recent edit operation.

    Declaration

    ComponentResult MCUndo ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Obtains the time value represented by the indicator on the movie controller's slider.

    Declaration

    TimeValue MCGetCurrentTime ( MovieController mc, TimeScale *scale );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    scale

    A pointer to a field that is to receive the time scale for the controller.

    Return Value

    A time value containing the time shown by the indicator on the movie controller's slider.

  • Lets your application set a controller's duration in the case where a controller does not have a movie associated with it.

    Declaration

    ComponentResult MCSetDuration ( MovieController mc, TimeValue duration );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    duration

    The new duration for the movie. This duration value must be in the controller's time scale.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Determines the current status of a movie controller and its associated movie, for menu highlighting.

    Declaration

    ComponentResult MCGetControllerInfo ( MovieController mc, long *someFlags );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    someFlags

    A pointer to flags (see below) that specify the current status and capabilities of the controller. More than one flag may be set to 1. See these constants:

    • mcInfoUndoAvailable

    • mcInfoCutAvailable

    • mcInfoCopyAvailable

    • mcInfoPasteAvailable

    • mcInfoClearAvailable

    • mcInfoHasSound

    • mcInfoIsPlaying

    • mcInfoIsLooping

    • mcInfoIsInPalindrome

    • mcInfoEditingEnabled

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    You can use the information returned by this function to control your application's menu highlighting.

  • Handles all events for a movie controller.

    Declaration

    ComponentResult ADD_MEDIA_BASENAME() MCIsPlayerEvent

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    e

    A pointer to the current EventRecord structure.

    Return Value

    A long integer indicating whether the movie controller component handled the event. The component sets this long integer to 1 if it handled the event. Your application should then skip the rest of its event loop and wait for the next event. The return value is 0 otherwise. Your application must then handle the event as part of its normal event processing.

    Discussion

    The movie controller component does everything necessary to support the movie controller and its associated movie. For example, the component calls MoviesTask for each movie. The movie controller component also handles suspend and resume events. It treats suspend events as deactivate requests and resume events as activate requests.

    The following sample code shows how to convert Windows messages to Macintosh events and then pass those events to the QuickTime movie controller, using this function:

    1. // MCIsPlayerEvent coding example
    2. // See "Discovering QuickTime," page 240
    3. MovieController mc; // Movie controller for movie
    4. LRESULT CALLBACK WndProc
    5. (HWND hwnd, // Handle to window
    6. UINT iMsg, // Message type
    7. WPARAM wParam, // Message-dependent parameter
    8. LPARAM lParam) // Message-dependent parameter
    9. {
    10. MSG msg; // Windows message structure
    11. EventRecord er; // Macintosh event record
    12. DWORD dwPos; // Mouse coordinates of message
    13. msg.hwnd =hwnd; // Window handle
    14. msg.message =iMsg; // Message type
    15. msg.wParam =wParam; // Word-length parameter
    16. msg.lParam =lParam; // Long-word parameter
    17. msg.time =GetMessageTime(); // Get time of message
    18. dwPos =GetMessagePos(); // Get mouse position
    19. msg.pt.x =LOWORD(dwPos); // Extract x coordinate
    20. msg.pt.y =HIWORD(dwPos); // Extract y coordinate
    21. WinEventToMacEvent(&msg, &er); // Convert to event
    22. MCIsPlayerEvent(mc, &er); // Pass event to QuickTime
    23. switch (iMsg) { // Dispatch on message type
    24. . . . // Handle message according to type
    25. } // end switch (iMsg)
    26. } // end WndProc
  • Reports whether a point is in the control area of a movie.

    Declaration

    ComponentResult MCPtInController ( MovieController mc, Point thePt, Boolean *inController );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    thePt

    The point to be checked. This point must be passed in local coordinates to the controller's window. This point is checked only against the movie controller's controls, not the movie itself.

    inController

    Returns true if the point is in the controller; false if it is not.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    While you could always determine if a point is contained in a movie, using PtInMovie, the MCPtInController function allows you to determine if a point is in the control area of a movie.

  • Displays a controller's badge.

    Declaration

    ComponentResult MCDrawBadge ( MovieController mc, RgnHandle movieRgn, RgnHandle *badgeRgn );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    movieRgn

    The boundary region of the controller's movie.

    badgeRgn

    A pointer to a region that is to receive information about the location of the badge. The movie controller returns the region where the badge is displayed. If you are not interested in this information, you may set this parameter to NIL. Your application must dispose of this handle.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    This function places the badge in an appropriate location based on the location of the controller's movie. MCDrawBadge can be useful in circumstances where you are using a movie controller component but do not want to incur the overhead of having the QuickTime movie in memory all the time. This function allows you to display the badge without having to display the movie. In addition, you can use the badge region to perform mouse-down event testing.

  • Obtains information describing a movie controller's clipping regions.

    Declaration

    ComponentResult MCGetClip ( MovieController mc, RgnHandle *theClip, RgnHandle *movieClip );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    theClip

    A pointer to a field that is to receive a handle to the clipping region of the entire movie controller. You must dispose of this region when you are done with it. If you are not interested in this information, set this parameter to NIL.

    movieClip

    A pointer to a field that is to receive a handle to the clipping region of the controller's movie. You must dispose of this region when you are done with it. If you are not interested in this information, set this parameter to NIL.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Returns a movie controller's boundary rectangle.

    Declaration

    ComponentResult MCGetControllerBoundsRect ( MovieController mc, Rect *bounds );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    bounds

    A pointer to a Rect structure that is to receive the coordinates of the movie controller's boundary rectangle. If there is insufficient screen space to display the controller, the function may return an empty structure.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Returns the actual region occupied by the controller and its movie.

    Declaration

    RgnHandle MCGetControllerBoundsRgn ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    A handle to a MacRegion structure that reflects the size, shape, and location of the controller. Your application must dispose of this structure.

    Discussion

    As with MCGetControllerBoundsRect, this function returns a region even if the controller is hidden. Some movie controllers may not be rectangular in shape. If the movie is not attached to its controller, the boundary region encloses only the control portion of the controller.

  • Returns a movie controller's color graphics port.

    Declaration

    CGrafPtr MCGetControllerPort ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    A pointer to the movie controller's CGrafPort structure.

  • Returns a value that indicates whether or not a movie controller is visible.

    Declaration

    ComponentResult MCGetVisible ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    If the controller is visible, the function result is set to 1. If the controller is not showing, the function result is set to 0. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError. See Error Codes.

  • Determines the window region that is actually in use by a controller and its movie.

    Declaration

    RgnHandle MCGetWindowRgn ( MovieController mc, WindowRef w );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the movie controller and its movie are displayed, if the control portion of the controller is attached to the movie. If the controller is detached and in a separate window from the movie, specify one of the windows.

    Return Value

    A handle to the MacRegion structure for the window that is actually in use. Your application must dispose of this structure.

    Discussion

    The region returned by this function contains only the visible portions of the controller and its movie.

  • Returns a value that indicates whether a movie controller is attached to its movie.

    Declaration

    ComponentResult MCIsControllerAttached ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    If the controller is attached, the returned value is set to 1. If the controller is not attached, the returned value is set to 0. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError.

  • Controls the position of a movie and its controller on the computer display.

    Declaration

    ComponentResult MCPositionController ( MovieController mc, const Rect *movieRect, const Rect *controllerRect, long someFlags );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    movieRect

    A pointer to a Rect structure that specifies the coordinates of the movie's boundary Rect structure.

    controllerRect

    A pointer to a Rect structure that specifies the coordinates of the controller's boundary Rect structure. The movie controller component always centers the control portion of the controller inside this rectangle. The movie controller component only uses this parameter when the control portion of the controller is detached from the movie. If you are working with an attached controller, you can set this parameter to NIL.

    someFlags

    Flags (see below) that control how the movie is drawn. If you set these flags to 0, the movie controller component centers the movie in the rectangle specified by movieRect and scales the movie to fit in that rectangle. See these constants:

    • mcTopLeftMovie

    • mcScaleMovieToFit

    • mcPositionDontInvalidate

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets you set a movie controller's clipping region.

    Declaration

    ComponentResult MCSetClip ( MovieController mc, RgnHandle theClip, RgnHandle movieClip );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    theClip

    A handle to a region that defines the controller's clipping region. This clipping region affects the entire movie controller and its movie, including the controller's badge and associated controls. Set this parameter to NIL to clear the controller's clipping region.

    movieClip

    A handle to a region that defines the clipping region of the controller's movie. This clipping region affects only the movie and the badge, not the movie controller. Set this parameter to NIL to clear the movie clipping region.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets your application control whether a movie controller is attached to its movie or detached from it.

    Declaration

    ComponentResult MCSetControllerAttached ( MovieController mc, Boolean attach );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    attach

    The action for this function. Set the attach parameter to TRUE to cause the controller to be attached to its movie. Set this parameter to FALSE to detach the controller from its movie.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Lets you change the position and size of a movie controller.

    Declaration

    ComponentResult MCSetControllerBoundsRect ( MovieController mc, const Rect *bounds );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    bounds

    A pointer to a Rect structure that contains the new boundary Rect structure for the movie controller.

    Return Value

    See Error Codes. Returns a value of controllerBoundsNotExact if the boundary rectangle has been changed but does not correspond to the rectangle you specified. In this case, the new boundary rectangle is always smaller than the requested rectangle. Returns noErr if there is no error.

  • Lets your application set the graphics port for a movie controller.

    Declaration

    ComponentResult MCSetControllerPort ( MovieController mc, CGrafPtr gp );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    gp

    A pointer to the new graphics port for the movie controller. Set this parameter to NIL to use the current graphics port.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    Movie controller components use MCSetControllerPort each time you create a new movie controller. Hence, your component must be set to a valid port before creating a new movie controller. You can use this function to place a movie and its associated movie controller in different graphics ports. If you are using an attached controller, both the controller and the movie's graphics ports are changed. If you are using a detached controller, this function changes only the graphics port of the control portion of the controller. You must use SetMovieGWorld followed by MCMovieChanged to change other portions.

    1. pascal ComponentResult MCSetControllerPort (MovieController mc,
    2. CGrafPtr gp);

    Special Considerations

    The movie controller component may use the foreground and background colors from the graphics port at the time this function is called to colorize the movie controller.

  • Lets your application control the visibility of a movie controller.

    Declaration

    ComponentResult MCSetVisible ( MovieController mc, Boolean visible );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    visible

    Set to TRUE to cause the controller to be visible, or FALSE to make the controller invisible.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Invokes a movie controller component and makes it perform a specified action.

    Declaration

    ComponentResult MCDoAction ( MovieController mc, short action, void *params );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    action

    The action to be taken. See Movie Controller Actions.

    params

    A pointer to the parameter data appropriate to the action. See Movie Controller Actions for information about the parameters required for each supported action.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Informs a movie controller component that your application has used the Movie Toolbox to change the characteristics of its associated movie.

    Declaration

    ComponentResult MCMovieChanged ( MovieController mc, Movie m );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    m

    The movie that has been changed.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Establishes an action filter function for a movie controller.

    Declaration

    ComponentResult MCSetActionFilterWithRefCon ( MovieController mc, MCActionFilterWithRefConUPP blob, long refCon );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    blob

    A pointer to your MCActionFilterWithRefConProc callback. Set this parameter to NIL to remove an existing callback.

    refCon

    A reference constant value. The movie controller component passes this reference constant to your action filter callback each time it calls it. Use this parameter to point to a data structure containing any information your callback needs.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

    Discussion

    The movie controller component calls your action filter function each time the component receives an action for its movie controller. Your filter function is then free to handle the action or to refer it back to the movie controller component. If you refer it back to the movie controller component, the component handles the action.

    If your filter function handles an action, you can handle the action in any way you desire. For example, your filter function could change the operation of movie controller buttons. More commonly, applications use the action filter function to monitor actions of the controller. For instance, your filter function might enable you to find out when the user clicks the play button, so that your application can enable appropriate menu selections. Alternatively, you can use the filter function to detect when the user resizes the movie.

  • Lets a movie controller component report its idling needs.

    Declaration

    ComponentResult MCSetIdleManager ( MovieController mc, IdleManager im );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    im

    A pointer to an opaque data structure that belongs to the Mac OS Idle Manager. You get this pointer by calling QTIdleManagerOpen.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Disposes of a MCActionFilterUPP pointer.

    Declaration

    void DisposeMCActionFilterUPP ( MCActionFilterUPP userUPP );

    Parameters

    userUPP

    A MCActionFilterUPP pointer. See Universal Procedure Pointers.

    Return Value

    You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

  • Disposes of a MCActionFilterWithRefConUPP pointer.

    Declaration

    void DisposeMCActionFilterWithRefConUPP ( MCActionFilterWithRefConUPP userUPP );

    Parameters

    userUPP

    A MCActionFilterWithRefConUPP pointer. See Universal Procedure Pointers.

    Return Value

    You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

  • Changes the views attributes.

    Declaration

    OSStatus HIMovieViewChangeAttributes ( HIViewRef inView, OptionBits inAttributesToSet, OptionBits inAttributesToClear );

    Parameters

    inView

    The HIMovieView.

    inAttributesToSet

    Attributes to set.

    inAttributesToClear

    Attributes to clear.

    Return Value

    An error code. Returns noErr if there is no error.

    Discussion

    Setting an attribute takes precedence over clearing the attribute.

  • Creates an HIMovieView object.

    Declaration

    OSStatus HIMovieViewCreate ( Movie inMovie, OptionBits inAttributes, HIViewRef *outMovieView );

    Parameters

    inMovie

    Initial movie to view; may be NULL.

    inAttributes

    Initial HIMovieView attributes.

    outMovieView

    Points to variable to receive new HIMovieView.

    Return Value

    Undocumented.

    Discussion

    If successful, the created view will have a single retain count.

  • Returns the view's current attributes.

    Declaration

    OptionBits HIMovieViewGetAttributes ( HIViewRef inView );

    Parameters

    inView

    The HIMovieView.

    Return Value

    Undocumented.

    Discussion

    The view's current attributes are returned.

  • Returns the size of the visible movie controller bar.

    Declaration

    HISize HIMovieViewGetControllerBarSize ( HIViewRef inView );

    Parameters

    inView

    The HIMovieView.

    Return Value

    Undocumented.

    Discussion

    The size of the visible movie controller bar is returned.

  • Returns the view's current movie.

    Declaration

    Movie HIMovieViewGetMovie ( HIViewRef inView );

    Parameters

    inView

    The HIMovieView.

    Return Value

    Undocumented.

    Discussion

    The view's current movie is returned.

  • Returns the view's current movie controller.

    Declaration

    MovieController HIMovieViewGetMovieController ( HIViewRef inView );

    Parameters

    inView

    The HIMovieView.

    Return Value

    Undocumented.

    Discussion

    The view's current movie controller is returned.

  • Pauses the view's current movie.

    Declaration

    OSStatus HIMovieViewPause ( HIViewRef movieView );

    Parameters

    movieView

    The movie view.

    Return Value

    An error code. Returns noErr if there is no error.

    Discussion

    This is a convenience routine to pause the view's current movie. If the movie is already paused, this function does nothing.

  • Plays the view's current movie.

    Declaration

    OSStatus HIMovieViewPlay ( HIViewRef movieView );

    Parameters

    movieView

    The movie view.

    Return Value

    An error code. Returns noErr if there is no error.

    Discussion

    This is a convenience routine to play the view's current movie. If the movie is already playing, this function does nothing.

  • Sets the view's current movie.

    Declaration

    OSStatus HIMovieViewSetMovie ( HIViewRef inView, Movie inMovie );

    Parameters

    inView

    The HIMovieView.

    inMovie

    The new movie to display.

    Return Value

    An error code. Returns noErr if there is no error.

    Discussion

    This routine sets the view's current movie.

  • Undocumented

    Declaration

    ComponentResult MCAddMovieSegment ( MovieController mc, Movie srcMovie, Boolean scaled );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    srcMovie

    The source movie. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, or NewMovieFromHandle.

    scaled

    Undocumented

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Undocumented

    Declaration

    ComponentResult MCAdjustCursor ( MovieController mc, WindowRef w, Point where, long modifiers );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the cursor is located.

    where

    The location of the cursor. This value is expressed in the local coordinates of the window specified by the w parameter.

    modifiers

    The cursor form (see below). See these constants:

    • kQTCursorOpenHand

    • kQTCursorClosedHand

    • kQTCursorPointingHand

    • kQTCursorRightArrow

    • kQTCursorLeftArrow

    • kQTCursorDownArrow

    • kQTCursorUpArrow

    • kQTCursorIBeam

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Retrieves the DoMCActionProc callback attached to a movie controller.

    Declaration

    ComponentResult MCGetDoActionsProc ( MovieController mc, DoMCActionUPP *doMCActionProc, long *doMCActionRefCon );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    doMCActionProc

    A pointer to a DoMCActionProc callback.

    doMCActionRefCon

    A reference constant that is passed to your callback. This parameter may point to a data structure containing information your function needs.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Gets the interface element of a specified type for a movie controller.

    Declaration

    ComponentResult MCGetInterfaceElement ( MovieController mc, MCInterfaceElement whichElement, void *element );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    whichElement

    A constant (see below) that identifies the interface element type. See these constants:

    • kMCIEEnabledButtonPicture

    • kMCIEDisabledButtonPicture

    • kMCIEDepressedButtonPicture

    • kMCIEEnabledSizeBoxPicture

    • kMCIEDisabledSizeBoxPicture

    • kMCIEEnabledUnavailableButtonPicture

    • kMCIEDisabledUnavailableButtonPicture

    • kMCIESoundSlider

    • kMCIESoundThumb

    element

    A pointer to the element type.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Invalidates a region of a movie controller's display.

    Declaration

    ComponentResult MCInvalidate ( MovieController mc, WindowRef w, RgnHandle invalidRgn );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    w

    A pointer to the window in which the movie controller and its movie are displayed, if the control portion of the controller is attached to the movie. If the controller is detached and in a separate window from the movie, specify one of the windows.

    invalidRgn

    A handle to a MacRegion structure that defines a region to invalidate.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Removes all movies associated with a controller.

    Declaration

    ComponentResult MCRemoveAllMovies ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Removes one movie from a multi-movie controller.

    Declaration

    ComponentResult MCRemoveAMovie ( MovieController mc, Movie m );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    m

    The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, or NewMovieFromHandle.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Removes a movie from a movie controller.

    Declaration

    ComponentResult MCRemoveMovie ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Sets the MCActionFilterProc callback for a movie controller.

    Declaration

    ComponentResult MCSetActionFilter ( MovieController mc, MCActionFilterUPP blob );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    blob

    A Universal Procedure Pointer to an MCActionFilterProc callback.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Undocumented

    Declaration

    ComponentResult MCSetControllerCapabilities ( MovieController mc, long flags, long flagsMask );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    flags

    Undocumented

    flagsMask

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Undocumented

    Declaration

    ComponentResult MCTrimMovieSegment ( MovieController mc );

    Parameters

    mc

    The movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    Return Value

    You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

  • Allocates a Universal Procedure Pointer for the MCActionFilterProc callback.

    Declaration

    MCActionFilterUPP NewMCActionFilterUPP ( MCActionFilterProcPtr userRoutine );

    Parameters

    userRoutine

    A pointer to your application-defined function.

    Return Value

    A new UPP; see Universal Procedure Pointers.

    Discussion

    This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

  • Allocates a Universal Procedure Pointer for the MCActionFilterWithRefConProc callback.

    Declaration

    MCActionFilterWithRefConUPP NewMCActionFilterWithRefConUPP ( MCActionFilterWithRefConProcPtr userRoutine );

    Parameters

    userRoutine

    A pointer to your application-defined function.

    Return Value

    A new UPP; see Universal Procedure Pointers.

    Discussion

    This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Callbacks

  • Responds to movie controller actions.

    Declaration

    typedef Boolean (*MCActionFilterProcPtr) ( MovieController mc, short *action, void *params);

    Parameters

    mc

    Specifies the movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    action

    A movie controller action. For a list of actions, see Chapter 2 of Inside Macintosh: QuickTime Components.

    params

    A pointer to a structure, such as QTStatusStringRecord or ResolvedQTEventSpec, that passes information to the callback. See Movies.h.

    Return Value

    Undocumented

    Discussion

    Movie controller components allow your application to field movie controller actions. You define an MCActionFilterProc in your application and assign it to a controller by calling the MCSetActionFilterWithRefCon function.

  • Responds to movie controller actions with a reference constant.

    Declaration

    typedef Boolean (*MCActionFilterWithRefConProcPtr) ( MovieController mc, short action, void *params, long refCon);

    Parameters

    mc

    Specifies the movie controller for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent, or from NewMovieController.

    action

    A movie controller action. For a list of actions, see Chapter 2 of Inside Macintosh: QuickTime Components.

    params

    A pointer to a structure, such as QTStatusStringRecord, that passes information to the callback. See Movies.h.

    refCon

    A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

    Return Value

    Undocumented

Data Types

  • Represents a type used by the Movie Controller API.

    Declaration

    typedef STACK_UPP_TYPE(MCActionFilterProcPtr) MCActionFilterUPP;

    Import Statement

  • Represents a type used by the Movie Controller API.

    Declaration

    typedef STACK_UPP_TYPE(MCActionFilterWithRefConProcPtr) MCActionFilterWithRefConUPP;

    Import Statement

  • Represents a type used by the Movie Controller API.

    Declaration

    typedef unsigned long MCInterfaceElement;

    Import Statement

  • Represents a type used by the Movie Controller API.

    Declaration

    typedef UInt32 OptionBits;

    Import Statement

Constants

  • Constants that represent options for movie controllers.

    Declaration

    enum { kMCIEEnabledButtonPicture = 1, kMCIEDisabledButtonPicture = 2, kMCIEDepressedButtonPicture = 3, kMCIEEnabledSizeBoxPicture = 4, kMCIEDisabledSizeBoxPicture = 5, kMCIEEnabledUnavailableButtonPicture = 6, kMCIEDisabledUnavailableButtonPicture = 7, kMCIESoundSlider = 128, kMCIESoundThumb = 129, kMCIEColorTable = 256, kMCIEIsFlatAppearance = 257, kMCIEDoButtonIconsDropOnDepress = 258 }; enum { mcFlagSuppressMovieFrame = 1 << 0, mcFlagSuppressStepButtons = 1 << 1, mcFlagSuppressSpeakerButton = 1 << 2, mcFlagsUseWindowPalette = 1 << 3, mcFlagsDontInvalidate = 1 << 4, mcFlagsUseCustomButton = 1 << 5 }; enum { mcInfoUndoAvailable = 1 << 0, mcInfoCutAvailable = 1 << 1, mcInfoCopyAvailable = 1 << 2, mcInfoPasteAvailable = 1 << 3, mcInfoClearAvailable = 1 << 4, mcInfoHasSound = 1 << 5, mcInfoIsPlaying = 1 << 6, mcInfoIsLooping = 1 << 7, mcInfoIsInPalindrome = 1 << 8, mcInfoEditingEnabled = 1 << 9, mcInfoMovieIsInteractive = 1 << 10 };

    Constants

    • kMCIESoundThumb

      The indicator on the sound slider.

    • mcFlagSuppressMovieFrame

      If this flag is set to 1, the controller does not display a frame around the movie. By default, this flag is set to 0.

    • mcFlagSuppressStepButtons

      If this flag is set to 1, the controller does not display the step buttons. By default, this flag is set to 0.

    • mcFlagSuppressSpeakerButton

      If this flag is set to 1, the controller does not display the speaker button. By default, this flag is set to 0.

    • mcFlagsUseWindowPalette

      If this flag is set to 1, the movie controller does not manage the window palette. This ensures that a movie's colors are reproduced as accurately as possible. This flag is particularly useful for movies with custom color tables. By default, this flag is set to 0.

  • Constants passed to MCAdjustCursor.

    Declaration

    enum { kQTCursorOpenHand = -19183, kQTCursorClosedHand = -19182, kQTCursorPointingHand = -19181, kQTCursorRightArrow = -19180, kQTCursorLeftArrow = -19179, kQTCursorDownArrow = -19178, kQTCursorUpArrow = -19177, kQTCursorIBeam = -19176 };

  • Constants passed to MCGetMenuString.

    Declaration

    enum { mcMenuUndo = 1, mcMenuCut = 3, mcMenuCopy = 4, mcMenuPaste = 5, mcMenuClear = 6 };

  • Constants passed to MCPositionController.

    Declaration

    enum { mcPositionDontInvalidate = 1 << 5 };