UIEvent

Inherits From

NSObject
UIEvent
UIPressesEvent

NSObject
UIEvent
UIPressesEvent

Conforms To

Import Statement

Objective-C

@import UIKit;

Swift

import UIKit

Availability

Available in iOS 2.0 and later

A UIEvent object (or, simply, an event object) represents an event in iOS. There are three general types of event: touch events, motion events, and remote-control events. Remote-control events allow a responder object to receive commands from an external accessory or headset so that it can manage manage audio and video—for example, playing a video or skipping to the next audio track. Motion events were introduced in iOS 3.0 and remote-control events in iOS 4.0.

A touch type of event object contains one or more touches (that is, finger gestures on the screen) that have some relation to the event. A touch is represented by a UITouch object. When a touch event occurs, the system routes it to the appropriate responder and passes in the UIEvent object in a message invoking a UIResponder method such as touchesBegan:withEvent:. The responder can then evaluate the touches for the event or for a particular phase of the event and handle them appropriately. The methods of UIEvent allow you to obtain all touches for the event (allTouches) or only those for a given view or window (touchesForView: or touchesForWindow:). It can also distinguish an event object from objects representing other events by querying an object for the time of its creation (timestamp).

A UIEvent object representing a touch event is persistent throughout a multi-touch sequence; UIKit reuses the same UIEvent instance for every event delivered to the application. You should never retain an event object or any object returned from an event object. If you need to keep information from an event around from one phase to another, you should copy that information from the UITouch or UIEvent object.

You can obtain event types and subtypes from the type and subtype properties. UIEvent defines event types for touch, motion, and remote-control events. It also defines a motion subtype for "shake” events and a series of subtype constants for remote-control events, such as “play” and “previous track.” The first responder or any responder in the responder chain implements the motion-related methods of UIResponder (such as motionBegan:withEvent:) to handle shaking-motion events. To handle remote-control events, a responder object must implement the remoteControlReceivedWithEvent: method of UIResponder.

The touchesForGestureRecognizer: method, which was introduced in iOS 3.2, allows you to query a gesture-recognizer object (an instance of a subclass of UIGestureRecognizer) for the touches it is currently handling.

Getting the Touches for an Event

allTouches() - allTouches

Returns all touch objects associated with the receiver.

Declaration

Swift

func allTouches() -> Set<UITouch>?

Objective-C

- (NSSet<UITouch *> *)allTouches

Return Value

A set of UITouch objects representing all touches associated with an event (represented by the receiver).

Discussion

If the touches of the event originate in different views and windows, the UITouch objects obtained from this method will have different responder objects associated with the touches.

Availability

Available in iOS 2.0 and later.

See Also

– touchesForView:
– touchesForWindow:
touchesForView(_:) - touchesForView:

Returns the touch objects that belong to a given view for the event represented by the receiver.

Declaration

Swift

func touchesForView(_ view: UIView) -> Set<UITouch>?

Objective-C

- (NSSet<UITouch *> *)touchesForView:(UIView *)view

Parameters

view

TheUIView object on which the touches related to the event were made.

Return Value

A set of UITouch objects representing the touches for the specified view related to the event represented by the receiver.

Availability

Available in iOS 2.0 and later.

See Also

– allTouches
– touchesForWindow:
touchesForWindow(_:) - touchesForWindow:

Returns the touch objects that belong to a given window for the event represented by the receiver.

Declaration

Swift

func touchesForWindow(_ window: UIWindow) -> Set<UITouch>?

Objective-C

- (NSSet<UITouch *> *)touchesForWindow:(UIWindow *)window

Parameters

window

The UIWindow object on which the touches related to the event were made.

Return Value

A set of UITouch objects representing the touches for the specified window related to the event represented by the receiver.

Availability

Available in iOS 2.0 and later.

See Also

– allTouches
– touchesForView:

Getting Event Attributes

timestamp timestamp Property

The time when the event occurred. (read-only)

Declaration

Swift

var timestamp: NSTimeInterval { get }

Objective-C

@property(nonatomic, readonly) NSTimeInterval timestamp

Discussion

The property value is the number of seconds since system startup. For a description of this time value, see the description of the systemUptime method of the NSProcessInfo class.

Availability

Available in iOS 2.0 and later.

Getting the Event Type

type type Property

Returns the type of the event. (read-only)

Declaration

Swift

var type: UIEventType { get }

Objective-C

@property(nonatomic, readonly) UIEventType type

Discussion

The UIEventType constant returned by this property indicates the general type of this event, for example, whether it is a touch or motion event.

Availability

Available in iOS 3.0 and later.

See Also

subtype
subtype subtype Property

Returns the subtype of the event. (read-only)

Declaration

Swift

var subtype: UIEventSubtype { get }

Objective-C

@property(nonatomic, readonly) UIEventSubtype subtype

Discussion

The UIEventSubtype constant returned by this property indicates the subtype of the event in relation to the general type, which is returned from the type property.

Availability

Available in iOS 3.0 and later.

Getting the Touches for a Gesture Recognizer


    
      
           touchesForGestureRecognizer(_:)
      
      
           - touchesForGestureRecognizer:

Returns the touch objects that are being delivered to the specified gesture recognizer.

Declaration

Swift

func touchesForGestureRecognizer(_ gesture: UIGestureRecognizer) -> Set<UITouch>?

Objective-C

- (NSSet<UITouch *> *)touchesForGestureRecognizer:(UIGestureRecognizer *)gesture

Parameters


  gesture

An instance of a subclass of the abstract base class UIGestureRecognizer. This gesture-recognizer object must be attached to a view to receive the touches hit-tested to that view and its subviews.

Return Value

A set of UITouch objects representing the touches being delivered to the specified gesture recognizer for the event represented by the receiver.

Availability

Available in iOS 3.2 and later.

Data Types

UIEventType UIEventType
Specifies the general type of an event

Declaration

Swift

enum UIEventType : Int { case Touches case Motion case RemoteControl case Presses }

Objective-C

typedef enum { UIEventTypeTouches, UIEventTypeMotion, UIEventTypeRemoteControl, UIEventTypePresses } UIEventType;

Constants
- Touches
  
  UIEventTypeTouches
  
  The event is related to touches on the screen.
  
  Available in iOS 3.0 and later.
- Motion
  
  UIEventTypeMotion
  
  The event is related to motion of the device, such as when the user shakes it.
  
  Available in iOS 3.0 and later.
- RemoteControl
  
  UIEventTypeRemoteControl
  
  The event is a remote-control event. Remote-control events originate as commands received from a headset or external accessory for the purposes of controlling multimedia on the device.
  
  Available in iOS 4.0 and later.
- Presses
  
  UIEventTypePresses
  
  The event is related to the press of a physical button.
  
  Available in iOS 9.0 and later.
Discussion

You can obtain the type of an event from the type property. To further identify the event, you might also need to determine its subtype, which you obtain from the subtype property.

Import Statement

Objective-C

@import UIKit;

Swift

import UIKit

Availability

Available in iOS 3.0 and later.
UIEventSubtype UIEventSubtype
Specifies the subtype of the event in relation to its general type.

Declaration

Swift

enum UIEventSubtype : Int { case None case MotionShake case RemoteControlPlay case RemoteControlPause case RemoteControlStop case RemoteControlTogglePlayPause case RemoteControlNextTrack case RemoteControlPreviousTrack case RemoteControlBeginSeekingBackward case RemoteControlEndSeekingBackward case RemoteControlBeginSeekingForward case RemoteControlEndSeekingForward }

Objective-C

typedef enum { UIEventSubtypeNone = 0, UIEventSubtypeMotionShake = 1, UIEventSubtypeRemoteControlPlay = 100, UIEventSubtypeRemoteControlPause = 101, UIEventSubtypeRemoteControlStop = 102, UIEventSubtypeRemoteControlTogglePlayPause = 103, UIEventSubtypeRemoteControlNextTrack = 104, UIEventSubtypeRemoteControlPreviousTrack = 105, UIEventSubtypeRemoteControlBeginSeekingBackward = 106, UIEventSubtypeRemoteControlEndSeekingBackward = 107, UIEventSubtypeRemoteControlBeginSeekingForward = 108, UIEventSubtypeRemoteControlEndSeekingForward = 109, } UIEventSubtype;

Constants
- None
  
  UIEventSubtypeNone
  
  The event has no subtype. This is the subtype for events of the UIEventTypeTouches general type.
  
  Available in iOS 3.0 and later.
- MotionShake
  
  UIEventSubtypeMotionShake
  
  The event is related to the user shaking the device. It is a subtype for the UIEventTypeMotion general event type.
  
  Available in iOS 3.0.
- RemoteControlPlay
  
  UIEventSubtypeRemoteControlPlay
  
  A remote-control event for playing audio or video. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlPause
  
  UIEventSubtypeRemoteControlPause
  
  A remote-control event for pausing audio or video. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlStop
  
  UIEventSubtypeRemoteControlStop
  
  A remote-control event for stopping audio or video from playing. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlTogglePlayPause
  
  UIEventSubtypeRemoteControlTogglePlayPause
  
  A remote-control event for toggling audio or video between play and pause. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlNextTrack
  
  UIEventSubtypeRemoteControlNextTrack
  
  A remote-control event for skipping to the next audio or video track. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlPreviousTrack
  
  UIEventSubtypeRemoteControlPreviousTrack
  
  A remote-control event for skipping to the previous audio or video track. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlBeginSeekingBackward
  
  UIEventSubtypeRemoteControlBeginSeekingBackward
  
  A remote-control event to start seeking backward through the audio or video medium. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlEndSeekingBackward
  
  UIEventSubtypeRemoteControlEndSeekingBackward
  
  A remote-control event to end seeking backward through the audio or video medium. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlBeginSeekingForward
  
  UIEventSubtypeRemoteControlBeginSeekingForward
  
  A remote-control event to start seeking forward through the audio or video medium. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
- RemoteControlEndSeekingForward
  
  UIEventSubtypeRemoteControlEndSeekingForward
  
  A remote-control event to end seeking forward through the audio or video medium. It is a subtype of the UIEventTypeRemoteControl general event type.
  
  Available in iOS 4.0.
Discussion

You can obtain the subtype of an event from the subtype property.

Import Statement

Objective-C

@import UIKit;

Swift

import UIKit

Availability

Available in iOS 3.0 and later.

UIEvent

Getting the Touches for an Event

Declaration

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Getting Event Attributes

Declaration

Discussion

Availability

Getting the Event Type

Declaration

Discussion

Availability

See Also

Declaration

Discussion

Availability

Getting the Touches for a Gesture Recognizer

Declaration

Parameters

Return Value

Availability

Data Types

Declaration

Constants

Discussion

Import Statement

Availability

Declaration

Constants

Discussion

Import Statement

Availability