| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UIEvent.h |
| Related sample code |
A UIEvent object (or, simply, an event object) represents an event in iPhone OS. There are two general types of event: touch events and motion events. (Motion events were introduced in iPhone OS 3.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 general types for touch and motion events, and defines a motion subtype for "shake” events. You implement the motion-related methods of UIResponder (such as motionBegan:withEvent:) to handle this type of event.
See Event Handling in iPhone Application Programming Guide for further information on event handling.
timestamp property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
Returns the subtype of the event. (read-only)
@property(readonly) UIEventSubtype subtype
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.
UIEvent.hThe time when the event occurred. (read-only)
@property(nonatomic, readonly) NSTimeInterval timestamp
The property value is the number of seconds since system startup.
UIEvent.hReturns the type of the event. (read-only)
@property(readonly) UIEventType type
The UIEventType constant returned by this property indicates the general type of this event, for example, whether it is a touch or motion event.
UIEvent.hReturns all touch objects associated with the receiver.
- (NSSet *)allTouches
A set of UITouch objects representing all touches associated with an event (represented by the receiver).
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.
UIEvent.hReturns the touch objects that belong to a given view for the event represented by the receiver.
- (NSSet *)touchesForView:(UIView *)view
TheUIView object on which the touches related to the event were made.
An set of UITouch objects representing the touches for the specified view related to the event represented by the receiver.
UIEvent.hReturns the touch objects that belong to a given window for the event represented by the receiver.
- (NSSet *)touchesForWindow:(UIWindow *)window
The UIWindow object on which the touches related to the event were made.
An set of UITouch objects representing the touches for the specified window related to the event represented by the receiver.
UIEvent.hSpecifies the general type of an event
typedef enum {
UIEventTypeTouches,
UIEventTypeMotion,
} UIEventType;
UIEventTypeTouchesThe event is related to touches on the screen.
Available in iPhone OS 3.0 and later.
Declared in UIEvent.h.
UIEventTypeMotionThe event is related to motion of the device, such as when the user shakes it.
Available in iPhone OS 3.0 and later.
Declared in UIEvent.h.
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.
UIEvent.hSpecifies the subtype of the event in relation to its general type.
typedef enum {
UIEventSubtypeNone = 0,
UIEventSubtypeMotionShake = 1,
} UIEventSubtype;
UIEventSubtypeNoneThe event has no subtype. This is the subtype for events of the UIEventTypeTouches general type.
Available in iPhone OS 3.0 and later.
Declared in UIEvent.h.
UIEventSubtypeMotionShakeThe event is related to the user shaking the device. It is a subtype for the UIEventTypeMotion general event type.
Available in iPhone OS 3.0 and later.
Declared in UIEvent.h.
You can obtain the subtype of an event from the subtype property.
UIEvent.hLast updated: 2009-03-08
iPhone OS Reference Library Data Management: Event Handling UIEvent Class Reference