ADC Home > Reference Library > Reference > Carbon > Events & Other Input > Carbon Event Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Carbon Event Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

ChangeMouseTrackingRegion

(Deprecated in Mac OS X v10.4. Use HIViewChangeTrackingArea instead.)

OSStatus ChangeMouseTrackingRegion (
   MouseTrackingRef inMouseRef,
   RgnHandle inRegion,
   RgnHandle inClip
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

ClipMouseTrackingRegion

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based mouse tracking areas instead.)

OSStatus ClipMouseTrackingRegion (
   MouseTrackingRef inMouseRef,
   RgnHandle inRegion
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. You generally don’t need to modify the clipping of a tracking area. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

ClipWindowMouseTrackingRegions

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus ClipWindowMouseTrackingRegions (
   WindowRef inWindow,
   OSType inSignature,
   RgnHandle inClip
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. You generally don’t need to modify the clipping of a tracking area. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

CreateMouseTrackingRegion

Creates a mouse tracking region. (Deprecated in Mac OS X v10.4. Use the HIView function HIViewNewTrackingArea instead.)

OSStatus CreateMouseTrackingRegion (
   WindowRef inWindow,
   RgnHandle inRegion,
   RgnHandle inClip,
   MouseTrackingOptions inOptions,
   MouseTrackingRegionID inID,
   void *inRefCon,
   EventTargetRef inTargetToNotify,
   MouseTrackingRef *outTrackingRef
);

Parameters
inWindow

The window to contain the tracking region.

inRegion

The region for which you want to receive mouse entered/exited events.

inClip

The clip region for the inRegion region (can be NULL).

inOptions

Tracking options that define whether the inRegion region is in local or global coordinates.

inID

A signature and ID to uniquely define this tracking region. See MouseTrackingRegionID for information about the structure of this ID.

inRefCon

A pointer to an application-defined value. You can obtain this value by calling GetMouseTrackingRegionRefCon.

inTargetToNotify

The event target to send the mouse tracking event. If you pass NULL, the event target is the owning window specified in inWindow.

outTrackingRef

On return, a pointer to the new mouse tracking region.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

CreateMouseTrackingRegion allows you to define regions in your window, and the specified event target is notified (using kEventMouseEntered or kEventMouseExited events) when the mouse cursor interacts with the region. Your application can define any number of regions as long as each has a unique ID. This function is especially useful for creating rollover effects without having to constantly poll the mouse.

If you need to keep track of the state of the mouse (down or up) in a region, you should use TrackMouseRegion, either instead of, or in conjunction with, mouse tracking regions.

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Related Sample Code
Declared In
CarbonEvents.h

GetMouseTrackingRegionID

(Deprecated in Mac OS X v10.4. Use HIViewGetTrackingAreaID instead.)

OSStatus GetMouseTrackingRegionID (
   MouseTrackingRef inMouseRef,
   MouseTrackingRegionID *outID
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

GetMouseTrackingRegionRefCon

Obtains the reference constant for a mouse tracking region. (Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based mouse tracking areas instead.)

OSStatus GetMouseTrackingRegionRefCon (
   MouseTrackingRef inMouseRef,
   void **outRefCon
);

Parameters
inMouseRef

The mouse tracking region whose reference count you want to obtain.

outRefCon

On return, a handler for the mouse tracking region.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You use this function to obtain the reference constant you set in the CreateMouseTrackingRegion function.

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. Mouse tracking areas do not support a reference constant. Instead, you can obtain the tracking area ID (using HIViewGetTrackingAreaID) and use that as a key to look up extended data in your own tables. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

MoveMouseTrackingRegion

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus MoveMouseTrackingRegion (
   MouseTrackingRef inMouseRef,
   SInt16 deltaH,
   SInt16 deltaV,
   RgnHandle inClip
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. HIView-based mouse tracking areas move automatically when the HIView moves. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

MoveWindowMouseTrackingRegions

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus MoveWindowMouseTrackingRegions (
   WindowRef inWindow,
   OSType inSignature,
   SInt16 deltaH,
   SInt16 deltaV,
   RgnHandle inClip
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. HIView-based mouse tracking areas move automatically when the HIView moves. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

RegisterToolboxObjectClass

Registers events to be associated with a toolbox object. (Deprecated in Mac OS X v10.4. Use the HIObject function HIObjectRegisterSubclass instead.)

OSStatus RegisterToolboxObjectClass (
   CFStringRef inClassID,
   ToolboxObjectClassRef inBaseClass,
   ItemCount inNumEvents,
   const EventTypeSpec *inEventList,
   EventHandlerUPP inEventHandler,
   void *inEventHandlerData,
   ToolboxObjectClassRef *outClassRef
);

Parameters
inClassID

The class ID of the toolbox object you want to register. This value should be a Core Foundation string in the form com.myCorp.myApp.myWidget.

inBaseClass

The class reference of this toolbox object’s base class. Pass NULL if there is no base class.

inNumEvents

The number of events to register for this object class.

inEventList

An array of events you want to register for this object class. You define these events just as you would for any other Carbon event handler.

inEventHandler

A universal procedure pointer to the event handler for this object class.

inEventHandlerData

Any application-specific data you want passed to your event handler when it is called.

outClassRef

On return, outClassRef contains a reference to the new object class. You use this value in your custom definition specification (such as a ControlDefSpec or WindowDefSpec) to define your new object class.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You use this function to register event handlers to implement what were formerly called defproc messages; that is, you can use toolbox objects in place of older custom window, menu, and control definitions.

Special Considerations

HIObject allows you to create subclasses that you can use for creating custom HIViews. HIViews support compositing and Quartz and provide an easier way to handle user elements in windows. Use HIObjectRegisterSubclass to create custom HIObjects and HIViews. See HIView Programming Guide for more details.

Availability
Declared In
CarbonEvents.h

ReleaseMouseTrackingRegion

Releases a mouse tracking region. (Deprecated in Mac OS X v10.4. Use HIViewDisposeTrackingArea instead.)

OSStatus ReleaseMouseTrackingRegion (
   MouseTrackingRef inMouseRef
);

Parameters
inMouseRef

The mouse tracking region to release.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

ReleaseMouseTrackingRegion decreases the reference count for the region. If the reference count drops to zero, the mouse tracking region is disposed.

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Related Sample Code
Declared In
CarbonEvents.h

ReleaseWindowMouseTrackingRegions

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus ReleaseWindowMouseTrackingRegions (
   WindowRef inWindow,
   OSType inSignature
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. If you need to release multiple tracking areas at once, you should keep track of them in your own data structures and release each one. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

RetainMouseTrackingRegion

Retains a mouse tracking region. (Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus RetainMouseTrackingRegion (
   MouseTrackingRef inMouseRef
);

Parameters
inMouseRef

The mouse tracking region to retain.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

RetainMouseTrackingRegion increases the reference count for the region.

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. Mouse tracking areas do not have a retain/release semantic, so there is no direct replacement for RetainMouseTrackingRegion. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

SetMouseTrackingRegionEnabled

(Deprecated in Mac OS X v10.4. No replacement function. Use HIView-based tracking areas instead.)

OSStatus SetMouseTrackingRegionEnabled (
   MouseTrackingRef inMouseRef,
   Boolean inEnabled
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. To disable tracking areas, you can either delete the tracking area or ignore kEventControlTrackingAreaEntered events. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

SetWindowMouseTrackingRegionsEnabled

(Deprecated in Mac OS X v10.4. Use HIView-based tracking areas instead.)

OSStatus SetWindowMouseTrackingRegionsEnabled (
   WindowRef inWindow,
   OSType inSignature,
   Boolean inEnabled
);

Special Considerations

Tracking areas are HIView-based rather than window-based. HIViews support compositing and Quartz, and provide a much easier way to handle user elements in windows. To disable tracking areas, you can either delete the tracking area or ignore kEventControlTrackingAreaEntered events. For more details about tracking areas, see the mouse tracking region section in Carbon Event Manager Programming Guide. For details about HIViews, see HIView Programming Guide.

Availability
Declared In
CarbonEvents.h

UnregisterToolboxObjectClass

Unregisters events for a given toolbox object class (Deprecated in Mac OS X v10.4. Use the HIObject function HIObjectUnregisterClass instead.)

OSStatus UnregisterToolboxObjectClass (
   ToolboxObjectClassRef inClassRef
);

Parameters
inClassRef

A reference to the toolbox object class you want to unregister.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Special Considerations

HIObject allows you to create subclasses that you can use for creating custom HIViews. HIViews support compositing and Quartz and provide an easier way to handle user elements in windows. Use HIObjectUnregisterClass to unregister custom HIObjects and HIViews. See HIView Programming Guide for more details.

Availability
Declared In
CarbonEvents.h

< Previous PageNext Page > Hide TOC

© 2003, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)

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.