iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIEvent Class Reference

Options
Deployment Target:

On This Page
Language:

UIEvent

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.

  • Returns all touch objects associated with the receiver.

    Declaration

    Swift

    func allTouches() -> Set<UITouch>?

    Objective-C

    - (NSSet<UITouch *> * _Nullable)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.

  • 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 *> * _Nullable)touchesForView:(UIView * _Nonnull)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.

  • 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 *> * _Nullable)touchesForWindow:(UIWindow * _Nonnull)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.

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

  • 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

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

  • 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 *> * _Nullable)touchesForGestureRecognizer:(UIGestureRecognizer * _Nonnull)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

  • Specifies the general type of an event

    Declaration

    Swift

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

    Objective-C

    typedef enum { UIEventTypeTouches, UIEventTypeMotion, UIEventTypeRemoteControl, } 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.

    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.

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