Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

New Media Handler APIs For Keyboard Focus

QuickTime 6 provides three new media handler calls that developers can use to write media handlers that support keyboard focus. These are

• MediaRefConSetProperty

• MediaRefConGetProperty

• MediaNavigateTargetRefCon

If you want to add interactive capabilities to your application, you need to use these media handler calls, discussed in this section.

Adding Keyboard Focus Capabilities

When authoring the movie, you need to make sure that you add a media property atom of type kTrackFocusCanEditFlag and set that to TRUE. Then you should check for the presence of this flag when called via MediaHasCharacteristic checking on the kCharacteristicProvidesKeyFocus.

You add the kTrackFocusCanEditFlag atom. If this property has been set to TRUE, the media handler receives the NavigateRefCon and Get/SetRefCon calls.

{

    QTAtomContainer mediaProperties;

    Boolean         canEdit = true;

    QTNewAtomContainer(&mediaProperties);

    QTInsertChild(mediaProperties, 0, kTrackFocusCanEditFlag, 1, 1,

                    sizeof(canEdit), &canEdit, NULL);

    myErr = SetMediaPropertyAtom(myMedia, mediaProperties);

    QTDisposeAtomContainer(mediaProperties);

}

pascal ComponentResult MediaHasCharacteristic(

                        MediaHandler mh,

                        OSType characteristic,

                        Boolean *hasIt)

{

    if (kCharacteristicProvidesKeyFocus == characteristic)  {

        OSErr           err;

        Boolean         canEdit = false;

        QTAtomContainer propertyContainer = nil;

        err = GetMediaPropertyAtom (store->media, &propertyContainer);

        if ((noErr == err) && (propertyContainer))  {

            QTAtom canEditAtom = QTFindChildByIndex(propertyContainer,

                kParentAtomIsContainer, kTrackFocusCanEditFlag, 1, nil);

            if (canEditAtom)

                QTCopyAtomDataToPtr(propertyContainer, canEditAtom,

                                    false, sizeof(Boolean), &canEdit,

                                    nil);

        }

        if (propertyContainer)      (void) QTDisposeAtomContainer

            (propertyContainer);

        *hasIt = canEdit;

    }

    ...

}

{

    QTAtomContainer mediaProperties;

    Boolean         hasActions = true;

    QTNewAtomContainer(&mediaProperties);

    QTInsertChild(mediaProperties, 0, kMediaPropertyHasActions, 1, 1,

                    sizeof(hasActions), &hasActions, NULL);

    myErr = SetMediaPropertyAtom(myMedia, mediaProperties);

    QTDisposeAtomContainer(mediaProperties);

}

MediaHitTestForTargetRefCon

Locates the object for hit testing.

ComponentResult MediaHitTestForTargetRefCon (
   MediaHandler    mh,
   long            flags,
   Point           loc,
   long            *targetRefCon );

Parameters

mh

A media handler. You can obtain this reference from GetMediaHandler (I-443).

flags

Flags (see below) that define the hit.

mHitTestBounds

The point may only be within the targetRefCon bounding box.

mHitTestImage

The point must be within the shape of the targetRefCon image.

mHitTestInvisible

An invisible targetRefCon may be hit tested, even if the object is invisible.

mHitTestIsClick

The hit is a mouse click for codecs that want mouse events.

loc

The location of the mouse.

targetRefCon

Returns a reference constant representing an object you’re interested in. If this reference constant is not 0, your media handler will receive calls to MediaGetActionsForQTEvent.

Return Value

See “Error Codes” (IV-2718). Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

The following flags are set by the Standard Controller, which currently sets mHitTestImage and mHitTestInvisible before it calls you.

This routine is used to locate the object for hit testing.

Introduced in QuickTime 6.

C interface file: MediaHandlers.h

MediaHitTestTargetRefCon

Detects if the mouse click and its release are in the same location, and within the object.

ComponentResult MediaHitTestTargetRefCon (
   MediaHandler    mh,
   long            targetRefCon,
   long            flags,
   Point           loc,
   Boolean         *wasHit );

Parameters

mh

A media handler. You can obtain this reference from GetMediaHandler (I-443).

targetRefCon

A reference constant set by the media handler in MediaHitTestForTargetRefCon.

flags

Flags (see below) that define the hit.

mHitTestBounds

The point may only be within the targetRefCon bounding box.

mHitTestImage

The point must be within the shape of the targetRefCon image.

mHitTestInvisible

An invisible targetRefCon may be hit tested.

mHitTestIsClick

The hit is a mouse click for codecs that want mouse events.

loc

The location of the mouse.

wasHit

A pointer to a Boolean; return TRUE if there was a hit, FALSE otherwise.

See “Error Codes” (IV-2718). Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

This routine is called after MediaGetActionsForQTEvent if a reference constant was set in MediaHitTestForTargetRefCon.

Introduced in QuickTime 6.

C interface file: MediaHandlers.h

MediaGetActionsForQTEvent

Returns an Event Handler for your Media Handler.

ComponentResult MediaGetActionsForQTEvent (
   MediaHandler        mh,
   QTEventRecordPtr    event,
   long                targetRefCon,
   QTAtomContainer     *container,
   QTAtom              *atom );

Parameters

mh

A media handler. You can obtain this reference from GetMediaHandler (I-443).

event

A pointer to a QTEventRecord (IV-2409) structure.

targetRefCon

A reference constant set by the media handler in MediaHitTestForTargetRefCon.

container

An atom container that you can pass back to the standard controller used for implementing sprite actions.

atom

An atom you can pass back to the standard controller used for implementing sprite actions.

See “Error Codes” (IV-2718). Returns noErr if there is no error. Returns qtEventWasHandledErr if event was handled by the media handler qtEventWasHandledErr = -2129.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

This routine returns an Event Handler for your Media Handler, and is called with the targetRefcon set in MediaHitTestForTargetRefCon.

Introduced in QuickTime 6.

C interface file: MediaHandlers.h

MediaDisposeTargetRefCon

Disposes any resources allocated as part of the RefCon.

ComponentResult MediaDisposeTargetRefCon (
   MediaHandler    mh,
   long            targetRefCon );

Parameters

mh

A media handler. You can obtain this reference from GetMediaHandler (I-443).

targetRefCon

A reference constant set by the media handler in MediaHitTestForTargetRefCon.

See “Error Codes” (IV-2718). Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

This routine disposes any resources that your application has allocated as part of the reference constant.

Introduced in QuickTime 6.

C interface file: MediaHandlers.h

MediaNavigateTargetRefCon

Locates the object for keyboard focus.

ComponentResult MediaNavigateTargetRefCon (
   MediaHandler    mh,
   long            navigation,
   long *          refCon );

Parameters

mh

A media handler. You can obtain this reference from GetMediaHandler (I-443).

navigation

Flags (see below) that define the direction.

refCon

Returns a reference constant representing an object you’re interested in. If this reference constant is not 0, your media handler will receive calls to MediaRefConSetProperty and MediaRefConGetProperty.

See “Error Codes” (IV-2718). Returns noErr if there is no error.

The following flags are set by the Standard Controller, which is determined by the user’s interaction with the tab and shift keys, and/or mouse.

kRefConNavigationNext

Tabbing direction is forward. If no item currently selection, then use first.

kRefConNavigationPrevious

Tabbing direction is backward. If no item currently selection, then use the last.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

These constants, which enable navigational direction, are defined as follows:

enum {

    kRefConNavigationNext = 0,

    kRefConNavigationPrevious = 1

};

This routine is locates the object for keyboard focus.

Introduced in QuickTime 6.

C interface file: MediaHandlers.h

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice