NSTouch Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSTouch.h
Related sample code

Overview

An instance of the NSTouch class is a snapshot of a particular touch at an instant in time.

A touch event is not persistent throughout the touch, new instances are created as the touch progresses. The identity property is used to follow a specific touch across its lifetime.

Touches do not have a corresponding screen location. The first touch of a touch collection is latched to the view underlying the cursor using the same hit detection as mouse events. Additional touches on the same device are also latched to the same view as any other touching touches. A touch remains latched to its view until the touch has either ended or is cancelled.

Tasks

Properties of This Touch

Properties of Touch Device

Properties

device

The digitizer that generated the touch. Useful to distinguish touches emanating from multiple-device scenario. (read-only)

@property(readonly, retain) id device
Availability
  • Available in OS X v10.6 and later.
Declared In
NSTouch.h

deviceSize

The range of the touch device in points (72ppi). (read-only)

@property(readonly) NSSize deviceSize
Discussion

The lower-left corner of the surface is considered (0,0).

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTouch.h

identity

Use this property to track changes to a particular touch during the touch's life. (read-only)

@property(readonly, retain) id<NSObject, NSCopying> identity
Discussion

While touch identities may be re-used, they are unique during the life of the touch, even when multiple devices are present.

Identity objects implement the NSCopying protocol so that they may be used as keys in an NSDictionary. Use isEqual: to compare two touch identities.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSTouch.h

isResting

Returns whether the touch is a resting touch. (read-only)

@property(readonly) BOOL isResting
Discussion

Resting touches occur when a user simply rests their thumb on the trackpad device.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTouch.h

normalizedPosition

The normalized position of the touch. (read-only)

@property(readonly) NSPoint normalizedPosition
Discussion

The normalized position is a scaled value between (0.0) and (1.0,1.0), where (0.0,0.0) is the lower-left position on the touch device.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSTouch.h

phase

The current phase of the touch. (read-only)

@property(readonly) NSTouchPhase phase
Discussion

See “NSTouchPhase” for possible values.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSTouch.h

Constants

NSTouchPhase

The possible phases of a touch. These constants are used by phase.

enum {
   NSTouchPhaseBegan           = 1U << 0,
   NSTouchPhaseMoved           = 1U << 1,
   NSTouchPhaseStationary      = 1U << 2,
   NSTouchPhaseEnded           = 1U << 3,
   NSTouchPhaseCancelled       = 1U << 4,
   NSTouchPhaseTouching        = NSTouchPhaseBegan | NSTouchPhaseMoved | NSTouchPhaseStationary,
   NSTouchPhaseAny             = NSUIntegerMax
};
typedef NSUInteger NSTouchPhase;
Constants
NSTouchPhaseBegan

A finger touched the device. Or, a resting touch transitioned to an active touch and resting touches are not wanted by the view hierarchy.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseMoved

A finger moved on the device.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseStationary

A finger is touching the device, but hasn't moved since the previous event.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseEnded

A finger was lifted from the screen. Or, an active touch transitioned to a resting touch and resting touches are not wanted by the view hierarchy.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseCancelled

The system cancelled tracking for the touch, as when (for example) the window associated with the touch resigns key or is deactivated.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseTouching

Matches the NSTouchPhaseBegan, NSTouchPhaseMoved, or NSTouchPhaseStationary phases of a touch.

Available in OS X v10.6 and later.

Declared in NSTouch.h.

NSTouchPhaseAny

Matches any phase of a touch.

Available in OS X v10.6 and later.

Declared in NSTouch.h.