UIEvent Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Event Handling Guide for iOS
Declared in
UIEvent.h
Related sample code

Overview

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.

Tasks

Getting the Touches for an Event

Getting Event Attributes

Getting the Event Type

Getting the Touches for a Gesture Recognizer

Properties

subtype

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

@property(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.
Related Sample Code
Declared In
UIEvent.h

timestamp

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

@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.
Declared In
UIEvent.h

type

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

@property(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
Related Sample Code
Declared In
UIEvent.h

Instance Methods

allTouches

Returns all touch objects associated with the receiver.

- (NSSet *)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
Related Sample Code
Declared In
UIEvent.h

touchesForGestureRecognizer:

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

- (NSSet *)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.
Declared In
UIEvent.h

touchesForView:

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

- (NSSet *)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
Related Sample Code
Declared In
UIEvent.h

touchesForWindow:

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

- (NSSet *)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
Declared In
UIEvent.h

Constants

UIEventType

Specifies the general type of an event

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

The event is related to touches on the screen.

Available in iOS 3.0 and later.

Declared in UIEvent.h.

UIEventTypeMotion

The event is related to motion of the device, such as when the user shakes it.

Available in iOS 3.0 and later.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIEvent.h

UIEventSubtype

Specifies the subtype of the event in relation to its general type.

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
UIEventSubtypeNone

The event has no subtype. This is the subtype for events of the UIEventTypeTouches general type.

Available in iOS 3.0 and later.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

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.

Declared in UIEvent.h.

Discussion

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

Availability
  • Available in iOS 3.0 and later.
Declared In
UIEvent.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-08-03)

Did this document help you? Yes It's good, but... Not helpful...