Mac Developer Library

Developer

AppKit Framework Reference NSTrackingArea Class Reference

Options
Deployment Target:

On This Page
Language:

NSTrackingArea

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.

An NSTrackingArea object defines a region of view that generates mouse-tracking and cursor-update events when the mouse is over that region.

When creating a tracking-area object, you specify a rectangle (in the view’s coordinate system), an owning object, and one or more options, along with (optionally) a dictionary of data. Once it’s created, you add the tracking-area object to a view using the addTrackingArea: method. Depending on the options specified, the owner of the tracking area receives mouseEntered:, mouseExited:, mouseMoved:, and cursorUpdate: messages when the mouse cursor enters, moves within, and leaves the tracking area. Currently the tracking area is restricted to rectangles.

An NSTrackingArea object belongs to its view rather than to its window. Consequently, you can add and remove tracking rectangles without needing to worry if the view has been added to a window. In addition, this design makes it possible for the Application Kit to compute the geometry of tracking areas automatically when a view moves and, in some cases, when a view changes size.

With NSTrackingArea, you can configure the scope of activity for mouse tracking. There are four options:

  • The tracking area is active only when the view is first responder.

  • The tracking area is active when the view is in the key window.

  • The tracking area is active when the application is active.

  • The tracking area is active always (even when the application is inactive).

Other options for NSTrackingArea objects include specifying that the tracking area should be synchronized with the visible rectangle of the view (visibleRect) and for generating mouseEntered: and mouseExited: events when the mouse is dragged.

Other NSView methods related to NSTrackingArea objects (in addition to addTrackingArea:) include removeTrackingArea: and updateTrackingAreas. Views can override the latter method to recompute and replace their NSTrackingArea objects in certain situations, such as a change in the size of the visibleRect.

  • Initializes and returns an object defining a region of a view to receive mouse-tracking events, mouse-moved events, cursor-update events, or possibly all these events.

    Declaration

    Swift

    init!(rect rect: NSRect, options options: NSTrackingAreaOptions, owner owner: AnyObject!, userInfo userInfo: [NSObject : AnyObject]?)

    Objective-C

    - (instancetype)initWithRect:(NSRect)rect options:(NSTrackingAreaOptions)options owner:(id)owner userInfo:(NSDictionary *)userInfo

    Parameters

    rect

    A rectangle that defines a region of a target view, in the view’s coordinate system, for tracking events related to mouse tracking and cursor updating. The specified rectangle should not exceed the view’s bounds rectangle.

    options

    One or more constants that specify the type of tracking area, the situations when the area is active, and special behaviors of the tracking area. See the description of NSTrackingAreaOptions and related constants for details. You must specify one or more options for the initialized object, in particular the type of tracking area; zero is not a valid value.

    owner

    The object to receive the requested mouse-tracking, mouse-moved, or cursor-update messages. It does not necessarily have to be the view associated with the created NSTrackingArea object, but should be an object capable of responding to the NSResponder methods mouseEntered:, mouseExited:, mouseMoved:, and cursorUpdate:.

    userInfo

    A dictionary containing arbitrary data for each mouse-entered, mouse-exited, and cursor-update event. When handling such an event you can obtain the dictionary by sending userData to the NSEvent object. (The dictionary is not available for mouse-moved events.) This parameter may be nil.

    Return Value

    The newly-initialized tracking area object.

    Discussion

    After creating and initializing an NSTrackingArea object with this method, you must add it to a target view using the addTrackingArea: method. When changes in the view require changes in the geometry of its tracking areas, the Application Kit invokes updateTrackingAreas. The view should implement this method to replace the current NSTrackingArea object with one with a recomputed area.

    Special Considerations

    Beginning with OS X v10.5, the initWithRect:options:owner:userInfo:, along with the addTrackingArea: method of NSView, replace the NSView method addTrackingRect:owner:userData:assumeInside:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the options specified for the receiver.

    Declaration

    Swift

    var options: NSTrackingAreaOptions { get }

    Objective-C

    @property(readonly) NSTrackingAreaOptions options

    Discussion

    The options for an NSTrackingArea object are specified when the object is created. To determine if a particular option is in effect, perform a bitwise-AND operation with an NSTrackingAreaOptions constant and the value returned from this method, for example:

    • if ([trackingAreaObj options] & NSTrackingInVisibleRect != 0) {
    • // do something appropriate
    • }

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the object owning the receiver, which is the recipient of mouse-tracking, mouse-movement, and cursor-update messages.

    Declaration

    Swift

    unowned(unsafe) var owner: AnyObject! { get }

    Objective-C

    @property(readonly, assign) id owner

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the rectangle defining the area encompassed by the receiver.

    Declaration

    Swift

    var rect: NSRect { get }

    Objective-C

    @property(readonly) NSRect rect

    Discussion

    The rectangle is specified in the local coordinate system of the associated view. if the NSTrackingInVisibleRect option is specified, the receiver is automatically synchronized with changes in the view’s visible area (visibleRect) and the value returned from this method is ignored.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the dictionary containing the data associated with the receiver when it was created.

    Declaration

    Swift

    var userInfo: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *userInfo

    Discussion

    Returns nil if no data was specified when the receiver was initialized. You can obtain this dictionary per event in each mouseEntered: and mouseExited: method by querying the passed-in NSEvent object with [[event trackingArea] userData].

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

Data Types