Overview

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 by Task

Associating Movies With Controllers

• MCGetIndMovie
• MCNewAttachedController
• MCSetMovie

Customizing Event Processing

• MCActivate
• MCClick
• MCDraw
• MCIdle
• MCKey

Editing Movies With a Controller

• MCClear
• MCCopy
• MCCut
• MCEnableEditing
• MCGetMenuString
• MCIsEditingEnabled
• MCPaste
• MCSetUpEditMenu
• MCUndo

Getting and Setting Movie Controller Time

• MCGetCurrentTime
• MCSetDuration

Handling Movie Events

• MCGetControllerInfo
• MCIsPlayerEvent
• MCPtInController

Managing Controller Attributes

• MCDrawBadge
• MCGetClip
• MCGetControllerBoundsRect
• MCGetControllerBoundsRgn
• MCGetControllerPort
• MCGetVisible
• MCGetWindowRgn
• MCIsControllerAttached
• MCPositionController
• MCSetClip
• MCSetControllerAttached
• MCSetControllerBoundsRect
• MCSetControllerPort
• MCSetVisible

Movie Controller Action Functions

• MCDoAction
• MCMovieChanged
• MCSetActionFilterWithRefCon

Working With The Idle Manager

• MCSetIdleManager

Supporting Functions

• DisposeMCActionFilterUPP
• DisposeMCActionFilterWithRefConUPP
• HIMovieViewChangeAttributes
• HIMovieViewCreate
• HIMovieViewGetAttributes
• HIMovieViewGetControllerBarSize
• HIMovieViewGetMovie
• HIMovieViewGetMovieController
• HIMovieViewPause
• HIMovieViewPlay
• HIMovieViewSetMovie
• MCAddMovieSegment
• MCAdjustCursor
• MCGetDoActionsProc
• MCGetInterfaceElement
• MCInvalidate
• MCRemoveAllMovies
• MCRemoveAMovie
• MCRemoveMovie
• MCSetActionFilter
• MCSetControllerCapabilities
• MCTrimMovieSegment
• NewMCActionFilterUPP
• NewMCActionFilterWithRefConUPP

Functions

DisposeMCActionFilterUPP

Disposes of a MCActionFilterUPP pointer.

void DisposeMCActionFilterUPP (
   MCActionFilterUPP userUPP
);

DisposeMCActionFilterWithRefConUPP

Disposes of a MCActionFilterWithRefConUPP pointer.

void DisposeMCActionFilterWithRefConUPP (
   MCActionFilterWithRefConUPP userUPP
);

HIMovieViewChangeAttributes

Changes the views attributes.

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

HIMovieViewCreate

Creates an HIMovieView object.

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

HIMovieViewGetAttributes

Returns the view's current attributes.

OptionBits HIMovieViewGetAttributes (
   HIViewRef inView
);

HIMovieViewGetControllerBarSize

Returns the size of the visible movie controller bar.

HISize HIMovieViewGetControllerBarSize (
   HIViewRef inView
);

HIMovieViewGetMovie

Returns the view's current movie.

Movie HIMovieViewGetMovie (
   HIViewRef inView
);

HIMovieViewGetMovieController

Returns the view's current movie controller.

MovieController HIMovieViewGetMovieController (
   HIViewRef inView
);

HIMovieViewPause

Pauses the view's current movie.

OSStatus HIMovieViewPause (
   HIViewRef movieView
);

HIMovieViewPlay

Plays the view's current movie.

OSStatus HIMovieViewPlay (
   HIViewRef movieView
);

HIMovieViewSetMovie

Sets the view's current movie.

OSStatus HIMovieViewSetMovie (
   HIViewRef inView,
   Movie inMovie
);

MCActivate

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

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

MCAddMovieSegment

Undocumented

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

MCAdjustCursor

Undocumented

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

MCClear

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

ComponentResult MCClear (
   MovieController mc
);

MCClick

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

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

MCCopy

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

Movie MCCopy (
   MovieController mc
);

MCCut

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.

Movie MCCut (
   MovieController mc
);

MCDoAction

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

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

MCDraw

Responds to an update event.

ComponentResult MCDraw (
   MovieController mc,
   WindowRef w
);

MCDrawBadge

Displays a controller's badge.

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

MCEnableEditing

Enables and disables editing for a movie controller.

ComponentResult MCEnableEditing (
   MovieController mc,
   Boolean enabled
);

MCGetClip

Obtains information describing a movie controller's clipping regions.

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

MCGetControllerBoundsRect

Returns a movie controller's boundary rectangle.

ComponentResult MCGetControllerBoundsRect (
   MovieController mc,
   Rect *bounds
);

MCGetControllerBoundsRgn

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

RgnHandle MCGetControllerBoundsRgn (
   MovieController mc
);

MCGetControllerInfo

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

ComponentResult MCGetControllerInfo (
   MovieController mc,
   long *someFlags
);

MCGetControllerPort

Returns a movie controller's color graphics port.

CGrafPtr MCGetControllerPort (
   MovieController mc
);

MCGetCurrentTime

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

TimeValue MCGetCurrentTime (
   MovieController mc,
   TimeScale *scale
);

MCGetDoActionsProc

Retrieves the DoMCActionProc callback attached to a movie controller.

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

MCGetIndMovie

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

Movie MCGetIndMovie (
   MovieController mc,
   short index
);

MCGetInterfaceElement

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

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

MCGetMenuString

Retrieves the text string for a movie controller menu command.

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

MCGetVisible

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

ComponentResult MCGetVisible (
   MovieController mc
);

MCGetWindowRgn

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

RgnHandle MCGetWindowRgn (
   MovieController mc,
   WindowRef w
);

MCIdle

Performs idle processing for a movie controller.

ComponentResult MCIdle (
   MovieController mc
);

MCInvalidate

Invalidates a region of a movie controller's display.

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

MCIsControllerAttached

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

ComponentResult MCIsControllerAttached (
   MovieController mc
);

MCIsEditingEnabled

Determines whether editing is currently enabled for a movie controller.

long MCIsEditingEnabled (
   MovieController mc
);

MCIsPlayerEvent

Handles all events for a movie controller.

ComponentResult ADD_MEDIA_BASENAME() MCIsPlayerEvent

// MCIsPlayerEvent coding example

// See "Discovering QuickTime," page 240

MovieController   mc;                   // Movie controller for movie

LRESULT CALLBACK WndProc

        (HWND       hwnd,               // Handle to window

         UINT       iMsg,               // Message type

         WPARAM     wParam,             // Message-dependent parameter

         LPARAM     lParam)             // Message-dependent parameter

{

    MSG             msg;                // Windows message structure

    EventRecord     er;                 // Macintosh event record

    DWORD           dwPos;              // Mouse coordinates of message

    msg.hwnd        =hwnd;             // Window handle

    msg.message     =iMsg;             // Message type

    msg.wParam      =wParam;           // Word-length parameter

    msg.lParam      =lParam;           // Long-word parameter

    msg.time =GetMessageTime();        // Get time of message

    dwPos  =GetMessagePos();           // Get mouse position

    msg.pt.x =LOWORD(dwPos);           // Extract x coordinate

    msg.pt.y =HIWORD(dwPos);           // Extract y coordinate

    WinEventToMacEvent(&msg, &er);      // Convert to event

    MCIsPlayerEvent(mc, &er);           // Pass event to QuickTime

    switch (iMsg) {                     // Dispatch on message type

        . . .       // Handle message according to type

    }  // end switch (iMsg)

}  // end WndProc

MCKey

Handles keyboard events for a movie controller.

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

MCMovieChanged

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

ComponentResult MCMovieChanged (
   MovieController mc,
   Movie m
);

MCNewAttachedController

Associates a specified movie with a movie controller.

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

MCPaste

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

ComponentResult MCPaste (
   MovieController mc,
   Movie srcMovie
);

MCPositionController

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

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

MCPtInController

Reports whether a point is in the control area of a movie.

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

MCRemoveAllMovies

Removes all movies associated with a controller.

ComponentResult MCRemoveAllMovies (
   MovieController mc
);

MCRemoveAMovie

Removes one movie from a multi-movie controller.

ComponentResult MCRemoveAMovie (
   MovieController mc,
   Movie m
);

MCRemoveMovie

Removes a movie from a movie controller.

ComponentResult MCRemoveMovie (
   MovieController mc
);

MCSetActionFilter

Sets the MCActionFilterProc callback for a movie controller.

ComponentResult MCSetActionFilter (
   MovieController mc,
   MCActionFilterUPP blob
);

MCSetActionFilterWithRefCon

Establishes an action filter function for a movie controller.

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

MCSetClip

Lets you set a movie controller's clipping region.

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

MCSetControllerAttached

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

ComponentResult MCSetControllerAttached (
   MovieController mc,
   Boolean attach
);

MCSetControllerBoundsRect

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

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

MCSetControllerCapabilities

Undocumented

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

MCSetControllerPort

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

ComponentResult MCSetControllerPort (
   MovieController mc,
   CGrafPtr gp
);

pascal ComponentResult MCSetControllerPort (MovieController mc,

                                            CGrafPtr gp);

MCSetDuration

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

ComponentResult MCSetDuration (
   MovieController mc,
   TimeValue duration
);

MCSetIdleManager

Lets a movie controller component report its idling needs.

ComponentResult MCSetIdleManager (
   MovieController mc,
   IdleManager im
);

MCSetMovie

Associates a movie with a specified movie controller.

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

MCSetUpEditMenu

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

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

MCSetVisible

Lets your application control the visibility of a movie controller.

ComponentResult MCSetVisible (
   MovieController mc,
   Boolean visible
);

MCTrimMovieSegment

Undocumented

ComponentResult MCTrimMovieSegment (
   MovieController mc
);

MCUndo

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

ComponentResult MCUndo (
   MovieController mc
);

NewMCActionFilterUPP

Allocates a Universal Procedure Pointer for the MCActionFilterProc callback.

MCActionFilterUPP NewMCActionFilterUPP (
   MCActionFilterProcPtr userRoutine
);

NewMCActionFilterWithRefConUPP

Allocates a Universal Procedure Pointer for the MCActionFilterWithRefConProc callback.

MCActionFilterWithRefConUPP NewMCActionFilterWithRefConUPP (
   MCActionFilterWithRefConProcPtr userRoutine
);

Callbacks

MCActionFilterProc

Responds to movie controller actions.

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

If you name your function MyMCActionFilterProc, you would declare it this way:

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

MCActionFilterWithRefConProc

Responds to movie controller actions with a reference constant.

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

If you name your function MyMCActionFilterWithRefConProc, you would declare it this way:

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

Data Types

MCActionFilterUPP

Represents a type used by the Movie Controller API.

typedef STACK_UPP_TYPE(MCActionFilterProcPtr) MCActionFilterUPP;

MCActionFilterWithRefConUPP

Represents a type used by the Movie Controller API.

typedef STACK_UPP_TYPE(MCActionFilterWithRefConProcPtr) MCActionFilterWithRefConUPP;

MCInterfaceElement

Represents a type used by the Movie Controller API.

typedef unsigned long MCInterfaceElement;

OptionBits

Represents a type used by the Movie Controller API.

typedef UInt32 OptionBits;

Constants

Movie Controller Options

Constants that represent options for movie controllers.

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.

Available in OS X v10.0 and later.

Declared in Movies.h.

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.

Available in OS X v10.0 and later.

Declared in Movies.h.

mcFlagSuppressStepButtons

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

Available in OS X v10.0 and later.

Declared in Movies.h.

mcFlagSuppressSpeakerButton

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

Available in OS X v10.0 and later.

Declared in Movies.h.

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.

Available in OS X v10.0 and later.

Declared in Movies.h.

MCAdjustCursor Values

Constants passed to MCAdjustCursor.

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

MCGetMenuString Values

Constants passed to MCGetMenuString.

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

MCPositionController Values

Constants passed to MCPositionController.

enum {
   mcPositionDontInvalidate      = 1 << 5
};