Mac Developer Library

Developer

AppKit Framework Reference NSTrackingArea Class Reference

Options
Deployment Target:

On This Page
Language:

NSTrackingArea

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

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.5 and later.
  • 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

    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

    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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.5 and later.

Data Types