Inside Macintosh: QuickTime Reference

| Previous | Chapter Contents | Chapter Top | Next |

Writing a Custom Action Handler Component

Any component type, whether it is a media handler, a codec, or your own component type, may be extended to handle custom actions. To extend your component, you implement the ExecuteWiredAction routine described below. If you are writing a component that is being used only to handle custom actions, you should use the component type 'wire'.

EXTERN_API( ComponentResult )
CallComponentExecuteWiredAction (ComponentInstance  ci,
                                QTAtomContainer actionContainer,
                                QTAtom  actionAtom,
                                QTCustomActionTargetPtr target,
                                QTEventRecordPtr event);

All the state passed to you in this routine is only valid for the duration of the execution of your custom action, which should be completed when you return from this routine.

The actionContainer contains all of the actions that are being executed in response to the current QTEvent. This atom container should not be edited, only read from, since other actions that have yet to be executed may be contained within it.

The actionAtom specifies the kActionAtom that concerns you, since it contains all of the atoms describing the action type and parameters to your components custom action that are to be executed.

The target parameter specifies the movie elements that you need in order to execute your action.

struct QTCustomActionTargetRecord {
    Movie                           movie;
    DoMCActionUPP                   doMCActionCallbackProc;
    long                            callBackRefcon;
    Track                           track;
    long                            trackObjectRefCon;
    Track                           defaultTrack;
    long                            defaultObjectRefCon;
    long                            reserved1;
    long                            reserved2;
};
typedef struct QTCustomActionTargetRecord QTCustomActionTargetRecord;
typedef QTCustomActionTargetRecord * QTCustomActionTargetPtr;

The movie field is the movie that is or contains the movie element, which is the target of the action.

The doMCActionCallbackProc and callBackRefcon specify the movie controller and refCon for the target movie's movie controller. They may be used with the CallDoMCActionProc routine to invoke the movie controller functionality, including the new mcActionFetchParameterAs.

The track field is the track that is or contains the movie element, which is the target of the action.

The trackObjectRefCon field is the refCon or ID of the movie element that is the target of the action. If the target is a sprite, this will be the sprite ID.

The defaultTrack is the track that contains the movie element that handled the QTEvent and generated the custom action. For example, if a hypertext element of a text track generated a SetSpriteVisible action for a sprite in a sprite track, the defaultTrack would be the Text track, while the Sprite Track would be the target track.

The defaultObjectRefCon is the refCon or ID of the movie element that handled the QTEvent and generated the custom action.

The event specifies information about what QTEvent generated the custom action.

The Action Being Executed

Fetching the Parameters

© 2000 Apple Computer, Inc.

Inside Macintosh: QuickTime Reference

| Previous | Chapter Contents | Chapter Top | Next |