uiresponder class

UIResponder Class Reference

Contents

UIResponder Class Reference 4Overview 4

Tasks 5

Managing the Responder Chain 5

Managing Input Views 5

Responding to Touch Events 6

Responding to Motion Events 6

Responding to Remote-Control Events 6

Getting the Undo Manager 6

Validating Commands 6

Accessing the Available Key Commands 7

Managing the Text Input Mode 7

Properties 7

inputAccessoryView 7

inputView 8

keyCommands 8

textInputContextIdentifier 9

textInputMode 9

undoManager 10

Class Methods 10

clearTextInputContextIdentifier: 10

Instance Methods 11

becomeFirstResponder 11

canBecomeFirstResponder 11

canPerformAction:withSender: 12

canResignFirstResponder 13

isFirstResponder 14

motionBegan:withEvent: 14

motionCancelled:withEvent: 15

motionEnded:withEvent: 16

nextResponder 16

reloadInputViews 17

remoteControlReceivedWithEvent: 17

resignFirstResponder 18

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

2

targetForAction:withSender: 19

touchesBegan:withEvent: 19

touchesCancelled:withEvent: 20

touchesEnded:withEvent: 21

touchesMoved:withEvent: 22

Document Revision History 24


3

Contents

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 UIResponder.h

Related sample code Handling Touches Using Responder Methods and Gesture Recognizers

iAdSuite

Managed App Configuration

TableView Fundamentals for iOS

Using NSXMLParser to parse XML documents

OverviewThe 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: (page 19), touchesMoved:withEvent: (page 22),

touchesEnded:withEvent: (page 21), and touchesCancelled:withEvent: (page 20). The parameters of

these methods associate touches with their eventsespecially touches that are new or have changedand

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.


4

UIResponder Class Reference

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: (page 14),

motionEnded:withEvent: (page 16), and motionCancelled:withEvent: (page 15). Additionally for iOS 3.0,

the canPerformAction:withSender: (page 12) method allows responders to validate commands in the user

interface while the undoManager (page 10) property returns the nearest NSUndoManager object in the responder

chain.

In iOS 4.0, UIResponder added the remoteControlReceivedWithEvent: (page 17) method for handling

remote-control events.

Tasks

Managing the Responder Chain

nextResponder (page 16)

Returns the receiver'snext responder, or nil if it has none.

isFirstResponder (page 14)

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

canBecomeFirstResponder (page 11)

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

becomeFirstResponder (page 11)

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

canResignFirstResponder (page 13)

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

resignFirstResponder (page 18)

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

Managing Input Views

inputView (page 8) property

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

inputAccessoryView (page 7) property

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

reloadInputViews (page 17)

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

UIResponder Class ReferenceTasks


5

Responding to Touch Events

touchesBegan:withEvent: (page 19)

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

touchesMoved:withEvent: (page 22)

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

touchesEnded:withEvent: (page 21)

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

touchesCancelled:withEvent: (page 20)

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

Responding to Motion Events

motionBegan:withEvent: (page 14)

Tells the receiver that a motion event has begun.

motionEnded:withEvent: (page 16)

Tells the receiver that a motion event has ended.

motionCancelled:withEvent: (page 15)

Tells the receiver that a motion event has been cancelled.

Responding to Remote-Control Events

remoteControlReceivedWithEvent: (page 17)

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

Getting the Undo Manager

undoManager (page 10) property

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

Validating Commands

canPerformAction:withSender: (page 12)

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

UIResponder Class ReferenceTasks


6

targetForAction:withSender: (page 19)

Returns the target object that responds to an action.

Accessing the Available Key Commands

keyCommands (page 8) property

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

Managing the Text Input Mode

textInputMode (page 9) property

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

textInputContextIdentifier (page 9) property

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

+ clearTextInputContextIdentifier: (page 10)

Clears text input mode information from the apps user defaults.

Properties

inputAccessoryView

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

@property(readonly, retain) UIView *inputAccessoryView

DiscussionThe 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 (page 8) 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.

AvailabilityAvailable in iOS 3.2 and later.

UIResponder Class ReferenceProperties


7

Declared inUIResponder.h

inputView

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

@property(readonly, retain) UIView *inputView

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



keyCommands

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

@property(nonatomic, readonly) NSArray *keyCommands

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



8



textInputContextIdentifier

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

@property(readonly, retain) NSString *textInputContextIdentifier

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



textInputMode

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

@property(readonly, retain) UITextInputMode *textInputMode

DiscussionThe 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 users 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.


See Also @property textInputContextIdentifier (page 9)



9


undoManager

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

@property(nonatomic, readonly) NSUndoManager *undoManager

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



Class Methods

clearTextInputContextIdentifier:

Clears text input mode information from the apps user defaults.

+ (void)clearTextInputContextIdentifier:(NSString *)identifier

Parametersidentifier

An identifier assigned to the textInputContextIdentifier (page 9) property of one of your responders.

DiscussionCalling this method removes any text input mode information associated with the specified identifier from

the apps user defaults. Removing this information causes the responder to use the default text input mode

again.

UIResponder Class ReferenceClass Methods


10



Instance Methods

becomeFirstResponder

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

- (BOOL)becomeFirstResponder

Return ValueYES if the receiver accepts first-responder status or NO if it refuses this status. The default implementation

returns YES, accepting first responder status.

DiscussionSubclasses 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 (page 13)) 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 views 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.


See Also isFirstResponder (page 14) canBecomeFirstResponder (page 11)


canBecomeFirstResponder

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

UIResponder Class ReferenceInstance Methods


11

- (BOOL)canBecomeFirstResponder

Return ValueYES if the receiver can become the first responder, NO otherwise.

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


See Also becomeFirstResponder (page 11)

Related Sample CodeAudio Mixer (MixerHost)Handling Touches Using Responder Methods and Gesture RecognizersMoviePlayer


canPerformAction:withSender:

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

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

Parametersaction

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.



12

Return ValueYES 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.

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



canResignFirstResponder

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

- (BOOL)canResignFirstResponder

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

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


See Also resignFirstResponder (page 18)



13


isFirstResponder

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

- (BOOL)isFirstResponder

Return ValueYES if the receiver is the first responder, NO otherwise.


See Also becomeFirstResponder (page 11) resignFirstResponder (page 18)

Related Sample CodeEADemoGeocoderDemo


motionBegan:withEvent:

Tells the receiver that a motion event has begun.

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

Parametersmotion

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.

DiscussioniOS informs the first responder only when a motion event starts and when it ends; for example, it doesnt report

individual shakes. The receiving object must be the first responder to receive motion events.



14

The default implementation of this method does nothing. However immediate UIKit subclasses of UIResponder,

particularly UIView, forward the message up the responder chain.


See Also motionEnded:withEvent: (page 16) motionCancelled:withEvent: (page 15)


motionCancelled:withEvent:

Tells the receiver that a motion event has been cancelled.

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

Parametersmotion

An event-subtype constant indicating the kind of motion associated with event. A common motion is

shaking, which is indicated by UIEventSubtypeMotionShake.

event


DiscussionThis 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: (page 14) implementation.




See Also motionBegan:withEvent: (page 14) motionEnded:withEvent: (page 16)



15


motionEnded:withEvent:

Tells the receiver that a motion event has ended.

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

Parametersmotion

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

by UIEventSubtypeMotionShake.

event


DiscussioniOS informs the responder only when a motion event starts and when it ends; for example, it doesnt report

individual shakes.




See Also motionBegan:withEvent: (page 14) motionCancelled:withEvent: (page 15)


nextResponder

Returns the receiver'snext responder, or nil if it has none.

- (UIResponder *)nextResponder

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



16

DiscussionThe 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 doesnt);

UIViewController implements the method by returning its views superview; UIWindow returns the

application object, and UIApplication returns nil.


See Also isFirstResponder (page 14)


reloadInputViews

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

- (void)reloadInputViews

DiscussionYou 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 immediatelythat is, without animating them

into place. If the current object is not the first responder, this method has no effect.



remoteControlReceivedWithEvent:

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

- (void)remoteControlReceivedWithEvent:(UIEvent *)event



17

Parametersevent

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

UIEventTypeRemoteControl.

DiscussionRemote-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 commandfor 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.



resignFirstResponder

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

- (BOOL)resignFirstResponder

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


See Also isFirstResponder (page 14) canResignFirstResponder (page 13)

Related Sample CodeAdvancedURLConnectionsAirDrop Examples



18

EADemoSimple Core Data RelationshipsUICatalog


targetForAction:withSender:

Returns the target object that responds to an action.

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

Parametersaction

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 ValueThe object whose action method is invoked to execute the command.

DiscussionThis method is called whenever an action needs to be invoked by the object. The default implementation calls

the canPerformAction:withSender: (page 12) 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.



touchesBegan:withEvent:

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

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



19

Parameterstouches

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.

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


See Also touchesMoved:withEvent: (page 22) touchesEnded:withEvent: (page 21) touchesCancelled:withEvent: (page 20)


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



20

Parameterstouches

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

by event.

event


DiscussionThis 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: (page 19) implementation.





[super touchesCancelled:touches withEvent:event];




See Also touchesBegan:withEvent: (page 19) touchesMoved:withEvent: (page 22) motionEnded:withEvent: (page 16)


touchesEnded:withEvent:

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



21

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

Parameterstouches

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

by event.

event






[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: (page 19) implementation.






See Also touchesBegan:withEvent: (page 19) touchesMoved:withEvent: (page 22) touchesCancelled:withEvent: (page 20)


touchesMoved:withEvent:

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



22

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

Parameterstouches

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

event.

event






[super touchesMoved:touches withEvent:event];






See Also touchesBegan:withEvent: (page 19) touchesEnded:withEvent: (page 21) touchesCancelled:withEvent: (page 20)




23

This table describes the changes to UIResponder Class Reference .

NotesDate

Added new APIs introduced in iOS 7.2013-09-18

Added caveats about calling super for the touch-handling methods and

for resignFirstResponder.

2011-03-07

Improved description of default behavior of touch- and motion-event

handling methods.

2010-08-03

Added a description of the remoteControlReceivedWithEvent: method

(iOS 4.0).

2010-04-15

Updated for iOS 3.2.2010-02-25

Made minor corrections.2009-05-27

Added descriptions of the methods added for iOS 3.0: undoManager,

canPerformAction:withSender:, and the motion-handling methods.

2009-03-08

New document describing the class that defines an interface for objects

responding to and handling events.

2008-06-26


24

Document Revision History

Apple Inc.Copyright 2013 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApples copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, Cocoa, Cocoa Touch, andShake are trademarks of Apple Inc., registered inthe U.S. and other countries.

iAd is a service mark of Apple Inc., registered inthe U.S. and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE.ASARESULT, THISDOCUMENT ISPROVIDEDAS IS, AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and youmay also have otherrights which vary from state to state.

UIResponder Class ReferenceContentsUIResponder Class ReferenceOverviewTasksManaging the Responder ChainManaging Input ViewsResponding to Touch EventsResponding to Motion EventsResponding to Remote-Control EventsGetting the Undo ManagerValidating CommandsAccessing the Available Key CommandsManaging the Text Input Mode

PropertiesinputAccessoryViewinputViewkeyCommandstextInputContextIdentifiertextInputModeundoManager

Class MethodsclearTextInputContextIdentifier:

Instance MethodsbecomeFirstRespondercanBecomeFirstRespondercanPerformAction:withSender:canResignFirstResponderisFirstRespondermotionBegan:withEvent:motionCancelled:withEvent:motionEnded:withEvent:nextResponderreloadInputViewsremoteControlReceivedWithEvent:resignFirstRespondertargetForAction:withSender:touchesBegan:withEvent:touchesCancelled:withEvent:touchesEnded:withEvent:touchesMoved:withEvent:

Revision History

uiresponder class

Documents