UIResponder Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UIResponder.h
Related sample code

Overview

The UIResponder class defines an interface for objects that respond to and handle events. It is the superclass of UIApplication, UIView and its subclasses (which include UIWindow). Instances of these classes are sometimes referred to as responder objects or, simply, responders.

There are two general kinds of events: touch events and motion events. The primary event-handling methods for touches are touchesBegan:withEvent:, touchesMoved:withEvent:, touchesEnded:withEvent:, and touchesCancelled:withEvent:. The parameters of these methods associate touches with their events—€”especially touches that are new or have changed—€”and thus allow responder objects to track and handle the touches as the delivered events progress through the phases of a multi-touch sequence. Any time a finger touches the screen, is dragged on the screen, or lifts from the screen, a UIEvent object is generated. The event object contains UITouch objects for all fingers on the screen or just lifted from it.

iOS 3.0 introduced system capabilities for generating motion events, specifically the motion of shaking the device. The event-handling methods for these kinds of events are motionBegan:withEvent:, motionEnded:withEvent:, and motionCancelled:withEvent:. Additionally for iOS 3.0, the canPerformAction:withSender: method allows responders to validate commands in the user interface while the undoManager property returns the nearest NSUndoManager object in the responder chain.

In iOS 4.0, UIResponder added the remoteControlReceivedWithEvent: method for handling remote-control events.

Tasks

Managing the Responder Chain

Managing Input Views

Responding to Touch Events

Responding to Motion Events

Responding to Remote-Control Events

Getting the Undo Manager

Validating Commands

Accessing the Available Key Commands

Managing the Text Input Mode

Properties

inputAccessoryView

The custom accessory view to display when the object becomes the first responder. (read-only)

@property(readonly, retain) UIView *inputAccessoryView
Discussion

The default value of this property is nil. Subclasses that want to attach custom controls to either a system-supplied input view (such as the keyboard) or a custom input view (one you provide in the inputView property) should redeclare this property as readwrite and use it to manage their custom accessory view. When the receiver subsequently becomes the first responder, the responder infrastructure attaches the view to the appropriate input view before displaying it.

This property is typically used to attach an accessory view to the system-supplied keyboard that is presented for UITextField and UITextView objects.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIResponder.h

inputView

The custom input view to display when the object becomes the first responder. (read-only)

@property(readonly, retain) UIView *inputView
Discussion

The value of this property is nil. Responder objects that require a custom view to gather input from the user should redeclare this property as readwrite and use it to manage their custom input view. When the receiver subsequently becomes the first responder, the responder infrastructure presents the specified input view automatically. Similarly, when the view resigns its first responder status, the responder infrastructure automatically dismisses the specified view.

This property is typically used to replace the system-supplied keyboard that is presented for UITextField and UITextView objects.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIResponder.h

keyCommands

The key commands that trigger actions on this responder. (read-only)

@property(nonatomic, readonly) NSArray *keyCommands
Discussion

A responder object that supports hardware keyboard commands can redefine this property and use it to return an array of UIKeyCommand objects that it supports. Each key command object represents the keyboard sequence to recognize and the action method of the responder to call in response.

The key commands you return from this method are applied to the entire responder chain. When an key combination is pressed that matches a key command object, UIKit walks the responder chain looking for an object that implements the corresponding action method. It calls that method on the first object it finds and then stops processing the event.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIResponder.h

textInputContextIdentifier

An identifier signifying that the responder should preserve its text input mode information. (read-only)

@property(readonly, retain) NSString *textInputContextIdentifier
Discussion

If you redefine this property and return a string value, UIKit tracks the current text input mode for the responder. While in tracking mode, any programmatic changes you make to the text input mode are remembered and restored whenever the responder becomes active.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIResponder.h

textInputMode

The text input mode for this responder object. (read-only)

@property(readonly, retain) UITextInputMode *textInputMode
Discussion

The text input mode identifies the language and keyboard displayed when this responder is active.

For responders, the system normally displays a keyboard that is based on the user’s language preferences. You can redefine this property and use it to return a different text input mode in cases where you want a responder to use a specific keyboard. The user can still change the keyboard while the responder is active, but switching away to another responder and then back restores the keyboard you specified.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIResponder.h

undoManager

Returns the nearest shared undo manager in the responder chain. (read-only)

@property(nonatomic, readonly) NSUndoManager *undoManager
Discussion

By default, every window of an application has an undo manager: a shared object for managing undo and redo operations. However, the class of any object in the responder chain can have their own custom undo manager. (For example, instances of UITextField have their own undo manager that is cleared when the text field resigns first-responder status.) When you request an undo manager, the request goes up the responder chain and the UIWindowobject returns a usable instance.

You may add undo managers to your view controllers to perform undo and redo operations local to the managed view.

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

Class Methods

clearTextInputContextIdentifier:

Clears text input mode information from the app’s user defaults.

+ (void)clearTextInputContextIdentifier:(NSString *)identifier
Parameters
identifier

An identifier assigned to the textInputContextIdentifier property of one of your responders.

Discussion

Calling this method removes any text input mode information associated with the specified identifier from the app’s user defaults. Removing this information causes the responder to use the default text input mode again.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIResponder.h

Instance Methods

becomeFirstResponder

Notifies the receiver that it is about to become first responder in its window.

- (BOOL)becomeFirstResponder
Return Value

YES if the receiver accepts first-responder status or NO if it refuses this status. The default implementation returns YES, accepting first responder status.

Discussion

Subclasses can override this method to update state or perform some action such as highlighting the selection.

A responder object only becomes the first responder if the current responder can resign first-responder status (canResignFirstResponder) and the new responder can become first responder.

You may call this method to make a responder object such as a view the first responder. However, you should only call it on that view if it is part of a view hierarchy. If the view’s window property holds a UIWindow object, it has been installed in a view hierarchy; if it returns nil, the view is detached from any hierarchy.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

canBecomeFirstResponder

Returns a Boolean value indicating whether the receiver can become first responder.

- (BOOL)canBecomeFirstResponder
Return Value

YES if the receiver can become the first responder, NO otherwise.

Discussion

Returns NO by default. If a responder object returns YES from this method, it becomes the first responder and can receive touch events and action messages. Subclasses must override this method to be able to become first responder.

You must not send this message to a view that is not currently attached to the view hierarchy. The result is undefined.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

canPerformAction:withSender:

Requests the receiving responder to enable or disable the specified command in the user interface.

- (BOOL)canPerformAction:(SEL)action withSender:(id)sender
Parameters
action

A selector that identifies a method associated with a command. For the editing menu, this is one of the editing methods declared by the UIResponderStandardEditActions informal protocol (for example, copy:).

sender

The object calling this method. For the editing menu commands, this is the shared UIApplication object. Depending on the context, you can query the sender for information to help you determine whether a command should be enabled.

Return Value

YES if the the command identified by action should be enabled or NO if it should be disabled. Returning YES means that your class can handle the command in the current context.

Discussion

This default implementation of this method returns YES if the responder class implements the requested action and calls the next responder if it does not. Subclasses may override this method to enable menu commands based on the current state; for example, you would enable the Copy command if there is a selection or disable the Paste command if the pasteboard did not contain data with the correct pasteboard representation type. If no responder in the responder chain returns YES, the menu command is disabled. Note that if your class returns NO for a command, another responder further up the responder chain may still return YES, enabling the command.

This method might be called more than once for the same action but with a different sender each time. You should be prepared for any kind of sender including nil.

For information on the editing menu, see the description of the UIMenuController class.

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

canResignFirstResponder

Returns a Boolean value indicating whether the receiver is willing to relinquish first-responder status.

- (BOOL)canResignFirstResponder
Return Value

YES if the receiver can resign first-responder status, NO otherwise.

Discussion

Returns YES by default. As an example, a text field in the middle of editing might want to implement this method to return NO to keep itself active during editing.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

isFirstResponder

Returns a Boolean value indicating whether the receiver is the first responder.

- (BOOL)isFirstResponder
Return Value

YES if the receiver is the first responder, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIResponder.h

motionBegan:withEvent:

Tells the receiver that a motion event has begun.

- (void)motionBegan:(UIEventSubtype)motion withEvent:(UIEvent *)event
Parameters
motion

An event-subtype constant indicating the kind of motion. A common motion is shaking, which is indicated by UIEventSubtypeMotionShake.

event

An object representing the event associated with the motion.

Discussion

iOS informs the first responder only when a motion event starts and when it ends; for example, it doesn’t report individual shakes. The receiving object must be the first responder to receive motion events.

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain.

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

motionCancelled:withEvent:

Tells the receiver that a motion event has been cancelled.

- (void)motionCancelled:(UIEventSubtype)motion withEvent:(UIEvent *)event
Parameters
motion

An event-subtype constant indicating the kind of motion associated with event. A common motion is shaking, which is indicated by UIEventSubtypeMotionShake.

event

An object representing the event associated with the motion.

Discussion

This method is invoked when the Cocoa Touch framework receives an interruption requiring cancellation of the motion event. This interruption is something that might cause the application to be no longer active or the view to be removed from the window. The method can also be invoked if the shaking goes on too long. All responders that handle motion events should implement this method; in it they should clean up any state information that was established in the motionBegan:withEvent: implementation.

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain.

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

motionEnded:withEvent:

Tells the receiver that a motion event has ended.

- (void)motionEnded:(UIEventSubtype)motion withEvent:(UIEvent *)event
Parameters
motion

An event-subtype constant indicating the kind of motion. A common motion is shaking, which is indicated by UIEventSubtypeMotionShake.

event

An object representing the event associated with the motion.

Discussion

iOS informs the responder only when a motion event starts and when it ends; for example, it doesn’t report individual shakes.

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain.

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

nextResponder

Returns the receiver'€™s next responder, or nil if it has none.

- (UIResponder *)nextResponder
Return Value

The next object in the responder chain to be presented with an event for handling.

Discussion

The UIResponder class does not store or set the next responder automatically, instead returning nil by default. Subclasses must override this method to set the next responder. UIView implements this method by returning the UIViewController object that manages it (if it has one) or its superview (if it doesn’t); UIViewController implements the method by returning its view’s superview; UIWindow returns the application object, and UIApplication returns nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

reloadInputViews

Updates the custom input and accessory views when the object is the first responder.

- (void)reloadInputViews
Discussion

You can use this method to refresh the custom input view or input accessory view associated with the current object when it is the first responder. The views are replaced immediately—that is, without animating them into place. If the current object is not the first responder, this method has no effect.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIResponder.h

remoteControlReceivedWithEvent:

Sent to the receiver when a remote-control event is received.

- (void)remoteControlReceivedWithEvent:(UIEvent *)event
Parameters
event

An event object encapsulating a remote-control command. Remote-control events have a type of UIEventTypeRemoteControl.

Discussion

Remote-control events originate as commands from external accessories, including headsets. An application responds to these commands by controlling audio or video media presented to the user. The receiving responder object should examine the subtype of event to determine the intended command—for example, play (UIEventSubtypeRemoteControlPlay)—and then proceed accordingly.

To allow delivery of remote-control events, you must call the beginReceivingRemoteControlEvents method of UIApplication; to turn off delivery of remote-control events, call endReceivingRemoteControlEvents.

Availability
  • Available in iOS 4.0 and later.
Declared In
UIResponder.h

resignFirstResponder

Notifies the receiver that it has been asked to relinquish its status as first responder in its window.

- (BOOL)resignFirstResponder
Discussion

The default implementation returns YES, resigning first responder status. Subclasses can override this method to update state or perform some action such as unhighlighting the selection, or to return NO, refusing to relinquish first responder status. If you override this method, you must call super (the superclass implementation) at some point in your code.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

targetForAction:withSender:

Returns the target object that responds to an action.

- (id)targetForAction:(SEL)action withSender:(id)sender
Parameters
action

A selector that identifies a method associated with a command.

sender

The object calling this method. For the editing menu commands, this is the shared UIApplication object. Depending on the context, you can query the sender for information to help you determine the target of the command.

Return Value

The object whose action method is invoked to execute the command.

Discussion

This method is called whenever an action needs to be invoked by the object. The default implementation calls the canPerformAction:withSender: method to determine whether it can invoke the action. If the object can invoke the action, it returns itself, otherwise it passes the request up the responder chain. Your app should override this method if it wants to override how a target is selected.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIResponder.h

touchesBegan:withEvent:

Tells the receiver when one or more fingers touch down in a view or window.

- (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event
Parameters
touches

A set of UITouch instances that represent the touches for the starting phase of the event represented by event.

event

An object representing the event to which the touches belong.

Discussion

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain. To forward the message to the next responder, send the message to super (the superclass implementation); do not send the message directly to the next responder. For example,

[super touchesBegan:touches withEvent:event];

If you override this method without calling super (a common use pattern), you must also override the other methods for handling touch events, if only as stub (empty) implementations.

Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the corresponding view instance to YES.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

touchesCancelled:withEvent:

Sent to the receiver when a system event (such as a low-memory warning) cancels a touch event.

- (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event
Parameters
touches

A set of UITouch instances that represent the touches for the ending phase of the event represented by event.

event

An object representing the event to which the touches belong.

Discussion

This method is invoked when the Cocoa Touch framework receives a system interruption requiring cancellation of the touch event; for this, it generates a UITouch object with a phase of UITouchPhaseCancel. The interruption is something that might cause the application to be no longer active or the view to be removed from the window

When an object receives a touchesCancelled:withEvent: message it should clean up any state information that was established in its touchesBegan:withEvent: implementation.

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain. To forward the message to the next responder, send the message to super (the superclass implementation); do not send the message directly to the next responder. For example,

[super touchesCancelled:touches withEvent:event];

If you override this method without calling super (a common use pattern), you must also override the other methods for handling touch events, if only as stub (empty) implementations.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

touchesEnded:withEvent:

Tells the receiver when one or more fingers are raised from a view or window.

- (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event
Parameters
touches

A set of UITouch instances that represent the touches for the ending phase of the event represented by event.

event

An object representing the event to which the touches belong.

Discussion

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain. To forward the message to the next responder, send the message to super (the superclass implementation); do not send the message directly to the next responder. For example,

[super touchesEnded:touches withEvent:event];

When an object receives a touchesEnded:withEvent: message it should clean up any state information that was established in its touchesBegan:withEvent: implementation.

Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the corresponding view instance to YES.

If you override this method without calling super (a common use pattern), you must also override the other methods for handling touch events, if only as stub (empty) implementations.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h

touchesMoved:withEvent:

Tells the receiver when one or more fingers associated with an event move within a view or window.

- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event
Parameters
touches

A set of UITouch instances that represent the touches that are moving during the event represented by event.

event

An object representing the event to which the touches belong.

Discussion

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder, particularly UIView, forward the message up the responder chain. To forward the message to the next responder, send the message to super (the superclass implementation); do not send the message directly to the next responder. For example,

[super touchesMoved:touches withEvent:event];

Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the corresponding view instance to YES.

If you override this method without calling super (a common use pattern), you must also override the other methods for handling touch events, if only as stub (empty) implementations.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIResponder.h