iOS Developer Library

Developer

UIKit Framework Reference UITouch Class Reference

Options
Deployment Target:

On This Page
Language:

UITouch

Inherits From

Conforms To

Import Statement

Objective-C

@import UIKit;

Swift

import UIKit

Availability

Available in iOS 2.0 and later

A UITouch object represents the location, size, movement, and force of a finger on the screen for a particular event. The force of a touch is available starting in iOS 9 on devices that support 3D Touch or Apple Pencil.

You access touch objects through UIEvent objects passed into responder objects for event handling. A touch object includes accessors for:

  • The view or window in which the touch occurred

  • The location of the touch within the view or window

  • The approximate radius of the touch

  • The force of the touch (on devices that support 3D Touch or Apple Pencil)

A touch object also contains a timestamp indicating when the touch occurred, an integer representing the number of times the user tapped the screen, and the phase of the touch in the form of a constant that describes whether the touch began, moved, or ended, or whether the system canceled the touch.

To learn how to work with swipes, read Handling Swipe and Drag Gestures in Event Handling Guide for iOS.

A touch object persists throughout a multi-touch sequence. Never retain a touch object when handling an event. If you need to keep information about a touch from one touch phase to another, copy that information from the touch.

The gestureRecognizers property of a touch contains the gesture recognizers currently handling the touch. Each gesture recognizer is an instance of a concrete subclass of UIGestureRecognizer.

Getting the Location of a Touch
  • locationInView(_: UIView?) -> CGPoint - locationInView:

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

    Declaration

    Swift

    func locationInView(_ view: UIView?) -> CGPoint

    Objective-C

    - (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.

    See Also

    – previousLocationInView:

  • previousLocationInView(_: UIView?) -> CGPoint - previousLocationInView:

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

    Declaration

    Swift

    func previousLocationInView(_ view: UIView?) -> CGPoint

    Objective-C

    - (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.

    See Also

    – locationInView:

  • view view Property

    The view to which touches are being delivered, if any. (read-only)

    Declaration

    Swift

    var view: UIView? { get }

    Objective-C

    @property(nonatomic, readonly, strong) UIView *view

    Discussion

    The value of this property is the view object to which touches are being delivered, which is not necessarily the view the touch is currently in. For example, when a gesture recognizer recognizes the touch, this property is nil because no view is receiving the touch.

    Availability

    Available in iOS 2.0 and later.

    See Also

    window

  • window window Property

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

    Declaration

    Swift

    var window: UIWindow? { get }

    Objective-C

    @property(nonatomic, readonly, strong) 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

    view

  • majorRadius majorRadius Property

    The radius (in points) of the touch. (read-only)

    Declaration

    Swift

    var majorRadius: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat majorRadius

    Discussion

    Use the value in this property to determine the size of the touch that was reported by the hardware. This value is an approximation of the size and can vary by the amount specified in the majorRadiusTolerance property.

    Availability

    Available in iOS 8.0 and later.

  • majorRadiusTolerance majorRadiusTolerance Property

    The tolerance (in points) of the touch’s radius. (read-only)

    Declaration

    Swift

    var majorRadiusTolerance: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat majorRadiusTolerance

    Discussion

    This value determines the accuracy of the value in the majorRadius property. Add this value to the radius to get the maximum touch radius. Subtract the value to get the minimum touch radius.

    Availability

    Available in iOS 8.0 and later.

  • preciseLocation(in:) - preciseLocationInView:

    Returns a precise location for the touch, when available.

    Declaration

    Swift

    func preciseLocationInView(_ view: UIView?) -> CGPoint

    Objective-C

    - (CGPoint)preciseLocationInView:(UIView *)view

    Parameters

    view

    The view that contains the touch.

    Return Value

    A precise location for the touch.

    Discussion

    You can use this method to get additional precision for a touch (when available), but you can’t use it for hit testing. In some cases, hit testing can indicate that a touch is within a view, but a more precise location may indicate that the touch is actually located outside of the view.

    Availability

    Available in iOS 9.1 and later.

  • precisePreviousLocation(in:) - precisePreviousLocationInView:

    Returns a precise previous location for the touch, when available.

    Declaration

    Swift

    func precisePreviousLocationInView(_ view: UIView?) -> CGPoint

    Objective-C

    - (CGPoint)precisePreviousLocationInView:(UIView *)view

    Parameters

    view

    The view that contained the touch.

    Return Value

    A precise previous location for the touch.

    Discussion

    You can use this method to get additional precision for a touch’s previous location (when available), but you can’t use it for hit testing. In some cases, hit testing can indicate that a touch was within a view, but a more precise location may indicate that the touch was actually located outside of the view.

    Availability

    Available in iOS 9.1 and later.

Getting Touch Attributes
  • tapCount tapCount Property

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

    Declaration

    Swift

    var tapCount: Int { get }

    Objective-C

    @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.

  • timestamp timestamp Property

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

    Declaration

    Swift

    var timestamp: NSTimeInterval { get }

    Objective-C

    @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.

  • type type Property

    The type of the touch.

    Declaration

    Swift

    var type: UITouchType { get }

    Objective-C

    @property(nonatomic, readonly) UITouchType type

    Discussion

    For a complete list of touch types, see Touch Type.

    Availability

    Available in iOS 9.0 and later.

  • phase phase Property

    The phase of the touch. (read-only)

    Declaration

    Swift

    var phase: UITouchPhase { get }

    Objective-C

    @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.

  • force force Property

    The force of the touch, where a value of 1.0 represents the force of an average touch (predetermined by the system, not user-specific). (read-only)

    Declaration

    Swift

    var force: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat force

    Discussion

    This property is available on devices that support 3D Touch or Apple Pencil. To check at runtime if a device supports 3D Touch, read the value of the forceTouchCapability property on the trait collection for any object in your app with a trait environment.

    Note that the force reported by Apple Pencil is measured along the axis of the pencil. If you want a force perpendicular to the device, you need to calculate this value using the altitudeAngle value.

    Availability

    Available in iOS 9.0 and later.

    See Also

    maximumPossibleForce

  • maximumPossibleForce maximumPossibleForce Property

    The maximum possible force for a touch. (read-only)

    Declaration

    Swift

    var maximumPossibleForce: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat maximumPossibleForce

    Discussion

    The value of this property is sufficiently high to provide a wide dynamic range for values of the force property.

    This property is available on devices that support 3D Touch or Apple Pencil. To check at runtime if a device supports 3D Touch, read the value of the forceTouchCapability property on the trait collection for any object in your app with a trait environment.

    Availability

    Available in iOS 9.0 and later.

    See Also

    force

  • altitudeAngle altitudeAngle Property

    The altitude (in radians) of the stylus. (read-only)

    Declaration

    Swift

    var altitudeAngle: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat altitudeAngle

    Discussion

    A value of 0 radians indicates that the stylus is parallel to the surface; when the stylus is perpendicular to the surface, altitudeAngle is Pi/2.

    Availability

    Available in iOS 9.1 and later.

  • azimuthAngle(in:) - azimuthAngleInView:

    Returns the azimuth angle (in radians) of the stylus.

    Declaration

    Swift

    func azimuthAngleInView(_ view: UIView?) -> CGFloat

    Objective-C

    - (CGFloat)azimuthAngleInView:(UIView *)view

    Parameters

    view

    The view that contains the stylus’s touch. Pass nil to get the azimuth angle that is relative to the touch’s window.

    Return Value

    The azimuth angle of the stylus, in radians.

    Discussion

    A value of 0 radians points along the positive x axis. The azimuth angle increases as the user swings the cap end of the stylus (that is, the end opposite of the stylus tip) in a clockwise direction. Note that it’s more expensive to get the azimuth angle (as opposed to the azimuth unit vector), but it can also be more convenient.

    Availability

    Available in iOS 9.1 and later.

    See Also

    – azimuthUnitVectorInView:

  • azimuthUnitVector(in:) - azimuthUnitVectorInView:

    Returns a unit vector that points in the direction of the azimuth of the stylus.

    Declaration

    Swift

    func azimuthUnitVectorInView(_ view: UIView?) -> CGVector

    Objective-C

    - (CGVector)azimuthUnitVectorInView:(UIView *)view

    Parameters

    view

    The view that contains the stylus’s touch. Pass nil to get the unit vector for the azimuth that is relative to the touch’s window.

    Return Value

    The unit vector that points in the direction of the azimuth of the stylus.

    Discussion

    It’s less expensive to get the azimuth unit vector (as opposed to the azimuth angle), and if you’re creating transform matrices, the unit vector can be more useful.

    Availability

    Available in iOS 9.1 and later.

    See Also


  • estimatedProperties estimatedProperties Property

    A set of touch properties that will get updated. (read-only)

    Declaration

    Swift

    var estimatedProperties: UITouchProperties { get }

    Objective-C

    @property(nonatomic, readonly) UITouchProperties estimatedProperties

    Discussion

    The value of this property contains a bit mask of touch properties given by Touch Properties.

    Availability

    Available in iOS 9.1 and later.

  • estimationUpdateIndex estimationUpdateIndex Property

    An index number that lets you correlate an updated touch with the original touch. (read-only)

    Declaration

    Swift

    var estimationUpdateIndex: NSNumber? { get }

    Objective-C

    @property(nonatomic, readonly) NSNumber *estimationUpdateIndex

    Discussion

    The value of this property increases monotonically for each touch that contains estimated properties. You can use this property to make sure that you apply touch updates to the appropriate touch. The value of this property is nil when the object does not contain either estimated or updated properties.

    Availability

    Available in iOS 9.1 and later.

    See Also

    estimatedProperties

  • estimatedPropertiesExpectingUpdates estimatedPropertiesExpectingUpdates Property

    A set of touch properties that expect to have incoming updates in the future.

    Declaration

    Swift

    var estimatedPropertiesExpectingUpdates: UITouchProperties { get }

    Objective-C

    @property(nonatomic, readonly) UITouchProperties estimatedPropertiesExpectingUpdates

    Discussion

    If no updates are expected for an estimated property, the current value is the final estimate.

    Availability

    Available in iOS 9.1 and later.

    See Also

    estimatedProperties

Getting a Touch Object’s Gesture Recognizers
  • gestureRecognizers gestureRecognizers Property

    The gesture recognizers that are receiving the touch object. (read-only)

    Declaration

    Swift

    var gestureRecognizers: [UIGestureRecognizer]? { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSArray <UIGestureRecognizer *> *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.

Working with Touch Events in Sprite Kit
  • locationInNode(_: SKNode) -> CGPoint - locationInNode:

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

    Declaration

    Swift

    func locationInNode(_ node: SKNode) -> CGPoint

    Objective-C

    - (CGPoint)locationInNode:(SKNode *)node

    Parameters

    node

    A node that is a descendant of a scene presented in the window that received the touch event.

    Return Value

    The location of the touch in the node’s coordinate system.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • previousLocationInNode(_: SKNode) -> CGPoint - previousLocationInNode:

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

    Declaration

    Swift

    func previousLocationInNode(_ node: SKNode) -> CGPoint

    Objective-C

    - (CGPoint)previousLocationInNode:(SKNode *)node

    Parameters

    node

    A node that is a descendant of a scene presented in the window that received the touch event.

    Return Value

    The location of the touch in the node’s coordinate system.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

Constants
  • UIForceTouchCapability

    A value that indicates if force touch is available.

    Declaration

    Swift

    enum UIForceTouchCapability : Int { case Unknown case Unavailable case Available }

    Objective-C

    typedef enum { UIForceTouchCapabilityUnknown = 0, UIForceTouchCapabilityUnavailable = 1, UIForceTouchCapabilityAvailable = 2 } UIForceTouchCapability;

    Constants

    • unknown

      UIForceTouchCapabilityUnknown

      The availability of force touch can’t be determined.

      Available in iOS 9.0 and later.

    • unavailable

      UIForceTouchCapabilityUnavailable

      Force touch is not available.

      Available in iOS 9.0 and later.

    • available

      UIForceTouchCapabilityAvailable

      Force touch is available.

      Available in iOS 9.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 9.0 and later.

  • UITouchType

    The type of touch received.

    Declaration

    Swift

    enum UITouchType : Int { case Direct case Indirect case Stylus }

    Objective-C

    typedef enum { UITouchTypeDirect, UITouchTypeIndirect, UITouchTypeStylus } UITouchType;

    Constants

    • direct

      UITouchTypeDirect

      A direct touch from a finger on the screen.

      Available in iOS 9.0 and later.

    • indirect

      UITouchTypeIndirect

      An indirect touch, not on a screen.

      Available in iOS 9.0 and later.

    • stylus

      UITouchTypeStylus

      A touch from a stylus.

      Available in iOS 9.1 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 9.1 and later.

  • UITouchProperties

    A bit mask of touch properties that may get updated.

    Declaration

    Swift

    struct UITouchProperties : OptionSetType { init(rawValue rawValue: Int) static var Force: UITouchProperties { get } static var Azimuth: UITouchProperties { get } static var Altitude: UITouchProperties { get } static var Location: UITouchProperties { get } }

    Objective-C

    typedef enum { UITouchPropertyForce = (1UL << 0), UITouchPropertyAzimuth = (1UL << 1), UITouchPropertyAltitude = (1UL << 2), UITouchPropertyLocation = (1UL << 3), } UITouchProperties;

    Constants

    • force

      UITouchPropertyForce

      A touch property, representing force, in a bit mask.

      Available in iOS 9.1 and later.

    • azimuth

      UITouchPropertyAzimuth

      A touch property, representing azimuth, in a bit mask.

      Available in iOS 9.1 and later.

    • altitude

      UITouchPropertyAltitude

      A touch property, representing altitude, in a bit mask.

      Available in iOS 9.1 and later.

    • location

      UITouchPropertyLocation

      A touch property, representing location, in a bit mask.

      Available in iOS 9.1 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 9.1 and later.

  • UITouchPhase

    The phase of a finger touch.

    Declaration

    Swift

    enum UITouchPhase : Int { case Began case Moved case Stationary case Ended case Cancelled }

    Objective-C

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

    Constants

    • began

      UITouchPhaseBegan

      A finger for a given event touched the screen.

      Available in iOS 2.0 and later.

    • moved

      UITouchPhaseMoved

      A finger for a given event moved on the screen.

      Available in iOS 2.0 and later.

    • stationary

      UITouchPhaseStationary

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

      Available in iOS 2.0 and later.

    • ended

      UITouchPhaseEnded

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

      Available in iOS 2.0 and later.

    • cancelled

      UITouchPhaseCancelled

      The system canceled tracking for the touch, as when (for example) the user moves the device against his or her face.

      Available in iOS 2.0 and later.

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

Copyright © 2016 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-03-21