Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Creating an NSTrackingArea Object

An NSTrackingArea object defines a region of a view that is sensitive to the movements of the mouse. When the mouse enters, moves about, and exits that region, the Application Kit sends mouse-tracking, mouse-moved, and cursor-update messages. The region is a rectangle specified in the local coordinate system of its associated view. The recipient of the messages (the owner) is specified when the tracking-area object is created; although the owner can be any object, it is often the view associated with the tracking-area object.

When you create an NSTrackingArea object you must specify one or more options. These options, which are enumerated constants declared by the class, configure various aspects of tracking-area behavior. They fall into three general categories:

• The type of event message sent

  You can request mouseEntered: and mouseExited: messages (NSTrackingMouseEnteredAndExited); you can request mouseMoved: messages (NSTrackingMouseMoved); and you can request cursorUpdate: messages (NSTrackingCursorUpdate).

  You are not limited to a single option from this set; you can perform a bitwise-OR operation to request multiple types of messages.

• The active scope of tracking-area messages

  You must specify one of the following options to request when the tracking area should actively generate events:

  • When the associated view is first responder (NSTrackingActiveWhenFirstResponder)

  • When the associated view is in the key window (NSTrackingActiveInKeyWindow)

  • When the associated view in in the active application (NSTrackingActiveInActiveApp)

  • At all times regardless of application activation (NSTrackingActiveAlways)

• Refinements of tracking-area behavior

  You can request that the first message be sent when the mouse cursor first leaves the tracking area (NSTrackingAssumeInside); you can request the tracking area to be the same as the visible rectangle of the associated view (NSTrackingInVisibleRect); and you can request that mouse drags into and out of the tracking area generate mouseEntered: and mouseExited: events (NSTrackingEnabledDuringMouseDrag).

  You are not limited to a single option from this set; you can perform a bitwise-OR operation to request multiple refinements on behavior.

You initialize an allocated instance of NSTrackingArea with the initWithRect:options:owner:userInfo: method. After creating the object, you must associate it with a view by invoking the NSView method addTrackingArea:. You can create an NSTrackingArea instance and add it to a view at any point because (unlike the mouse-tracking API in earlier releases), successful creation does not depend on the view being added to a window. Listing 6-1 shows the creation and addition of an NSTrackingArea instance in a custom view’s initWithFrame: method; in this case, the owning view is requesting that the Application Kit send mouseEntered:, mouseExited: and mouseMoved: messages whenever its window is the key window.

Listing 6-1  Initializing an NSTrackingArea instance

- (id)initWithFrame:(NSRect)frame {

    self = [super initWithFrame:frame];

    if (self) {

        trackingArea = [[NSTrackingArea alloc] initWithRect:eyeBox

            options: (NSTrackingMouseEnteredAndExited | NSTrackingMouseMoved | NSTrackingActiveInKeyWindow )

            owner:self userInfo:nil];

        [self addTrackingArea:trackingArea];

    }

    return self;

}

The last parameter of initWithRect:options:owner:userInfo: is a dictionary that you can use to pass arbitrary data to the recipient of mouse-tracking and cursor-update messages. The receiving object can access the dictionary by sending userData to the NSEvent object passed into the mouseEntered:, mouseExited:, or cursorUpdate: method. Sending userData messages in mouseMoved: methods causes an assertion failure. (In the example in Listing 6-1, the userInfo parameter is set to nil.)

Tracking rectangle bounds are inclusive for the top and left edges, but not for the bottom and right edges. Thus, if you have a unflipped view with a tracking rectangle covering its bounds, and the view’s frame has the geometry frame.origin = (100, 100), frame.size = (200, 200), then the area for which the tracking rectangle is active is frame.origin = (100, 101), frame.size = (199, 199), in frame coordinates.

< 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