UITouch Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UITouch.h
Related sample code

Overview

A UITouch object represents the presence or movement of a finger on the screen for a particular event. You access UITouch objects through UIEvent objects passed into responder objects for event handling.

A UITouch object includes methods for accessing the view or window in which the touch occurred and for obtaining the location of the touch in a specific view or window. it also lets you find out when the touch occurred, whether the user tapped more than once, whether the finger is swiped (and if so, in which direction), and the phase of a touch—that is, whether it began, moved, or ended the gesture, or whether it was canceled.

A UITouch object is persistent throughout a multi-touch sequence. You should never retain an UITouch object when handling an event. If you need to keep information about a touch from one phase to another, you should copy that information from the UITouch object.

The gestureRecognizers property, which was introduced in iOS 3.2, returns the gesture recognizers—that is, instances of a concrete subclass of UIGestureRecognizer—that are currently handling the given touch.

Tasks

Getting the Location of Touches

Getting Touch Attributes

Getting a Touch Object’s Gesture Recognizers

Properties

gestureRecognizers

The gesture recognizers that are receiving the touch object.

@property(nonatomic,readonly,copy) NSArray *gestureRecognizers
Discussion

The objects in the array are instances of a subclass of the abstract base class UIGestureRecognizer. If there are no gesture recognizers currently receiving the touch objects, this property holds an empty array.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITouch.h

phase

The type of touch. (read-only)

@property(nonatomic, readonly) UITouchPhase phase
Discussion

The property value is a constant that indicates whether the touch began, moved, ended, or was canceled. For descriptions of possible UITouchPhase values, see “Touch Phase.”

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITouch.h

tapCount

The number of times the finger was tapped for this given touch. (read-only)

@property(nonatomic, readonly) NSUInteger tapCount
Discussion

The value of this property is an integer indicating the number of times the user tapped their fingers on a certain point within a predefined period. If you want to determine whether the user single-tapped, double-tapped, or even triple-tapped a particular view or window, you should evaluate the value returned by this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITouch.h

timestamp

The time when the touch occurred or when it was last mutated. (read-only)

@property(nonatomic, readonly) NSTimeInterval timestamp
Discussion

The value of this property is the time, in seconds, since system startup the touch either originated or was last changed. You can store and compare the initial value of this attribute to subsequent timestamp values of the UITouch instance to determine the duration of the touch and, if it is being swiped, the speed of movement. For a definition of the time-since-boot value, see the description of the systemUptime method of the NSProcessInfo class.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITouch.h

view

The view in which the touch initially occurred. (read-only)

@property(nonatomic, readonly, retain) UIView *view
Discussion

The value of the property is the view object in which the touch originally occurred. This object might not be the view the touch is currently in.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UITouch.h

window

The window in which the touch initially occurred. (read-only)

@property(nonatomic, readonly, retain) UIWindow *window
Discussion

The value of the property is the window object in which the touch originally occurred. This object might not be the window the touch is currently in.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UITouch.h

Instance Methods

locationInView:

Returns the current location of the receiver in the coordinate system of the given view.

- (CGPoint)locationInView:(UIView *)view
Parameters
view

The view object in whose coordinate system you want the touch located. A custom view that is handling the touch may specify self to get the touch location in its own coordinate system. Pass nil to get the touch location in the window’s coordinates.

Return Value

A point specifying the location of the receiver in view.

Discussion

This method returns the current location of a UITouch object in the coordinate system of the specified view. Because the touch object might have been forwarded to a view from another view, this method performs any necessary conversion of the touch location to the coordinate system of the specified view.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITouch.h

previousLocationInView:

Returns the previous location of the receiver in the coordinate system of the given view.

- (CGPoint)previousLocationInView:(UIView *)view
Parameters
view

The view object in whose coordinate system you want the touch located. A custom view that is handling the touch may specify self to get the touch location in its own coordinate system. Pass nil to get the touch location in the window’s coordinates.

Return Value

This method returns the previous location of a UITouch object in the coordinate system of the specified view. Because the touch object might have been forwarded to a view from another view, this method performs any necessary conversion of the touch location to the coordinate system of the specified view.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITouch.h

Constants

Touch Phase

The phase of a finger touch.

typedef enum {
   UITouchPhaseBegan,
   UITouchPhaseMoved,
   UITouchPhaseStationary,
   UITouchPhaseEnded,
   UITouchPhaseCancelled,
} UITouchPhase;
Constants
UITouchPhaseBegan

A finger for a given event touched the screen.

Available in iOS 2.0 and later.

Declared in UITouch.h.

UITouchPhaseMoved

A finger for a given event moved on the screen.

Available in iOS 2.0 and later.

Declared in UITouch.h.

UITouchPhaseStationary

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

Available in iOS 2.0 and later.

Declared in UITouch.h.

UITouchPhaseEnded

A finger for a given event was lifted from the screen.

Available in iOS 2.0 and later.

Declared in UITouch.h.

UITouchPhaseCancelled

The system cancelled tracking for the touch, as when (for example) the user puts the device to his or her face.

Available in iOS 2.0 and later.

Declared in UITouch.h.

Discussion

The phase of a UITouch instance changes in a certain order during the course of an event. You access this value through the phase property.

Declared In
UITouch.h